diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..dd84ea7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + - OS: [e.g. iOS] + - Browser [e.g. chrome, safari] + - Version [e.g. 22] + +**Smartphone (please complete the following information):** + - Device: [e.g. iPhone6] + - OS: [e.g. iOS8.1] + - Browser [e.g. stock browser, safari] + - Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..8a18e08 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for RangeShifter +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/improve-existing-content.md b/.github/ISSUE_TEMPLATE/improve-existing-content.md new file mode 100644 index 0000000..8950ab1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/improve-existing-content.md @@ -0,0 +1,10 @@ +--- +name: Improve existing content +about: 'Make a suggestion to improve the R package ' +title: '' +labels: '' +assignees: '' + +--- + + diff --git a/.gitignore b/.gitignore index 9bd72d2..594d926 100644 --- a/.gitignore +++ b/.gitignore @@ -11,9 +11,11 @@ compile_commands.json Makefile .build-release/ build-Release/ +*.txt *.project *.workspace *.mk +*.txt *.tags # Hidden source @@ -79,9 +81,8 @@ vignettes/*.pdf *.utf8.md *.knit.md -# compilation files -*.o +# Test Scripts +/Model/ +TestScript.R + -# Visual Studio files -.vs/ -out/ diff --git a/CMakeLists.txt b/CMakeLists.txt deleted file mode 100644 index c14a3e3..0000000 --- a/CMakeLists.txt +++ /dev/null @@ -1,30 +0,0 @@ -# Config file for compilation with CMake - -if (NOT batchmode) # that is, RScore as a standalone - cmake_minimum_required(VERSION 3.10) - # set the project name and version - project(RScore VERSION 2.1.0) - # specify the C++ standard - set(CMAKE_CXX_STANDARD 17) - set(CMAKE_CXX_STANDARD_REQUIRED True) - add_executable(RScore Main.cpp Species.cpp Cell.cpp Community.cpp FractalGenerator.cpp Genome.cpp Individual.cpp Landscape.cpp Model.cpp Parameters.cpp Patch.cpp Population.cpp RandomCheck.cpp RSrandom.cpp SubCommunity.cpp Utils.cpp) -else() # that is, RScore compiled as library within RangeShifter_batch - add_library(RScore Species.cpp Cell.cpp Community.cpp FractalGenerator.cpp Genome.cpp Individual.cpp Landscape.cpp Model.cpp Parameters.cpp Patch.cpp Population.cpp RandomCheck.cpp RSrandom.cpp SubCommunity.cpp Utils.cpp) -endif() - -# pass config definitions to compiler -target_compile_definitions(RScore PRIVATE RSWIN64) - -# enable LINUX_CLUSTER macro on Linux + macOS -if(CMAKE_SYSTEM_NAME STREQUAL "Linux" OR CMAKE_SYSTEM_NAME STREQUAL "Darwin") - add_compile_definitions("LINUX_CLUSTER") -endif() - -# Debug Mode by default, unless "release" is passed -if(NOT DEFINED release) - add_compile_definitions(RSDEBUG) -endif() - -if(NOT batchmode) - target_include_directories(RScore PUBLIC "${PROJECT_BINARY_DIR}") -endif() \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e1b62ff..57a075e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,11 +3,11 @@ ## How to contribute Thank you for your interest in contributing to the RangeShifter platform. -In this document we will give you guidance on how to contribute to the RangeShifter project regarding issues, bug fixing and adding new features. +In this document we will give you guidance on how to contribute to the RangeShifter project regarding issues, bug fixing and adding new features. We distinguish between contributing to the RangeShifter core code and the different interfaces - in this case the R package. ## Repo structure -![Rangeshifter repo structure](RS_repos.png) +![Rangeshifter repo structure](RangeShiftR/man/figures/RS_repos.png) RangeShifter is distributed with three user interfaces, each living in their own repo: @@ -15,9 +15,9 @@ RangeShifter is distributed with three user interfaces, each living in their own - RangeShifter Batch Mode (command line interface) - the RangeShiftR package (R interface) -All three share the same source code for the core simulation (i.e., the actual model), which lives in this repo (RScore). Each of the interfaces keeps a copy of this core code in a subfolder called RScore, kept in sync with the RScore repo via a git subtree (see Git subtree usage section). +All three share the same source code for the core simulation (i.e., the actual model), which lives in its own repo (RScore). Each of the interfaces keeps a copy of this core code in a subfolder called RScore, kept in sync with the RScore repo via a git subtree (see [Git subtree usage section](https://github.com/RangeShifter/RScore?tab=readme-ov-file#usage-git-subtree). -⚠️ If you wish to propose a change to one of the interfaces, please do so in the corresponding repo: [RangeShifter batch mode](https://github.com/RangeShifter/RangeShifter_batch_dev), [RangeShiftR package](https://github.com/RangeShifter/RangeShiftR-package-dev). +⚠️ If you wish to propose a change to the core code of the simulation, please do so *in the [RScore](https://github.com/RangeShifter/RScore) repo*, rather than in the RScore folder of either interface. *The RangeShifter GUI is currently being rewritten, and is not open source yet. @@ -40,42 +40,54 @@ Anyone who whishes to make changes to RangeShifter's code, including regular dev ## Branching policy -![](branches.png) - -*Check out the [Git cheatsheet](https://github.com/RangeShifter/RScore/blob/main/git_cheatsheet.md) for a reminder on the main git commands* +![](RangeShiftR/man/figures/branches.png) This policy applies to RScore and all three RangeShifter interfaces. RangeShifter uses the following branching structure: - `main` is the default branch, where stable releases live. Because it contains the version of RangeShifter that users normally interact with, it must be stable and build at all times. -Only maintainers should make significant changes to `main`, normally by merging `develop` into `main` to make newly developed features available to users, and marking a release while doing so. -- `develop` is the development branch containing new, in-development features. It is the reference branch for all developers. Contributors may make small changes directly to `develop` but should ensure that new changes do not break the build. If one happens to break `develop`, it should be their top priority to fix it as this will disrupt the work of all other contributors. -Larger changes should instead be developed on feature branches. + Only maintainers should make significant changes to `main`, normally by merging `develop` into `main` to make newly developed features and bug fixes available to users, and marking a release while doing so. +- `develop` is the development branch containing new, in-development features. It is the reference branch for all developers. Contributors may make small changes and bug fixes directly to `develop` but should ensure that new changes do not break the build. If one happens to break `develop`, it should be their top priority to fix it as this will disrupt the work of all other contributors. + Larger changes should instead be developed on feature branches. - Larger changes should be first developed on feature (e.g. `cmake`, `mutualism`, etc.) or contributor (e.g., `theo`) branches. Contributors are welcome to experiment and break such branches at any time, as this will not impact users or other contributors. -When progress is deemed satisfactory, changes can be brought to `develop`. Please open a pull request on GitHub, and assign at least one maintainer as a reviewer. As a pre-requisite, RangeShifter must build on the branch before merging. Please enter a descriptive title and use the description field to describe what you have changed. + When progress is deemed satisfactory, changes can be brought to `develop`. Please open a pull request on GitHub, and assign at least one maintainer as a reviewer. As a pre-requisite, RangeShifter must build on the branch before merging. Please enter a descriptive title and use the description field to describe what you have changed. -In the meantime, we encourage contributors to work in small and frequent commits, and to merge `develop` into their branch often to update their branch with newest changes. + In the meantime, we encourage contributors to work in small and frequent commits, and to merge `develop` into their branch often to update their branch with newest changes. + +If you need a reminder on the main git commands related to committing and branching, head to the [Git cheatsheet](https://github.com/RangeShifter/RScore/blob/main/git_cheatsheet.md). + +## Contributing to the RangeShifter core code + +Any changes (issues, bugs, features) regarding the actual RangeShifter core code should be done in [this](https://github.com/RangeShifter/RScore) repository and can afterwards be synced with all interfaces using the git subtree feature (see [Git subtree](https://github.com/RangeShifter/RScore?tab=readme-ov-file#usage-git-subtree) section in the README). + +Please check the [contributing guidelines for the RScore code](https://github.com/RangeShifter/RScore/blob/main/CONTRIBUTING.md). -### Contributing to RangeShifter core code +## Contributing to the RangeShiftR package -Any changes regarding the RangeShifter core code should be done in this repository and can afterwards be synced with all interfaces using the git subtree feature (see [Git subtree](https://github.com/RangeShifter/RScore/tree/main?tab=readme-ov-file#usage-git-subtree) section in the README). +Please follow these guidelines for issues, bugs or new features related to the RangeShiftR-package. -#### Bugs +### Issues and bugs -To report a bug, please [open an issue](https://github.com/RangeShifter/RangeShiftR-package-dev/issues/new), using the Bug Report template. -Please do check if a related issue has already open on one of the other interfaces ([here](https://github.com/RangeShifter/RangeShifter_batch-dev/issues) for the batch interface or [here](https://github.com/RangeShifter/RangeShiftR-package-dev) for the R package interface). -To propose a bug fix (thank you!!), please create and work on your own branch or fork, from either `main` or `develop` (preferred), and open a pull request when your fix is ready to be merged into the original branch. +Issues should be used for reporting technical problems and bugs with the R package or suggest improvements e.g. in the documentation. +General and more conceptual questions regarding the application and settings of RangeShifter parameters should be asked in the [discussion forum](https://github.com/RangeShifter/RangeshiftR-tutorials/discussions) and answered by the broader RangeShifter community. -Maintainers will review the pull request, possibly request changes, and eventually integrate the bug fix into RScore, and update the subtrees to bring the fix to all interfaces. +#### Create a new issue -#### New features +If you encounter a technical problem, find a bug related to the RangeShiftR package or would like to suggest an improvement to the R package, please search if [a related issue already exists](https://github.com/RangeShifter/RangeShiftR-package-dev/issues). If you can't find a related issue, you can open a new issue using a relevant [issue form](https://github.com/RangeShifter/RangeShiftR-package-dev/issues/new/choose). To propose a bug fix (thank you!!), please create and work on your own branch or fork, from either `main` or `develop` (preferred), and open a pull request when your fix is ready to be merged into the original branch. -Do you have an idea of a new feature in the RangeShifter platform that should be integrated and is of use for other RangeShifter users? -Please get in touch with the RangeShifter development team (rangeshiftr@uni-potsdam.de) to discuss a collaboration. +As a prerequisite for merging, please ensure that the R package is build correctly. GitHub Action will soon be used for ensuring a successfull build of the R package interface on all operating systems (i.e. R CMD CHECK needs to run without warnings). -⚠️ We advise to contact the developer team as early as possible if you plan on implementing a new feature. This could prevent simultaneous development of the same feature and coordinate potential joint development. +Maintainers will review the pull request, possibly request changes, and eventually integrate the bug fix into the RangeShiftR package. -Alternatively, proceed as with the bug fix above: create your own branch or fork _from `develop`_ and work from there, and submit a pull request when your new features are ready to join the core code. +### New feature + +Do you have an idea of a new feature in the RangeShiftR package that should be integrated and is of use for other RangeShiftR users? +Please get in touch with the RangeShifter development team directly (rangeshiftr@uni-potsdam.de) to discuss a collaboration. + +⚠️ We advise to contact the developer team as early as possible if you plan on implementing a new feature of the R package interface. This could prevent simultaneous development of the same feature and coordinate potential joint development. + +Alternatively, proceed as with the bug fix above: create your own branch _from `develop`_ and work from there, and submit a pull request when your new features are ready to join the core code. We recommend that you update your branch regularly to new changes on `develop` (using `git merge develop`) to reduce the risk of merge conflicts or your version getting out-of-touch in the late stages of development. We also recommend that you work in small commits, as this makes the code easier to debug, and makes it easier for maintainers to understand your contributions when reviewing a pull request. + diff --git a/Cell.cpp b/Cell.cpp deleted file mode 100644 index 1c0f937..0000000 --- a/Cell.cpp +++ /dev/null @@ -1,237 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -//--------------------------------------------------------------------------- - -#include "Cell.h" - -//--------------------------------------------------------------------------- - -//--------------------------------------------------------------------------- - -// Cell functions - -Cell::Cell(int xx,int yy,intptr patch,int hab) -{ -x = xx; y = yy; -pPatch = patch; -envVal = 1.0; // default - no effect of any gradient -envDev = eps = 0.0; -habIxx.push_back(hab); -#if RSDEBUG -//DebugGUI(("Cell::Cell(): this=" + Int2Str((int)this) -// + " x=" + Int2Str(x) + " y=" + Int2Str(y) -// + " habIndex=" + Int2Str(habIndex) -//).c_str()); -#endif -visits = 0; -smsData = 0; -} - -Cell::Cell(int xx,int yy,intptr patch,float hab) -{ -x = xx; y = yy; -pPatch = patch; -envVal = 1.0; // default - no effect of any gradient -envDev = eps = 0.0; -habitats.push_back(hab); -visits = 0; -smsData = 0; -} - -Cell::~Cell() { -#if RSDEBUG -//DEBUGLOG << "Cell::~Cell(): this = " << this << " smsData = " << smsData << endl; -#endif -habIxx.clear(); -habitats.clear(); -if (smsData != 0) { - if (smsData->effcosts != 0) delete smsData->effcosts; - delete smsData; -} -#if RSDEBUG -//DEBUGLOG << "Cell::~Cell(): deleted" << endl; -#endif -} - -void Cell::setHabIndex(short hx) { -#if RSDEBUG -//DebugGUI(("Cell::setHabIndex(): this=" + Int2Str((int)this) -// + " x=" + Int2Str(x) + " y=" + Int2Str(y) -// + " habIx=" + Int2Str(habIx) -//).c_str()); -#endif -if (hx < 0) habIxx.push_back(0); -else habIxx.push_back(hx); -} - -void Cell::changeHabIndex(short ix,short hx) { -if (ix >= 0 && ix < (short)habIxx.size() && hx >= 0) habIxx[ix] = hx; -else habIxx[ix] = 0; -} - -int Cell::getHabIndex(int ix) { -if (ix < 0 || ix >= (int)habIxx.size()) - // nodata cell OR should not occur, but treat as such - return -1; -else return habIxx[ix]; -} -int Cell::nHabitats(void) { -int nh = (int)habIxx.size(); -if ((int)habitats.size() > nh) nh = (int)habitats.size(); -return nh; -} - -void Cell::setHabitat(float q) { -if (q >= 0.0 && q <= 100.0) habitats.push_back(q); -else habitats.push_back(0.0); -} - -float Cell::getHabitat(int ix) { -if (ix < 0 || ix >= (int)habitats.size()) - // nodata cell OR should not occur, but treat as such - return -1.0; -else return habitats[ix]; -} - -void Cell::setPatch(intptr p) { -pPatch = p; -} -intptr Cell::getPatch(void) -{ -#if RSDEBUG -//DebugGUI(("Cell::getPatch(): this=" + Int2Str((int)this) -// + " x=" + Int2Str(x) + " y=" + Int2Str(y) -// + " habIxx[0]=" + Int2Str(habIxx[0]) + " pPatch=" + Int2Str(pPatch) -//).c_str()); -#endif -return pPatch; -} - -locn Cell::getLocn(void) { locn q; q.x = x; q.y = y; return q; } - -void Cell::setEnvDev(float d) { envDev = d; } - -float Cell::getEnvDev(void) { return envDev; } - -void Cell::setEnvVal(float e) { -if (e >= 0.0) envVal = e; -} - -float Cell::getEnvVal(void) { return envVal; } - -void Cell::updateEps(float ac,float randpart) { -eps = eps*ac + randpart; -} - -float Cell::getEps(void) { return eps; } - -// Functions to handle costs for SMS - -int Cell::getCost(void) { -int c; -if (smsData == 0) c = 0; // costs not yet set up -else c = smsData->cost; -return c; -} - -void Cell::setCost(int c) { -if (smsData == 0) { - smsData = new smscosts; - smsData->effcosts = 0; -} -smsData->cost = c; -} - -// Reset the cost and the effective cost of the cell -void Cell::resetCost(void) { -if (smsData != 0) { resetEffCosts(); delete smsData; } -smsData = 0; -} - -array3x3f Cell::getEffCosts(void) { -array3x3f a; -if (smsData == 0 || smsData->effcosts == 0) { // effective costs have not been calculated - for (int i = 0; i < 3; i++) { - for (int j = 0; j < 3; j++) { - a.cell[i][j] = -1.0; - } - } -} -else - a = *smsData->effcosts; -return a; -} - -void Cell::setEffCosts(array3x3f a) { -if (smsData->effcosts == 0) smsData->effcosts = new array3x3f; -*smsData->effcosts = a; -} - -// Reset the effective cost, but not the cost, of the cell -void Cell::resetEffCosts(void) { -if (smsData != 0) { - if (smsData->effcosts != 0) { - delete smsData->effcosts; - smsData->effcosts = 0; - } -} -} - -void Cell::resetVisits(void) { visits = 0; } -void Cell::incrVisits(void) { visits++; } -unsigned long int Cell::getVisits(void) { return visits; } - -//--------------------------------------------------------------------------- - -// Initial species distribution cell functions - -DistCell::DistCell(int xx,int yy) { -x = xx; y = yy; initialise = false; -} - -DistCell::~DistCell() { - -} - -void DistCell::setCell(bool init) { -initialise = init; -} - -bool DistCell::toInitialise(locn loc) { -if (loc.x == x && loc.y == y) return initialise; -else return false; -} - -bool DistCell::selected(void) { return initialise; } - -locn DistCell::getLocn(void) { -locn loc; loc.x = x; loc.y = y; return loc; -} - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - - - - diff --git a/FractalGenerator.cpp b/FractalGenerator.cpp deleted file mode 100644 index 7a5ccc3..0000000 --- a/FractalGenerator.cpp +++ /dev/null @@ -1,243 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -//--------------------------------------------------------------------------- - -#include "FractalGenerator.h" -//--------------------------------------------------------------------------- - -vector patches; - -//----- Landscape creation -------------------------------------------------- - -land::land(): x_coord(0), y_coord(0), value(0.0), avail(0) {} - -bool compare(const land& z, const land& zz) //compares only the values of the cells -{ -return z.value < zz.value; -} - -vector& fractal_landscape(int X,int Y,double Hurst,double prop, - double maxValue,double minValue) -{ -#if RSDEBUG -DEBUGLOG << "fractal_landscape(): X=" << X << " Y=" << Y - << " Hurst=" << Hurst << " prop=" << prop - << " maxValue=" << maxValue << " minValue=" << minValue - << endl; -#endif - -int ii, jj, x, y; -int ix, iy; -//int x0, y0, size, kx, kx2, ky, ky2; -int kx,kx2,ky,ky2; - -double range; //range to draw random numbers at each iteration -double nx, ny; -double i, j; -int Nx = X; -int Ny = Y; - -double ran[5]; // to store each time the 5 random numbers for the random displacement - -int Nno; // number of cells NON suitable as habitat - -// exponents used to obtain the landscape dimensions -double pow2x = log(((double)X-1.0))/log(2.0); -double pow2y = log(((double)Y-1.0))/log(2.0); - -double **arena = new double *[X]; -for(ii = 0; ii < X; ii++) { - arena[ii] = new double[Y]; -} - -patches.clear(); -// initialise all the landscape with zeroes -for (jj = 0; jj < X; jj++) { - for (ii = 0; ii < Y; ii++) { - arena[jj][ii]=0; - } -} - -// initialisation of the four corners -arena[0][0] = 1.0 + pRandom->Random() * (maxValue-1.0); -arena[0][Y-1] = 1.0 + pRandom->Random() * (maxValue-1.0); -arena[X-1][0] = 1.0 + pRandom->Random() * (maxValue-1.0); -arena[X-1][Y-1] = 1.0 + pRandom->Random() * (maxValue-1.0); - -/////////////MIDPOINT DISPLACEMENT ALGORITHM////////////////////////////////// -kx = (Nx-1) / 2; -kx2 = 2 * kx; -ky = (Ny-1) / 2; -ky2 = 2 * ky; - -for (ii = 0; ii < 5; ii++) //random displacement -{ - ran[ii] = 1.0 + pRandom->Random() * (maxValue-1.0); -} - -//The diamond step: -arena[kx][ky] = ((arena[0][0] + arena[0][ky2] + arena[kx2][0] + arena[kx2][ky2])/4) + ran[0]; - -//The square step: -//left -arena[0][ky] = ((arena[0][0] +arena[0][ky2] + arena[kx][ky]) / 3) + ran[1]; -//top -arena[kx][0] = ((arena[0][0] + arena[kx][ky] + arena[kx2][0]) / 3) + ran[2]; -//right -arena[kx2][ky] = ((arena[kx2][0] + arena[kx][ky] + arena[kx2][ky2]) / 3) + ran[3]; -//bottom -arena[kx][ky2] = ((arena[0][ky2] + arena[kx][ky] +arena[kx2][ky2]) / 3) + ran[4]; - -range = maxValue*pow(2,-Hurst); - -i = pow2x-1; -j = pow2y-1; - -while (i > 0) { - nx = pow(2,i)+1; - kx = (int)((nx-1) / 2); - kx2 = 2 * kx; - - ny = pow(2,j)+1; - ky = (int)((ny-1) / 2); - ky2 = 2 * ky; - - ix = 0; - while (ix <= (Nx-nx)) { - iy = 0; - while (iy <= (Ny-ny)) { - for (ii = 0; ii < 5; ii++) //random displacement - { - ran[ii] = (int)(pRandom->Random() * 2.0 * range - range); - } - //The diamond step: - - arena[ix+kx][iy+ky] = ((arena[ix][iy] + arena[ix][iy+ky2] + arena[ix+ky2][iy] - + arena[ix+kx2][iy+ky2])/ 4) + ran[0]; - if (arena[ix+kx][iy+ky] < 1) arena[ix+kx][iy+ky] = 1; - - //The square step: - //left - arena[ix][iy+ky] =((arena[ix][iy] +arena[ix][iy+ky2] + arena[ix+kx][iy+ky])/3) - + ran[1]; - if (arena[ix][iy+ky] < 1) arena[ix][iy+ky] = 1; - //top - arena[ix+kx][iy] =((arena[ix][iy] + arena[ix+kx][iy+ky] + arena[ix+kx2][iy])/3) - + ran[2]; - if (arena[ix+kx][iy] < 1) arena[ix+kx][iy] = 1; - //right - arena[ix+kx2][iy+ky] = ((arena[ix+kx2][iy] + arena[ix+kx][iy+ky] + - arena[ix+kx2][iy+ky2]) / 3) + ran[3]; - if (arena[ix+kx2][iy+ky] < 1) arena[ix+kx2][iy+ky] = 1; - //bottom - arena[ix+kx][iy+ky2] = ((arena[ix][iy+ky2] + arena[ix+kx][iy+ky] + - arena[ix+kx2][iy+ky2]) / 3) + ran[4]; - if (arena[ix+kx][iy+ky2] < 1) arena[ix+kx][iy+ky2] = 1; - - iy += ((int)ny-1); - } - ix += ((int)nx-1); - } - if (i==j) j--; - i--; - - range = range*pow(2,-Hurst); //reduce the random number range -} - -// Now all the cells will be sorted and the Nno cells with the lower carrying -// capacity will be set as matrix, i.e. with K = 0 - -land *patch; - -for (x = 0; x < X; x++) // put all the cells with their values in a vector -{ - for (y = 0; y < Y; y++) - { - patch = new land; - patch->x_coord = x; - patch->y_coord = y; - patch->value = (float)arena[x][y]; - patch->avail = 1; - - patches.push_back(*patch); - - delete patch; - } -} - - -sort(patches.begin(),patches.end(),compare); // sorts the vector - -Nno = (int)(prop*X*Y); -for (ii = 0; ii < Nno; ii++) -{ - patches[ii].value = 0.0; - patches[ii].avail = 0; -} - -double min = (double)patches[Nno].value; // variables for the rescaling -double max = (double)patches[X*Y-1].value; - -double diff = max - min; -double diffK = maxValue-minValue; -double new_value; - -vector::iterator iter = patches.begin(); -while (iter != patches.end()) -{ - if (iter->value > 0) // rescale to a range of K between Kmin and Kmax - { - new_value = maxValue - diffK * (max - (double)iter->value) / diff; - - iter->value = (float)new_value; - } - else iter->value = 0; - - iter++; -} - -if (arena != NULL) { -#if RSDEBUG -//DebugGUI(("fractal_landscape(): arena=" + Int2Str((int)arena) -// + " X=" + Int2Str(X) + " Y=" + Int2Str(Y) -// ).c_str()); -#endif - for(ii = 0; ii < X; ii++) { -#if RSDEBUG -//DebugGUI(("fractal_landscape(): ii=" + Int2Str(ii) -// + " arena[ii]=" + Int2Str((int)arena[ii]) -// ).c_str()); -#endif - delete[] arena[ii]; - } - delete[] arena; -} - -return patches; - -} - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - diff --git a/Genome.cpp b/Genome.cpp deleted file mode 100644 index 59a68b1..0000000 --- a/Genome.cpp +++ /dev/null @@ -1,419 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - -#include "Genome.h" -//--------------------------------------------------------------------------- - -ofstream outGenetic; - -//--------------------------------------------------------------------------- - -Chromosome::Chromosome(int nloc) -{ - if (nloc > 0) nloci = nloc; else nloci = 1; - pLoci = new locus[nloci]; - for (int i = 0; i < nloci; i++) { - pLoci[i].allele[0] = pLoci[i].allele[1] = 0; - } -} - -Chromosome::~Chromosome() { - if (pLoci != 0) { - delete[] pLoci; pLoci = NULL; - } -} - -short Chromosome::nLoci(void) { return nloci; } - -locus Chromosome::alleles(const int loc) { // return allele values at a specified locus - locus l; l.allele[0] = l.allele[1] = 0; - if (loc >= 0 && loc < nloci) { - l.allele[0] = pLoci[loc].allele[0]; l.allele[1] = pLoci[loc].allele[1]; - } - return l; -} - -double Chromosome::additive(const bool diploid) { - int sum = 0; - for (int i = 0; i < nloci; i++) { - sum += pLoci[i].allele[0]; - if (diploid) sum += pLoci[i].allele[1]; - } - return (double)sum / INTBASE; -} - -double Chromosome::meanvalue(const bool diploid) { - int sum = 0; - double mean; - for (int i = 0; i < nloci; i++) { - sum += pLoci[i].allele[0]; - if (diploid) sum += pLoci[i].allele[1]; - } - mean = (double)sum / (double)nloci; - if (diploid) mean /= 2.0; - mean /= INTBASE; - return mean; -} - -double Chromosome::additive(const short loc, const bool diploid) { - int sum = 0; - sum += pLoci[loc].allele[0]; - if (diploid) sum += pLoci[loc].allele[1]; - return (double)sum / INTBASE; -} - -// Set up chromosome at simulation initialisation -void Chromosome::initialise(const double mean, const double sd, - const bool diploid) { - double avalue; - double intbase = INTBASE; - - for (int i = 0; i < nloci; i++) { - avalue = pRandom->Normal(mean, sd); - if (avalue > 0.0) - pLoci[i].allele[0] = (int)(avalue * intbase + 0.5); - else - pLoci[i].allele[0] = (int)(avalue * intbase - 0.5); - if (diploid) { - avalue = pRandom->Normal(mean, sd); - if (avalue > 0.0) - pLoci[i].allele[1] = (int)(avalue * intbase + 0.5); - else - pLoci[i].allele[1] = (int)(avalue * intbase - 0.5); - } - } - -} - -// Set up specified locus at simulation initialisation -void Chromosome::initialise(const short locus, const short posn, const int aval) -{ - // note that initialising value is ADDED to current value to allow for pleiotropy - pLoci[locus].allele[posn] += aval; -} - -// Inherit from specified parent -void Chromosome::inherit(const Chromosome* parentChr, const short posn, const short nloc, - const double probmutn, const double probcross, const double mutnSD, const bool diploid) -{ - // NOTE: At present for diploid genome, presence of crossover is determined at each - // locus (except first). However, Roslyn has shown that it is more efficient to sample - // crossover locations from geometric distribution if number of loci is large. - // HOW LARGE IS 'LARGE' IN THIS CASE?... - - int ix = 0; // indexes maternal and paternal strands - if (diploid) ix = pRandom->Bernoulli(0.5); // start index at random - for (int i = 0; i < nloc; i++) { - if (diploid) { - pLoci[i].allele[posn] = parentChr->pLoci[i].allele[ix]; - if (pRandom->Bernoulli(probcross)) { // crossover occurs - if (ix == 0) ix = 1; else ix = 0; - } - } - else - pLoci[i].allele[posn] = parentChr->pLoci[i].allele[0]; - if (pRandom->Bernoulli(probmutn)) { // mutation occurs - double intbase = INTBASE; -#if RSDEBUG - int oldval = pLoci[i].allele[posn]; -#endif - double mutnvalue = pRandom->Normal(0, mutnSD); - if (mutnvalue > 0.0) - pLoci[i].allele[posn] += (int)(intbase * mutnvalue + 0.5); - else - pLoci[i].allele[posn] += (int)(intbase * mutnvalue - 0.5); -#if RSDEBUG - MUTNLOG << mutnvalue << " " << oldval << " " << pLoci[i].allele[posn] << " " << endl; -#endif - } - } -} - - -//--------------------------------------------------------------------------- - -// NB THIS FUNCTION IS CURRENTLY NOT BEING CALLED TO CONSTRUCT AN INSTANCE OF Genome -// Genome(int) IS USED INSTEAD - -Genome::Genome() { - pChromosome = NULL; - nChromosomes = 0; -} - -// Set up new genome at initialisation for 1 chromosome per trait -Genome::Genome(int nchromosomes, int nloci, bool d) { - - diploid = d; - if (nchromosomes > 0) nChromosomes = nchromosomes; else nChromosomes = 1; - pChromosome = new Chromosome * [nChromosomes]; - for (int i = 0; i < nChromosomes; i++) { - pChromosome[i] = new Chromosome(nloci); - } - -} - -// Set up new genome at initialisation for trait mapping -Genome::Genome(Species* pSpecies) { - int nloci; - nChromosomes = pSpecies->getNChromosomes(); - diploid = pSpecies->isDiploid(); - pChromosome = new Chromosome * [nChromosomes]; - for (int i = 0; i < nChromosomes; i++) { - nloci = pSpecies->getNLoci(i); - pChromosome[i] = new Chromosome(nloci); - } -} - -// Inherit genome from parent(s) -Genome::Genome(Species* pSpecies, Genome* mother, Genome* father) -{ - genomeData gen = pSpecies->getGenomeData(); - - nChromosomes = mother->nChromosomes; - diploid = mother->diploid; - pChromosome = new Chromosome * [nChromosomes]; - - for (int i = 0; i < nChromosomes; i++) { - pChromosome[i] = new Chromosome(mother->pChromosome[i]->nLoci()); - inherit(mother, 0, i, gen.probMutn, gen.probCrossover, gen.mutationSD); - if (diploid) { - if (father == 0) { // species is hermaphrodite - inherit again from mother - inherit(mother, 1, i, gen.probMutn, gen.probCrossover, gen.mutationSD); - } - else inherit(father, 1, i, gen.probMutn, gen.probCrossover, gen.mutationSD); - } - } - -} - -Genome::~Genome() { - - if (pChromosome == NULL) return; - - for (int i = 0; i < nChromosomes; i++) { - delete pChromosome[i]; - } - delete[] pChromosome; - -} - -//--------------------------------------------------------------------------- - -void Genome::setDiploid(bool dip) { diploid = dip; } -bool Genome::isDiploid(void) { return diploid; } -short Genome::getNChromosomes(void) { return nChromosomes; } - -//--------------------------------------------------------------------------- - -// Inherit from specified parent -void Genome::inherit(const Genome* parent, const short posn, const short chr, - const double probmutn, const double probcross, const double mutnSD) -{ - pChromosome[chr]->inherit(parent->pChromosome[chr], posn, parent->pChromosome[chr]->nLoci(), - probmutn, probcross, mutnSD, diploid); - -} - -void Genome::outGenHeaders(const int rep, const int landNr, const bool xtab) -{ - - if (landNr == -999) { // close file - if (outGenetic.is_open()) { - outGenetic.close(); outGenetic.clear(); - } - return; - } - - string name; - simParams sim = paramsSim->getSim(); - - if (sim.batchMode) { - name = paramsSim->getDir(2) - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) - + "_Land" + Int2Str(landNr) + "_Rep" + Int2Str(rep) + "_Genetics.txt"; - } - else { - name = paramsSim->getDir(2) + "Sim" + Int2Str(sim.simulation) - + "_Rep" + Int2Str(rep) + "_Genetics.txt"; - } - outGenetic.open(name.c_str()); - - outGenetic << "Rep\tYear\tSpecies\tIndID"; - if (xtab) { - for (int i = 0; i < nChromosomes; i++) { - int nloci = pChromosome[i]->nLoci(); - for (int j = 0; j < nloci; j++) { - outGenetic << "\tChr" << i << "Loc" << j << "Allele0"; - if (diploid) outGenetic << "\tChr" << i << "Loc" << j << "Allele1"; - } - } - outGenetic << endl; - } - else { - outGenetic << "\tChromosome\tLocus\tAllele0"; - if (diploid) outGenetic << "\tAllele1"; - outGenetic << endl; - } - -} - -void Genome::outGenetics(const int rep, const int year, const int spnum, - const int indID, const bool xtab) -{ - locus l; - if (xtab) { - outGenetic << rep << "\t" << year << "\t" << spnum << "\t" << indID; - for (int i = 0; i < nChromosomes; i++) { - int nloci = pChromosome[i]->nLoci(); - for (int j = 0; j < nloci; j++) { - l = pChromosome[i]->alleles(j); - outGenetic << "\t" << l.allele[0]; - if (diploid) outGenetic << "\t" << l.allele[1]; - } - } - outGenetic << endl; - } - else { - for (int i = 0; i < nChromosomes; i++) { - int nloci = pChromosome[i]->nLoci(); - for (int j = 0; j < nloci; j++) { - outGenetic << rep << "\t" << year << "\t" << spnum << "\t" - << indID << "\t" << i << "\t" << j; - l = pChromosome[i]->alleles(j); - outGenetic << "\t" << l.allele[0]; - if (diploid) outGenetic << "\t" << l.allele[1]; - outGenetic << endl; - } - } - } -} - -//--------------------------------------------------------------------------- - -// Set up new gene at initialisation for 1 chromosome per trait -void Genome::setGene(const short chr, const short exp, - const double traitval, const double alleleSD) - // NB PARAMETER exp FOR EXPRESSION TYPE IS NOT CURRENTLY USED... -{ - if (chr >= 0 && chr < nChromosomes) { - pChromosome[chr]->initialise(traitval, alleleSD, diploid); - } -} - -// Set up trait at initialisation for trait mapping -void Genome::setTrait(Species* pSpecies, const int trait, - const double traitval, const double alleleSD) -{ - traitAllele allele; - int nalleles = pSpecies->getNTraitAlleles(trait); - int ntraitmaps = pSpecies->getNTraitMaps(); - - int avalue; - double intbase = INTBASE; - if (trait < ntraitmaps) { - for (int i = 0; i < nalleles; i++) { - allele = pSpecies->getTraitAllele(trait, i); - avalue = (int)(pRandom->Normal(traitval, alleleSD) * intbase); - pChromosome[allele.chromo]->initialise(allele.locus, 0, avalue); - if (diploid) { - avalue = (int)(pRandom->Normal(traitval, alleleSD) * intbase); - pChromosome[allele.chromo]->initialise(allele.locus, 1, avalue); - } - } - } - else { // insufficient traits were defined - // alleles cannot be initialised - all individuals have mean phenotype - } - -} - -// Set up trait at initialisation for trait mapping -void Genome::setNeutralLoci(Species* pSpecies, const double alleleSD) -{ - traitAllele allele; - int nneutral = pSpecies->getNNeutralLoci(); - - double avalue; - double intbase = INTBASE; - for (int i = 0; i < nneutral; i++) { - allele = pSpecies->getNeutralAllele(i); - avalue = pRandom->Normal(0.0, alleleSD); - if (avalue > 0.0) - pChromosome[allele.chromo]->initialise(allele.locus, 0, (int)(avalue * intbase + 0.5)); - else - pChromosome[allele.chromo]->initialise(allele.locus, 0, (int)(avalue * intbase - 0.5)); - if (diploid) { - avalue = pRandom->Normal(0.0, alleleSD); - if (avalue > 0.0) - pChromosome[allele.chromo]->initialise(allele.locus, 1, (int)(avalue * intbase + 0.5)); - else - pChromosome[allele.chromo]->initialise(allele.locus, 1, (int)(avalue * intbase - 0.5)); - } - } -} - -// Return the expressed value of a gene when species has one chromosome per trait -double Genome::express(short chr, short expr, short indsex) -{ - double genevalue = 0.0; - genevalue = pChromosome[chr]->meanvalue(diploid); - return genevalue; -} - -// Return the expressed value of a trait when genetic architecture is defined -double Genome::express(Species* pSpecies, short traitnum) -{ - double genevalue = 0.0; - - traitAllele allele; - int nalleles = pSpecies->getNTraitAlleles(traitnum); - if (nalleles > 0) { - for (int i = 0; i < nalleles; i++) { - allele = pSpecies->getTraitAllele(traitnum, i); - genevalue += pChromosome[allele.chromo]->additive(allele.locus, diploid); - } - genevalue /= (double)nalleles; - if (diploid) genevalue /= 2.0; - } - return genevalue; -} - - -locusOK Genome::getAlleles(short chr, short loc) { - locusOK l; - l.allele[0] = l.allele[1] = 0; l.ok = false; - if (chr >= 0 && chr < nChromosomes) { - if (pChromosome[chr] != 0) { - if (loc >= 0 && loc < pChromosome[chr]->nLoci()) { - locus a = pChromosome[chr]->alleles(loc); - l.allele[0] = a.allele[0]; l.allele[1] = a.allele[1]; l.ok = true; - } - } - } - - return l; -} - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - diff --git a/Genome.h b/Genome.h deleted file mode 100644 index 4f01ede..0000000 --- a/Genome.h +++ /dev/null @@ -1,173 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - -#ifndef GenomeH -#define GenomeH - -#include -#include - -#include "Parameters.h" -#include "Species.h" - -#define INTBASE 100.0; // to convert integer alleles into continuous traits - -struct locus { short allele[2]; }; -struct locusOK { short allele[2]; bool ok; }; - -//--------------------------------------------------------------------------- - -class Chromosome { - -public: - Chromosome(int); - ~Chromosome(); - short nLoci(void); - double additive( // Return trait value on normalised genetic scale - const bool // diploid - ); - double meanvalue( // Return trait value on normalised genetic scale - const bool // diploid - ); - double additive( // Return trait value on normalised genetic scale - const short, // locus - const bool // diploid - ); - locus alleles( // Return allele values at a specified locus - const int // position of locus on chromosome - ); - void initialise( // Set up chromosome at simulation initialisation - const double, // normalised phenotypic trait value - const double, // s.d. of allelic variance (genetic scale) - const bool // diploid - ); - void initialise( // Set up specified locus at simulation initialisation - const short, // locus - const short, // position: 0 from mother, 1 from father - const int // allele value - ); - void inherit( // Inherit chromosome from specified parent - const Chromosome*, // pointer to parent's chromosome - const short, // position: 0 from mother, 1 from father - const short, // no. of loci - const double, // mutation probability - const double, // crossover probability - const double, // s.d. of mutation magnitude (genetic scale) - const bool // diploid - ); - -protected: - -private: - short nloci; - locus* pLoci; - -}; - -//--------------------------------------------------------------------------- - -class Genome { - -public: - Genome(); - Genome(int, int, bool); - Genome(Species*); - Genome(Species*, Genome*, Genome*); - ~Genome(); - void setGene( // Set up new gene at initialisation for 1 chromosome per trait - const short, // chromosome number - const short, // expression type (NOT CURRENTLY USED) - const double, // normalised trait value - const double // s.d. of allelic variance - ); - void setTrait( // Set up trait at initialisation for trait mapping - Species*, // pointer to Species - const int, // trait number - const double, // normalised trait value - const double // s.d. of allelic variance - ); - void setNeutralLoci( // Set up neutral loci at initialisation - Species*, // pointer to Species - const double // s.d. of allelic variance - ); - double express( - // Return the expressed value of a gene when species has one chromosome per trait - short, // chromosome number - short, // expression type (NOT CURRENTLY USED) - short // individual's sex (NOT CURRENTLY USED) - ); - double express( - // Return the expressed value of a trait when genetic architecture is defined - Species*, // pointer to Species - short // trait number - ); - locusOK getAlleles( // Get allele values at a specified locus - short, // chromosome number - short // locus position on chromosome - ); - // SCFP NEW DECLARATIONS - void setDiploid(bool); - bool isDiploid(void); - void inherit( // Inherit from specified parent - const Genome*, // pointer to parent's genome - const short, // position: 0 from mother, 1 from father - const short, // chromasome number - const double, // mutation probability - const double, // crossover probability - const double // s.d. of mutation magnitude (genetic scale) - ); - short getNChromosomes(void); - void outGenHeaders( - const int, // replicate - const int, // landscape number - const bool // output as cross table? - ); - void outGenetics( - const int, // replicate - const int, // year - const int, // species number - const int, // individual ID - const bool // output as cross table? - ); - - -private: - short nChromosomes; // no. of chromosomes - bool diploid; - Chromosome** pChromosome; - -}; - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - -extern paramSim* paramsSim; -extern RSrandom* pRandom; - -#if RSDEBUG -extern ofstream DEBUGLOG; -extern ofstream MUTNLOG; -extern void DebugGUI(string); -#endif - -//--------------------------------------------------------------------------- - -#endif diff --git a/Individual.h b/Individual.h deleted file mode 100644 index bdc4ecb..0000000 --- a/Individual.h +++ /dev/null @@ -1,312 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -/*------------------------------------------------------------------------------ - -RangeShifter v2.0 Individual - -Implements the Individual class - -Various optional attributes (genes for traits, movement parameters, etc.) are -allocated dynamically and accessed by pointers if required. - -For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. -and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. -Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 - -Authors: Greta Bocedi & Steve Palmer, University of Aberdeen - -Last updated: 26 October 2021 by Steve Palmer - -------------------------------------------------------------------------------*/ - -#ifndef IndividualH -#define IndividualH - - -#include -#include -using namespace std; - -#include "Parameters.h" -#include "Species.h" -#include "Landscape.h" -#include "Patch.h" -#include "Cell.h" -#include "Genome.h" - -#define NODATACOST 100000 // cost to use in place of nodata value for SMS -#define ABSNODATACOST 100 // cost to use in place of nodata value for SMS - // when boundaries are absorbing - -//--------------------------------------------------------------------------- - -struct indStats { - short stage; short sex; short age; short status; short fallow; - bool isDeveloping; -}; -struct pathData { // to hold path data common to SMS and CRW models - int year, total, out; // nos. of steps - Patch* pSettPatch; // pointer to most recent patch tested for settlement - short settleStatus; // whether ind may settle in current patch - // 0 = not set, 1 = debarred through density dependence rule - // 2 = OK to settle subject to finding a mate -#if RS_RCPP - short pathoutput; -#endif -}; -struct pathSteps { // nos. of steps for movement model - int year, total, out; -}; -struct settlePatch { - Patch* pSettPatch; short settleStatus; -}; -struct crwParams { // to hold data for CRW movement model - float prevdrn; // direction of previous step (UNITS) - float xc,yc; // continuous cell co-ordinates - float stepL; // phenotypic step length (m) - float rho; // phenotypic step correlation coefficient -}; -struct array3x3d { double cell[3][3]; }; -struct movedata { float dist; float cost; }; -struct smsdata { - locn prev; // location of previous cell - locn goal; // location of goal - float dp; // directional persistence - float gb; // goal bias - float alphaDB; // dispersal bias decay rate - int betaDB; // dispersal bias decay inflection point (no. of steps) -}; - -class Individual { - -public: - static int indCounter; // used to create ID, held by class, not members of class - Individual( // Individual constructor - Cell*, // pointer to Cell - Patch*, // pointer to patch - short, // stage - short, // age - short, // reproduction interval (no. of years/seasons between breeding attempts) - float, // probability that sex is male - bool, // TRUE for a movement model, FALSE for kernel-based transfer - short // movement type: 1 = SMS, 2 = CRW - ); - ~Individual(void); - void setGenes( // Set genes for individual variation from species initialisation parameters - Species*, // pointer to Species - int // Landscape resolution - ); - void setGenes( // Inherit genome from parents - Species*, // pointer to Species - Individual*, // pointer to mother - Individual*, // pointer to father (must be 0 for an asexual Species) - int // Landscape resolution - ); - void setEmigTraits( // Set phenotypic emigration traits - Species*, // pointer to Species - short, // location of emigration genes on genome - short, // number of emigration genes - bool // TRUE if emigration is sex-dependent - ); - emigTraits getEmigTraits(void); // Get phenotypic emigration traits - - void setKernTraits( // Set phenotypic transfer by kernel traits - Species*, // pointer to Species - short, // location of kernel genes on genome - short, // number of kernel genes - int, // Landscape resolution - bool // TRUE if transfer is sex-dependent - ); - trfrKernTraits getKernTraits(void); // Get phenotypic transfer by kernel traits - - void setSMSTraits( // Set phenotypic transfer by SMS traits - Species*, // pointer to Species - short, // location of SMS genes on genome - short, // number of SMS genes - bool // TRUE if transfer is sex-dependent - ); - trfrSMSTraits getSMSTraits(void); // Get phenotypic transfer by SMS traits - void setCRWTraits( // Set phenotypic transfer by CRW traits - Species*, // pointer to Species - short, // location of CRW genes on genome - short, // number of CRW genes - bool // TRUE if transfer is sex-dependent - ); - trfrCRWTraits getCRWTraits(void); // Get phenotypic transfer by CRW traits - - void setSettTraits( // Set phenotypic settlement traits - Species*, // pointer to Species - short, // location of settlement genes on genome - short, // number of settlement genes - bool // TRUE if settlement is sex-dependent - ); - settleTraits getSettTraits(void); // Get phenotypic settlement traits - - // Identify whether an individual is a potentially breeding female - - // if so, return her stage, otherwise return 0 - int breedingFem(void); - int getId(void); - int getSex(void); - int getStatus(void); - indStats getStats(void); - Cell* getLocn( // Return location (as pointer to Cell) - const short // option: 0 = get natal locn, 1 = get current locn - ); // - Patch* getNatalPatch(void); - void setYearSteps(int); - pathSteps getSteps(void); - settlePatch getSettPatch(void); - void setSettPatch(const settlePatch); - void setStatus(short); - void developing(void); - void develop(void); - void ageIncrement( // Age by one year - short // maximum age - if exceeded, the Individual dies - ); - void incFallow(void); // Inrement no. of reproductive seasons since last reproduction - void resetFallow(void); - void moveto( // Move to a specified neighbouring cell - Cell* // pointer to the new cell - ); - // Move to a new cell by sampling a dispersal distance from a single or double - // negative exponential kernel - // Returns 1 if still dispersing (including having found a potential patch), otherwise 0 - int moveKernel( - Landscape*, // pointer to Landscape - Species*, // pointer to Species - const short, // reproduction type (see Species) - const bool // absorbing boundaries? - ); - // Make a single movement step according to a mechanistic movement model - // Returns 1 if still dispersing (including having found a potential patch), otherwise 0 - int moveStep( - Landscape*, // pointer to Landscape - Species*, // pointer to Species - const short, // landscape change index - const bool // absorbing boundaries? - ); - movedata smsMove( // Move to a neighbouring cell according to the SMS algorithm - Landscape*, // pointer to Landscape - Species*, // pointer to Species - const short, // landscape change index - const bool, // TRUE if still in (or returned to) natal patch - const bool, // individual variability? - const bool // absorbing boundaries? - ); - array3x3d getSimDir( // Weight neighbouring cells on basis of current movement direction - const int, // current x co-ordinate - const int, // current y co-ordinate - const float // directional persistence value - ); - array3x3d getGoalBias( // Weight neighbouring cells on basis of goal bias - const int, // current x co-ordinate - const int, // current y co-ordinate - const int, // goal type: 0 = none, 1 = towards goal (NOT IMPLEMENTED), 2 = dispersal bias - const float // GOAL BIAS VALUE - ); - array3x3d calcWeightings( // Calculate weightings for neighbouring cells - const double, // base for power-law (directional persistence or goal bias value) - const double // direction in which lowest (unit) weighting is to be applied - ); - array3x3f getHabMatrix( // Weight neighbouring cells on basis of (habitat) costs - Landscape*, // pointer to Landscape - Species*, // pointer to Species - const int, // current x co-ordinate - const int, // current y co-ordinate - const short, // perceptual range (cells) - const short, // perceptual range evaluation method (see Species) - const short, // landscape change index - const bool // absorbing boundaries? - ); - void outGenetics( // Write records to genetics file - const int, // replicate - const int, // year - const int, // species number - const int, // landscape number - const bool // output as cross table? - ); -#if RS_RCPP - void outMovePath( // Write records to movement paths file - const int // year - ); -#endif - -private: - int indId; - short stage; - short sex; - short age; - short status; // 0 = initial status in natal patch / philopatric recruit - // 1 = disperser - // 2 = disperser awaiting settlement in possible suitable patch - // 3 = waiting between dispersal events - // 4 = completed settlement - // 5 = completed settlement in a suitable neighbouring cell - // 6 = died during transfer by failing to find a suitable patch - // (includes exceeding maximum number of steps or crossing - // absorbing boundary) - // 7 = died during transfer by constant, step-dependent, - // habitat-dependent or distance-dependent mortality - // 8 = failed to survive annual (demographic) mortality - // 9 = exceeded maximum age - short fallow; // reproductive seasons since last reproduction - bool isDeveloping; - Cell *pPrevCell; // pointer to previous Cell - Cell *pCurrCell; // pointer to current Cell - Patch *pNatalPatch; // pointer to natal Patch - emigTraits *emigtraits; // pointer to emigration traits - trfrKernTraits *kerntraits; // pointers to transfer by kernel traits - pathData *path; // pointer to path data for movement model - crwParams *crw; // pointer to CRW traits and data - smsdata *smsData; // pointer to variables required for SMS - settleTraits *setttraits; // pointer to settlement traits - std::queue memory; // memory of last N squares visited for SMS - - Genome *pGenome; - -}; - - -//--------------------------------------------------------------------------- - -double cauchy(double location, double scale) ; -double wrpcauchy (double location, double rho = exp(double(-1))); - -extern RSrandom *pRandom; - -#if RSDEBUG -extern ofstream DEBUGLOG; -#endif - -#if RS_RCPP -extern ofstream outMovePaths; -#endif - -#if RSDEBUG -void testIndividual(); -#endif - -//--------------------------------------------------------------------------- -#endif // IndividualH diff --git a/LICENSE b/LICENSE index 94a9ed0..f288702 100644 --- a/LICENSE +++ b/LICENSE @@ -1,7 +1,7 @@ GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 - Copyright (C) 2007 Free Software Foundation, Inc. + Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -645,7 +645,7 @@ the "copyright" line and a pointer to where the full notice is found. GNU General Public License for more details. You should have received a copy of the GNU General Public License - along with this program. If not, see . + along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. @@ -664,11 +664,11 @@ might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see -. +. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read -. +. diff --git a/Patch.cpp b/Patch.cpp deleted file mode 100644 index 60421c4..0000000 --- a/Patch.cpp +++ /dev/null @@ -1,358 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -//--------------------------------------------------------------------------- - -#include "Patch.h" -//--------------------------------------------------------------------------- - -//--------------------------------------------------------------------------- - -Patch::Patch(int seqnum,int num) -{ -patchSeqNum = seqnum; patchNum = num; nCells = 0; -xMin = yMin = 999999999; xMax = yMax = 0; x = y = 0; -subCommPtr = 0; -localK = 0.0; -for (int sex = 0; sex < NSEXES; sex++) { - nTemp[sex] = 0; -} -changed = false; -} - -Patch::~Patch() { -cells.clear(); -popns.clear(); -} - -int Patch::getSeqNum(void) { return patchSeqNum; } - -int Patch::getPatchNum(void) { return patchNum; } - -int Patch::getNCells(void) { return nCells; } - -patchLimits Patch::getLimits(void) { -patchLimits p; -p.xMin = xMin; p.xMax = xMax; p.yMin = yMin; p.yMax = yMax; -return p; -} - -// Does the patch fall (partially) within a specified rectangle? -bool Patch::withinLimits(patchLimits rect){ -locn loc; -if (xMin <= rect.xMax && xMax >= rect.xMin && yMin <= rect.yMax && yMax >= rect.yMin) { - // patch is within the rectangle UNLESS it is irregular in shape and lies at a corner - // of the rectangle - if ((xMin >= rect.xMin && xMax <= rect.xMax) - || (yMin >= rect.yMin && yMax <= rect.yMax)) { - // patch lies within or along an edge of the initialistaion rectangle - return true; - } - else { - // check for any cell of the patch lying within the rectangle - int ncells = (int)cells.size(); - for (int i = 0; i < ncells; i++) { - loc = getCellLocn(i); - if (loc.x >= rect.xMin && loc.x <= rect.xMax - && loc.y >= rect.yMin && loc.y <= rect.yMax) { - // cell lies within the rectangle - return true; - } - } - } - } -return false; -} - -// Reset minimum and maximum co-ordinates of the patch if it has been changed -void Patch::resetLimits(void) { -if (changed) { - // remove any deleted cells - std::vector newcells; // for all retained and added cells - int ncells = (int)cells.size(); - for (int i = 0; i < ncells; i++) { - if (cells[i] != NULL) { - newcells.push_back(cells[i]); - } - } - cells.clear(); - cells = newcells; - // reset patch limits - locn loc; - xMin = yMin = 999999999; xMax = yMax = 0; - ncells = (int)cells.size(); - for (int i = 0; i < ncells; i++) { - loc = getCellLocn(i); - if (loc.x < xMin) xMin = loc.x; - if (loc.x > xMax) xMax = loc.x; - if (loc.y < yMin) yMin = loc.y; - if (loc.y > yMax) yMax = loc.y; - } - changed = false; -} -} - -// Add a cell to the patch -void Patch::addCell(Cell* pCell,int x,int y) { - cells.push_back(pCell); - nCells++; - if (x < xMin) xMin = x; - if (x > xMax) xMax = x; - if (y < yMin) yMin = y; - if (y > yMax) yMax = y; -} - -// Calculate the total carrying capacity (no. of individuals) and -// centroid co-ordinates of the patch -void Patch::setCarryingCapacity(Species *pSpecies,patchLimits landlimits, - float epsGlobal,short nHab,short rasterType,short landIx,bool gradK) { -envStochParams env = paramsStoch->getStoch(); -//Cell *pCell; -locn loc; -int xsum,ysum; -short hx; -float k,q,envval; - -localK = 0.0; // no. of suitable cells (unadjusted K > 0) in the patch -int nsuitable = 0; -double mean; - -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " xMin=" << xMin << " yMin=" << yMin << " xMax=" << xMax << " yMax=" << yMax -// << endl; -#endif - -if (xMin > landlimits.xMax || xMax < landlimits.xMin -|| yMin > landlimits.yMax || yMax < landlimits.yMin) { - // patch lies wholely outwith current landscape limits - // NB the next statement is unnecessary, as localK has been set to zero above - // retained only for consistency in standard variant - localK = 0.0; -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " localK=" << localK -// << endl; -#endif - return; -} - -int ncells = (int)cells.size(); -xsum = ysum = 0; -for (int i = 0; i < ncells; i++) { - if (gradK) // gradient in carrying capacity - envval = cells[i]->getEnvVal(); // environmental gradient value - else envval = 1.0; // no gradient effect - if (env.stoch && env.inK) { // environmental stochasticity in K - if (env.local) { -// pCell = getRandomCell(); -// if (pCell != 0) envval += pCell->getEps(); - envval += cells[i]->getEps(); - } - else { // global stochasticity - envval += epsGlobal; - } - } - switch (rasterType) { - case 0: // habitat codes - hx = cells[i]->getHabIndex(landIx); - k = pSpecies->getHabK(hx); - if (k > 0.0) { - nsuitable++; - localK += envval * k; - } - break; - case 1: // cover % - k = 0.0; - for (int j = 0; j < nHab; j++) { // loop through cover layers - q = cells[i]->getHabitat(j); - k += q * pSpecies->getHabK(j) / 100.0f; - } - if (k > 0.0) { - nsuitable++; - localK += envval * k; - } - break; - case 2: // habitat quality - q = cells[i]->getHabitat(landIx); - if (q > 0.0) { - nsuitable++; - localK += envval * pSpecies->getHabK(0) * q / 100.0f; - } - break; - } -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " i=" << i << " hx=" << hx << " q=" << q << " k=" << k << " localK=" << localK -// << endl; -#endif - loc = cells[i]->getLocn(); - xsum += loc.x; ysum += loc.y; -} -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " epsGlobal=" << epsGlobal << " localK=" << localK -// << endl; -#endif -// calculate centroid co-ordinates -if (ncells > 0) { - mean = (double)xsum / (double)ncells; - x = (int)(mean + 0.5); - mean = (double)ysum / (double)ncells; - y = (int)(mean + 0.5); -} -if (env.stoch && env.inK) { // environmental stochasticity in K - // apply min and max limits to K over the whole patch - // NB limits have been stored as N/cell rather than N/ha - float limit; - limit = pSpecies->getMinMax(0) * (float)nsuitable; - if (localK < limit) localK = limit; -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " limit=" << limit << " localK=" << localK -// << endl; -#endif - limit = pSpecies->getMinMax(1) * (float)nsuitable; - if (localK > limit) localK = limit; -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " limit=" << limit << " localK=" << localK -// << endl; -#endif -} -#if RSDEBUG -//DEBUGLOG << "Patch::setCarryingCapacity(): patchNum=" << patchNum -// << " localK=" << localK -// << endl; -#endif -} - - -float Patch::getK(void) { return localK; } - -// Return co-ordinates of a specified cell -locn Patch::getCellLocn(int ix) { -locn loc; loc.x = -666; loc.y = -666; -int ncells = (int)cells.size(); -if (ix >= 0 && ix < ncells) { - loc = cells[ix]->getLocn(); -} -return loc; -} -// Return pointer to a specified cell -Cell* Patch::getCell(int ix) { -int ncells = (int)cells.size(); -if (ix >= 0 && ix < ncells) return cells[ix]; -else return 0; -} -// Return co-ordinates of patch centroid -locn Patch::getCentroid(void) { -locn loc; loc.x = x; loc.y = y; -return loc; -} - -// Select a Cell within the Patch at random, and return pointer to it -// For a cell-based model, this will be the only Cell -Cell* Patch::getRandomCell(void) { -Cell *pCell = 0; -int ix; -int ncells = (int)cells.size(); -if (ncells > 0) { - if (ncells == 1) ix = 0; - else ix = pRandom->IRandom(0,ncells-1); - pCell = cells[ix]; -} -return pCell; -} - -// Remove a cell from the patch -void Patch::removeCell(Cell* pCell) { -int ncells = (int)cells.size(); -for (int i = 0; i < ncells; i++) { - if (pCell == cells[i]) { - cells[i] = NULL; i = ncells; - nCells--; - changed = true; - } -} -} - -void Patch::setSubComm(intptr sc) -{ subCommPtr = sc; } - -// Get pointer to corresponding Sub-community (cast as an integer) -intptr Patch::getSubComm(void) -{ return subCommPtr; } - -void Patch::addPopn(patchPopn pop) { -popns.push_back(pop); -} - -// Return pointer (cast as integer) to the Population of the specified Species -intptr Patch::getPopn(intptr sp) -{ -int npops = (int)popns.size(); -for (int i = 0; i < npops; i++) { - if (popns[i].pSp == sp) return popns[i].pPop; -} -return 0; -} - -void Patch::resetPopn(void) { -popns.clear(); -} - -void Patch::resetPossSettlers(void) { -for (int sex = 0; sex < NSEXES; sex++) { - nTemp[sex] = 0; -} -} - -// Record the presence of a potential settler within the Patch -void Patch::incrPossSettler(Species *pSpecies,int sex) { -#if RSDEBUG -//DEBUGLOG << "Patch::incrPossSettler(): 5555: patchNum = " << patchNum -// << " sex = " << sex << endl; -#endif -// NOTE: THE FOLLOWING OPERATION WILL NEED TO BE MADE SPECIES-SPECIFIC... -if (sex >= 0 && sex < NSEXES) { - nTemp[sex]++; -} -} - -// Get number of a potential settlers within the Patch -int Patch::getPossSettlers(Species *pSpecies,int sex) { -#if RSDEBUG -//DEBUGLOG << "Patch::getPossSettlers(): 5555: patchNum = " << patchNum -// << " sex = " << sex << endl; -#endif -// NOTE: THE FOLLOWING OPERATION WILL NEED TO BE MADE SPECIES-SPECIFIC... -if (sex >= 0 && sex < NSEXES) return nTemp[sex]; -else return 0; -} - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - - - diff --git a/Patch.h b/Patch.h deleted file mode 100644 index 4095908..0000000 --- a/Patch.h +++ /dev/null @@ -1,174 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -/*------------------------------------------------------------------------------ - -RangeShifter v2.0 Patch - -Implements the class: Patch - -A patch is a collection of one or more Cells in the the gridded Landscape, -which together provide the area in which a single demographic unit of a Species, -i.e. a Population, can reproduce. One or more Populations (of different Species) -form a Sub-community associated with the Patch. - -There is no requirement that all the Cells be adjacent, although in practice -that would usually be the case. - -Each Patch must have a unique positive integer id number supplied by the user, -and the matrix, i.e. any part of the landscape which is not a breeding patch, -is represented by Patch 0. However, as patch numbers need not be sequential, -an internal sequential number is also applied. - -For a 'cell-based model', the user supplies no patch numbers, and a separate -Patch is generated internally for each Cell, i.e. the 'cell-based model' is a -special case of the 'patch-based model' in which each Patch has a single Cell. -Moreover, there is also the 'matrix' Patch 0, which has no cells, but which -holds the disperser population whilst its Individuals are in transit. - -In a true patch-based model, each Patch hold a list of its constituent Cells, -EXCEPT for the matrix Patch 0. This is because that list would be extremely -long for a very large landscape in which suitable patches are small and/or rare, -and removing Cells from it if the landscape is dynamic would be inefficient. - -For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. -and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. -Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 - -Authors: Greta Bocedi & Steve Palmer, University of Aberdeen - -Last updated: 25 June 2021 by Steve Palmer - -------------------------------------------------------------------------------*/ - -#ifndef PatchH -#define PatchH - -#include -using namespace std; - -#include "Parameters.h" -#include "Cell.h" -#include "Species.h" - -//--------------------------------------------------------------------------- - -struct patchLimits { - int xMin,xMax,yMin,yMax; -}; -struct patchPopn { - intptr pSp,pPop; // pointers to Species and Population cast as integers -}; - -class Patch{ -public: - Patch( - int, // internal sequential number - int // patch id number - ); - ~Patch(); - int getSeqNum(void); - int getPatchNum(void); - int getNCells(void); - patchLimits getLimits(void); // Returns the minimum and maximum co-ordinates of the patch - bool withinLimits( // Does the patch fall (partially) within a specified rectangle? - patchLimits // structure holding the SW and NE co-ordinates of the rectangle - ); - void resetLimits(void); // Reset minimum and maximum co-ordinates of the patch - void addCell( - Cell*, // pointer to the Cell to be added to the Patch - int,int // x (column) and y (row) co-ordinates of the Cell - ); - locn getCellLocn( // Return co-ordinates of a specified cell - int // index no. of the Cell within the vector cells - ); - Cell* getCell( // Return pointer to a specified cell - int // index no. of the Cell within the vector cells - ); - locn getCentroid(void); // Return co-ordinates of patch centroid - void removeCell( - Cell* // pointer to the Cell to be removed from the Patch - ); - Cell* getRandomCell(void); - void setSubComm( - intptr // pointer to the Sub-community cast as an integer - ); - intptr getSubComm(void); - void addPopn( - patchPopn // structure holding pointers to Species and Population cast as integers - ); - intptr getPopn( // return pointer (cast as integer) to the Population of the Species - intptr // pointer to Species cast as integer - ); - void resetPopn(void); - void resetPossSettlers(void); - void incrPossSettler( // Record the presence of a potential settler within the Patch - Species*, // pointer to the Species - int // sex of the settler - ); - int getPossSettlers( // Get number of a potential settlers within the Patch - Species*, // pointer to the Species - int // sex of the settlers - ); - void setCarryingCapacity( // Calculate total Patch carrying capacity (no. of inds) - Species*, // pointer to the Species - patchLimits, // current min and max limits of landscape - float, // global stochasticity value (epsilon) for the current year - short, // no. of habitat classes in the Landscape - short, // rasterType (see Landscape) - short, // landscape change index (always zero if not dynamic) - bool // TRUE if there is a gradient in carrying capacity across the Landscape - ); - float getK(void); - // dummy function for batch version - void drawCells(float,int,rgb); - - private: - int patchSeqNum;// sequential patch number - patch 0 is reserved for the inter-patch matrix - int patchNum; // patch number as supplied by the user (not forced to be sequential) - int nCells; // no. of cells in the patch - int xMin,xMax,yMin,yMax; // min and max cell co-ordinates - int x,y; // centroid co-ordinates (approx.) - intptr subCommPtr; // pointer (cast as integer) to sub-community associated with the patch - // NOTE: FOR MULTI-SPECIES MODEL, PATCH WILL NEED TO STORE K FOR EACH SPECIES - float localK; // patch carrying capacity (individuals) - bool changed; -// NOTE: THE FOLLOWING ARRAY WILL NEED TO BE MADE SPECIES-SPECIFIC... - short nTemp[NSEXES]; // no. of potential settlers in each sex - - std::vector cells; - std::vector popns; - -}; - -//--------------------------------------------------------------------------- - -extern paramStoch *paramsStoch; -extern RSrandom *pRandom; - -#if RSDEBUG -extern ofstream DEBUGLOG; -#endif - -#endif diff --git a/Population.h b/Population.h deleted file mode 100644 index fd1fa66..0000000 --- a/Population.h +++ /dev/null @@ -1,245 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -/*------------------------------------------------------------------------------ - -RangeShifter v2.0 Population - -Implements the Population class - -There is ONE instance of a Population for each Species within each SubCommunity -(including the matrix). The Population holds a list of all the Individuals in -the Population. - -The matrix Population(s) hold(s) Individuals which are currently in the process -of transfer through the matrix. - -For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. -and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. -Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 - -Authors: Greta Bocedi & Steve Palmer, University of Aberdeen - -Last updated: 22 January 2022 by Steve Palmer - -------------------------------------------------------------------------------*/ - -#ifndef PopulationH -#define PopulationH - -#include -#include -using namespace std; - -#include "Parameters.h" -#include "Individual.h" -#include "Species.h" -#include "Landscape.h" -#include "Patch.h" -#include "Cell.h" - -//--------------------------------------------------------------------------- - -struct popStats { - Species *pSpecies; Patch *pPatch; int spNum,nInds,nNonJuvs,nAdults; bool breeding; -}; -struct disperser { - Individual *pInd; Cell *pCell; bool yes; -}; -struct traitsums { // sums of trait genes for dispersal - int ninds[NSEXES]; // no. of individuals - double sumD0[NSEXES]; // sum of maximum emigration probability - double ssqD0[NSEXES]; // sum of squares of maximum emigration probability - double sumAlpha[NSEXES]; // sum of slope of emigration dens-dep reaction norm - double ssqAlpha[NSEXES]; // sum of squares of slope of emigration den-dep reaction norm - double sumBeta[NSEXES]; // sum of inflection point of emigration reaction norm - double ssqBeta[NSEXES]; // sum of squares of inflection point of emigration reaction norm - double sumDist1[NSEXES]; // sum of kernel I mean - double ssqDist1[NSEXES]; // sum of squares of kernel I mean - double sumDist2[NSEXES]; // sum of kernel II mean - double ssqDist2[NSEXES]; // sum of squares of kernel II mean - double sumProp1[NSEXES]; // sum of propn using kernel I - double ssqProp1[NSEXES]; // sum of squares of propn using kernel I - double sumDP[NSEXES]; // sum of SMS directional persistence - double ssqDP[NSEXES]; // sum of squares of SMS directional persistence - double sumGB[NSEXES]; // sum of SMS goal bias - double ssqGB[NSEXES]; // sum of squares of SMS goal bias - double sumAlphaDB[NSEXES]; // sum of SMS dispersal bias decay rate - double ssqAlphaDB[NSEXES]; // sum of squares of SMS dispersal bias decay rate - double sumBetaDB[NSEXES]; // sum of SMS dispersal bias decay infl. pt. - double ssqBetaDB[NSEXES]; // sum of squares of SMS dispersal bias decay infl. pt. - double sumStepL[NSEXES]; // sum of CRW step length - double ssqStepL[NSEXES]; // sum of squares of CRW step length - double sumRho[NSEXES]; // sum of CRW correlation coefficient - double ssqRho[NSEXES]; // sum of squares of CRW correlation coefficient - double sumS0[NSEXES]; // sum of maximum settlement probability - double ssqS0[NSEXES]; // sum of squares of maximum settlement probability - double sumAlphaS[NSEXES]; // sum of slope of settlement den-dep reaction norm - double ssqAlphaS[NSEXES]; // sum of squares of slope of settlement den-dep reaction norm - double sumBetaS[NSEXES]; // sum of inflection point of settlement reaction norm - double ssqBetaS[NSEXES]; // sum of squares of inflection point of settlement reaction norm -}; - -class Population { - -public: - Population(void); // default constructor - Population( // constructor for a Population of a specified size - Species*, // pointer to Species - Patch*, // pointer to Patch - int, // no. of Individuals - int // Landscape resolution - ); - ~Population(void); - traitsums getTraits(Species*); - popStats getStats(void); - Species* getSpecies(void); - int getNInds(void); - int totalPop(void); - int stagePop( // return no. of Individuals in a specified stage - int // stage - ); - void extirpate(void); // Remove all individuals - void reproduction( - const float, // local carrying capacity - const float, // effect of environmental gradient and/or stochasticty - const int // Landscape resolution - ); - // Following reproduction of ALL species, add juveniles to the population - void fledge(void); - void emigration( // Determine which individuals will disperse - float // local carrying capacity - ); - void allEmigrate(void); // All individuals emigrate after patch destruction - // If an individual has been identified as an emigrant, remove it from the Population - disperser extractDisperser( - int // index no. to the Individual in the inds vector - ); - // For an individual identified as being in the matrix population: - // if it is a settler, return its new location and remove it from the current population - // otherwise, leave it in the matrix population for possible reporting before deletion - disperser extractSettler( - int // index no. to the Individual in the inds vector - ); - void recruit( // Add a specified individual to the population - Individual* // pointer to Individual - ); -#if RS_RCPP - int transfer( // Executed for the Population(s) in the matrix only - Landscape*, // pointer to Landscape - short, // landscape change index - short // year - ); - // Determine whether there is a potential mate present in a patch which a potential - // settler has reached - bool matePresent( - Cell*, // pointer to the Cell which the potential settler has reached - short // sex of the required mate (0 = female, 1 = male) - ); -#else - int transfer( // Executed for the Population(s) in the matrix only - Landscape*, // pointer to Landscape - short // landscape change index - ); - // Determine whether there is a potential mate present in a patch which a potential - // settler has reached - bool matePresent( - Cell*, // pointer to the Cell which the potential settler has reached - short // sex of the required mate (0 = female, 1 = male) - ); -#endif // RS_RCPP - // Determine survival and development and record in individual's status code - // Changes are NOT applied to the Population at this stage - void survival0( - float, // local carrying capacity - short, // option0: 0 - stage 0 (juveniles) only - // 1 - all stages - // 2 - stage 1 and above (all non-juveniles) - short // option1: 0 - development only (when survival is annual) - // 1 - development and survival - // 2 - survival only (when survival is annual) - ); - void survival1(void); // Apply survival changes to the population - void ageIncrement(void); - bool outPopHeaders( // Open population file and write header record - int, // Landscape number (-999 to close the file) - bool // TRUE for a patch-based model, FALSE for a cell-based model - ); - void outPopulation( // Write record to population file - int, // replicate - int, // year - int, // generation - float, // epsilon - global stochasticity value - bool, // TRUE for a patch-based model, FALSE for a cell-based model - bool, // TRUE to write environmental data - bool // TRUE if there is a gradient in carrying capacity - ); - - void outIndsHeaders( // Open individuals file and write header record - int, // replicate - int, // Landscape number (-999 to close the file) - bool // TRUE for a patch-based model, FALSE for a cell-based model - ); - void outIndividual( // Write records to individuals file - Landscape*, // pointer to Landscape - int, // replicate - int, // year - int, // generation - int // Patch number - ); - void outGenetics( // Write records to genetics file - const int, // replicate - const int, // year - const int // landscape number - ); - void clean(void); // Remove zero pointers to dead or dispersed individuals - -private: - short nStages; - short nSexes; - Species *pSpecies; // pointer to the species - Patch *pPatch; // pointer to the patch - int nInds[NSTAGES][NSEXES]; // no. of individuals in each stage/sex - - std::vector inds; // all individuals in population except ... - std::vector juvs; // ... juveniles until reproduction of ALL species - // has been completed - -}; - -//--------------------------------------------------------------------------- - -extern paramGrad *paramsGrad; -extern paramStoch *paramsStoch; -extern paramInit *paramsInit; -extern paramSim *paramsSim; -extern RSrandom *pRandom; - -#if RSDEBUG -extern ofstream DEBUGLOG; -#endif - -//--------------------------------------------------------------------------- -#endif - diff --git a/README.md b/README.md index 832f354..7d04a8b 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,69 @@ -# RangeShifter core code +# RangeShiftR -This repo contains the core simulation code for RangeShifter v2.0 and is not meant to be compiled or run on its own. +The RangeShiftR package implements the RangeShifter simulation platform for R. - +[RangeShifter](https://rangeshifter.github.io/) +is a state-of-the-art eco-evolutionary modelling platform that is becoming +increasingly used worldwide for both theoretical and applied purposes +[(Bocedi et al. 2014)](https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.12162). -If you are only interested in using RangeShifter, you can ignore this and head to the repo of one of the interfaces: +RangeShifter is a spatially-explicit, individual-based simulation platform that +allows modelling species’ range dynamics, such as expansion and shifting, and +patch connectivity by linking complex local population dynamics and dispersal +behaviour, while also taking into account inter-individual variability and +evolutionary processes. RangeShifter is highly flexible in terms of the spatial +resolution and extent, and regarding the complexity of the considered ecological +processes. Due to its modular structure, the level of detail in demographic and +dispersal processes can be easily adapted to different research questions and +available data. -- [WIP] RangeShifter GUI -- [RangeShiftR](https://github.com/RangeShifter/RangeShiftR-pkg) +## Installation -- [RangeShifter-batch](https://github.com/RangeShifter/RangeShifter_batch) +RangeShiftR is only available from this github repository. +(It may move to CRAN in the future.) -## Usage: git subtree +RangeShiftR has to be built from source and requires the package `Rcpp` as +well as a functional C++ compiler toolchain. -In order to ensure that the same version of RangeShifter's core code is used by all three interfaces (RangeShiftR, RangeShifter-batch and the GUI), each interface repo keeps a copy of RScore as a git subtree. In this section, we describe how to use the git subtrees to update the subfolder and copy this repo anew. - -First, in a local clone of one of the interface repos, add a remote named `RScore` pointing to the RScore repo. This will be convenient as a shortcut for git subtree commands. - -```bash -git remote add RScore https://github.com/RangeShifter/RScore.git +```r +# Install RangeShiftR from GitHub: +devtools::install_github("RangeShifter/RangeShiftR-pkg", ref="main", subdir="RangeShiftR") ``` -### Pulling new changes - -To update the RScore subfolder with new changes made to the RScore repo, one can use the `git subtree pull` command: - -```bash -git subtree pull --prefix RScore -``` - -Note the path must match the location of the RScore subfolder, and the branch must match the one the subtree was originally added from (by default, this should be `main`). - -e.g. for RangeShifter-batch, use: +## Usage and help -```bash -git subtree pull --prefix src/RScore RScore main -``` +Please refer to our [website](https://rangeshifter.github.io/) for more information about RangeShifter simulation +platform. RangeShifter is accompanied by extensive documentation. -while for RangeShiftR, use: +For getting acquainted with the software, we recommend to first read the [manual](https://raw.githubusercontent.com/RangeShifter/RangeShifter-software-and-documentation/master/RangeShifter_v2.0_UserManual.pdf) to understand the conceptual underpinnings of RangeShifter. -```bash -git subtree pull --prefix RangeShiftR/src/RScore RScore main -``` +Analogous to the RangeShifter GUI, we provide [tutorials](https://rangeshifter.github.io/RangeshiftR-tutorials/) to learn the different features of RangeshiftR using example applications from Bocedi et al. (2014, 2021) and Malchow et al. (2021). These cover some of the main features of RangeShifter, and help becoming familiar with the software. -### Pushing new changes to RScore +If you have any further question related to the general concepts and usage of RangeShifter, please browse earlier topics in the [forum pages](https://github.com/RangeShifter/RangeshiftR-tutorials/discussions) or add a new one. Often it is also helpful to review [published studies](https://rangeshifter.github.io/site/references/) using the RangeShifter modelling platform. -```bash -git subtree push --prefix RScore -``` +For technical questions related to the RangeShiftR package interface and which cannot be answered with the documentation provided above, please browse the [issues section](https://github.com/RangeShifter/RangeShiftR-package-dev/issues) of this repository and open a new issues if required. We also offer *technical support* for the RangeShiftR package via mail (rangeshiftr@uni-potsdam.de) if you follow the guidelines of how to ask for help, e.g. guidelines given by [StackOverflow](https://stackoverflow.com/help/how-to-ask): -e.g., from RangeShifter-batch's `main` to RScore's `main`: +## Contributing -```bash -git subtree push --prefix src/RScore RScore main -``` +See [Contributing guidelines](https://github.com/RangeShifter/RangeShiftR-package-dev/blob/main/CONTRIBUTING.md) -### Switching the subfolder to a new branch +## See also -There is unfortunately to do so. To track a different branch of RScore, one must delete the RScore subfolder (via git) and import the subtree again: +- [Compiled software and documentation](https://github.com/RangeShifter/RangeShifter-software-and-documentation) +- [RScore](https://github.com/RangeShifter/RScore), source for RangeShifter's core code +- [RangeShifter batch mode](https://github.com/RangeShifter/RangeShifter_batch_dev), source for the batch mode interface -```bash -git rm src/RScore -r -git commit -m "switching subtree branch" -git subtree add --prefix src/RScore RScore -``` +## Maintainer -## Contributing to RangeShifter core code +- [@JetteReeg](https://github.com/JetteReeg) -See [CONTRIBUTING](https://github.com/RangeShifter/RScore/blob/main/CONTRIBUTING.md). +## References -## Maintainers + - Bocedi G, Palmer SCF, Pe’er G, Heikkinen RK, Matsinos YG, Watts K, Travis JMJ (2014). + *RangeShifter: A Platform for Modelling Spatial Eco-Evolutionary Dynamics and + Species’ Responses to Environmental Changes.* Methods in Ecology and Evolution 5: 388–96. -- [@JetteReeg](https://github.com/JetteReeg) -- [@TheoPannetier](https://github.com/TheoPannetier) + - Bocedi G, Palmer SCF, Malchow AK, Zurell D, Watts K, Travis JMJ (2021) RangeShifter 2.0: An extended and enhanced platform for modelling spatial eco-evolutionary dynamics and species’ responses to environmental changes. Ecography 44:1453-1462. + + - Malchow AK, Bocedi G, Palmer SCF, Travis JMJ, Zurell D (2021) RangeShiftR: an R package for individual-based simulation of spatial eco-evolutionary dynamics and species’ responses to environmental change. Ecography 4: 1443-1452. diff --git a/RSrandom.cpp b/RSrandom.cpp deleted file mode 100644 index 8f638d7..0000000 --- a/RSrandom.cpp +++ /dev/null @@ -1,283 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -#include "RSrandom.h" - -//--------------- 2.) New version of RSrandom.cpp - -#if !RS_RCPP - -#if RSDEBUG -#include "Parameters.h" -extern paramSim* paramsSim; -// ofstream RSRANDOMLOG; -#endif - -int RS_random_seed = 0; - -// C'tor -RSrandom::RSrandom() -{ -#if RSDEBUG - // fixed seed - RS_random_seed = 666; -#else - // random seed -#if LINUX_CLUSTER - std::random_device device; - RS_random_seed = device(); // old versions of g++ on Windows return a constant value within a given Windows - // session; in this case better use time stamp -#else - RS_random_seed = std::time(NULL); -#endif -#endif // RSDEBUG - -#if BATCH && RSDEBUG - DEBUGLOG << "RSrandom::RSrandom(): RS_random_seed=" << RS_random_seed << endl; -#endif // RSDEBUG - - // set up Mersenne Twister RNG - gen = new mt19937(RS_random_seed); - - // Set up standard uniform distribution - pRandom01 = new uniform_real_distribution(0.0, 1.0); - // Set up standard normal distribution - pNormal = new normal_distribution(0.0, 1.0); -} - -RSrandom::~RSrandom(void) -{ - delete gen; - if(pRandom01 != 0) - delete pRandom01; - if(pNormal != 0) - delete pNormal; -} - -mt19937 RSrandom::getRNG(void) -{ - return *gen; -} - -double RSrandom::Random(void) -{ - // return random number between 0 and 1 - return pRandom01->operator()(*gen); -} - -int RSrandom::IRandom(int min, int max) -{ - // return random integer in the interval min <= x <= max - uniform_int_distribution unif(min, max); - return unif(*gen); -} - -int RSrandom::Bernoulli(double p) -{ - if (p < 0) throw runtime_error("Bernoulli's p cannot be negative.\n"); - if (p > 1) throw runtime_error("Bernoulli's p cannot be above 1.\n"); - return Random() < p; -} - -double RSrandom::Normal(double mean, double sd) -{ - return mean + sd * pNormal->operator()(*gen); -} - -int RSrandom::Poisson(double mean) -{ - poisson_distribution poiss(mean); - return poiss(*gen); -} - - -//-------------------------------------------------------------------------------------------------- -//-------------------------------------------------------------------------------------------------- - -#else // if RS_RCPP - -//--------------- 3.) R package version of RSrandom.cpp - - #if RSDEBUG - #include "Parameters.h" - extern paramSim *paramsSim; - //ofstream RSRANDOMLOG; - #endif - - std::uint32_t RS_random_seed = 0; - - // C'tor - // if parameter seed is negative, a random seed will be generated, else it is used as seed - RSrandom::RSrandom(std::int64_t seed) - { - // get seed - std::vector random_seed(3); - random_seed[0] = 1967593562; - random_seed[1] = 3271254416; - if (seed < 0) { - // random seed - #if RSWIN64 - random_seed[2] = std::time(NULL) + ( seed * (-17) ); - #else - std::random_device device; - random_seed[2] = device(); - #endif - #if BATCH && RSDEBUG - DEBUGLOG << "RSrandom::RSrandom(): Generated random seed = "; - #endif - } - else{ - // fixed seed - random_seed[2] = seed; - #if BATCH && RSDEBUG - DEBUGLOG << "RSrandom::RSrandom(): Use fixed seed = "; - #endif - } - - RS_random_seed = random_seed[2]; - #if BATCH && RSDEBUG - DEBUGLOG << RS_random_seed << endl; - #endif - - // set up Mersenne Twister random number generator with seed sequence - std::seed_seq seq(random_seed.begin(),random_seed.end()); - gen = new mt19937(seq); - - // Set up standard uniform distribution - pRandom01 = new uniform_real_distribution (0.0,1.0); - // Set up standard normal distribution - pNormal = new normal_distribution (0.0,1.0); - } - - RSrandom::~RSrandom(void) { - delete gen; - if (pRandom01 != 0) delete pRandom01; - if (pNormal != 0) delete pNormal; - } - - mt19937 RSrandom::getRNG(void) { - // return random number generator - return *gen; - } - - double RSrandom::Random(void) { - // return random number between 0 and 1 - return pRandom01->operator()(*gen); - } - - int RSrandom::IRandom(int min,int max) { - // return random integer in the interval min <= x <= max - uniform_int_distribution unif(min,max); - return unif(*gen); - } - - int RSrandom::Bernoulli(double p) { - if (p < 0) throw runtime_error("Bernoulli's p cannot be negative.\n"); - if (p > 1) throw runtime_error("Bernoulli's p cannot be above 1.\n"); - return Random() < p; - } - - double RSrandom::Normal(double mean,double sd) { - return mean + sd * pNormal->operator()(*gen); - } - - int RSrandom::Poisson(double mean) { - poisson_distribution poiss(mean); - return poiss(*gen); - } - - - /* ADDITIONAL DISTRIBUTIONS - - // Beta distribution - sample from two gamma distributions - double RSrandom::Beta(double p0,double p1) { - double g0,g1,beta; - if (p0 > 0.0 && p1 > 0.0) { // valid beta parameters - gamma_distribution gamma0(p0,1.0); - gamma_distribution gamma1(p1,1.0); - g0 = gamma0(*gen); - g1 = gamma1(*gen); - beta = g0 / (g0 + g1); - } - else { // return invalid value - beta = -666.0; - } - return beta; - } - - // Gamma distribution - double RSrandom::Gamma(double p0,double p1) { // using shape (=p0) and scale (=p1) - double p2,gamma; - if (p0 > 0.0 && p1 > 0.0) { // valid gamma parameters - p2 = 1.0 / p1; - gamma_distribution gamma0(p0,p2); // using shape/alpha (=p0) and rate/beta (=p2=1/p1) - gamma = gamma0(*gen); - } - else { // return invalid value - gamma = -666.0; - } - return gamma; - } - - // Cauchy distribution - double RSrandom::Cauchy(double loc, double scale) { - double res; - if (scale > 0.0) { // valid scale parameter - cauchy_distribution cauchy(loc,scale); - res = cauchy(*gen); - } - else { // return invalid value - res = -666.0; - } - return res; - } - - - */ - -#endif // RS_RCPP - - -#if RSDEBUG && !RS_RCPP - void testRSrandom() { - - { - // Bernoulli distribution - // Abuse cases - assert_error("Bernoulli's p cannot be negative.\n", []{ - RSrandom rsr; - rsr.Bernoulli(-0.3); - }); - assert_error("Bernoulli's p cannot be above 1.\n", [] { - RSrandom rsr; - rsr.Bernoulli(1.1); - }); - // Use cases - RSrandom rsr; - assert(rsr.Bernoulli(0) == 0); - assert(rsr.Bernoulli(1) == 1); - int bern_trial = rsr.Bernoulli(0.5); - assert(bern_trial == 0 || bern_trial == 1); - } - } -#endif // RSDEBUG -//--------------------------------------------------------------------------- diff --git a/RSrandom.h b/RSrandom.h deleted file mode 100644 index 9767245..0000000 --- a/RSrandom.h +++ /dev/null @@ -1,131 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -/*------------------------------------------------------------------------------ - -RangeShifter v2.0 RSrandom - -Implements the RSrandom class - -Authors: Steve Palmer, University of Aberdeen - Anne-Kathleen Malchow, Potsdam University - -Last updated: 12 January 2021 by Steve Palmer - -------------------------------------------------------------------------------*/ - -#ifndef RSrandomH -#define RSrandomH - -#include -#include -#include -#include "Utils.h" - -using namespace std; - -#if RSDEBUG -extern ofstream DEBUGLOG; -#endif - -#if !RS_RCPP -//--------------- 2.) New version of RSrandom.cpp - #include - #include - #if !LINUX_CLUSTER - #include - #endif - - class RSrandom - { - - public: - RSrandom(void); - ~RSrandom(void); - double Random(void); - int IRandom(int, int); - int Bernoulli(double); - double Normal(double, double); - int Poisson(double); - mt19937 getRNG(void); - - private: - mt19937* gen; - std::uniform_real_distribution<>* pRandom01; - std::normal_distribution<>* pNormal; - }; - - -//-------------------------------------------------------------------------------------------------- -//-------------------------------------------------------------------------------------------------- - - - -//--------------- 3.) R package version of RSrandom.cpp - - -#else // if RS_RCPP - - - #include - #include - #if RSWIN64 - #include - #endif - - class RSrandom { - - public: - RSrandom(std::int64_t); // if int is negative, a random seed will be generated, else it is used as seed - ~RSrandom(void); - mt19937 getRNG(void); - double Random(void); - int IRandom(int,int); - int Bernoulli(double); - double Normal(double,double); - int Poisson(double); - /* ADDITIONAL DISTRIBUTIONS - double Beta(double,double); - double Gamma(double,double); // !! make sure correct definition is used: using shape and scale (as defined here) OR using shape/alpha and rate/beta (=1/scale) - double Cauchy(double,double); - */ - - private: - mt19937 *gen; - std::uniform_real_distribution<> *pRandom01; - std::normal_distribution<> *pNormal; - }; - - - -#endif // !RS_RCPP - -#if RSDEBUG - void testRSrandom(); -#endif // RSDEBUG - -//--------------------------------------------------------------------------- - -#endif // RSrandomH - - - diff --git a/RandomCheck.cpp b/RandomCheck.cpp deleted file mode 100644 index e18aeaa..0000000 --- a/RandomCheck.cpp +++ /dev/null @@ -1,93 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - -//--------------------------------------------------------------------------- - -#include "RandomCheck.h" -//--------------------------------------------------------------------------- - -ifstream inRandom; -ofstream outRandom; -ofstream outBernoulli; -ofstream outNormal; -ofstream outPoisson; -ofstream outIRandom; - -void randomCheck(void) -{ - -int samplesize,irandMin,irandMax; -double bernMean,normMean,normSD,poisMean; -string name,header; -simParams sim = paramsSim->getSim(); - - name = paramsSim->getDir(1) + "RandomCheck.txt"; - inRandom.open(name.c_str()); - if (!inRandom.is_open()) { - #if !RS_RCPP - cout << endl << "***** Error opening input file RandomCheck.txt" << endl; - #endif - inRandom.clear(); - return; - } - for (int i = 0; i < 7; i++) { - inRandom >> header; - } - inRandom >> samplesize >> bernMean >> normMean >> normSD >> poisMean >> irandMin >> irandMax; - - name = paramsSim->getDir(2) + "Random.txt"; - outRandom.open(name.c_str()); - name = paramsSim->getDir(2) + "Bernoulli.txt"; - outBernoulli.open(name.c_str()); - name = paramsSim->getDir(2) + "Normal.txt"; - outNormal.open(name.c_str()); - name = paramsSim->getDir(2) + "Poisson.txt"; - outPoisson.open(name.c_str()); - name = paramsSim->getDir(2) + "IRandom.txt"; - outIRandom.open(name.c_str()); - - for (int i = 0; i < samplesize; i++) { - outRandom << pRandom->Random() << endl; - outBernoulli << pRandom->Bernoulli(bernMean) << endl; - outNormal << pRandom->Normal(normMean,normSD) << endl; - outPoisson << pRandom->Poisson(poisMean) << endl; - outIRandom << pRandom->IRandom(irandMin,irandMax) << endl; - } - - inRandom.close(); - inRandom.clear(); - outRandom.close(); - outRandom.clear(); - outBernoulli.close(); - outBernoulli.clear(); - outNormal.close(); - outNormal.clear(); - outPoisson.close(); - outPoisson.clear(); - outIRandom.close(); - outIRandom.clear(); - -} - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- diff --git a/RangeShiftR/.Rbuildignore b/RangeShiftR/.Rbuildignore new file mode 100644 index 0000000..163aee9 --- /dev/null +++ b/RangeShiftR/.Rbuildignore @@ -0,0 +1,6 @@ +^.*\.Rproj$ +^\.Rproj\.user$ +^src/BatchMode\.cpp$ +^src/Main\.cpp$ +^src/BatchMode\.h$ +^LICENSE\.md$ diff --git a/RangeShiftR/DESCRIPTION b/RangeShiftR/DESCRIPTION new file mode 100644 index 0000000..0a68204 --- /dev/null +++ b/RangeShiftR/DESCRIPTION @@ -0,0 +1,45 @@ +Package: RangeShiftR +Type: Package +Title: An R package for individual-based simulation of spatial eco-evolutionary dynamics and species' responses to environmental changes +Version: 3.0.0 +Authors@R: c( + person("Anne-Kathleen", "Malchow", email = "rangeshiftr@uni-potsdam.de", role = c("aut", "cre")), + person("Greta", "Bocedi", role = c("aut")), + person("Stephen C.F.", "Palmer", role = c("aut")), + person("Justin M.J.", "Travis", role = c("aut")), + person("Damaris", "Zurell", role = c("aut")) + ) +Date: 2025-11-21 +URL: https://rangeshifter.github.io/RangeshiftR-tutorials/ +Description: RangeShiftR provides individual-based simulations of spatial eco-evolutionary dynamics. It is based on the C++ software RangeShifter, making it flexible and fast. RangeShiftR models the processes of demography, dispersal and evolution in an inter-dependent way, offering substantial complexity in the corresponding modelling choices. It is entirely open-source and aims to facilitate the application of individual-based and mechanistic modelling to eco-evolutionary questions. +License: GPL-3 +Depends: R (>= 3.6) +SystemRequirements: C++20 +Imports: + Rcpp (>= 1.0.0), + Rdpack (>= 0.7), + methods, + rmarkdown, + terra +RdMacros: Rdpack +LinkingTo: Rcpp +Encoding: UTF-8 +RoxygenNote: 7.3.3 +Collate: + 'class_ManagementParams.R' + 'Rfunctions.R' + 'plotProbs.R' + 'class_InitialisationParams.R' + 'class_GeneticsParams.R' + 'class_DispersalParams.R' + 'class_DemogParams.R' + 'class_LandParams.R' + 'class_SimulationParams.R' + 'class_ControlParams.R' + 'class_RSparams.R' + 'RSsim.R' + 'RangeShiftR.R' + 'RcppExports.R' + 'RunRS.R' + 'addition.R' + 'output_handling.R' diff --git a/RangeShiftR/LICENSE.md b/RangeShiftR/LICENSE.md new file mode 100644 index 0000000..565779e --- /dev/null +++ b/RangeShiftR/LICENSE.md @@ -0,0 +1,595 @@ +GNU General Public License +========================== + +_Version 3, 29 June 2007_ +_Copyright © 2007 Free Software Foundation, Inc. <>_ + +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. + +## Preamble + +The GNU General Public License is a free, copyleft license for software and other +kinds of works. + +The licenses for most software and other practical works are designed to take away +your freedom to share and change the works. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change all versions of a +program--to make sure it remains free software for all its users. We, the Free +Software Foundation, use the GNU General Public License for most of our software; it +applies also to any other work released this way by its authors. You can apply it to +your programs, too. + +When we speak of free software, we are referring to freedom, not price. Our General +Public Licenses are designed to make sure that you have the freedom to distribute +copies of free software (and charge for them if you wish), that you receive source +code or can get it if you want it, that you can change the software or use pieces of +it in new free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you these rights or +asking you to surrender the rights. Therefore, you have certain responsibilities if +you distribute copies of the software, or if you modify it: responsibilities to +respect the freedom of others. + +For example, if you distribute copies of such a program, whether gratis or for a fee, +you must pass on to the recipients the same freedoms that you received. You must make +sure that they, too, receive or can get the source code. And you must show them these +terms so they know their rights. + +Developers that use the GNU GPL protect your rights with two steps: **(1)** assert +copyright on the software, and **(2)** offer you this License giving you legal permission +to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains that there is +no warranty for this free software. For both users' and authors' sake, the GPL +requires that modified versions be marked as changed, so that their problems will not +be attributed erroneously to authors of previous versions. + +Some devices are designed to deny users access to install or run modified versions of +the software inside them, although the manufacturer can do so. This is fundamentally +incompatible with the aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we have designed +this version of the GPL to prohibit the practice for those products. If such problems +arise substantially in other domains, we stand ready to extend this provision to +those domains in future versions of the GPL, as needed to protect the freedom of +users. + +Finally, every program is threatened constantly by software patents. States should +not allow patents to restrict development and use of software on general-purpose +computers, but in those that do, we wish to avoid the special danger that patents +applied to a free program could make it effectively proprietary. To prevent this, the +GPL assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and modification follow. + +## TERMS AND CONDITIONS + +### 0. Definitions + +“This License” refers to version 3 of the GNU General Public License. + +“Copyright” also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + +“The Program” refers to any copyrightable work licensed under this +License. Each licensee is addressed as “you”. “Licensees” and +“recipients” may be individuals or organizations. + +To “modify” a work means to copy from or adapt all or part of the work in +a fashion requiring copyright permission, other than the making of an exact copy. The +resulting work is called a “modified version” of the earlier work or a +work “based on” the earlier work. + +A “covered work” means either the unmodified Program or a work based on +the Program. + +To “propagate” a work means to do anything with it that, without +permission, would make you directly or secondarily liable for infringement under +applicable copyright law, except executing it on a computer or modifying a private +copy. Propagation includes copying, distribution (with or without modification), +making available to the public, and in some countries other activities as well. + +To “convey” a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through a computer +network, with no transfer of a copy, is not conveying. + +An interactive user interface displays “Appropriate Legal Notices” to the +extent that it includes a convenient and prominently visible feature that **(1)** +displays an appropriate copyright notice, and **(2)** tells the user that there is no +warranty for the work (except to the extent that warranties are provided), that +licensees may convey the work under this License, and how to view a copy of this +License. If the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +### 1. Source Code + +The “source code” for a work means the preferred form of the work for +making modifications to it. “Object code” means any non-source form of a +work. + +A “Standard Interface” means an interface that either is an official +standard defined by a recognized standards body, or, in the case of interfaces +specified for a particular programming language, one that is widely used among +developers working in that language. + +The “System Libraries” of an executable work include anything, other than +the work as a whole, that **(a)** is included in the normal form of packaging a Major +Component, but which is not part of that Major Component, and **(b)** serves only to +enable use of the work with that Major Component, or to implement a Standard +Interface for which an implementation is available to the public in source code form. +A “Major Component”, in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system (if any) on which +the executable work runs, or a compiler used to produce the work, or an object code +interpreter used to run it. + +The “Corresponding Source” for a work in object code form means all the +source code needed to generate, install, and (for an executable work) run the object +code and to modify the work, including scripts to control those activities. However, +it does not include the work's System Libraries, or general-purpose tools or +generally available free programs which are used unmodified in performing those +activities but which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for the work, and +the source code for shared libraries and dynamically linked subprograms that the work +is specifically designed to require, such as by intimate data communication or +control flow between those subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can regenerate +automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same work. + +### 2. Basic Permissions + +All rights granted under this License are granted for the term of copyright on the +Program, and are irrevocable provided the stated conditions are met. This License +explicitly affirms your unlimited permission to run the unmodified Program. The +output from running a covered work is covered by this License only if the output, +given its content, constitutes a covered work. This License acknowledges your rights +of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, without +conditions so long as your license otherwise remains in force. You may convey covered +works to others for the sole purpose of having them make modifications exclusively +for you, or provide you with facilities for running those works, provided that you +comply with the terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for you must do so +exclusively on your behalf, under your direction and control, on terms that prohibit +them from making any copies of your copyrighted material outside their relationship +with you. + +Conveying under any other circumstances is permitted solely under the conditions +stated below. Sublicensing is not allowed; section 10 makes it unnecessary. + +### 3. Protecting Users' Legal Rights From Anti-Circumvention Law + +No covered work shall be deemed part of an effective technological measure under any +applicable law fulfilling obligations under article 11 of the WIPO copyright treaty +adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention +of such measures. + +When you convey a covered work, you waive any legal power to forbid circumvention of +technological measures to the extent such circumvention is effected by exercising +rights under this License with respect to the covered work, and you disclaim any +intention to limit operation or modification of the work as a means of enforcing, +against the work's users, your or third parties' legal rights to forbid circumvention +of technological measures. + +### 4. Conveying Verbatim Copies + +You may convey verbatim copies of the Program's source code as you receive it, in any +medium, provided that you conspicuously and appropriately publish on each copy an +appropriate copyright notice; keep intact all notices stating that this License and +any non-permissive terms added in accord with section 7 apply to the code; keep +intact all notices of the absence of any warranty; and give all recipients a copy of +this License along with the Program. + +You may charge any price or no price for each copy that you convey, and you may offer +support or warranty protection for a fee. + +### 5. Conveying Modified Source Versions + +You may convey a work based on the Program, or the modifications to produce it from +the Program, in the form of source code under the terms of section 4, provided that +you also meet all of these conditions: + +* **a)** The work must carry prominent notices stating that you modified it, and giving a +relevant date. +* **b)** The work must carry prominent notices stating that it is released under this +License and any conditions added under section 7. This requirement modifies the +requirement in section 4 to “keep intact all notices”. +* **c)** You must license the entire work, as a whole, under this License to anyone who +comes into possession of a copy. This License will therefore apply, along with any +applicable section 7 additional terms, to the whole of the work, and all its parts, +regardless of how they are packaged. This License gives no permission to license the +work in any other way, but it does not invalidate such permission if you have +separately received it. +* **d)** If the work has interactive user interfaces, each must display Appropriate Legal +Notices; however, if the Program has interactive interfaces that do not display +Appropriate Legal Notices, your work need not make them do so. + +A compilation of a covered work with other separate and independent works, which are +not by their nature extensions of the covered work, and which are not combined with +it such as to form a larger program, in or on a volume of a storage or distribution +medium, is called an “aggregate” if the compilation and its resulting +copyright are not used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work in an aggregate +does not cause this License to apply to the other parts of the aggregate. + +### 6. Conveying Non-Source Forms + +You may convey a covered work in object code form under the terms of sections 4 and +5, provided that you also convey the machine-readable Corresponding Source under the +terms of this License, in one of these ways: + +* **a)** Convey the object code in, or embodied in, a physical product (including a +physical distribution medium), accompanied by the Corresponding Source fixed on a +durable physical medium customarily used for software interchange. +* **b)** Convey the object code in, or embodied in, a physical product (including a +physical distribution medium), accompanied by a written offer, valid for at least +three years and valid for as long as you offer spare parts or customer support for +that product model, to give anyone who possesses the object code either **(1)** a copy of +the Corresponding Source for all the software in the product that is covered by this +License, on a durable physical medium customarily used for software interchange, for +a price no more than your reasonable cost of physically performing this conveying of +source, or **(2)** access to copy the Corresponding Source from a network server at no +charge. +* **c)** Convey individual copies of the object code with a copy of the written offer to +provide the Corresponding Source. This alternative is allowed only occasionally and +noncommercially, and only if you received the object code with such an offer, in +accord with subsection 6b. +* **d)** Convey the object code by offering access from a designated place (gratis or for +a charge), and offer equivalent access to the Corresponding Source in the same way +through the same place at no further charge. You need not require recipients to copy +the Corresponding Source along with the object code. If the place to copy the object +code is a network server, the Corresponding Source may be on a different server +(operated by you or a third party) that supports equivalent copying facilities, +provided you maintain clear directions next to the object code saying where to find +the Corresponding Source. Regardless of what server hosts the Corresponding Source, +you remain obligated to ensure that it is available for as long as needed to satisfy +these requirements. +* **e)** Convey the object code using peer-to-peer transmission, provided you inform +other peers where the object code and Corresponding Source of the work are being +offered to the general public at no charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded from the +Corresponding Source as a System Library, need not be included in conveying the +object code work. + +A “User Product” is either **(1)** a “consumer product”, which +means any tangible personal property which is normally used for personal, family, or +household purposes, or **(2)** anything designed or sold for incorporation into a +dwelling. In determining whether a product is a consumer product, doubtful cases +shall be resolved in favor of coverage. For a particular product received by a +particular user, “normally used” refers to a typical or common use of +that class of product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected to use, the +product. A product is a consumer product regardless of whether the product has +substantial commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + +“Installation Information” for a User Product means any methods, +procedures, authorization keys, or other information required to install and execute +modified versions of a covered work in that User Product from a modified version of +its Corresponding Source. The information must suffice to ensure that the continued +functioning of the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or specifically for +use in, a User Product, and the conveying occurs as part of a transaction in which +the right of possession and use of the User Product is transferred to the recipient +in perpetuity or for a fixed term (regardless of how the transaction is +characterized), the Corresponding Source conveyed under this section must be +accompanied by the Installation Information. But this requirement does not apply if +neither you nor any third party retains the ability to install modified object code +on the User Product (for example, the work has been installed in ROM). + +The requirement to provide Installation Information does not include a requirement to +continue to provide support service, warranty, or updates for a work that has been +modified or installed by the recipient, or for the User Product in which it has been +modified or installed. Access to a network may be denied when the modification itself +materially and adversely affects the operation of the network or violates the rules +and protocols for communication across the network. + +Corresponding Source conveyed, and Installation Information provided, in accord with +this section must be in a format that is publicly documented (and with an +implementation available to the public in source code form), and must require no +special password or key for unpacking, reading or copying. + +### 7. Additional Terms + +“Additional permissions” are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. Additional +permissions that are applicable to the entire Program shall be treated as though they +were included in this License, to the extent that they are valid under applicable +law. If additional permissions apply only to part of the Program, that part may be +used separately under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option remove any +additional permissions from that copy, or from any part of it. (Additional +permissions may be written to require their own removal in certain cases when you +modify the work.) You may place additional permissions on material, added by you to a +covered work, for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you add to a +covered work, you may (if authorized by the copyright holders of that material) +supplement the terms of this License with terms: + +* **a)** Disclaiming warranty or limiting liability differently from the terms of +sections 15 and 16 of this License; or +* **b)** Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices displayed by works +containing it; or +* **c)** Prohibiting misrepresentation of the origin of that material, or requiring that +modified versions of such material be marked in reasonable ways as different from the +original version; or +* **d)** Limiting the use for publicity purposes of names of licensors or authors of the +material; or +* **e)** Declining to grant rights under trademark law for use of some trade names, +trademarks, or service marks; or +* **f)** Requiring indemnification of licensors and authors of that material by anyone +who conveys the material (or modified versions of it) with contractual assumptions of +liability to the recipient, for any liability that these contractual assumptions +directly impose on those licensors and authors. + +All other non-permissive additional terms are considered “further +restrictions” within the meaning of section 10. If the Program as you received +it, or any part of it, contains a notice stating that it is governed by this License +along with a term that is a further restriction, you may remove that term. If a +license document contains a further restriction but permits relicensing or conveying +under this License, you may add to a covered work material governed by the terms of +that license document, provided that the further restriction does not survive such +relicensing or conveying. + +If you add terms to a covered work in accord with this section, you must place, in +the relevant source files, a statement of the additional terms that apply to those +files, or a notice indicating where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the form of a +separately written license, or stated as exceptions; the above requirements apply +either way. + +### 8. Termination + +You may not propagate or modify a covered work except as expressly provided under +this License. Any attempt otherwise to propagate or modify it is void, and will +automatically terminate your rights under this License (including any patent licenses +granted under the third paragraph of section 11). + +However, if you cease all violation of this License, then your license from a +particular copyright holder is reinstated **(a)** provisionally, unless and until the +copyright holder explicitly and finally terminates your license, and **(b)** permanently, +if the copyright holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + +Moreover, your license from a particular copyright holder is reinstated permanently +if the copyright holder notifies you of the violation by some reasonable means, this +is the first time you have received notice of violation of this License (for any +work) from that copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the licenses of +parties who have received copies or rights from you under this License. If your +rights have been terminated and not permanently reinstated, you do not qualify to +receive new licenses for the same material under section 10. + +### 9. Acceptance Not Required for Having Copies + +You are not required to accept this License in order to receive or run a copy of the +Program. Ancillary propagation of a covered work occurring solely as a consequence of +using peer-to-peer transmission to receive a copy likewise does not require +acceptance. However, nothing other than this License grants you permission to +propagate or modify any covered work. These actions infringe copyright if you do not +accept this License. Therefore, by modifying or propagating a covered work, you +indicate your acceptance of this License to do so. + +### 10. Automatic Licensing of Downstream Recipients + +Each time you convey a covered work, the recipient automatically receives a license +from the original licensors, to run, modify and propagate that work, subject to this +License. You are not responsible for enforcing compliance by third parties with this +License. + +An “entity transaction” is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an organization, or +merging organizations. If propagation of a covered work results from an entity +transaction, each party to that transaction who receives a copy of the work also +receives whatever licenses to the work the party's predecessor in interest had or +could give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if the predecessor +has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the rights granted or +affirmed under this License. For example, you may not impose a license fee, royalty, +or other charge for exercise of rights granted under this License, and you may not +initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging +that any patent claim is infringed by making, using, selling, offering for sale, or +importing the Program or any portion of it. + +### 11. Patents + +A “contributor” is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The work thus +licensed is called the contributor's “contributor version”. + +A contributor's “essential patent claims” are all patent claims owned or +controlled by the contributor, whether already acquired or hereafter acquired, that +would be infringed by some manner, permitted by this License, of making, using, or +selling its contributor version, but do not include claims that would be infringed +only as a consequence of further modification of the contributor version. For +purposes of this definition, “control” includes the right to grant patent +sublicenses in a manner consistent with the requirements of this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free patent license +under the contributor's essential patent claims, to make, use, sell, offer for sale, +import and otherwise run, modify and propagate the contents of its contributor +version. + +In the following three paragraphs, a “patent license” is any express +agreement or commitment, however denominated, not to enforce a patent (such as an +express permission to practice a patent or covenant not to sue for patent +infringement). To “grant” such a patent license to a party means to make +such an agreement or commitment not to enforce a patent against the party. + +If you convey a covered work, knowingly relying on a patent license, and the +Corresponding Source of the work is not available for anyone to copy, free of charge +and under the terms of this License, through a publicly available network server or +other readily accessible means, then you must either **(1)** cause the Corresponding +Source to be so available, or **(2)** arrange to deprive yourself of the benefit of the +patent license for this particular work, or **(3)** arrange, in a manner consistent with +the requirements of this License, to extend the patent license to downstream +recipients. “Knowingly relying” means you have actual knowledge that, but +for the patent license, your conveying the covered work in a country, or your +recipient's use of the covered work in a country, would infringe one or more +identifiable patents in that country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or arrangement, you +convey, or propagate by procuring conveyance of, a covered work, and grant a patent +license to some of the parties receiving the covered work authorizing them to use, +propagate, modify or convey a specific copy of the covered work, then the patent +license you grant is automatically extended to all recipients of the covered work and +works based on it. + +A patent license is “discriminatory” if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on the +non-exercise of one or more of the rights that are specifically granted under this +License. You may not convey a covered work if you are a party to an arrangement with +a third party that is in the business of distributing software, under which you make +payment to the third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties who would receive +the covered work from you, a discriminatory patent license **(a)** in connection with +copies of the covered work conveyed by you (or copies made from those copies), or **(b)** +primarily for and in connection with specific products or compilations that contain +the covered work, unless you entered into that arrangement, or that patent license +was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting any implied +license or other defenses to infringement that may otherwise be available to you +under applicable patent law. + +### 12. No Surrender of Others' Freedom + +If conditions are imposed on you (whether by court order, agreement or otherwise) +that contradict the conditions of this License, they do not excuse you from the +conditions of this License. If you cannot convey a covered work so as to satisfy +simultaneously your obligations under this License and any other pertinent +obligations, then as a consequence you may not convey it at all. For example, if you +agree to terms that obligate you to collect a royalty for further conveying from +those to whom you convey the Program, the only way you could satisfy both those terms +and this License would be to refrain entirely from conveying the Program. + +### 13. Use with the GNU Affero General Public License + +Notwithstanding any other provision of this License, you have permission to link or +combine any covered work with a work licensed under version 3 of the GNU Affero +General Public License into a single combined work, and to convey the resulting work. +The terms of this License will continue to apply to the part which is the covered +work, but the special requirements of the GNU Affero General Public License, section +13, concerning interaction through a network will apply to the combination as such. + +### 14. Revised Versions of this License + +The Free Software Foundation may publish revised and/or new versions of the GNU +General Public License from time to time. Such new versions will be similar in spirit +to the present version, but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program specifies that +a certain numbered version of the GNU General Public License “or any later +version” applies to it, you have the option of following the terms and +conditions either of that numbered version or of any later version published by the +Free Software Foundation. If the Program does not specify a version number of the GNU +General Public License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions of the GNU +General Public License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the Program. + +Later license versions may give you additional or different permissions. However, no +additional obligations are imposed on any author or copyright holder as a result of +your choosing to follow a later version. + +### 15. Disclaimer of Warranty + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER +EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE +QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +### 16. Limitation of Liability + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY +COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS +PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, +INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE +OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE +WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +### 17. Interpretation of Sections 15 and 16 + +If the disclaimer of warranty and limitation of liability provided above cannot be +given local legal effect according to their terms, reviewing courts shall apply local +law that most closely approximates an absolute waiver of all civil liability in +connection with the Program, unless a warranty or assumption of liability accompanies +a copy of the Program in return for a fee. + +_END OF TERMS AND CONDITIONS_ + +## How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest possible use to +the public, the best way to achieve this is to make it free software which everyone +can redistribute and change under these terms. + +To do so, attach the following notices to the program. It is safest to attach them +to the start of each source file to most effectively state the exclusion of warranty; +and each file should have at least the “copyright” line and a pointer to +where the full notice is found. + + + Copyright (C) 2020 Greta Bocedi,Justin Travis,Steve Palmer,Anne-Kathleen Malchow + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short notice like this +when it starts in an interactive mode: + + RangeshiftR Copyright (C) 2020 Greta Bocedi,Justin Travis,Steve Palmer,Anne-Kathleen Malchow + This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type 'show c' for details. + +The hypothetical commands `show w` and `show c` should show the appropriate parts of +the General Public License. Of course, your program's commands might be different; +for a GUI interface, you would use an “about box”. + +You should also get your employer (if you work as a programmer) or school, if any, to +sign a “copyright disclaimer” for the program, if necessary. For more +information on this, and how to apply and follow the GNU GPL, see +<>. + +The GNU General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may consider it +more useful to permit linking proprietary applications with the library. If this is +what you want to do, use the GNU Lesser General Public License instead of this +License. But first, please read +<>. diff --git a/RangeShiftR/NAMESPACE b/RangeShiftR/NAMESPACE new file mode 100644 index 0000000..8bb8975 --- /dev/null +++ b/RangeShiftR/NAMESPACE @@ -0,0 +1,43 @@ +# Generated by roxygen2: do not edit by hand + +export(ArtificialLandscape) +export(ColonisationStats) +export(CorrRW) +export(CorrRWTraits) +export(Demography) +export(Dispersal) +export(DispersalKernel) +export(Emigration) +export(EmigrationTraits) +export(GeneticLoadTraits) +export(Genetics) +export(ImportedLandscape) +export(Initialise) +export(KernelTraits) +export(Management) +export(NeutralTraits) +export(RSsim) +export(RangeShiftR_citation) +export(RangeShiftR_license) +export(RunRS) +export(SMS) +export(SMSTraits) +export(SMSpathLengths) +export(Settlement) +export(SettlementTraits) +export(Simulation) +export(StageStructure) +export(Traits) +export(Translocation) +export(createODD) +export(createParameterTables) +export(getLocalisedEquilPop) +export(plotAbundance) +export(plotOccupancy) +export(plotProbs) +export(readPop) +export(readRange) +export(validateRSparams) +importFrom(Rcpp,sourceCpp) +importFrom(Rdpack,reprompt) +useDynLib(RangeShiftR) diff --git a/RangeShiftR/R/RSsim.R b/RangeShiftR/R/RSsim.R new file mode 100644 index 0000000..1396271 --- /dev/null +++ b/RangeShiftR/R/RSsim.R @@ -0,0 +1,143 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +# ----- +# +# RangeShiftR parameter master +# +# ----- + +#' Define a RangeShiftR parameter master object +#' +#' Set up a parameter master that can be used in \code{\link[RangeShiftR]{RunRS}}() to run a simulation.\cr +#' All parameter modules can be added to an existing parameter master via the "+"-functions. However, note that the entire respective module will be overwritten.\cr +#' +#' @usage RSsim(batchnum = 1L, +#' simul = Simulation(), +#' land = ArtificialLandscape(), +#' demog = Demography(Rmax = 1.5), +#' dispersal = Dispersal(), +#' gene = Genetics(), +#' management = Management(), +#' init = Initialise(), +#' seed = 0, +#' fixreplicateseed = FALSE) +#' @include class_RSparams.R +#' @param batchnum Batch ID is part of output files names and can be used to prevent overwriting. +#' @param simul Set \code{\link[RangeShiftR]{Simulation}} parameters +#' @param land Set landscape parameters. Can be either \code{\link[RangeShiftR]{ArtificialLandscape}} or \code{\link[RangeShiftR]{ImportedLandscape}}. +#' @param demog Set \code{\link[RangeShiftR]{Demography}} parameters +#' @param dispersal Set \code{\link[RangeShiftR]{Dispersal}} parameters +#' @param gene Set \code{\link[RangeShiftR]{Genetics}} parameters +#' @param management Set \code{\link[RangeShiftR]{Management}} parameters +#' @param init Set \code{\link[RangeShiftR]{Initialise}} parameters +#' @param seed Set seed for random number generator. If non-positive, a random seed will be generated. +#' @param fixreplicateseed Use the same seed for all replicates. +#' @return returns a \emph{RangeShiftR} parameter master object (class 'RSparams') +#' @details +#' \emph{Demographic stochasticity} \cr Demographic stochasticity is fundamentally important for the dynamics of populations that are naturally small or have declined to low abundances owing to +#' anthropogenic pressures. Additionally, inter-individual variability within populations can have a major influence on dynamics. Modelling stochastic events +#' that happen to individuals is crucial for avoiding systematic overestimation of population viability or rate of spread +#' \insertCite{clark2001invasion,kendall2003unstructured,robert2003variation,grimm2005individual,jongejans2008dispersal,travis2011improving}{RangeShiftR}. +#' Thus, population dynamics in \emph{RangeShiftR} were constructed to be +#' fully individual-based and stochastic. Each reproductive individual produces a discrete number of offspring sampled from a Poisson distribution with a mean +#' that is influenced by the species’ demographic parameters and the local population density. As \emph{RangeShiftR} has been designed for modelling a variety of +#' species with different life-history traits, a range of different population models can be chosen, depending on the species being modelled and on the +#' available information (see \code{\link[RangeShiftR]{Demography}}). In all cases demographic stochasticity is implemented. +#' +#' \emph{Cell-based vs. patch-based model} \cr +#' \emph{RangeShiftR} can be run as a cell-based or patch-based model \insertCite{bian2003representation}{RangeShiftR}. It should be noted +#' that the selection between cell-based or patch-based model is of fundamental importance for population dynamics calculations because +#' it influences the spatial extent at which density dependence operates. In both cases, the landscape is represented as a grid with cells +#' belonging to a particular habitat type, holding a percentage of habitat cover or being assigned a habitat quality index. However, +#' when \emph{RangeShiftR} is run using the cell-based setting, the cell is the scale at which processes such as population dynamics and dispersal +#' act. The individuals present in a cell define a distinct population, and density-dependencies for reproduction, emigration and settlement +#' all operate at this scale. Even in the case where two habitat cells are adjacent, they still hold separate populations. In contrast, in +#' the patch-based model, population dynamics happen at the patch level, a patch being an assemblage of landscape cells of potentially +#' different habitat types. Patches are not defined automatically by \emph{RangeShiftR} (see \code{\link[RangeShiftR]{ImportedLandscape}}). +#' Rather, the user is required to define which cells belong +#' to which patch, taking into account the ecological understanding of the study species. Density-dependencies regarding reproduction, +#' development, survival, emigration and settlement will depend on the density of individuals in a patch. However, discrete step-wise +#' movements during the transfer phase will always use the cell as the resolution at which steps occur, thus retaining important information +#' about the landscape heterogeneity.\cr +#' The choice between cell- and patch-based modelling can be of crucial importance. While a cell-based model provides an excellent abstraction +#' of space for many theoretical studies, for some applied studies it may be insufficient. This is because the misrepresentation of population +#' dynamics and dispersal (in terms of the scale at which they operate) can lead to substantial biases in projections regarding, for example, +#' rate of range expansion and population persistence \insertCite{bocedi2012projecting}{RangeShiftR}. Ideally, the scales at which population dynamics and dispersal +#' processes are modelled (by choosing the cell resolution or by defining the patches) should be those that are relevant for the species. +#' Importantly, the patch-based implementation allows separating the scales used for population dynamics and movements. In this case, the +#' landscape can be modelled at very fine resolution in order to capture the features that are likely to influence movements (e.g. narrow linear +#' features) without constraining the local population dynamics to operate at too small a scale. +#' +#' \emph{Temporal and spatial scales} \cr +#' It is important to note an essential difference in spatial scale between +#' the cell-based and the patch-based version. In the cell-based model, the cell resolution represents the spatial scale at which the two fundamental +#' processes of population dynamics and dispersal happen. This means that all the density-dependencies in the model (reproduction, survival, +#' emigration, settlement, etc...) act at the cell scale and the same scale is used as a single step unit for discrete movement models. In +#' the patch-based version, two spatial scales are simultaneously present: the cell scale, which in this case is used just for the transfer phase +#' of dispersal (movements) and the patch scale, at which the density-dependences are acting. The choice of type of model and cell resolution (as +#' well as the definition/scale of patches) is of fundamental importance because, depending on the system and on the question being tackled, it can +#' systematically bias the outcomes of the model.\cr +#' The user also defines the temporal scales. There are three distinct temporal scales. The highest-level one has years as units and represents the +#' scale at which variations in the abiotic environment are modelled (\emph{RangeShiftR} does not explicitly model within-year variability in conditions). +#' The intermediate scale is the species’ reproductive season. The model can be used to simulate the case where there is only one reproductive +#' season per year but it is also possible to simulate situations where there more than one per year or only one every \eqn{N} years. A single +#' reproductive event is always followed by dispersal. Finally, the smallest time scale is represented by the number of steps that emigrants take +#' during the movement phase of dispersal. This can be determined by a maximum number of steps, per-step mortality or both. +#' +#' @references +#' \insertAllCited{} +#' @return if given parameters pass validity check, returns a RangeShiftR parameter master object of class "RSparams", otherwise NULL +#' @author Anne-Kathleen Malchow +#' @export +RSsim <- function(batchnum = 1L, + simul = NULL, + land = NULL, + demog = NULL, + dispersal = NULL, + gene = NULL, + management = NULL, + init = NULL, + seed = 0L, + fixreplicateseed = FALSE){ + args <- as.list(match.call()) + # filter for names in ... that are also in slots(ControlParams) and pass them on + s <- RSparams(control = ControlParams(batchnum = batchnum, seed = seed, fixreplicateseed = fixreplicateseed), + simul = Simulation(), + land = ArtificialLandscape(), + demog = Demography(Rmax = 1.5), + dispersal = Dispersal(), + gene = Genetics(), + management = Management(), + init = Initialise()) + if (!is.null(args$land)) s <- s + land + if (!is.null(args$simul)) s <- s + simul + if (!is.null(args$demog)) s <- s + demog + if (!is.null(args$dispersal)) s <- s + dispersal + if (!is.null(args$gene)) s <- s + gene + if (!is.null(args$management)) s <- s + management + if (!is.null(args$init)) s <- s + init + # check validity + if(validObject(s)) return(s) + else return(NULL) +} diff --git a/RangeShiftR/R/RangeShiftR.R b/RangeShiftR/R/RangeShiftR.R new file mode 100644 index 0000000..09b3ef6 --- /dev/null +++ b/RangeShiftR/R/RangeShiftR.R @@ -0,0 +1,96 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + +#' @details +#' \code{RangeShiftR} provides flexible and fast simulations of spatial eco-evolutionary dynamics. +#' It implements the individual-based simulation software \emph{RangeShifter}, +#' \insertCite{bocedi2014,bocedi2020}{RangeShiftR}, +#' making it available for all machines that can build and run \emph{R}. +#' +#' \code{RangeShiftR} models the processes of demography, dispersal and evolution in an +#' inter-dependent way, offering substantial complexity in the corresponding modelling choices. +#' It is entirely open-source and aims to facilitate the application +#' of individual-based and mechanistic modelling to eco-evolutionary questions. +#' +#' The \emph{RangeShifter} project is presented on our website +#' \url{https://rangeshifter.github.io/}. +#' +#' To get started with the package, please find an overview and a range of tutorials here: +#' \url{https://rangeshifter.github.io/RangeshiftR-tutorials/}. +#' +#' @references +#' \insertAllCited{} +#' @keywords internal +"_PACKAGE" + + +#' @useDynLib RangeShiftR +#' @importFrom Rcpp sourceCpp +#' @importFrom Rdpack reprompt +NULL + + +# Show start-up message upon loading the package +.onAttach <- function(libname, pkgname) { + packageStartupMessage("RangeshiftR version 3.0.0 (21.11.2025)\n", + "Copyright (C) 2020-2025 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Jette Wolff, Damaris Zurell\n\n", + "This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.\n", + "You are welcome to redistribute it and/or modify it under certain conditions;\n", + "type 'RangeShiftR_license()' for details.\n") +} + +# Unload dynamic library when unloading the package +.onUnload <- function (libpath) { + library.dynam.unload("RangeShiftR", libpath) +} + + +#' Display RangeShiftR license information +#' +#' @export +RangeShiftR_license <- function () +{ + cat("\nRangeshiftR version 3.0.0 (21.11.2025)\n") + cat("Copyright (C) 2020-2025 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Jette Wolff, Damaris Zurell\n\n") + cat("This program is free software: you can redistribute it and/or modify\n") + cat("it under the terms of the GNU General Public License as published by\n") + cat("the Free Software Foundation, either version 3 of the License, or\n") + cat("(at your option) any later version.\n\n") + cat("This software is distributed in the hope that it will be useful,\n") + cat("but WITHOUT ANY WARRANTY; without even the implied warranty of\n") + cat("MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n") + cat("GNU General Public License for more details.\n\n") + cat("You should have received a copy of the GNU General Public License\n") + cat("along with this software. Copies of the license can also be found at\n") + cat("http://www.gnu.org/licenses/\n") + cat("\n") + cat("'Share and Enjoy.'\n\n") +} + + +#' Display citation +#' +#' @export +RangeShiftR_citation <- function () +{ + citation(package = "RangeShiftR", lib.loc = NULL, auto = NULL) +} diff --git a/RangeShiftR/R/RcppExports.R b/RangeShiftR/R/RcppExports.R new file mode 100644 index 0000000..5767fb2 --- /dev/null +++ b/RangeShiftR/R/RcppExports.R @@ -0,0 +1,7 @@ +# Generated by using Rcpp::compileAttributes() -> do not edit by hand +# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393 + +run_from_R <- function(dirpath, ParMaster) { + .Call('_RangeShiftR_BatchMainR', PACKAGE = 'RangeShiftR', dirpath, ParMaster) +} + diff --git a/RangeShiftR/R/Rfunctions.R b/RangeShiftR/R/Rfunctions.R new file mode 100644 index 0000000..4017f68 --- /dev/null +++ b/RangeShiftR/R/Rfunctions.R @@ -0,0 +1,65 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +# ----- +# +# R-level functions +# +# ----- + + +#-- define ClassUnions +#---------------------- + +#for Integer and Numerical so that 'Integer'-slots can also accept 'Numerical' input +setClassUnion("integer_OR_numeric", c("integer", "numeric")) + +#for Matrix and Numerical so that 'Matrix'-slots can also accept 'Numerical' input when 1x1-Matrix is expected +setClassUnion("matrix_OR_numeric", c("matrix", "numeric")) + +#for Matrix and Logical so that 'Matrix'-slots can also accept 'Logical' input when 1x1-Matrix is expected +setClassUnion("matrix_OR_logical", c("matrix", "logical")) + +#for cost layer to accept habitat codes or raster map file +setClassUnion("numeric_OR_character", c("numeric", "character")) + + +#-- define error and warning messages +#---------------------- +warn_msg_ignored = " will be ignored " + + +#-- density dependence function +#---------------------- +densdep <- function(x, A0 = 1.0, alpha = 1.0, beta = 0.0) { + A0/(1+exp(alpha*(beta-x))) +} + + +#-- validation function +#---------------------- + +#' Validate a given RS parameter object +#' +#' @export +validateRSparams <- function(x){validObject(x)} diff --git a/RangeShiftR/R/RunRS.R b/RangeShiftR/R/RunRS.R new file mode 100644 index 0000000..bcc4a79 --- /dev/null +++ b/RangeShiftR/R/RunRS.R @@ -0,0 +1,155 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + +# ----- +# +# Run a RangeShiftR simulation +# +# ----- + +#' Run the Simulation +#' +#' @param RSparams A parameter master object (class 'RSparams'), contains all parameters to specify the simulation settings. +#' Can be generated using the function \code{\link[RangeShiftR]{RSsim}}. +#' @param dirpath File path to RS working directory; must contain the folders 'Inputs', 'Outputs', 'Output_Maps'.\cr +#' If NULL, the current \code{R} working directory will be used. +#' @return returns an error code +#' @export +RunRS <- function(RSparams, dirpath = getwd()){ + if (missing(RSparams)) { + stop("Missing parameter object") + } + else{ + if (class(RSparams)[1] != "RSparams") { + stop("Parameter object must be of class RSparams") + } + else { + validObject(RSparams) + } + } + if (is.null(dirpath)) { + dirpath = getwd() + } + + out = run_from_R(dirpath, RSparams) + + if (class(out)=="list" && is.null(out$Errors)) { + if ( length(out)>0 ) { + if(RSparams@simul@ReturnPopMatrix){ + resol = RSparams@control@resolution + if (RSparams@control@threadsafe){ +# if(class(RSparams@land)=="ImportedLandscape") llcorner = RSparams@land@OriginCoords +# else llcorner = c(0,0) +# +# raster_list <- vector("list", length(out)) +# + # for(i in seq_along(out)) { + # + # r <- terra::rast(out[[i]]) + # # ext(r) <- c(llcorner[1], ncol(out[[1]])*resol+llcorner[1], llcorner[2], nrow(out[[1]])*resol+llcorner[2]) + # + # raster_list[[i]] <- r + # + # out[[i]] <- 0 + # } +# +# gc() +# +# +# # raster_list <- lapply(out, function(x) { +# # r <- terra::rast(x) +# # ext(r) <- c(llcorner[1], ncol(out[[1]])*resol+llcorner[1], llcorner[2], nrow(out[[1]])*resol+llcorner[2]) +# # return(r) +# # }) +# +# out <- NULL +# return(terra::rast(raster_list)) + return(out) + } else { +# raster_list <- vector("list", length(out)) +# +# for(i in seq_along(out)) { +# +# r <- terra::rast(out[[i]]) +# ext(r) <- c(0, ncol(out[[i]]) * resol, +# 0, nrow(out[[i]]) * resol) +# +# raster_list[[i]] <- r +# +# out[[i]] <- NULL +# } +# +# gc() +# +# # raster_list <- lapply(out, function(x) { +# # r <- terra::rast(x) +# # ext(r) <- c(0, ncol(out[[1]])*resol, 0, nrow(out[[1]])*resol) +# # return(r) +# # }) +# return(terra::rast(raster_list)) + return(out) + } + } + if(RSparams@simul@ReturnPopDataFrame){ + stage_idx <- which(RSparams@simul@ReturnStages) + df <- do.call( + rbind, + lapply(names(out), function(nm) { + + mat <- out[[nm]] + + # extract Rep and Year from list name + rep <- as.integer(sub(".*rep([0-9]+).*", "\\1", nm)) + year <- as.integer(sub(".*year([0-9]+).*", "\\1", nm)) + + # matrix -> data.frame + d <- as.data.frame(mat, stringsAsFactors = FALSE) + + # base column names + colnames(d)[1:2] <- c("PatchID", "totalAbundance") + + # stage column names based on ReturnStages + if (ncol(d) > 2) { + colnames(d)[3:ncol(d)] <- paste0( + "NInd_Stage", + stage_idx[seq_len(ncol(d) - 2)] + ) + } + + # add Rep and Year + d$Rep <- rep + d$Year <- year + + # reorder columns + d[, c("Rep", "Year", colnames(d)[!colnames(d) %in% c("Rep", "Year")])] + }) + ) + return(df) + } + + } + else return(NULL) + } + else { + return(out) + } +} diff --git a/RangeShiftR/R/addition.R b/RangeShiftR/R/addition.R new file mode 100644 index 0000000..8bea0b8 --- /dev/null +++ b/RangeShiftR/R/addition.R @@ -0,0 +1,197 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +# ----- +# +# Define Addition operations between modules +# +# ----- + + +setGeneric("+") + +setMethod("+", signature(e1 = "RSparams", e2 = "SimulationParams"), function(e1, e2) { + validObject(e2) + e1@simul <- e2 + return(e1)} +) + +setMethod("+", signature(e1 = "RSparams", e2 = "LandParams"), function(e1, e2) { + validObject(e2) + if (class(e2)[1] == "ImportedLandscape") { + if (any(is.null(e2@PatchFile)) && length(e2@PatchMatrix)==0) { + e1@control@patchmodel = FALSE + } + else { + e1@control@patchmodel = TRUE + } + e1@control@resolution = e2@Resolution + if (e2@HabPercent) { + e1@control@landtype = 2L + e1@control@maxNhab = 1L + } + else { # habitat codes + e1@control@landtype = 0L + e1@control@maxNhab = e2@Nhabitats + } + if (is.null(e2@SpDistFile) && length(e2@SpDistMatrix)==0) { + e1@control@speciesdist = FALSE + e1@control@distresolution = -9L + } + else { + e1@control@speciesdist = TRUE + e1@control@distresolution = e2@SpDistResolution + } + if(length(e2@LandscapeMatrix)>0){ + e1@control@threadsafe = TRUE + } + if(e2@nrDemogScaleLayers>0){ + e1@control@spatial_demography = TRUE + } + } + if (class(e2)[1] == "ArtificialLandscape") { + e1@control@patchmodel = FALSE + e1@control@resolution = e2@Resolution + e1@control@landtype = 9L + e1@control@maxNhab = 1L + e1@control@speciesdist = FALSE + e1@control@distresolution = 0L + } + e1@land = e2 + return(e1)} +) + +setMethod("+", signature(e1 = "RSparams", e2 = "DemogParams"), function(e1, e2) { + validObject(e2) + e1@control@reproductn = e2@ReproductionType + if (class(e2@StageStruct)[1] == "StagesParams") { + e1@control@repseasons = e2@StageStruct@RepSeasons + e1@control@stagestruct = TRUE + e1@control@stages = e2@StageStruct@Stages + if (length(e2@StageStruct@MinAge)==1 && e2@StageStruct@MinAge==0) { + if (e2@ReproductionType==2) { + e2@StageStruct@MinAge <- rep(0L, 2*e2@StageStruct@Stages-1) + } + else { + e2@StageStruct@MinAge <- rep(0L, e2@StageStruct@Stages) + } + } + } + else { + e1@control@repseasons = 1L + e1@control@stagestruct = FALSE + e1@control@stages = 1L + } + e1@demog <- e2 + return(e1)} +) + +setMethod("+", signature(e1 = "DemogParams", e2 = "StagesParams"), function(e1, e2) { + validObject(e2) + e1@StageStruct <- e2 + e1@Rmax <- -9L + e1@bc <- -9L + return(e1)} +) + +setMethod("+", signature(e1 = "RSparams", e2 = "DispersalParams"), function(e1, e2) { + validObject(e2) + if (class(e2@Transfer)[1] == "DispersalKernel") { + e1@control@transfer = 0 + } + else { + if (class(e2@Transfer)[1] == "StochMove") { + e1@control@transfer = 1 + } + else { + if (class(e2@Transfer)[1] == "CorrRW") { + e1@control@transfer = 2 + } + else { + e1@control@transfer = NA_integer_ + } + } + } + e1@dispersal <- e2 + return(e1)} +) + +setMethod("+", signature(e1 = "DispersalParams", e2 = "EmigrationParams"), function(e1, e2) { + validObject(e2) + e1@Emigration <- e2 + validObject(e1) + return(e1)} +) + +setMethod("+", signature(e1 = "DispersalParams", e2 = "TransferParams"), function(e1, e2) { + validObject(e2) + e1@Transfer <- e2 + validObject(e1) + return(e1)} +) + +setMethod("+", signature(e1 = "DispersalParams", e2 = "SettlementParams"), function(e1, e2) { + validObject(e2) + e1@Settlement <- e2 + validObject(e1) + return(e1)} +) + +setMethod("+", signature(e1 = "RSparams", e2 = "GeneticsParams"), function(e1, e2) { + validObject(e2) + e1@gene <- e2 + if (e2@OutputGlobalFst || e2@OutputPairwiseFst) { # neutral traits are true as soon as the output is activated + # if(class(e2@Traits@Neutral)[1] == "NeutralTraitsParams") { + e1@control@neutralgenetics = TRUE + # } + } + else { + e1@control@neutralgenetics = FALSE + } + if (class(e2@Traits@GeneticLoad)[1] == "GeneticLoadParams") { # dispersal traits are checked later + e1@control@geneticload = TRUE + } + else { + e1@control@geneticload = FALSE + } + + return(e1)} +) + +setMethod("+", signature(e1 = "RSparams", e2 = "ManagementParams"), function(e1, e2) { + validObject(e2) + if (class(e2@Translocation)[1] == "TranslocationParams") { + e1@control@translocation = TRUE + } + else { + e1@control@translocation = FALSE + } + e1@management <- e2 + return(e1)} +) + +setMethod("+", signature(e1 = "RSparams", e2 = "InitialisationParams"), function(e1, e2) { + validObject(e2) + e1@init <- e2 + return(e1)} +) diff --git a/RangeShiftR/R/class_ControlParams.R b/RangeShiftR/R/class_ControlParams.R new file mode 100644 index 0000000..cc9ceb2 --- /dev/null +++ b/RangeShiftR/R/class_ControlParams.R @@ -0,0 +1,93 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#### CLASS CONTROLPARAMS + +# from RS 'CONTROL.txt' file + +ControlParams <- setClass("ControlParams", slots = c( + #nSimuls = "integer_OR_numeric", # Not yet used by R version, in C++ version its read from parameterfile + #nLandscapes = "integer_OR_numeric", # Not yet used by R version, in C++ version its read from landfile + batchnum = "integer_OR_numeric", # only variable to set from RSsim(), optional + patchmodel = "logical", # set via +Land + resolution = "integer_OR_numeric", # set via +Land + landtype = "integer_OR_numeric", # set via +Land + maxNhab = "integer_OR_numeric", # set via +Land + speciesdist = "logical", # set via +Land + distresolution = "integer_OR_numeric", # set via +Land + threadsafe = "logical", # set via +Land + reproductn = "integer_OR_numeric", # set via +Demography + repseasons = "integer_OR_numeric", # set via +Demography if (StageStruct is Type "StagesParams") {repseasons = 1} else {demo@StageStruct@repseasons} + stagestruct = "logical", # set via +Demography + stages = "integer_OR_numeric", # set via +Demography@StageStruct + transfer = "integer_OR_numeric", # set via +Dispersal Transfer method: 0 = dispersal kernels, 1 = SMS, 2 = CRW) + translocation = "logical", # set via +Management + spatial_demography = "logical", # set via +Land + neutralgenetics = "logical", # set via +Genetics + geneticload = "logical", # set via +Genetics + seed = "integer_OR_numeric", + fixreplicateseed = "logical") + ,prototype = list(#nSimuls = 1L, + #nLandscapes = 1L, + batchnum = 0L, + patchmodel = FALSE, + resolution = 100L, + landtype = 9L, + maxNhab = 1L, + speciesdist = FALSE, + distresolution = NA_integer_, + threadsafe = FALSE, + reproductn = 0L, + repseasons = 1L, + stagestruct = FALSE, + stages = NA_integer_, + transfer = 0L, + translocation = FALSE, + spatial_demography = FALSE, + neutralgenetics = FALSE, + geneticload = FALSE, + seed = 0L, + fixreplicateseed = FALSE) +) +setValidity("ControlParams", function(object){ + msg <- NULL + if(object@stagestruct) { + stg <- as.integer(object@stages) + if(stg < 2 || stg > 10) msg <- c(msg, "Number of Stages must be in the interval [2; 10]") + #paste("Unequal x,y lengths: ", length(object@x), ", ", length(object@y), sep="") + } + if(object@seed > 4000000000) { + warning("RSsim(): Seeds greater than 4e9 should be avoided, since they might not be handled correctly.", call. = FALSE) + } + if (is.null(msg)) TRUE else msg} +) +setMethod("show", "ControlParams", function(object){ + cat(" Batch #", object@batchnum, "\n") + if(object@seed){ + cat(" Seed =", object@seed) + if(object@seed<0) cat(" (generate random seed)") + if(object@seed>0) cat(" (fixed seed)") + if(object@fixreplicateseed==TRUE) cat(" all replicates use the same seed") + cat("\n") + } +}) diff --git a/RangeShiftR/R/class_DemogParams.R b/RangeShiftR/R/class_DemogParams.R new file mode 100644 index 0000000..2497dbc --- /dev/null +++ b/RangeShiftR/R/class_DemogParams.R @@ -0,0 +1,957 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#### DEMOGRAPHY #### + + +### SUBCLASS STAGESPARAMS + +# from RS 'StageStruct' file + +#' Define a Stage-structure +#' +#' Set all demographic parameters for a stage-structured population. All elements of the transition matrix, i.e. Fecundity, Development, and Survival can be subjected to a density-dependent scaling. +#' In this case, the base probabilities given via the transition matrix will be reduced exponentially with the strength of density dependence \eqn{b(i,t)} times abundance \eqn{N(i,t)}, in patch \eqn{i} at time \eqn{t}. +#' Additionally, the effect of the abundances of each stage/sex on these parameters can be weighted. For more information, see the details. +#' +#' @usage StageStructure(Stages, TransMatrix, MaxAge = 100, MinAge = 0, +#' RepSeasons = 1, PRep = 1.0, RepInterval = 0, SurvSched = 0, +#' FecDensDep = FALSE, DevDensDep = FALSE, SurvDensDep = FALSE, +#' FecStageWtsMatrix, DevStageWtsMatrix, SurvStageWtsMatrix, +#' FecLayer, DevLayer, SurvLayer, +#' PostDestructn = FALSE) +#' @param Stages Number of life-stages (integer). Requires a minimum of \eqn{2}, for "juvenile" (stage 0) and "adult". Maximum is 10. +#' @param TransMatrix Transition matrix. Defines the development probabilities from each stage into the next, as well as the respective survival probabilities and fecundities. See Details for matrix structure and notation. +#' @param MaxAge Maximum age in years, defaults to \eqn{100}. (integer) +#' @param MinAge Integer vector containing the ages which an individual in stage \eqn{i-1} (with sex \eqn{m/f}, if applicable) must already have reached before it can develop into the next stage \eqn{(i)}. The defaults are \eqn{0} for all stages and sexes. The required format is described in the Details. +#' @param RepSeasons Number of potential reproduction events per year. Defaults to \eqn{1}. (integer) +#' @param RepInterval Number of reproductive seasons which must be missed following a reproduction attempt, before another reproduction attempt may occur. Defaults to \eqn{0}. (integer) +#' @param PRep Probability of reproducing in subsequent reproductive seasons. Defaults to \eqn{1.0}. +#' @param SurvSched Scheduling of Survival. When should survival and development occur?\cr 0 = At reproduction\cr 1 = Between reproductive events (default)\cr 2 = Annually (only for \code{RepSeasons>1}) +#' @param FecDensDep,DevDensDep,SurvDensDep Density-dependent fecundity / development / survival probabilities? Defaults to \code{FALSE}. See Details for functional form of density-dependence. +#' @param DevDensCoeff,SurvDensCoeff Relative density dependence coefficient for development / survival. Defaults to \eqn{1.0}. +# @param FecStageWts,DevStageWts,SurvStageWts Stage-dependent density dependence in fecundity / development / survival? Defaults to \code{FALSE}. +# @param FecStageWtsMatrix,DevStageWtsMatrix,SurvStageWtsMatrix Required if stage-dependent density dependence, i.e. if respective \code{FecStageWts}/\code{DevStageWts}/\code{SurfStageWts=TRUE}. Takes a quadratic matrix with (#stages * #sexes) rows/columns indicating the weight of the abundance of each sex/stage on the fecundity/development/survival of each other sex/stage. +#' @param FecStageWtsMatrix,DevStageWtsMatrix,SurvStageWtsMatrix Stage-dependent weights in density dependence of fecundity / development / survival. Takes a quadratic matrix with (#sexes * #stages) rows/columns indicating the weight of the abundance of each stage/sex on the fecundity/development/survival of each other stage/sex. If not set, all stages are weighted equally. +#' @param FecLayer,DevLayer,SurvLayer A matrix of layer indices for the three demographic rates (fecundity/development/survival) if they are spatially varying. The indices match the +#' scaling layers given in the \code{\link[RangeShiftR]{ImportedLandscape}} module to each demographic rate. The value NA denotes a spatially constant rate. The row number corresponds +#' to the stage; the first/second column contains the layer index for females/males. In case of a female-only or simple sexual model (\code{ReproductionType={0,1}}) only the first +#' column is needed and a vector is accepted to represent it. In any case, values will be coerced to integer. +#' @param PostDestructn In a dynamic landscape, determine if all individuals of a population should die (\code{FALSE}, default) or disperse (\code{TRUE}) if its patch gets destroyed. +#' @details In stage-structured populations, generations can overlap and individuals can be classified in different stages (e.g. immature vs. breeding individuals) differing in their +#' demographic parameters. Individuals are characterized by their age and stage. Each stage has a certain fecundity, survival probability and probability of developing to the next stage. +#' +#' These parameters are provided through classical transition matrices \insertCite{caswell2001}{RangeShiftR}. +#' \ifelse{html}{\out{φi}}{\eqn{φ_i}} is the fecundity of stage \eqn{i} ; +#' \ifelse{html}{\out{σi}}{\eqn{σ_i}} is the survival probability of an individual in stage \eqn{i} ; +#' and \ifelse{html}{\out{γi-j}}{\eqn{γ_(i-j)}} is the probability of developing from stage \eqn{i} to stage \eqn{j}. +#' In this way, the transition matrix describes the effect of each individuals current stage (column) on all stages at the next timestep (rows). +#' Since all offspring is born into the juvenile stage (stage 0), all fecundities are always located in the first row of the matrix. +#' +#' However, in \emph{RangeShiftR}, these parameters are not used deterministically as \emph{rates} (like it is typical for matrix models) but, instead, as \emph{probabilities} which are +#' applied stochastically at the individual level. Hence, each female at stage \eqn{i}, if it reproduces, produces a number of offspring given by \eqn{Poisson}(\ifelse{html}{\out{φi}}{\eqn{φ_i}}), +#' while Bernoulli trials \eqn{Bern}(\ifelse{html}{\out{σi}}{\eqn{σ_i}}) and \eqn{Bern}(\ifelse{html}{\out{γi,i+1}}{\eqn{γ_(i,i+1)}}) determine if an individual/female survives or not +#' and - if it survives - if it develops to the next stage or not. +#' +#' An example transition matrix for a 3-staged only-female or simple sexual (\code{ReproductionType={0,1}}) population model: +#' \tabular{ccccc}{0 \tab | \tab 0 \tab | \tab \ifelse{html}{\out{φ2}}{\eqn{φ_2}} \cr +#' \eqn{1.0} \tab | \tab \ifelse{html}{\out{σ1 (1-γ1-2)}}{\eqn{σ_1 (1 − γ_(1-2))}} \tab | \tab \eqn{0} \cr +#' \eqn{0} \tab | \tab \ifelse{html}{\out{σ1 γ1-2}}{\eqn{σ_1 γ_(1-2)}} \tab | \tab \ifelse{html}{\out{σ2}}{\eqn{σ_2}} \cr} +#' +#' In a female-only model (\code{ReproductionType=0}), \ifelse{html}{\out{φ}}{\eqn{φ}} represents the number of female offspring per female and reproductive event. \cr +#' Note that for an implicit (simple) sexual model (\code{ReproductionType=1}), the demographic parameters are not sex-specific. However, individuals are defined by their sex, which is acknowledged for example in the dispersal +#' process and transmission of alleles. The fecundities \ifelse{html}{\out{φ}}{\eqn{φ}} refer to the number of all offspring (males and females) per female and reproductive event. +#' +#' In case of an explicit (complex) sexual model (\code{ReproductionType=2}), in contrast, each stage must be represented by two columns and rows to distinguish male and female demographic parameters. +#' Note, however, that in any case the juvenile stage has only one row; it contains the fecundities. Male fecundities should have one of two possible values: set \ifelse{html}{\out{φm}}{\eqn{φ_m}} \eqn{=1.0} for reproductive males or \ifelse{html}{\out{φm}}{\eqn{φ_m}} \eqn{=0.0} for non-reproductive males.\cr +#' An example transition matrix for a 3-staged explicit sexual population model \insertCite{weeks1986,lindstrom1998}{RangeShiftR}: +#' \tabular{ccccccccccc}{\eqn{0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{φ1m}}{\eqn{φ_1m}} \tab | \tab \ifelse{html}{\out{φ1f}}{\eqn{φ_1f}} \tab | \tab \ifelse{html}{\out{φ2m}}{\eqn{φ_2m}} \tab | \tab \ifelse{html}{\out{φ2f}}{\eqn{φ_2f}} \cr +#' \eqn{1.0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1m (1-γ1-2,m)}}{\eqn{σ_1m (1 − γ_(1-2,m))}} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \cr +#' \eqn{0} \tab | \tab \eqn{1.0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1f γ1-2,f}}{\eqn{σ_1f γ_(1-2,f)}} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \cr +#' \eqn{0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1m γ1-2,m}}{\eqn{σ_1m γ_(1-2,m)}} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ2m}}{\eqn{σ_2m}} \tab | \tab \eqn{0} \cr +#' \eqn{0} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1f γ1-2,f}}{\eqn{σ_1f γ_(1-2,f)}} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ2f}}{\eqn{σ_2f}} \cr}#' The mating system is explicitly modelled and a female’s probability of reproducing is determined as described in \code{\link[RangeShiftR]{Demography}} \insertCite{weeks1986,caswell2001}{RangeShiftR}. +#' +#' A common mistake in building a transition matrix is made when offspring produced at year \eqn{t} develop to the next stage in the same year \insertCite{@ @caswell2001 pg. 60-62}{RangeShiftR}. To avoid this problem without losing the offspring stage, and hence the chance for simulating post-natal dispersal, +#' we require an additional explicit juvenile stage (stage 0). Juveniles have to develop to stage 1 in the same year they are born. Hence the minimum number of stages of a stage-structured model is always \eqn{2}. It is important to note that juvenile mortality can be accounted for in +#' two ways. Either, as in the examples above, it is included in adult fecundity \ifelse{html}{\out{φ}}{\eqn{φ}} (by appropriately reducing its value), and \ifelse{html}{\out{σ0 γ(0-1)}}{\eqn{σ_0 γ_(0-1)}} is equal to \eqn{1.0}. This is how it is typically accounted for in matrix models. Or, alternatively, +#' φ is equal to the true maximum fecundity and \ifelse{html}{\out{σ0 γ(0-1)}}{\eqn{σ_0 γ_(0-1)}} is less than \eqn{1.0}. +#' Only the first approach allows straightforward direct comparison with standard analytical matrix models. +#' +#' \emph{Minimum ages:} For every row in the transition matrix, a minimum age must be provided through a vector in argument \code{MinAge}. It specifies the age which an individual in stage \eqn{i-1} (with sex \eqn{m/f}, if applicable) must already have reached before it can develop into the next stage \eqn{(i)}. The vector must be in +#' the order of increasing stage, stating first male then female values; i.e. \eqn{0,1m,1f,2m,2f,...}. Note that (analogous to the transition matrix) the juvenile stage (\eqn{i=0}) has only one entry for male and female. The defaults are \eqn{0} for all stages and sexes. +#' Note that the minimum age for juveniles (stage \eqn{0}) is by definition zero, and that the minimum age for stage \eqn{1} is required to also be zero because individuals may not persist as juveniles beyond the breeding season in which they are born. +#' +#' It is possible to have one or more reproductive seasons per year (\code{RepSeasons}), or a reproductive event once every few years (controlled by \code{RepInterval}). At each reproductive season, two parameters +#' control the likelihood that each individual / female reproduces: +#' \enumerate{ +#' \item First, it is determined whether a reproductively mature female is a potential reproducer. The user specifies a minimum interval (\code{RepInterval}) before an individual, that has +#' already reproduced, is able to reproduce again. Only those mature individuals that are either yet to reproduce, or last reproduced more than this number of reproductive seasons previously, are potential breeders. +#' \item Potential breeders all reproduce with a set probability (\code{PRep}). Note that this probability is different from the probability of reproducing \ifelse{html}{\out{pr}}{\eqn{p_r}} described in \code{\link[RangeShiftR]{Demography}}. +#' The latter will be additionally applied only in the case of more complex modelling of the mating system (\code{ReproductionType=2}) and it is determined by the number of reproductive males and females present in the cell/patch. +#' } +#' Note that in the current implementation, reproductive attempts that result in zero offspring still count in terms of an individual having to wait for the chance to reproduce again. +#' +#' A major difference between transition matrices and this individual-based model is that in the first, the three processes of reproduction, survival and development happen simultaneously while, in the second, they are explicitly modelled in sequence. +#' The sequence of these events and the time of the dispersal phase in relation to them can change the actual dynamics and density-dependencies in both population growth and dispersal. At the beginning of each year, reproduction is always the first +#' process to be modelled. However, there can be multiple reproductive seasons per year (default is one); in this case the year starts with a succession of all reproductive seasons. There are three choices for the scheduling of reproduction, survival, development and dispersal: +#' \itemize{ +#' \item \code{SurvSched=0}: For each reproductive season: reproduction; survival and development of all stages (apart from stage 0); dispersal; survival and development of stage 0. Then: aging; end of the year. +#' \item \code{SurvSched=1}: For each reproductive season: reproduction; dispersal; survival and successive development of all stages. Then: aging; end of the year. +#' \item \code{SurvSched=2}: For each reproductive season: reproduction; dispersal. Then: survival and development of all stages; aging; end of the year. This option applies only for species having multiple reproductive seasons in a year, otherwise it is equivalent to \code{SurvSched=1}. +#' } +#' Option \code{SurvSched=0} gives results that are comparable with the deterministic solution of the matrix. The choice will depend on the biology of the species. If the main mortality happens overwinter, option \code{SurvSched=1} might be more appropriate. +#' +#' Note that \code{SurvSched=1} in combination with multiple reproductive seasons (\code{RepSeasons>1}) implies several evaluations of the fecundity and the survival and development probabilities, so that the transition matrix should be set accordingly. +#' If the transition matrix contains the annual survival and development rates, \code{SurvSched=2} is the appropriate option (fecundity, however, is still given per reproductive event). +#' +#' \emph{Density dependence} can act on each of the three demographic phases (i.e. reproduction, survival and development) and is controlled by \code{FecDensDep,DevDensDep,SurvDensDep}. +#' It is implemented as an exponential decay \insertCite{neubert2000}{RangeShiftR}: +#' +#' \ifelse{html}{\out{   φi(r,t) = φ0,i * e - b(r) N(t) }}{\deqn{φ_i(r,t)=φ_(0,i) * exp(- b(r) N(t) ) }} +#' +#' \ifelse{html}{\out{   σi(r,t) = σ0,i * e - Cσ b(r) N(t) }}{\deqn{σ_i(r,t)=σ_(0,i) * exp(- C_\sigma b(r) N(t) ) }} +#' +#' \ifelse{html}{\out{   γi(r,t) = γ0,i * e - Cγ b(r) N(t) }}{\deqn{γ_i(r,t)=γ_(0,i) * exp(- C_γ b(r) N(t) ) }} +#' +#' where \eqn{b(r)} is the strength of density dependence in fecundity at site \eqn{r}, which is given by the argument \code{K_or_DensDep} in the landscape module. +#' Furthermore, \ifelse{html}{\out{Cσ}}{\eqn{C_\sigma}} and \ifelse{html}{\out{Cγ}}{\eqn{C_γ}} (\code{DevDensCoeff,SurvDensCoeff}) +#' scale the strength of density dependence in survival and development relative to that in fecundity. +#' +#' Moreover, the strength of density-dependence can be uniform for all stages or stage-dependent. Even greater complexity can be incorporated with +#' different stages contributing differently to density-dependence \insertCite{caswell2004}{RangeShiftR}: +#' +#' \ifelse{html}{\out{  φi(r,t) = φ0,i * e - b(r) ΣjS ωφ,ij N(j,t)}}{\deqn{φ_i(r,t)=φ_(0,i) * exp(- b(r) \Sigma_j^S ω_{φ,ij} N_j(t) ) }} +#' +#' \ifelse{html}{\out{  σi(r,t) = σ0,i * e - Cσ b(r) ΣjS ωσ,ij N(j,t) }}{\deqn{σ_i(r,t)=σ_(0,i) * exp(- C_\sigma b(r) \Sigma_j^S ω_{σ,ij} N_j(t) )}} +#' +#' \ifelse{html}{\out{  γi(r,t) = γ0,i * e - Cγ b(r) ΣjS ωγ,ij N(j,t)}}{\deqn{γ_i(r,t)=γ_(0,i) * exp(- C_γ b(r) \Sigma_j^S ω_{γ,ij} N_j(t) )}} +#' +#' where \ifelse{html}{\out{ωφ}}{\eqn{ω_φ}}, \ifelse{html}{\out{ωσ}}{\eqn{ω_σ}}, \ifelse{html}{\out{ωγ}}{\eqn{ω_γ}} are weight matrices given by \code{FecStageWtsMatrix, DevStageWtsMatrix, SurvStageWtsMatrix}. Their elements \ifelse{html}{\out{ωij}}{\eqn{ω_ij}} +#' represent the contributions of the abundance of stage \eqn{j} to the density dependence in the fecundity / survival / development of stage \eqn{i}, thus they are quadratic matrices of size \code{Stages}\eqn{^2}. Note that the row sums are not required to be normalized, therefore they can be used +#' to scale the density-dependence for the different stages. In fact, any real value will be accepted for the single weights, so care should be taken when setting them. +#' +#' The demographic rates (fecundity, development probability and survival probability) can be allowed to vary spatially, if the landscape is an imported habitat quality map. In this case, additional maps with the same resolution and extent as the habitat quality map(s) need to be given +#' in \code{\link[RangeShiftR]{ImportedLandscape}()}. These additional layers contain percentage values between 0 and 100 and the matrices \code{FecLayer}, \code{DevLayer}, and \code{SurvLayer} indicate the mapping of each demographic rate to these layers. The local value +#' of a given demographic rate for a certain stage and sex in a cell or patch is then determined as the maximum value (the value given in the transition matrix \code{TransMatrix}) scaled with the percentage in the respective mapped layer. +#' For a patch-based landscape, the scaling percentage of a patch is given by the average percentage of its constituent cells. +#' Potential density-dependence mediated by the strength 1/b still takes effect also for spatially-varying demographic rates. The respective base values φ_0, σ_0 or γ_0 are then replaced by their locally scaled values. +#' @examples # Stage-structure for simple sexual model +#' transmat <- matrix(c(0,1,0,0,0,0.3,0.4,0,1.5,0,0.6,0.3,2.5,0,0,0.8), ncol = 4) +#' stg <- StageStructure(Stages = 4, TransMatrix = transmat, FecDensDep = TRUE, SurvDensDep = TRUE, SurvDensCoeff = 1.5) +#' plotProbs(stg, stage=1:3) +#' +#' # Stage-structure for explicit sexual model +#' transmat_2 <- matrix(c(0,0.5,0,0,0,0,0,0.5,0,0,1.0,0.4,0,0.3,0,3.0,0,0.3,0,0.4,1.0,0,0,0.85,0,5,0,0,0,0.8), ncol = 6) +#' stg_2 <- StageStructure(Stages = 3, TransMatrix = transmat_2, FecDensDep = TRUE, DevDensDep = TRUE, DevDensCoeff = 1.2) +#' plotProbs(stg_2, stage=c(1,2), sex = 1) +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "StagesParams" +#' @author Anne-Kathleen Malchow +#' @name StageStructure +#' @export StageStructure +StageStructure <- setClass("StagesParams", slots = c(Stages = "integer_OR_numeric", + TransMatrix = "matrix", + MaxAge = "integer_OR_numeric", + MinAge = "integer_OR_numeric", + RepSeasons = "integer_OR_numeric", # No. of reproductive seasons per year + RepInterval = "integer_OR_numeric", + PRep = "numeric", + SurvSched = "integer_OR_numeric", + FecDensDep = "logical", + FecStageWts = "logical", + FecStageWtsMatrix = "matrix", + DevDensDep = "logical", + DevDensCoeff = "integer_OR_numeric", + DevStageWts = "logical", + DevStageWtsMatrix = "matrix", + SurvDensDep = "logical", + SurvDensCoeff = "integer_OR_numeric", + SurvStageWts = "logical", + SurvStageWtsMatrix = "matrix", + FecLayer = "matrix_OR_numeric", + DevLayer = "matrix_OR_numeric", + SurvLayer = "matrix_OR_numeric", + PostDestructn = "logical") + , prototype = list(#Stages = 2L, + #TransMatrix = matrix(data = NA, nrow = 1, ncol = 1), + MaxAge = 100L, + MinAge = 0L, + RepSeasons = 1L, + RepInterval = 0L, + PRep = 1.0, + SurvSched = 1L, + FecDensDep = FALSE, + FecStageWts = FALSE, + #FecStageWtsMatrix = matrix(data = NA, nrow = 1, ncol = 1), + DevDensDep = FALSE, + DevDensCoeff = 1.0, + DevStageWts = FALSE, + #DevStageWtsMatrix = matrix(data = NA, nrow = 1, ncol = 1), + SurvDensDep = FALSE, + SurvDensCoeff = 1.0, + SurvStageWts = FALSE, + #SurvStageWtsMatrix = matrix(data = NA, nrow = 1, ncol = 1), + #FecLayer,DevLayer,SurvLayer, + PostDestructn = FALSE) +) + # check forbidden transitions in TransMatrix (e.g. between non-successive stages or between sexes) +setValidity("StagesParams", function(object) { + msg <- NULL + if (anyNA(object@Stages) || length(object@Stages)!=1) { + msg <- c(msg, "Number of Stages must be set and of length 1!") + } + else { + if (object@Stages<2) { + msg <- c(msg, "Number of Stages must be at least 2!") + } + } + if (anyNA(object@TransMatrix)) { + msg <- c(msg, "Transition matrix must be given!") + } + else { + if (any(object@TransMatrix[-1, ] < 0 ) || any(object@TransMatrix[-1, ] > 1 ) ) { + msg <- c(msg, "All elements exept the first row of the transition matrix must be between 0 and 1!") + } + if (any(object@TransMatrix[ 1, ] < 0 ) ) { + msg <- c(msg, "All elements in the first row of the transition matrix (i.e. the fecundities) must be positive!") + } + } + if (anyNA(object@MaxAge) || length(object@MaxAge)!=1) { + msg <- c(msg, "MaxAge must be set and of length 1!") + } + else { + if (object@MaxAge<2) { + msg <- c(msg, "MaxAge must be greater than 1!") + } + } + if (anyNA(object@MinAge) || length(object@MinAge)==0) { + msg <- c(msg, "MinAge must be set!") + } + else { + if (any(object@MinAge<0)) { + msg <- c(msg, "MinAge must be positive!") + } + if (any(object@MinAge>=object@MaxAge)) { + msg <- c(msg, "MinAge must be smaller than MaxAge for all stages and sexes!") + } + } + if (anyNA(object@RepSeasons) || length(object@RepSeasons)!=1) { + msg <- c(msg, "RepSeasons must be set and of length 1!") + } + else { + if (object@RepSeasons<1) { + msg <- c(msg, "RepSeasons must be at least 1!") + } + } + if (anyNA(object@RepInterval) || length(object@RepInterval)!=1) { + msg <- c(msg, "RepInterval must be set and of length 1!") + } + else { + if (object@RepInterval<0) { + msg <- c(msg, "RepInterval must be positive!") + } + } + if (anyNA(object@PRep) || length(object@PRep)!=1) { + msg <- c(msg, "PRep must be set and of length 1!") + } + else { + if (object@PRep <= 0 || object@PRep > 1.0) { + msg <- c(msg, "PRep must in the half-open interval (0;1]!") + } + } + if (anyNA(object@SurvSched) || length(object@SurvSched)!=1) { + msg <- c(msg, "SurvSched must be set and of length 1!") + } + else { + if (! object@SurvSched %in% (0:2) ) { + msg <- c(msg, "SurvSched must be 0, 1 or 2!") + } + } + if (anyNA(object@FecDensDep) || length(object@FecDensDep)!=1) { + msg <- c(msg, "FecDensDep must be set and of length 1!") + } + else{ + if(object@FecDensDep) { + if (anyNA(object@FecStageWts) || length(object@FecStageWts)!=1) { + msg <- c(msg, "FecStageWts must be set and of length 1!") + } + else{ + if (object@FecStageWts) { + if (anyNA(object@FecStageWtsMatrix)) { + msg <- c(msg, "FecStageWtsMatrix must be set (since FecStageWts = TRUE) !") + } + # else { + # if(any(object@FecStageWtsMatrix < 0)){ + # msg <- c(msg, "All elements of FecStageWtsMatrix must be positive or zero!") + # } + # } + } + } + } + } + if (anyNA(object@DevDensDep) || length(object@DevDensDep)!=1) { + msg <- c(msg, "DevDensDep must be set and of length 1!") + } + else{ + if(object@DevDensDep) { + if (anyNA(object@DevDensCoeff) || length(object@DevDensCoeff)!=1) { + msg <- c(msg, "DevDensCoeff must be set and of length 1!") + } + else { + if (object@DevDensCoeff<=0) { + msg <- c(msg, "DevDensCoeff must be greater than zero!") + } + } + if (anyNA(object@DevStageWts) || length(object@DevStageWts)!=1) { + msg <- c(msg, "DevStageWts must be set and of length 1!") + } + else{ + if (object@DevStageWts) { + if (anyNA(object@DevStageWtsMatrix)) { + msg <- c(msg, "DevStageWtsMatrix must be set (since DevStageWts = TRUE) !") + } + # else { + # if(any(object@DevStageWtsMatrix < 0)){ + # msg <- c(msg, "All elements of DevStageWtsMatrix must be positive or zero!") + # } + # } + } + } + } + } + if (anyNA(object@SurvDensDep) || length(object@SurvDensDep)!=1) { + msg <- c(msg, "SurvDensDep must be set and of length 1!") + } + else{ + if(object@SurvDensDep){ + if (anyNA(object@SurvDensCoeff) || length(object@SurvDensCoeff)!=1) { + msg <- c(msg, "SurvDensCoeff must be set and of length 1!") + } + else { + if (object@SurvDensCoeff<=0) { + msg <- c(msg, "SurvDensCoeff must be greater than zero!") + } + } + if (anyNA(object@SurvStageWts) || length(object@SurvStageWts)!=1) { + msg <- c(msg, "SurvStageWts must be set and of length 1!") + } + else{ + if (object@SurvStageWts) { + if (anyNA(object@SurvStageWtsMatrix)) { + msg <- c(msg, "SurvStageWtsMatrix must be set (since SurvStageWts = TRUE) !") + } + # else{ + # if(any(object@SurvStageWtsMatrix < 0)){ + # msg <- c(msg, "All elements of SurvStageWtsMatrix must be positive or zero!") + # } + # } + } + } + } + } + if (length(object@FecLayer)>0) { + if( any( !is.na( object@FecLayer[object@FecLayer<=0] ))) { + msg <- c(msg, "Elements of FecLayer must be strictly postive integers or NA for no spatial variation!") + } + if( min(nrow(object@FecLayer),length(object@FecLayer)) != object@Stages) { + msg <- c(msg, "FecLayer must have as many rows as Stages!") + } + } + if (length(object@DevLayer)>0) { + if( any( !is.na( object@DevLayer[object@DevLayer<=0] ))) { + msg <- c(msg, "Elements of DevLayer must be strictly postive integers or NA for no spatial variation!") + } + if( min(nrow(object@DevLayer),length(object@DevLayer)) != object@Stages) { + msg <- c(msg, "DevLayer must have as many rows as Stages!") + } + } + if (length(object@SurvLayer)>0) { + if( any( !is.na( object@SurvLayer[object@SurvLayer<=0] ))) { + msg <- c(msg, "Elements of SurvLayer must be strictly postive integers or NA for no spatial variation!") + } + if( min(nrow(object@SurvLayer),length(object@SurvLayer)) != object@Stages) { + msg <- c(msg, "SurvLayer must have as many rows as Stages!") + } + } + if (is.na(object@PostDestructn) || length(object@PostDestructn)!=1) { + msg <- c(msg, "PostDestructn must be set and of length 1!") + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "StagesParams", function(.Object,...) { + this_func = "StageStructure(): " + args <- list(...) + #set weights switches if matrix is given + if (!is.null(args$FecStageWtsMatrix)) { + .Object@FecStageWts <- TRUE + } + if (!is.null(args$DevStageWtsMatrix)) { + .Object@DevStageWts <- TRUE + } + if (!is.null(args$SurvStageWtsMatrix)) { + .Object@SurvStageWts <- TRUE + } + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (!.Object@FecDensDep) { + if (.Object@FecStageWts) { + warning(this_func, "FecStageWts stage weigths", warn_msg_ignored, "since FecDensDep = FALSE.", call. = FALSE) + } + } + if (!.Object@DevDensDep) { + if (!is.null(args$DevDensCoeff)) { + warning(this_func, "DevDensCoeff", warn_msg_ignored, "since DevDensDep = FALSE.", call. = FALSE) + } + if (.Object@DevStageWts) { + warning(this_func, "DevStageWts stage weigths", warn_msg_ignored, "since DevDensDep = FALSE.", call. = FALSE) + } + } + if (!.Object@SurvDensDep) { + if (!is.null(args$SurvDensCoeff)) { + warning(this_func, "SurvDensCoeff", warn_msg_ignored, "since SurvDensDep = FALSE.", call. = FALSE) + } + if (.Object@SurvStageWts) { + warning(this_func, "SurvStageWts stage weigths", warn_msg_ignored, "since SurvDensDep = FALSE.", call. = FALSE) + } + } + # replace NAs & convert to matrix + if (!is.null(args$FecLayer)) { + #.Object@FecLayer[is.na(.Object@FecLayer)] <- -9 + if(class(.Object@FecLayer)[1]!="matrix") .Object@FecLayer <- matrix(.Object@FecLayer) + } + if (!is.null(args$DevLayer)) { + #.Object@DevLayer[is.na(.Object@DevLayer)] <- -9 + if(class(.Object@DevLayer)[1]!="matrix") .Object@DevLayer <- matrix(.Object@DevLayer) + } + if (!is.null(args$SurvLayer)) { + #.Object@SurvLayer[is.na(.Object@SurvLayer)] <- -9 + if(class(.Object@SurvLayer)[1]!="matrix") .Object@SurvLayer <- matrix(.Object@SurvLayer) + } + # convert to integer + if(length(.Object@FecLayer)>0) mode(.Object@FecLayer) <- "integer" + if(length(.Object@DevLayer)>0) mode(.Object@DevLayer) <- "integer" + if(length(.Object@SurvLayer)>0) mode(.Object@SurvLayer) <- "integer" + .Object} +) +setMethod("show", "StagesParams", function(object){ + cat(" Stages :", paste(object@Stages), "\n") + cat(" Transition matrix:\n") + print(object@TransMatrix) + cat(" Maximum age :", paste(object@MaxAge) , "\n") + cat(" Minimum age :", paste(object@MinAge) , "\n") + cat(" Reprod. seasons :", paste(object@RepSeasons) , "\n") + cat(" Prob. Reprod. :", paste(object@PRep) , "\n") + cat(" Reprod. Intervals:", paste(object@RepInterval) , "\n") + cat(" SurvScheduling :", paste(object@SurvSched) , "\n") + if (object@FecDensDep || object@DevDensDep || object@SurvDensDep) { + cat(" Density-dependence in:\n") + } + if (object@FecDensDep) { + cat(" - Fecundity\n") + if (object@FecStageWts) { + cat(" with stage-dependent density depedence with weights:\n") + print(object@FecStageWtsMatrix) + } + } + if (object@DevDensDep) { + cat(" - Development, with coefficient = ", paste(object@DevDensCoeff) , "\n") + if (object@DevStageWts) { + cat(" and stage-dependence with weights: \n") + print(object@DevStageWtsMatrix) + } + } + if (object@SurvDensDep) { + cat(" - Survival, with coefficient =", paste(object@SurvDensCoeff) , "\n") + if (object@SurvStageWts) { + cat(" and stage-dependence with weights: \n") + print(object@SurvStageWtsMatrix) + } + } + if(length(object@FecLayer)>0) { + cat(" Spatially varying fecundity layer indices:\n") + print(object@FecLayer) + } + if(length(object@DevLayer)>0) { + cat(" Spatially varying development layer indices:\n") + print(object@DevLayer) + } + if(length(object@SurvLayer)>0) { + cat(" Spatially varying survival layer indices:\n") + print(object@SurvLayer) + } + cat(" PostDestructn :", paste(object@PostDestructn) ) + if (object@PostDestructn) { + cat(" (all disperse)\n") + } + else { + cat(" (all die)\n") + } + cat ("\n")} +) +setMethod("plotProbs", "StagesParams", function(x, stage = NULL, sex = NULL, xmax = NULL, ymax = NULL){ + lines <- dim(x@TransMatrix)[2] + if (lines==x@Stages) {SexDep = FALSE} + else if (lines==(2*x@Stages)) {SexDep = TRUE} + else { + print("Wrong format of transition matrix.\n") + return(NULL) + } + fecs <- x@TransMatrix[1,] + if (SexDep) { + surv <- devs <- rep(0,lines) + for(s in 1:lines ){ + if(s==1) ss <- x@TransMatrix[s,s] else ss <- x@TransMatrix[s-1,s] + if((s+2)>lines) dd <- 0 else dd <- x@TransMatrix[s+1,s] + surv[s] <- ss+dd + devs[s] <- dd/(ss+dd) + } + } + else { # !SexDep + if (!is.null(sex)) print("This stage structure has no sex-dependency.\n") + surv <- devs <- rep(0,lines) + for(s in 1:lines ){ + ss <- x@TransMatrix[s,s] + if(s!=lines) dd <- x@TransMatrix[s+1,s] else dd <- 0 + surv[s] <- ss+dd + devs[s] <- dd/(ss+dd) + } + } + if (is.null(stage)){stage <- 0:10} + if (is.null(sex)){sex <- 0:1} + # New plot + if (is.null(xmax)) {xmax = 4.0} + xvals = seq(0, xmax, length.out = 100) + if (is.null(ymax)) { ymax = max(1.0,fecs) } + plot(NULL, type = "n", ylab = "Fecundity, Survival, Development", xlab = "relative population density bN", xlim = c(0,xmax), ylim = c(0,ymax)) + leg.txt <- leg.col <- c() + for(line in 1:lines ){ + if (SexDep) { + this.stage = as.integer(line/2-0.1) + this.sex = (line+1)%%2 + } + else { + this.stage = line-1 + this.sex = 0 + } + if (this.stage %in% stage && this.sex %in% sex) { + if(x@FecDensDep){ lines(xvals, fecs[line]*exp(-xvals), type = "l", lty = 1, col = line) } + else{ lines(xvals, rep(fecs[line], length(xvals)), type = "l", lty = 1, col = line) } + if(x@SurvDensDep){ lines(xvals, surv[line]*exp(-x@SurvDensCoeff*xvals), type = "l", lty = 2, col = line) } + else{ lines(xvals, rep(surv[line], length(xvals)), type = "l", lty = 2, col = line) } + if(x@DevDensDep){ lines(xvals, devs[line]*exp(-x@DevDensCoeff*xvals), type = "l", lty = 3, col = line) } + else{ lines(xvals, rep(devs[line], length(xvals)), type = "l", lty = 3, col = line) } + if(SexDep) {leg.txt <- c(leg.txt, paste0("Stage ",this.stage, ifelse(this.sex," female"," male")))} + else {leg.txt <- c(leg.txt, paste0("Stage ",this.stage))} + leg.col <- c(leg.col, line) + } + } + if (length(leg.txt)>0) { + leg.txt <- c("Fecundity","Survival prob.","Developmt. prob.",leg.txt) + legend("topright", leg.txt, col = c(rep(1,3),leg.col), lwd = 1.5, lty = c(1:3,rep(1,length(leg.col))) ) + } +}) + + +#### CLASS DEMOGRAPHY + +# contains basic demographic parameters (originally in RS 'Rarameters'-file) and optionally the 'StageStruct' object + +# define this ClassUnion so that the 'stages' slot in the parameter master class 'RSparams' can be FALSE for option 'population with non-overlapping generations' +setClassUnion("StagesSlot", c("logical", "StagesParams")) + +#' Set Demographic Parameters +#' +#' For a simple non-structured population, set its basic demographic parameters here, i.e. the maximum growth rate (\code{Rmax}) and the competition coefficient (\code{bc}). +#' For a stage-structured population, define its corresponding parameters via \code{\link[RangeShiftR]{StageStructure}} and add it to Demography.\cr +#' \cr +#' Choose the Reproduction model that determines if sexes are considered implicitly or explicitly and if a mating system is used. If applicable, set the corresponding parameters, i.e. the proportion of males (\code{PropMales}) and the maximum harem size (\code{Harem}). +#' +#' @usage Demography(Rmax, bc = 1.0, StageStruct = FALSE, +#' ReproductionType = 0, PropMales = 0.5, Harem = 1) +#' @param Rmax Maximum growth rate. Describes the mean number of offspring per female and reproductive event at very low density. Only required if \code{StageStruct=FALSE}. +#' @param bc Competition coefficient. Describes the type of density regulation, providing the possibility for under-compensatory (\eqn{b_c < 1}), compensatory (\eqn{b_c = 1}) (default) or over-compensatory (\eqn{b_c > 1}) dynamics. Only required if \code{StageStruct=FALSE}. +#' @param StageStruct \code{FALSE} (default) yields a population model with non-overlapping generations.\cr For a stage-structured population, this takes the corresponding parameter object generated by \code{\link[RangeShiftR]{StageStructure}}, which holds all demographic parameters. +#' @param ReproductionType 0 = asexual / only female model (default)\cr1 = simple sexual model\cr2 = sexual model with explicit mating system +#' @param PropMales Required if \code{ReproductionType={1,2}}: Proportion of males in the population, between \eqn{0} and \eqn{1}. Defaults to \eqn{0.5}. +#' @param Harem Required if \code{ReproductionType=2}: Maximum harem size. The maximum number of pair bonds that a male can establish. \eqn{Harem = 1} (default) corresponds to monogamy, \eqn{01} to polygyny. +#' @details The following information regards the population dynamics of a \strong{non-structured} (\code{StageStruct=FALSE}) population.\cr +#' For more information on the population dynamics of a \strong{structured} population, see \code{\link[RangeShiftR]{StageStructure}}. +#' +#' Populations with non-overlapping generations, i.e. with \strong{no stage-structure} are the appropriate way to model species that have discrete generations. +#' At each generation the life cycle comprises - in that order - reproduction, death of the adults and offspring dispersal. +#' Two parameters determine the nature of the demographic density dependence: +#' the carrying capacity \eqn{K} (given by the argument \code{K_or_DensDep} in the landscape module) and +#' the competition coefficient \eqn{b_c} (given by the argument \code{bc}). +#' These discrete generation models can be applied to asexual species, species for which it is assumed that females play the dominant role in spatial dynamics +#' and for species for which it is considered crucial to model both sexes explicitly. +#' +#' \emph{Asexual / only-female models:} (\code{ReproductionType=0})\cr +#' Recruitment is determined by a stochastic, individual-based formulation of the \insertCite{smith1973;textual}{RangeShiftR} population model, where the number of offspring produced by a single individual in the cell/patch \eqn{i} at time \eqn{t}, is drawn from the following distribution:\cr +#' +#' \ifelse{html}{\out{  Njuv(i,t) = Poisson( R(i,t) / (1+|R(i,t) - 1| * (N(i,t) / K(i,t))bc ) ) } }{\deqn{N_juv(i,t) = Poisson( R(i,t) / (1 + |R(i,t) - 1|*( N(i,t) / K(i,t) )^bc ) ) } } +#' +#' Here, \eqn{R(i,t)} is the maximum growth rate \code{Rmax} (obtained at very low density only) and \eqn{K(i,t)} is the carrying capacity +#' at patch \eqn{i} and time \eqn{t}. +#' Both \eqn{R(i,t)} and \eqn{K(i,t)} can vary in space and time, depending on the model setting. \ifelse{html}{\out{bc}}{\eqn{b_c}} +#' is the competition coefficient which describes the type of density regulation, providing the possibility for under-compensatory +#' (\ifelse{html}{\out{bc < 1}}{\eqn{b_c < 1}}), compensatory (\ifelse{html}{\out{bc = 1}}{\eqn{b_c = 1}}) or +#' over-compensatory (\ifelse{html}{\out{bc > 1}}{\eqn{b_c > 1}}) dynamics.\cr +#' \cr +#' \emph{Sexual models}\cr +#' In this type of models, individuals are explicitly characterized by their sex. The proportion of each sex in the population is controlled by setting the proportion of males (\code{PropMales}). There are two types of possible sexual sub-models:\cr +#' \cr +#' \emph{Simple mating system:} (\code{ReproductionType=1})\cr +#' This is the simplest form of mate limitation. Each female individual is assumed to mate, as long as there is at least one male in the population. As for the asexual case, the Maynard Smith and Slatkin model is used to determine the expected number of +#' offspring produced by each female. To maintain equivalence between the asexual and sexual versions, the expected value of the Poisson distribution is multiplied by \eqn{2} (Lindström & Kokko 1998):\cr +#' +#' \ifelse{html}{\out{  Njuv(i,t) = Poisson( 2 R(i,t) / (1+|R(i,t) - 1| * (N(i,t) / K(i,t) )bc ) ) } }{\deqn{N_juv(i,t) = Poisson( 2 R(i,t) / (1 + |R(i,t) - 1|*( N(i,t) / K(i,t) )^bc ) ) } } +#' +#' \emph{Complex mating system:} (\code{ReproductionType=2})\cr +#' More complex and flexible mating system. Mating is explicitly modelled through a mating function +#' \insertCite{lindstrom1998,legendre2004,bessa2010}{RangeShiftR}, where the number of mated females \eqn{c} is given by: +#' \deqn{c = f * min(1, 2hm/(f+hm) )} +#' where \eqn{f} and \eqn{m} are the numbers of potentially reproductive females and males, respectively, and \eqn{h} is the maximum harem size \code{Harem}, i.e. the maximum number of pair bonds that a male can establish. \eqn{h=1} corresponds to monogamy, \eqn{01} to polygyny. Each potentially reproductive female has a probability of reproducing \ifelse{html}{\out{pr}}{\eqn{p_r}} given by: +#' \deqn{p_r=c/f} +#' A Bernoulli trial \eqn{Bern}\ifelse{html}{\out{(pr)}}{\eqn{(p_r)}} determines if the female reproduces or not. For females that reproduce, the number of offspring is determined through the Poisson distribution as stated above. Hence, the specification of the mating system determines the probability for each female to reproduce. However, no explicit pair bonds are formed, and in the cases where traits inheritance is +#' involved, the father (of all the offspring produced by a single female in a single reproductive event) is selected randomly from the males in the population.\cr +#' \cr +#' Populations with overlapping generations, i.e. with \strong{with stage-structure} are the appropriate choice for species in which generations can overlap and individuals can be classified in different stages +#' (e.g. immature vs. breeding individuals) differing in their demographic parameters. Individuals are characterized by their age and stage. Each stage has a certain fecundity (which will be used as expected value of the Poisson distribution for reproduction), survival +#' and probability of developing to the next stage. The parameters are provided as classical transition matrices \insertCite{caswell2001}{RangeShiftR} through a \code{\link[RangeShiftR]{StageStructure}} +#' parameter object. For more information on the population dynamics in this case, see the details there. +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "DemogParams" +#' @author Anne-Kathleen Malchow +#' @name Demography +#' @export Demography +Demography <- setClass("DemogParams", slots = c(Rmax = "integer_OR_numeric", + bc = "numeric", + StageStruct = "StagesSlot", + ReproductionType = "integer_OR_numeric", + PropMales = "numeric", + Harem = "integer_OR_numeric") + , prototype = list(#Rmax = 1.5, + bc = 1.0, + StageStruct = FALSE, + ReproductionType = 0L, + PropMales = 0.5, + Harem = 1L) +) +setValidity("DemogParams", function(object) { + msg <- NULL + if (anyNA(object@ReproductionType) || length(object@ReproductionType)!=1) { + msg <- c(msg, "ReproductionType must be set and of length 1!") + } + else { + if (! object@ReproductionType %in% (0:2) ) { + msg <- c(msg, "ReproductionType must be 0, 1 or 2!") + } + else{ + if (object@ReproductionType) { + if (anyNA(object@PropMales) || length(object@PropMales)!=1) { + msg <- c(msg, "Proportion of males must be set and of length 1!") + } + else { + if (object@PropMales <= 0.0 || object@PropMales >= 1.0) { + msg <- c(msg, "Proportion of males must be in the open interval (0,1)!") + } + } + } + if (object@ReproductionType==2) { + if (anyNA(object@Harem) || length(object@Harem)!=1) { + msg <- c(msg, "Maximum harem size must be set and of length 1!") + } + else { + if (object@Harem<=0) { + msg <- c(msg, "Maximum harem size must be positive!") + } + } + } + } + } + validObject(object@StageStruct) + if (class(object@StageStruct)[1]=="logical") { + if (object@StageStruct) { # StageStruct=TRUE + msg <- c(msg, "StageStruct must either be FALSE or an object of class \"StagesParams\" !") + } + else { # StageStruct=FALSE + if (anyNA(object@Rmax) || length(object@Rmax)!=1) { + msg <- c(msg, "Maximum growth rate Rmax must be set for a non-structured population!") + } + else { + if (object@Rmax<=0) { + msg <- c(msg, "Maximum growth rate Rmax must be positive!") + } + } + if (anyNA(object@bc) || length(object@bc)!=1) { + msg <- c(msg, "Competition coefficient bc must be set for a non-structured population!") + } + else { + if (object@bc<=0) { + msg <- c(msg, "Competition coefficient bc must be positive!") + } + } + } + } + else{ + if (class(object@StageStruct)[1]=="StagesParams") { #stage-structured model + stgs <- object@StageStruct@Stages + if (object@ReproductionType == 2) { # explicit sexual model + if ( any(dim(object@StageStruct@TransMatrix)!=c(2*stgs-1,2*stgs) )) { + msg <- c(msg, "Transition Matrix must have dimensions 2*\'Stages\'-1 x 2*\'Stages\' !") + } + else { # check transition matrix + if (any(object@StageStruct@TransMatrix[1,1:2]!=0) ) { + msg <- c(msg, "Transition Matrix: Fecundity of juvenile stage must be zero!") + } + if (any(object@StageStruct@TransMatrix[1,]<0) ) { + msg <- c(msg, "Transition Matrix: Fecunditiy must be positive or zero!") + } + if (any(object@StageStruct@TransMatrix[-1,]<0) || any(object@StageStruct@TransMatrix[-1,]>1) ) { + msg <- c(msg, "Transition Matrix: All transition probabilities must be in the closed interval [0,1]") + } + else{ # passed first line of tests + for (ss in 1:2){ + if (any(object@StageStruct@TransMatrix[-(ss+1),ss]!=0)) { + msg <- c(msg, "Transition Matrix: Found non-zero entries (in juvenile) where zeroes are expected!") + } + } + if (stgs>2){ + for (ss in 3:((stgs-1)*2)){ + if (sum(object@StageStruct@TransMatrix[c((ss-1),(ss+1)),ss])>1) { + msg <- c(msg, "Transition Matrix: Sum of probabilities to stay in current stage and to develop can't exceed 1!") + } + if (any(object@StageStruct@TransMatrix[-c(1,(ss-1),(ss+1)),ss]!=0)) { + msg <- c(msg, "Transition Matrix: Found non-zero entries where zeroes are expected!") + } + } + } + for (ss in (stgs*2-1):(stgs*2)){ + if (any(object@StageStruct@TransMatrix[-c(1,(ss-1)),ss]!=0)) { + msg <- c(msg, "Transition Matrix: Found non-zero entries where zeroes are expected!") + } + } + } + } + if (length(object@StageStruct@MinAge)==1 && object@StageStruct@MinAge==0) { + # do nothing and figure out a way to set as default a null vector of the correct length + } + else { + if (length(object@StageStruct@MinAge)!=(2*stgs-1)) { + msg <- c(msg, "Minimum Age vector must have dimensions 2*\'Stages\'-1 !") + } + else{ + if (any(object@StageStruct@MinAge[1:2]!=0) ) { + msg <- c(msg, "MinAge of stages 0 and 1 must be zero!") + } + if (any(object@StageStruct@MinAge<0)) { + msg <- c(msg, "MinAge must be positive!") + } + } + } + if (object@StageStruct@FecStageWts) { + if (!anyNA(object@StageStruct@FecStageWtsMatrix)) { + if ( any(dim(object@StageStruct@FecStageWtsMatrix)!=c(2*stgs,2*stgs) )) { + msg <- c(msg, "FecStageWtsMatrix must have dimensions 2*\'Stages\' x 2*\'Stages\' !") + } + } + } + if (object@StageStruct@DevStageWts) { + if (!anyNA(object@StageStruct@DevStageWtsMatrix)) { + if ( any(dim(object@StageStruct@DevStageWtsMatrix)!=c(2*stgs,2*stgs) )) { + msg <- c(msg, "DevStageWtsMatrix must have dimensions 2*\'Stages\' x 2*\'Stages\' !") + } + } + } + if (object@StageStruct@SurvStageWts) { + if (!anyNA(object@StageStruct@SurvStageWtsMatrix)) { + if ( any(dim(object@StageStruct@SurvStageWtsMatrix)!=c(2*stgs,2*stgs) )) { + msg <- c(msg, "SurvStageWtsMatrix must have dimensions 2*\'Stages\' x 2*\'Stages\' !") + } + } + } + if (length(object@StageStruct@FecLayer)>0) { + if ( any(dim(object@StageStruct@FecLayer)!=c(stgs,2) )) { + msg <- c(msg, "FecLayer must have dimensions \'Stages\' x 2 !") + } + } + if (length(object@StageStruct@DevLayer)>0) { + if ( any(dim(object@StageStruct@DevLayer)!=c(stgs,2) )) { + msg <- c(msg, "DevLayer must have dimensions \'Stages\' x 2 !") + } + } + if (length(object@StageStruct@SurvLayer)>0) { + if ( any(dim(object@StageStruct@SurvLayer)!=c(stgs,2) )) { + msg <- c(msg, "SurvLayer must have dimensions \'Stages\' x 2 !") + } + } + } + else{ # asexual model or simple sexual model + if ( any(dim(object@StageStruct@TransMatrix)!=c(stgs,stgs) )) { + msg <- c(msg, "Transition Matrix must have dimensions \'Stages\' x \'Stages\' !") + } + else { # check transition matrix + if (object@StageStruct@TransMatrix[1,1]!=0) { + msg <- c(msg, "Transition Matrix: Fecundity of juvenile stage must be zero!") + } + if (any(object@StageStruct@TransMatrix[1,]<0) ) { + msg <- c(msg, "Transition Matrix: Fecunditiy must be positive or zero!") + } + if (any(object@StageStruct@TransMatrix[-1,]<0) || any(object@StageStruct@TransMatrix[-1,]>1) ) { + msg <- c(msg, "Transition Matrix: All transition probabilities must be in the closed interval [0,1]") + } + else{ # passed first line of tests + for (ss in 1:(stgs-1)){ + if (sum(object@StageStruct@TransMatrix[ss:(ss+1),ss])>1) { + msg <- c(msg, "Transition Matrix: Sum of probabilities to stay in current stage and to develop can't exceed 1!") + } + if (any(object@StageStruct@TransMatrix[-c(1,ss,(ss+1)),ss]!=0)) { + msg <- c(msg, "Transition Matrix: Found non-zero entries where zeroes are expected!") + } + } + if (any(object@StageStruct@TransMatrix[-c(1,stgs),stgs]!=0)) { + msg <- c(msg, "Transition Matrix: Found non-zero entries where zeroes are expected!") + } + } + } + if (length(object@StageStruct@MinAge)==1 && object@StageStruct@MinAge==0) { + # do nothing and figure out a way to set as default a null vector of the correct length + } + else { + if (length(object@StageStruct@MinAge)!=stgs) { + msg <- c(msg, "Minimum Age vector must have dimensions \'Stages\' !") + } + else{ + if (any(object@StageStruct@MinAge[1:2]!=0) ) { + msg <- c(msg, "MinAge of stages 0 and 1 must be zero!") + } + if (any(object@StageStruct@MinAge<0)) { + msg <- c(msg, "MinAge must be positive!") + } + } + } + if (object@StageStruct@FecStageWts) { + if (!anyNA(object@StageStruct@FecStageWtsMatrix)) { + if ( any(dim(object@StageStruct@FecStageWtsMatrix)!=c(stgs,stgs) )) { + msg <- c(msg, "FecStageWtsMatrix must have dimensions \'Stages\' x \'Stages\' !") + } + } + } + if (object@StageStruct@DevStageWts) { + if (!anyNA(object@StageStruct@DevStageWtsMatrix)) { + if ( any(dim(object@StageStruct@DevStageWtsMatrix)!=c(stgs,stgs) )) { + msg <- c(msg, "DevStageWtsMatrix must have dimensions \'Stages\' x \'Stages\' !") + } + } + } + if (object@StageStruct@SurvStageWts) { + if (!anyNA(object@StageStruct@SurvStageWtsMatrix)) { + if ( any(dim(object@StageStruct@SurvStageWtsMatrix)!=c(stgs,stgs) )) { + msg <- c(msg, "SurvStageWtsMatrix must have dimensions \'Stages\' x \'Stages\' !") + } + } + } + if (length(object@StageStruct@FecLayer)>0) { + if ( any(dim(object@StageStruct@FecLayer)!=c(stgs,1) )) { + msg <- c(msg, "FecLayer must have dimensions \'Stages\' x 1 !") + } + } + if (length(object@StageStruct@DevLayer)>0) { + if ( any(dim(object@StageStruct@DevLayer)!=c(stgs,1) )) { + msg <- c(msg, "DevLayer must have dimensions \'Stages\' x 1 !") + } + } + if (length(object@StageStruct@SurvLayer)>0) { + if ( any(dim(object@StageStruct@SurvLayer)!=c(stgs,1) )) { + msg <- c(msg, "SurvLayer must have dimensions \'Stages\' x 1 !") + } + } + } + } + else{ + msg <- c(msg, "StageStruct must either be FALSE or an object of class \"StagesParams\" !") + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "DemogParams", function(.Object,...) { + this_func = "Demography(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (class(.Object@StageStruct)[1]=="StagesParams") { + .Object@Rmax = -9L + if (!is.null(args$Rmax)) { + warning(this_func, "Maximum growth rate Rmax", warn_msg_ignored, "in a stage-structured model.", call. = FALSE) + } + .Object@bc = -9L + if (!is.null(args$bc)) { + warning(this_func, "Competition coefficient bc", warn_msg_ignored, "in a stage-structured model.", call. = FALSE) + } + } + if (.Object@ReproductionType==0) { + .Object@PropMales = -9L + if (!is.null(args$PropMales)) { + warning(this_func, "Proportion of males", warn_msg_ignored, "in an asexual / only-female model.", call. = FALSE) + } + } + if (.Object@ReproductionType!=2) { + .Object@Harem = -9L + if (!is.null(args$Harem)) { + warning(this_func, "Maximum harem size", warn_msg_ignored, "in a model without mating system. (Only used when ReproductionType = 2)", call. = FALSE) + } + } + .Object} +) +setMethod("show", "DemogParams", function(object){ + cat(" Demography:\n") + if (class(object@StageStruct)[1]=="StagesParams") { + cat(" Stage-structured population:\n") + print(object@StageStruct) + } + else { + cat(" Unstructured population:\n") + cat(" Rmax :", paste(object@Rmax), "\n") + cat(" bc :", paste(object@bc) , "\n") + } + cat(" Reproduction Type :", paste(object@ReproductionType)) + if(object@ReproductionType) { + cat(" (sexual model)\n") + cat(" PropMales :", paste(object@PropMales), "\n") + } + else{ + cat(" (female only)\n") + } + if(object@ReproductionType==2) { + cat(" Harem :", paste(object@Harem), "\n") + } +}) + +# RS manual 2.4.2 (page 23) - 2.4.3 (page 34) diff --git a/RangeShiftR/R/class_DispersalParams.R b/RangeShiftR/R/class_DispersalParams.R new file mode 100644 index 0000000..aca55ec --- /dev/null +++ b/RangeShiftR/R/class_DispersalParams.R @@ -0,0 +1,1946 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#### DISPERSAL #### + + +### SUBCLASS EMIGRATIONPARAMS + +# from RS 'Emigration' file + +#' Set Emigration Parameters +#' +#' Emigration - the first phase of dispersal - is modelled as the probability that an individual leaves its natal patch during the present year (or season). +#' It is constant by default, but can be set to be density-dependent (\code{DensDep}) and/or to vary for each individual (\code{IndVar}). In case of a stage-structured/sexual +#' population model, the emigration probabilities can also vary with stage/sex (\code{StageDep/SexDep}). If inter-individual variability is +#' enabled, the emigration traits can also be allowed to evolve (see \code{\link[RangeShiftR]{EmigrationTraits}}). +#' +#' @usage Emigration(EmigProb = 0.0, +#' SexDep = FALSE, StageDep = FALSE, +#' DensDep = FALSE, +#' IndVar = FALSE, +#' EmigStage, +#' UseFullKern = FALSE) +#' @param EmigProb Matrix containing all parameters (#columns) to determine emigration probabilities for each stage/sex (#rows). Its structure depends on the other parameters, see the Details. +#' If the emigration probability is constant (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}), \code{EmigProb} can take a single numeric. Defaults to \eqn{0.0}. +#' @param SexDep Sex-dependent emigration probability? (default: \code{FALSE}) +#' @param StageDep Stage-dependent emigration probability? (default: \code{FALSE}) Must be \code{FALSE} if \code{IndVar=TRUE}. +#' @param DensDep Density-dependent emigration probability? (default: \code{FALSE}) +#' @param IndVar Individual variability in emigration traits? (default: \code{FALSE}) Must be \code{FALSE} if \code{StageDep=TRUE}. +#' @param EmigStage Required for stage-structured populations with \code{IndVar=TRUE}: Stage which emigrates. (\code{StageDep} must be \code{FALSE}) +#' @param UseFullKern Applicable only if transfer phase is modelled by a \code{\link[RangeShiftR]{DispersalKernel}} and \code{DensDep=FALSE}: Shall the emigration probability be derived from dispersal kernel? +#' @details Emigration is modelled as the probability \eqn{d} that an individual leaves its natal patch during the present year or season (every reproductive event +#' is always followed by dispersal). +#' Populations with non-overlapping generations have only a single opportunity to emigrate, whereas in a stage-structured population the realised overall emigration +#' rate can be larger than \eqn{d}, if a stage with \eqn{d>0} lasts for more than one year so that an individual has multiple opportunities to emigrate (each with probability \eqn{d}). +#' +#' The emigration probability \eqn{d} can be density-dependent (set \code{DensDep=TRUE}), in which case it is given by the following function, introduced by \insertCite{kun2006evolution;textual}{RangeShiftR}: +#' +#' \ifelse{html}{\out{   d(i,t) = D0 / ( 1 + e-αsub>E (N(i,t) / K(i,t) - βsub>E) ) } }{\deqn{ d(i,t) = D_0 / ( 1 + exp[-α_E (N(i,t)/K(i,t) - β_E) ] ) } } +#' +#' In the case of stage-structured models this equation is modified to: +#' +#' \ifelse{html}{\out{   d(i,t) = D0 / ( 1 + e-αsub>E (b(i,t) * N(i,t) - βsub>E) ) } }{\deqn{ d(i,t) = D_0 / ( 1 + exp[-α_E (b(i,t) N(i,t) - β_E) ] ) } } +#' +#' In the first case, \eqn{K(i,t)} is the carrying capacity of the cell/patch \eqn{i} at time \eqn{t} given by \code{K_or_DensDep}. +#' In the latter case, \eqn{b(i,t)} represents the strength of density dependence and is given by the inverse of \code{K_or_DensDep}.\cr +#' Further, \ifelse{html}{\out{D0}}{\eqn{D_0}} is the maximum emigration probability, +#' \eqn{N(i,t)} is the number of individuals in the cell/patch \eqn{i} at time \eqn{t}, +#' \ifelse{html}{\out{βE}}{\eqn{β_S}} is the inflection point of the function and +#' \ifelse{html}{\out{αE}}{\eqn{α_S}} is the slope at the inflection point.\cr +#' +#' Various functions have been proposed for density dependent emigration \insertCite{hovestadt2010information,poethke2011ability}{RangeShiftR}. +#' This one was chosen here because it is a flexible function that +#' allows for modelling a range of different reaction norms, as well as their emergence through evolution. In the case of density-dependent +#' emigration, we assume individuals to have full knowledge of the population density and carrying capacity (or 1/b, respectively) in their natal patch. +#' Information acquisition is not explicitly modelled. +#' +#' The emigration probability can be allowed to vary between individuals (set \code{IndVar=TRUE}) and to evolve. In the this case, individuals exhibit either one trait +#' determining the density-independent \eqn{d} (when \code{DensDep=FALSE}), or the three traits \ifelse{html}{\out{D0}}{\eqn{D_0}}, \eqn{α} and +#' \eqn{β} determining the density-dependent emigration probability (when \code{DensDep=TRUE}).\cr +#' The traits must be set in \code{\link[RangeShiftR]{EmigrationTraits}} (instead of the constant value(s) in this funciton). +#' Also, if \code{IndVar=TRUE} is set for a stage-structured population, it is required to specify the stage which emigrates via \code{EmigStage}. +#' +#' It is possible to model sex-specific emigration strategies (set \code{SexDep=TRUE}) \insertCite{greenwood1980mating,lawson2007advances}{RangeShiftR}. +#' In this case the number of traits is doubled; one set coding for the trait(s) in females and the other for the trait(s) in males. +#' As well as being sex-biased, emigration parameters can be stage-biased (set \code{StageDep=TRUE}) when modelling stage-structured populations. +#' However, the current version does not accommodate inter-individual variation in emigration strategies when they are stage-dependent. +#' +#' If there is no inter-individual variation in emigration, the parameters that determine the emigration probabilities have to be provided via \code{EmigProb}, which generally takes a matrix, or - if only a single constant probability is +#' used (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}) - a single numeric. If inter-individual variation is enabled, the parameters are set in \code{\link[RangeShiftR]{EmigrationTraits}} and EmigProb is not required. +#' +#' The format of the matrix is defined as follows: The number of columns depend on the options \code{DensDep}. If \code{DensDep=FALSE}, the +#' density-independent probability \eqn{d} must be specified. If \code{DensDep=TRUE}, the functional parameters \ifelse{html}{\out{D0}}{\eqn{D_0}}, \eqn{α} and \eqn{β} (cp. equation above) must be specified. +#' +#' All parameters have to be given for each stage/sex if the respective dependence is enabled. If \code{StageDep=TRUE}, state the corresponding stage in the first column. +#' If \code{SexDep=TRUE}, state the corresponding stage in the next (i.e. first/second) column, with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. The following table lists the required columns and their correct order for different settings: +#' +#' \tabular{ccccc}{DensDep \tab IndVar \tab StageDep \tab SexDep \tab columns \cr +#' F \tab F \tab F \tab F \tab \eqn{d} \cr +#' F \tab F \tab T \tab F \tab stage, \eqn{d} \cr +#' F \tab F \tab F \tab T \tab sex, \eqn{d} \cr +#' F \tab F \tab T \tab T \tab stage, sex, \eqn{d} \cr +#' T \tab F \tab F \tab F \tab \ifelse{html}{\out{D0}}{\eqn{D_0}}, \eqn{α}, \eqn{β} \cr +#' } +#' +#' The column headings need not be included, only the numeric matrix is required. The rows require no particular order, but there must be exactly one row for each stage/sex combination. For example, in the case of density-, stage- and sex-dependent emigration with no individual variability: +#' \tabular{ccccc}{ \out{ } 0 \tab \out{ } 0 \tab \out{ } 1.0 \tab \out{ } 20 \tab \out{ } 0.2 \cr +#' \out{ } 0 \tab \out{ } 1 \tab \out{ } 1.0 \tab \out{ } 20 \tab \out{ } 0.1 \cr +#' \out{ } 1 \tab \out{ } 0 \tab \out{ } 0.7 \tab \out{ } 25 \tab \out{ } 0.5 \cr +#' \out{ } 1 \tab \out{ } 1 \tab \out{ } 0.8 \tab \out{ } 50 \tab \out{ } 0.5 \cr +#' \out{ } 2 \tab \out{ } 0 \tab \out{ } 0.4 \tab \out{ } 10 \tab \out{ } 1.0 \cr +#' \out{ } 2 \tab \out{ } 1 \tab \out{ } 0.5 \tab \out{ } 20 \tab \out{ } 1.0 +#' } +#' +#' In the special case that \code{DensDep=FALSE} and transfer is realised by \code{\link[RangeShiftR]{DispersalKernel}}, then the option \code{UseFullKern} may be switched on. It +#' will prevent re-sampling from the kernel if the distance sampled does not move the individual out of its natal cell/patch. Such individuals +#' are treated as philopatric recruits, and hence the kernel determines the probability of emigration. In this case, the emigration probability +#' for all stages/sexes which potentially disperse should be set to \eqn{1.0}. +#' @examples # stage- and sex-dependent constant emigration probabilities: +#' emigmat_1 <- matrix(c(0,0,1,0,1,1,1,0,.7,1,1,.8,2,0,.4,2,1,.5), byrow = TRUE, ncol = 3) +#' emig_1 <- Emigration(StageDep = TRUE, SexDep = TRUE, EmigProb = emigmat_1) +#' plotProbs(emig_1) +#' +#' # stage- and sex- and density-dependent emigration: +#' emigmat_2 <- matrix(c(0,0,1,20,.2,0,1,1,20,.1,1,0,.7,25,.5,1,1,.8,50,.5,2,0,.4,10,1,2,1,.5,20,1), byrow = TRUE, ncol = 5) +#' emig_2 <- Emigration(DensDep = TRUE, StageDep = TRUE, SexDep = TRUE, EmigProb = emigmat_2) +#' plotProbs(emig_2) +#' +#' emig_3 <- Emigration(DensDep = TRUE, IndVar = TRUE, SexDep = TRUE, EmigProb = 0) + +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "EmigrationParams" +#' @author Anne-Kathleen Malchow and Jette Wolff +#' @name Emigration +#' @export Emigration +Emigration <- setClass("EmigrationParams", slots = c(DensDep = "logical", + IndVar = "logical", + StageDep = "logical", + SexDep = "logical", + EmigProb = "matrix_OR_numeric", + EmigStage = "integer_OR_numeric", + UseFullKern = "logical") + , prototype = list(DensDep = FALSE, + IndVar = FALSE, + StageDep = FALSE, + SexDep = FALSE, + EmigProb = matrix(data = 0.0, nrow = 1, ncol = 1), + EmigStage = 0L, + UseFullKern = FALSE) +) + # discuss TraitScaleFactor in the Details + + +setValidity("EmigrationParams", function(object) { + msg <- NULL + if (anyNA(object@DensDep) || length(object@DensDep)!=1) { + msg <- c(msg, "DensDep must be set and of length 1!") + } + if (anyNA(object@IndVar) || length(object@IndVar)!=1) { + msg <- c(msg, "IndVar must be set and of length 1!") + } + else { + if (anyNA(object@StageDep) || length(object@StageDep)!=1) { + msg <- c(msg, "StageDep must be set and of length 1!") + } + else{ + if (object@IndVar && object@StageDep) { + msg <- c(msg, "Inter-individual variability (IndVar=TRUE) in stage-dependent (StageDep=TRUE) emigration traits is not implemented!") + } + } + } + if (anyNA(object@SexDep) || length(object@SexDep)!=1) { + msg <- c(msg, "SexDep must be set and of length 1!") + } + if (anyNA(object@EmigProb) || length(object@EmigProb)==0) { + msg <- c(msg, "EmigProb must be set!") + } + else{ + if (!object@IndVar && !object@DensDep && !object@StageDep && !object@SexDep) { + if (length(object@EmigProb)==1) { + if (object@EmigProb < 0 || object@EmigProb > 1) { + msg <- c(msg, "EmigProb must be in the closed interval [0,1]!") + } + } + else { + msg <- c(msg, "EmigProb must have only one entry since it is set to be constant!") + } + } + else { + if (class(object@EmigProb)[1]!="matrix" && length(object@EmigProb)!=1 && !object@IndVar) { + msg <- c(msg, "EmigProb must be a matrix!") + } + else { + if (!object@IndVar && object@DensDep && !object@StageDep && !object@SexDep && any(dim(object@EmigProb)!=c(1,3)) ) { + msg <- c(msg, "EmigProb must be a 1x3 matrix if IndVar,StageDep,SexDep = FALSE and DensDep = TRUE!") + } + if (!object@IndVar && !object@DensDep && object@StageDep && !object@SexDep && dim(object@EmigProb)[2]!=2 ) { + msg <- c(msg, "EmigProb must have 2 columns if IndVar,DensDep,SexDep = FALSE and StageDep = TRUE!") + } + if (!object@IndVar && !object@DensDep && !object@StageDep && object@SexDep && any(dim(object@EmigProb)!=c(2,2)) ) { + msg <- c(msg, "EmigProb must be a 2x2 matrix if IndVar,DensDep,StageDep = FALSE and SexDep = TRUE!") + } + if (!object@IndVar && !object@DensDep && object@StageDep && object@SexDep && dim(object@EmigProb)[2]!=3 ) { + msg <- c(msg, "EmigProb must have 3 columns if IndVar,DensDep = FALSE and StageDep,SexDep = TRUE!") + } + if (!object@IndVar && object@DensDep && object@StageDep && !object@SexDep && dim(object@EmigProb)[2]!=4 ) { + msg <- c(msg, "EmigProb must have 4 columns if IndVar,SexDep = FALSE and DensDep,StageDep = TRUE!") + } + if (!object@IndVar && object@DensDep && !object@StageDep && object@SexDep && any(dim(object@EmigProb)!=c(2,4)) ) { + msg <- c(msg, "EmigProb must be a 2x4 matrix if IndVar,StageDep = FALSE and DensDep,SexDep = TRUE!") + } + if (!object@IndVar && object@DensDep && object@StageDep && object@SexDep && dim(object@EmigProb)[2]!=5 ) { + msg <- c(msg, "EmigProb must have 5 columns if IndVar = FALSE and DensDep,StageDep,SexDep = TRUE!") + } + } + } + } + + if (anyNA(object@UseFullKern) || length(object@UseFullKern)!=1) { + msg <- c(msg, "UseFullKern must be set and of length 1!") + } + else { + if (object@DensDep && object@UseFullKern) { + msg <- c(msg, "UseFullKern is not applicable if DensDep = TRUE!") + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "EmigrationParams", function(.Object, ...) { + this_func = "Emigration(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (!is.null(args$EmigProb)) { + if (class(args$EmigProb)[1] =="numeric" && length(args$EmigProb)==1) { + .Object@EmigProb <- as.matrix(args$EmigProb) + } + } + # else { + # warning(this_func, "Using default EmigProb = 0.0", call. = FALSE) + # } + if (!.Object@IndVar) { + .Object@EmigStage = -9L + if (!is.null(args$EmigStage)) { + warning(this_func, "EmigStage", warn_msg_ignored, "since IndVar = FALSE.", call. = FALSE) + } + } + if (.Object@UseFullKern) { + if (any(.Object@EmigProb!=0.0 & .Object@EmigProb!=1.0)) { + warning(this_func, "If UseFullKern = TRUE, it is recommended (in most cases) to set all elements of EmigProb to either 1.0 or 0.0, since the emigration probability will be evaluated using the dispersal kernel.", call. = FALSE) + } + } + .Object} +) +setMethod("show", "EmigrationParams", function(object){ + if (object@DensDep) { + cat(" DensDep =", object@DensDep, "\n") + } + if (object@IndVar) { + cat(" IndVar =", object@IndVar, "\n") + } + if (object@StageDep) { + cat(" StageDep =", object@StageDep, "\n") + } + if (object@SexDep) { + cat(" SexDep =", object@SexDep, "\n") + } + cat(" Emigration probabilities:\n") + if (!object@IndVar){ + print(object@EmigProb) + } + if (object@IndVar) { + if (!anyNA(object@EmigStage) && length(object@EmigStage)!=0) { + cat(" EmigStage =", object@EmigStage, "\n") + } + } + if (!object@DensDep && object@UseFullKern) { + cat(" UseFullKern =", object@UseFullKern, "\n") + } +}) +setMethod("plotProbs", "EmigrationParams", function(x, stage = NULL, sex = NULL, xmax = NULL, ymax = NULL){ + emig <- x@EmigProb + if (x@IndVar) { + print("Plotting of inter-individual variability in emigration traits is not implemented yet.") + return() + } else{ + # error messages + if (!is.null(stage)){ + if (x@StageDep) { + emig <- subset(emig, emig[,1] %in% stage) + } + else{ print("This emigration module has no stage-dependency.\n") } + } + if (!is.null(sex)){ + if (x@SexDep) { + if (x@StageDep) emig <- subset(emig, emig[,2] %in% sex) + else emig <- subset(emig, emig[,1] %in% sex) + } + else{ print("This emigration module has no sex-dependency.\n") } + } + # get column indices + if (x@StageDep) { + if (x@SexDep) {ind_D0 <- 3} else {ind_D0 <- 2} + }else{ + if (x@SexDep) {ind_D0 <- 2} else {ind_D0 <- 1} + } + # if (x@IndVar) {IV <- 2} else {IV <- 1} + IV <- 1 + # New plot + if (x@DensDep) { + if (is.null(xmax)) { + ind_max <- which.max(emig[,ind_D0+2*IV]) + xmax = min(2*emig[ind_max,ind_D0+2*IV], emig[ind_max,ind_D0+2*IV] + 4.0/emig[ind_max,ind_D0+IV]) + } + xvals = seq(0, xmax, length.out = 100) + } + else {if(is.null(xmax)) xmax <- 1} # !DensDep + + if (is.null(ymax)) {ymax = 1} + plot(NULL, type = "n", ylab = "Emigration probability", xlab = "relative population density (N/K or bN)", xlim = c(0,xmax), ylim = c(0,ymax)) + leg.txt <- c() + # Go through lines of distances matrix and add curves to plot + for(line in 1:nrow(emig)){ + # if (x@IndVar) { + # if (x@DensDep) { + # res <- matrix(ncol = 8, nrow = length(xvals)) + # res[,1] <- densdep(xvals, A0 = emig[line,ind_D0]-emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]-emig[line,ind_D0+3], beta = emig[line,ind_D0+4]-emig[line,ind_D0+5]) + # res[,2] <- densdep(xvals, A0 = emig[line,ind_D0]-emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]-emig[line,ind_D0+3], beta = emig[line,ind_D0+4]+emig[line,ind_D0+5]) + # res[,3] <- densdep(xvals, A0 = emig[line,ind_D0]-emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]+emig[line,ind_D0+3], beta = emig[line,ind_D0+4]-emig[line,ind_D0+5]) + # res[,4] <- densdep(xvals, A0 = emig[line,ind_D0]-emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]+emig[line,ind_D0+3], beta = emig[line,ind_D0+4]+emig[line,ind_D0+5]) + # res[,5] <- densdep(xvals, A0 = emig[line,ind_D0]+emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]-emig[line,ind_D0+3], beta = emig[line,ind_D0+4]-emig[line,ind_D0+5]) + # res[,6] <- densdep(xvals, A0 = emig[line,ind_D0]+emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]-emig[line,ind_D0+3], beta = emig[line,ind_D0+4]+emig[line,ind_D0+5]) + # res[,7] <- densdep(xvals, A0 = emig[line,ind_D0]+emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]+emig[line,ind_D0+3], beta = emig[line,ind_D0+4]-emig[line,ind_D0+5]) + # res[,8] <- densdep(xvals, A0 = emig[line,ind_D0]+emig[line,ind_D0+1], alpha = emig[line,ind_D0+2]+emig[line,ind_D0+3], beta = emig[line,ind_D0+4]+emig[line,ind_D0+5]) + # polygon(c(xvals,rev(xvals)), c(apply(res, 1, min), rev(apply(res, 1, max))), border=NA, col='grey80') + # } + # else {#constant + # polygon(c(0,xmax,xmax,0), c(rep(emig[line,ind_D0]-emig[line,ind_D0+1],2),rep(emig[line,ind_D0]+emig[line,ind_D0+1],2)), border=NA, col='grey80') + # } + # } + if (x@DensDep) { + lines(xvals, densdep(xvals, A0 = emig[line,ind_D0], alpha = emig[line,ind_D0+IV], beta = emig[line,ind_D0+2*IV]), type = "l", lty = 1, col = line) + } + else {#constant + lines(x=c(0,xmax), y=rep(emig[line,ind_D0],2), type = "l", lty = 1, col = line) + } + if (x@StageDep) { + if (x@SexDep) {leg.txt <- c(leg.txt, paste0("Stage ",emig[line,1], ifelse(emig[line,2]," male"," female")))} else {leg.txt <- c(leg.txt, paste0("Stage ",emig[line,1]))} + } + else { + if (x@SexDep) {leg.txt <- c(leg.txt, ifelse(emig[line,1],"male","female"))} + } + } + if (length(leg.txt)>0) { + legend("topleft", leg.txt, col = 1:nrow(emig), lwd = 1.5) + } + } + +}) + + +### SUBCLASS TRANSFERPARAMS + +# from RS 'Transfer' file +# vitual class acting as superclass for: 'DispersalKernel', 'StochMove', 'CorrRW' + +#' Set a Transfer method +#' +#' Transfer (or transience) is the second phase of dispersal. It consists of the movement of an individual departing from its natal patch towards +#' a potential new patch, ending with settlement or mortality. This movement can be modelled by one of three alternative processes:\cr +#' - Dispersal kernel: use \code{\link[RangeShiftR]{DispersalKernel}}\cr +#' - Stochastic movement simulator (SMS): use \code{\link[RangeShiftR]{SMS}}\cr +#' - Correlated random walk (CRW): use \code{\link[RangeShiftR]{CorrRW}} +#' +#' @details +#' The choice between the two main methods to model the transfer phase, i.e. phenomenological dispersal kernels or mechanistic movement processes +#' (SMS and CRW) depends on the information available for a given species and on the level of detail that is considered important to represent in +#' the model (which will depend on its aim and the scale). +#' \cr +#' Dispersal is often a costly process for an organism \insertCite{bonte2012costs}{RangeShiftR} and, in some cases, a dispersing individual may +#' suffer mortality. Obtaining a sensible +#' representation of dispersal requires that these mortality costs are described appropriately. The total dispersal mortality experienced will +#' be the sum of two main sources of mortality: First, as the result of individuals failing to reach suitable habitat, and second, as the result +#' of increased energetic, time or attritional costs that longer-distance dispersers will experience. +#' For more details, refer also to the respective Details sections of the different transfer methods. +#' In parameterising the model, it will be important to recognise this such that dispersal mortality is not double-accounted. +#' @references +#' \insertAllCited{} +#' @author Anne-Kathleen Malchow +#' @name Transfer +TransferParams <- setClass("TransferParams") +setMethod("show", "TransferParams", function(object){ + if (class(object)[1] == "DispersalKernel") cat(" Dispersal Kernel\n") + if (class(object)[1] == "StochMove") cat(" Stochastic Movement Simulator\n") + if (class(object)[1] == "CorrRW") cat(" Correlated Random Walk\n") + } +) + + + +## Transfer-class DISPERSALKERNEL + +#' Set up a Dispersal Kernel +#' +#' A method to describe \code{\link[RangeShiftR]{Transfer}}: Dispersal kernels are statistical distributions that are largely used to describe dispersal distances. The main assumption behind them +#' is that the principal determinant of the probability of an individual dispersing to a particular site is the distance from the starting location.\cr +#' As for the other dispersal phases, movement abilities and strategies are under multiple selective pressures and can evolve separately. +#' As a result, the realised dispersal kernels will themselves evolve. +#' +#' @usage DispersalKernel(Distances = matrix(c(100),nrow=1), DoubleKernel = FALSE, +#' SexDep = FALSE, StageDep = FALSE, +#' IndVar = FALSE, +#' DistMort = FALSE, +#' MortProb = 0.0, Slope, InflPoint) +#' @param Distances Matrix containing all dispersal kernel parameters (#columns) for each stage/sex (#rows) if applicable. Its structure depends on the other parameters, see the Details. +#' If the mean dispersal distance is constant (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}), \code{Distances} must be a matrix with a single value. Default is to \code{matrix(c(100),nrow=1)}. +#' @param DoubleKernel Use a mixed (i.e. double negative exponential) kernel? (default: \code{FALSE}) Set probability for using Kernel-1 in matrix \code{Distances}. +#' @param SexDep Sex-dependent dispersal kernel? (default: \code{FALSE}) +#' @param StageDep Stage-dependent dispersal kernel? (default: \code{FALSE}) Must be \code{FALSE} if \code{IndVar=TRUE}. +#' @param IndVar Individual variability in dispersal kernel traits? (default: \code{FALSE}) Must be \code{FALSE}, if \code{StageDep=TRUE}. If \code{IndVar=TRUE}, specify the trait in \code{\link[RangeShiftR]{KernelTraits}}. +#' @param TraitScaleFactor Required if \code{IndVar=TRUE}: The scaling factor(s) for dispersal kernel traits. A numeric of length \eqn{1} (if \code{DoubleKernel=FALSE}) or \eqn{3} (if \code{DoubleKernel=TRUE}). +#' @param DistMort Distance-dependent mortality probability? (default: \code{FALSE}) +#' @param MortProb Constant mortality probability. Required if \code{DistMort=FALSE}, defaults to \eqn{0.0}. +#' @param InflPoint Required if \code{DistMort=TRUE}: Inflection point for the mortality distance dependence function. +#' @param Slope Required if \code{DistMort=TRUE}: Slope at inflection point for the mortality distance dependence function. +#' @details +#' Two types of dispersal kernels are implemented: negative exponential and a mixed kernel given by two different negative exponentials. +#' Here, kernels are considered as ‘distance kernels’, i.e. the statistical distribution of the probability that an individual will move a +#' certain distance \insertCite{hovestadt2012evolution,nathan2012dispersal}{RangeShiftR}. These kernels are specifically used for the \code{\link[RangeShiftR]{Transfer}} phase, meaning that they do +#' not incorporate information on the \code{\link[RangeShiftR]{Emigration}} or \code{\link[RangeShiftR]{Settlement}} probabilities, which are modelled independently. Therefore, dispersal kernels are +#' applied only to dispersing individuals and not normally to the entire population. However, the program allows a particular setting where +#' emigration and transfer are not explicitly separated but are both modelled through the kernel (see the parameter \code{UseFullKern} in +#' \code{\link[RangeShiftR]{Emigration}} and the Details there). +#' +#' There are many possible statistical distributions that have been fitted to dispersal data, which in many cases perform better +#' than the negative exponential \insertCite{nathan2012dispersal}{RangeShiftR}. However, the negative exponential is still commonly used, has been found useful for +#' describing dispersal patterns of certain organisms and the combination of two different negative exponentials has been demonstrated to be a +#' valuable method for discerning between common short-distance and rare long-distance dispersal \insertCite{hovestadt2011all}{RangeShiftR}. +#' +#' \emph{Negative exponential} \cr +#' If the individual disperses, the distance and the movement direction are determined in continuous space. +#' The distance is drawn from a negative exponential distribution with a given mean \eqn{δ}, and the direction is selected randomly from a uniform +#' distribution between \eqn{0} and \eqn{2π} radians. +#' +#' \ifelse{html}{\out{   p(d;δ) = δ-1 e- d / δ}}{\deqn{ p(d;δ) = 1/δ exp(-d/δ) } } +#' +#' If the arrival point lies beyond the boundary of the landscape, distance and direction are re-drawn.\cr +#' The individual is displaced from a random point (using continuous coordinates) inside the natal cell to the arrival cell where the model +#' switches back to discrete space \insertCite{bocedi2012projecting}{RangeShiftR}. If the arrival point is inside the natal cell, individual starting position, distance and direction are +#' re-sampled until the individual leaves the natal cell. In the case of patch-based models, the individual is assumed to disperse from a +#' random point in the patch and this position, the dispersal distance and direction are drawn until the individual leaves the patch. In order +#' to separate emigration and transfer explicitly, and to avoid potential infinite re-sampling, the program requires the mean of the kernel +#' to be greater or equal the cell resolution. This condition is relaxed only in the special case where emigration probability is set to be +#' density-independent and the kernel is applied to the entire population without re-sampling (the \code{UseFullKern} option in \code{\link[RangeShiftR]{Emigration}}). Individuals +#' which draw a short movement distance do not leave the natal cell/patch and implicitly become sedentary, and therefore the kernel itself +#' defines the proportion of individuals which emigrate. When this option is selected, the emigration probability for those stages/sexes +#' which disperse should be set to \eqn{1.0}; otherwise, only a proportion of such individuals would use the kernel to determine whether or +#' not they emigrate. +#' +#' \emph{Mixed kernel} \cr +#' The distance an individual moves is sampled from a mixed kernel given by the combination of two negative exponentials +#' with different means \ifelse{html}{\out{δ1}}{\eqn{δ_1}} and \ifelse{html}{\out{δ2}}{\eqn{δ_2}}, +#' occurring with probability \ifelse{html}{\out{pI}}{\eqn{p_I}} and \eqn{1-}\ifelse{html}{\out{pI}}{\eqn{p_I}} respectively \insertCite{hovestadt2011all}{RangeShiftR}. +#' Otherwise, the conditions for the single kernel apply. +#' +#' \ifelse{html}{\out{   p(d; δ1,δ2) = pI p(d;δ1) + (1-pI) p(d;δ1)}}{\deqn{ p(d; δ_1,δ_2) = p_I p(d;δ_1) + (1-p_I) p(d;δ_2)}} +#' +#' For both types of kernel, inter-individual variability of the kernel traits is possible (set \code{IndVar=TRUE}). Individuals will +#' carry either one trait for \eqn{δ} or three traits for \ifelse{html}{\out{δ1}}{\eqn{δ_1}}, \ifelse{html}{\out{δ2}}{\eqn{δ_2}} and +#' \ifelse{html}{\out{pI}}{\eqn{p_I}}, which they inherit from their parents. In this case, you must set the \code{Distances} to \code{NULL} here and specify +#' them in the \code{\link[RangeShiftR]{KernelTraits}} module to set up the genetics (see \code{\link[RangeShiftR]{Genetics}})\cr +#' Dispersal kernels can also be sex-dependent (set \code{SexDep=TRUE}). In the case of inter-individual variability, the number of traits is doubled to two trait (female \eqn{δ} +#' and male δ) or six traits (female and male \ifelse{html}{\out{δ1}}{\eqn{δ_1}}, \ifelse{html}{\out{δ2}}{\eqn{δ_2}} and \ifelse{html}{\out{pI}}{\eqn{p_I}}).\cr +#' For each trait the initial distribution in the population (as mean and standard variation) must be set in \code{Distances} (instead of only one constant value), +#' as well as their scaling factors in \code{TraitScaleFactor} (see \code{\link[RangeShiftR]{Genetics}}).\cr +#' +#' Further, dispersal kernels can be stage-specific (set \code{StageDep=TRUE}). For this case, inter-individual variability is not implemented. +#' +#' All dispersal kernel parameters have to be provided via \code{Distances}, which generally takes a matrix, or - if only a single constant mean distance is +#' used (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}) - a single numeric. The format of the matrix is defined as follows: The number of columns depend on the options \code{IndVar} and \code{DoubleKernel}. +#' If \code{DoubleKernel=FALSE}, the mean dispersal distance \eqn{δ} must be specified (in meters). If \code{DoubleKernel=TRUE}, the mean dispersal distances +#' \ifelse{html}{\out{δ1}}{\eqn{δ_1}} and \ifelse{html}{\out{δ2}}{\eqn{δ_2}} (in meters), as well as the probability \ifelse{html}{\out{pI}}{\eqn{p_I}} of using Kernel-1 must be specified. +#' If \code{IndVar=TRUE}, \code{Distances} must be \code{NULL} and the dispersal kernel traits must be set in the \code{\link[RangeShiftR]{KernelTraits}} modules. +#' +#' All parameters have to be given for each stage/sex if the respective dependence is enabled. If \code{StageDep=TRUE}, state the corresponding stage in the first column. +#' If \code{SexDep=TRUE}, state the corresponding stage in the next (i.e. first/second) column, with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. The following +#' table lists the required columns and their correct order for different settings: +#' +#' \tabular{ccccc}{IndVar \tab DoubleKernel \tab StageDep \tab SexDep \tab columns \cr +#' F \tab F \tab F \tab F \tab \eqn{δ} \cr +#' F \tab F \tab T \tab F \tab stage, \eqn{δ} \cr +#' F \tab F \tab F \tab T \tab sex, \eqn{δ} \cr +#' F \tab F \tab T \tab T \tab stage, sex, \eqn{δ} \cr +#' F \tab T \tab F \tab F \tab \ifelse{html}{\out{δ1, δ2, pI}}{\eqn{δ_1, δ_2, p_I}} \cr +#' } +#' +#' The column headings need not be included, only the numeric matrix is required. The rows require no particular order, but there must be exactly +#' one row for each stage/sex combination. For example, in the case of a mixed kernel with stage- and sex-dependent distances and no individual variability: +#' \tabular{ccccc}{ \out{ } 0 \tab \out{ } 0 \tab \out{ } 1000 \tab \out{ } 4500 \tab \out{ } 0.92 \cr +#' \out{ } 0 \tab \out{ } 1 \tab \out{ } 1400 \tab \out{ } 6000 \tab \out{ } 0.95 \cr +#' \out{ } 1 \tab \out{ } 0 \tab \out{ } 700 \tab \out{ } 500 \tab \out{ } 0.50 \cr +#' \out{ } 1 \tab \out{ } 1 \tab \out{ } 500 \tab \out{ } 600 \tab \out{ } 0.55 \cr +#' \out{ } 2 \tab \out{ } 0 \tab \out{ } 100 \tab \out{ } 0 \tab \out{ } 1.0 \cr +#' \out{ } 2 \tab \out{ } 1 \tab \out{ } 100 \tab \out{ } 0 \tab \out{ } 1.0 +#' } +#' +#' In the case that the dispersal kernel is applied to the entire +#' population (i.e. density-independent emigration probability of \eqn{1.0}), the mean dispersal distance can evolve down to zero (i.e. +#' evolution for no dispersal). In all other cases where emigration and transfer are modelled separately, the mean dispersal distance has a +#' lower limit which can evolve equal to the landscape resolution. +#' +#' \emph{Mortality}\cr +#' There are two main sources of mortality: First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. When a simple dispersal +#' kernel is used with no possibility for individuals to search for locally-suitable habitat (see \code{\link[RangeShiftR]{Settlement}}), +#' mortality occurs to all individuals that arrive in unsuitable habitat. In this first case, dispersal mortality clearly depends upon the +#' proportion of suitable habitat in the landscape and will increase as the availability of habitat declines.\cr +#' A second source of dispersal mortality can be specified via the option \code{DistMort}: The probability of mortality is either a constant +#' (\eqn{m=}\code{MortProb}) or a function of distance \eqn{d} (i.e. individuals that travel further are more likely to die): +#' +#' \ifelse{html}{\out{   m(d) = 1 / ( 1 + e-a (d- b) ) } }{\deqn{ m(d) = 1 / ( 1 + exp[-α (d-b) ] ) } } +#' +#' with the inflection point \eqn{b=}\code{InflPoint} at which \eqn{m(d=b)=0.5} and the slope \eqn{a=}\code{Slope}.This option may be thought +#' to represent the increased energetic, time or attritional costs that longer-distance dispersers will experience \insertCite{bonte2012costs}{RangeShiftR}. +#' +#' Note that the total dispersal mortality experienced will be the sum of the mortalities due to the two sources identified above and, +#' in parameterising the model, it will be important to recognize this such that dispersal mortality is not double-accounted. +#' @examples # stage- and sex-dependent mixed kernel +#' dists_1 <- matrix(c(0,0,1000,4500,0.92,0,1,1400,6000,0.95,1,0,700,500,0.50,1,1,500,600,0.55,2,0,100,0,1.0,2,1,100,0,1.0), byrow = TRUE, ncol = 5) +#' disp_1 <- DispersalKernel(Distances = dists_1, SexDep = TRUE, StageDep = TRUE, DoubleKernel = TRUE, DistMort = TRUE, Slope = 0.001, InflPoint = 4000) +#' plotProbs(disp_1, sex = 0, ymax = 0.002) +#' plotProbs(disp_1, mortality = TRUE) +#' +#' # mixed kernel with inter-individual variation +#' dists_2 <- matrix(c(0,1000,300,2500,500,0.62,0.13,1,3400,860,8000,2800,0.72,0.12), byrow = TRUE, ncol = 7) +#' disp_2 <- DispersalKernel(Distances = dists_2, SexDep = TRUE, DoubleKernel = TRUE, TraitScaleFactor = c(900,2800,0.14), IndVar = TRUE) +#' plotProbs(disp_2, xmax = 10000, combinekernels = TRUE) +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "DispersalKernel" +#' @author Anne-Kathleen Malchow +#' @name DispersalKernel +#' @export DispersalKernel +DispersalKernel <- setClass("DispersalKernel", slots = c(IndVar = "logical", + DoubleKernel = "logical", + StageDep = "logical", + SexDep = "logical", + Distances = "ANY", + DistMort = "logical", + MortProb = "numeric", + Slope = "numeric", + InflPoint = "numeric") + , prototype = list(IndVar = FALSE, + DoubleKernel = FALSE, + StageDep = FALSE, + SexDep = FALSE, + Distances = matrix(data = 100L, nrow = 1, ncol = 1), + DistMort = FALSE, + MortProb = 0.0 + #,Slope = -9, + #InflPoint = -9 + ) + , contains = "TransferParams" +) + +setValidity("DispersalKernel", function(object) { + msg <- NULL + if (anyNA(object@DoubleKernel) || length(object@DoubleKernel)!=1) { + msg <- c(msg, "DoubleKernel must be set and of length 1!") + } + if (anyNA(object@IndVar) || length(object@IndVar)!=1) { + msg <- c(msg, "IndVar must be set and of length 1!") + } + else { + if (anyNA(object@StageDep) || length(object@StageDep)!=1) { + msg <- c(msg, "StageDep must be set and of length 1!") + } + else{ + if (object@IndVar && object@StageDep) { + msg <- c(msg, "Inter-individual variability (IndVar=TRUE) in stage-dependent (StageDep=TRUE) dispersal kernel traits is not implemented!") + } + } + } + if (anyNA(object@SexDep) || length(object@SexDep)!=1) { + msg <- c(msg, "SexDep must be set and of length 1!") + } + if(object@IndVar){ + if(!is.null(object@Distances)){ + msg <- c(msg, "Distances must be NULL if IndVar=TRUE!") + } + } else{ + if (anyNA(object@Distances) || length(object@Distances)==0) { + msg <- c(msg, "Distances must be set!") + } + else{ + if (!object@DoubleKernel && !object@StageDep && !object@SexDep) { + if (length(object@Distances)!=1) { + msg <- c(msg, "Distances must be a single value if IndVar,DoubleKernel,StageDep,SexDep = FALSE!") + } + } + else { + if (class(object@Distances)[1] !="matrix") { + msg <- c(msg, "Distances must be a matrix!") + } + } + } + } + + if (is.null(msg)) { + if (!object@IndVar && object@DoubleKernel && !object@StageDep && !object@SexDep && any(dim(object@Distances)!=c(1,3)) ) { + msg <- c(msg, "Distances must be a 1x3 matrix if IndVar,StageDep,SexDep = FALSE and DoubleKernel = TRUE!") + } + if (!object@IndVar && !object@DoubleKernel && !object@StageDep && object@SexDep && any(dim(object@Distances)!=c(2,2)) ) { + msg <- c(msg, "Distances must be a 2x2 matrix if IndVar,DoubleKernel,StageDep = FALSE and SexDep = TRUE!") + } + if (!object@IndVar && !object@DoubleKernel && object@StageDep && object@SexDep && dim(object@Distances)[2]!=3 ) { + msg <- c(msg, "Distances must have 3 columns if IndVar,DoubleKernel = FALSE and StageDep,SexDep = TRUE!") + } + if (!object@IndVar && object@DoubleKernel && object@StageDep && !object@SexDep && dim(object@Distances)[2]!=4 ) { + msg <- c(msg, "Distances must have 4 columns if IndVar,SexDep = FALSE and DoubleKernel,StageDep = TRUE!") + } + if (!object@IndVar && object@DoubleKernel && !object@StageDep && object@SexDep && any(dim(object@Distances)!=c(2,4)) ) { + msg <- c(msg, "Distances must be a 2x4 matrix if IndVar,StageDep = FALSE and DoubleKernel,SexDep = TRUE!") + } + } + if (anyNA(object@DistMort) || length(object@DistMort)!=1) { + msg <- c(msg, "DistMort must be set and of length 1!") + } + else { + if (object@DistMort) { + # atm no conditions for Slope, InflPoint + if (anyNA(object@Slope) || length(object@Slope)!=1) { + msg <- c(msg, "Slope must be set and of length 1!") + } + if (anyNA(object@InflPoint) || length(object@InflPoint)!=1) { + msg <- c(msg, "InflPoint must be set and of length 1!") + } + } + else { + if (anyNA(object@MortProb) || length(object@MortProb)!=1) { + msg <- c(msg, "MortProb must be set and of length 1!") + } + else { + if (object@MortProb < 0 | object@MortProb >= 1 ) { + msg <- c(msg, "MortProb must be in the half-open interval [0,1) !") + } + } + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "DispersalKernel", function(.Object, ...) { + this_func = "DispersalKernel(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (class(args$Distances)[1]=="numeric" && length(args$Distances)==1) { + .Object@Distances <- as.matrix(args$Distances) + } + if (.Object@DistMort) { + .Object@MortProb = -9L + if (!is.null(args$MortProb)) { + warning(this_func, "MortProb", warn_msg_ignored, "since DistMort = TRUE.", call. = FALSE) + } + } + else { + .Object@Slope = -9L + if (!is.null(args$Slope)) { + warning(this_func, "Slope", warn_msg_ignored, "since DistMort = FALSE.", call. = FALSE) + } + .Object@InflPoint = -9L + if (!is.null(args$InflPoint)) { + warning(this_func, "InflPoint", warn_msg_ignored, "since DistMort = FALSE.", call. = FALSE) + } + } + .Object} +) +setMethod("show", "DispersalKernel", function(object){ + callNextMethod() + if (object@IndVar) { + cat(" IndVar =", object@IndVar, "\n") + } + if (object@DoubleKernel) { + cat(" DoubleKernel =", object@DoubleKernel, "\n") + } + if (object@StageDep) { + cat(" StageDep =", object@StageDep, "\n") + } + if (object@SexDep) { + cat(" SexDep =", object@SexDep, "\n") + } + cat(" Dispersal kernel traits:\n") + if(!object@IndVar) print(object@Distances) + else print("Traits defined in KernelTraits()") + if (object@DistMort) { + cat(" Distance-dependent mortality prob with:\n Inflection point =", object@InflPoint, "\n Slope =", object@Slope, "\n") + } + else { + cat(" Constant mortality prob =", object@MortProb, "\n") + } +}) +setMethod("plotProbs", "DispersalKernel", function(x, mortality = FALSE, combinekernels = FALSE, stage = NULL, sex = NULL, xmax = NULL, ymax = NULL){ + if (mortality) { + # New plot + if (x@DistMort) { + if (is.null(xmax)) {xmax = min(2*x@InflPoint, x@InflPoint + 3.0/x@Slope)} + xvals = seq(0, xmax, length.out = 100) + plot(xvals, densdep(xvals, alpha = x@Slope, beta = x@InflPoint), type = "l", lwd = 1.5, ylab = "Mortality Probability", xlab = "Dispersal distance", ylim = c(0,1)) + } + else { + plot(x=c(0,10000), y=rep(x@MortProb,2), type = "l", lwd = 1.5, ylab = "Mortality Probability", xlab = "Dispersal distance", ylim = c(0,1)) + } + } + else { # !mortality + dists <- x@Distances + # error messages + if (!is.null(stage)){ + if (x@StageDep) { + dists <- subset(dists, dists[,1] %in% stage) + } + else{ print("This dispersal kernel has no stage-dependency.\n") } + } + if (!is.null(sex)){ + if (x@SexDep) { + if (x@StageDep) dists <- subset(dists, dists[,2] %in% sex) + else dists <- subset(dists, dists[,1] %in% sex) + } + else{ print("This dispersal kernel has no sex-dependency.\n") } + } + if (combinekernels){ + if (!x@DoubleKernel) { + print("Kernels can only be combined if a mixed kernel (DoubleKernel = TRUE) is given.\n") + combinekernels = FALSE + } + } + # get column indices + if (x@StageDep) { + if (x@SexDep) {ind_kernel1 <- 3} else {ind_kernel1 <- 2} + } + else{ + if (x@SexDep) {ind_kernel1 <- 2} else {ind_kernel1 <- 1} + } + if (x@DoubleKernel) { + if (x@IndVar) {ind_kernel2 <- ind_kernel1 + 2} else {ind_kernel2 <- ind_kernel1 + 1} + } + if (combinekernels){ + if (x@IndVar) {ind_pI <- ind_kernel2 + 2} else {ind_pI <- ind_kernel2 + 1} + } + # New plot + xlab = "Dispersal distance" + if (x@DoubleKernel && !combinekernels) xlab <- paste(xlab, "(Kernel-1 solid, Kernel-2 dashed)") + if (x@IndVar) xlab <- paste(xlab, ", initial dist.") + if (is.null(xmax)) {xmax = 3*max(dists)} + xvals = seq(0, xmax, length.out = 100) + if (is.null(ymax)) { + if (x@DoubleKernel){ + ymax = 1/(min(dists[,c(ind_kernel1,ind_kernel2)][dists[,c(ind_kernel1,ind_kernel2)]>0])) + } + else{ + ymax = 1/(min(dists[,ind_kernel1][dists[,ind_kernel1]>0])) + } + } + plot(NULL, type = "n", ylab = "Probability Density", xlab = xlab, xlim = c(0,xmax), ylim = c(0,ymax)) + leg.txt <- c() + # Go through lines of distances matrix and add curves to plot + for(line in 1:nrow(dists)){ + if(dists[line,ind_kernel1]>0){ + if (!combinekernels){ + if (x@IndVar) { + res <- matrix(ncol = 3, nrow = length(xvals)) + res[,1] <- dexp(xvals, rate = 1/(dists[line,ind_kernel1])) + res[,2] <- dexp(xvals, rate = 1/(dists[line,ind_kernel1]+dists[line,ind_kernel1+1])) + res[,3] <- dexp(xvals, rate = 1/(dists[line,ind_kernel1]-dists[line,ind_kernel1+1])) + polygon(c(xvals,rev(xvals)), c(apply(res, 1, min), rev(apply(res, 1, max))), border=NA, col='grey80') + } + lines(xvals,dexp(xvals,rate = 1/dists[line,ind_kernel1]), type = "l", lty = 1, col = line) + } + } + else {lines(xvals, rep(0, length(xvals)), type = "l", lty = 1, col = line)} + if (x@DoubleKernel){ + if(dists[line,ind_kernel2]>0){ + if (combinekernels){ + pI <- dists[line,ind_pI] + if (x@IndVar) { + pI_sd <- c(pI+dists[line,ind_pI+1],pI-dists[line,ind_pI+1]) + res <- matrix(ncol = 8, nrow = length(xvals)) + res[,1] <- pI_sd[1] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]+dists[line,ind_kernel1+1])) + (1-pI_sd[1]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]+dists[line,ind_kernel2+1])) + res[,2] <- pI_sd[2] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]+dists[line,ind_kernel1+1])) + (1-pI_sd[2]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]+dists[line,ind_kernel2+1])) + res[,3] <- pI_sd[1] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]-dists[line,ind_kernel1+1])) + (1-pI_sd[1]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]+dists[line,ind_kernel2+1])) + res[,4] <- pI_sd[2] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]-dists[line,ind_kernel1+1])) + (1-pI_sd[2]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]+dists[line,ind_kernel2+1])) + res[,5] <- pI_sd[1] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]+dists[line,ind_kernel1+1])) + (1-pI_sd[1]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]-dists[line,ind_kernel2+1])) + res[,6] <- pI_sd[2] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]+dists[line,ind_kernel1+1])) + (1-pI_sd[2]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]-dists[line,ind_kernel2+1])) + res[,7] <- pI_sd[1] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]-dists[line,ind_kernel1+1])) + (1-pI_sd[1]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]-dists[line,ind_kernel2+1])) + res[,8] <- pI_sd[2] * dexp(xvals, rate = 1/(dists[line,ind_kernel1]-dists[line,ind_kernel1+1])) + (1-pI_sd[2]) * dexp(xvals, rate = 1/(dists[line,ind_kernel2]-dists[line,ind_kernel2+1])) + polygon(c(xvals,rev(xvals)), c(apply(res, 1, min), rev(apply(res, 1, max))), border=NA, col='grey80') + } + yvals <- pI * dexp(xvals, rate = 1/dists[line,ind_kernel1]) + (1-pI) * dexp(xvals, rate = 1/dists[line,ind_kernel2]) + lines(xvals, yvals , type = "l", lty = 1, col = line) + } + else { + if (x@IndVar) { + res[,1] <- dexp(xvals, rate = 1/(dists[line,ind_kernel2])) + res[,2] <- dexp(xvals, rate = 1/(dists[line,ind_kernel2]+dists[line,ind_kernel2+1])) + res[,3] <- dexp(xvals, rate = 1/(dists[line,ind_kernel2]-dists[line,ind_kernel2+1])) + polygon(c(xvals,rev(xvals)), c(apply(res, 1, min), rev(apply(res, 1, max))), border=NA, col='grey80') + } + lines(xvals,dexp(xvals,rate = 1/dists[line,ind_kernel2]), type = "l", lty = 2, col = line) + } + } + else{ + lines(xvals, rep(0, length(xvals)), type = "l", lty = 2, col = line) + } + } + if (x@StageDep) { + if (x@SexDep) {leg.txt <- c(leg.txt, paste0("Stage ",dists[line,1], ifelse(dists[line,2]," male"," female")))} else {leg.txt <- c(leg.txt, paste0("Stage ",dists[line,1]))} + } + else { + if (x@SexDep) {leg.txt <- c(leg.txt, ifelse(dists[line,1],"male","female"))} + } + } + if (length(leg.txt)>0) { + legend("topright", leg.txt, col = 1:nrow(dists), lwd = 1.5) + } + } +}) + + + +## Transfer-class STOCHMOVE + +#' Set up a Stochastic Movement Simulator +#' +#' A method to describe \code{\link[RangeShiftR]{Transfer}}: +#' SMS is a stochastic individual-based movement model where organisms move through grid-based, heterogeneous landscapes. The model uses similar +#' cost surfaces as the least cost path (LCP) method, but it relaxes two of its main assumptions: Firstly, individuals are not assumed to be +#' omniscient, but move according to what they can perceive of the landscape within their perceptual range (\code{PR}). Secondly, individuals +#' do not know a priori their final destination, which is a reasonable assumption for dispersing individuals. For a complete description of the +#' method, see the Details below or refer to \insertCite{palmer2011introducing;textual}{RangeShiftR}. +#' +#' @usage SMS(PR = 1, PRMethod = 1, MemSize = 1, +#' DP = 1.0, +#' GoalType = 0, +#' GoalBias = 1.0, AlphaDB, BetaDB, +#' IndVar = FALSE, +#' Costs, StepMort = 0.0, +#' StraightenPath = TRUE) +#' @param PR Perceptual range. Given in number of cells, defaults to \eqn{1}. (integer) +#' @param PRMethod Method to evaluate the effective cost of a particular step from the landscape within the perceptual range:\cr \eqn{1 = }Arithmetic mean (default)\cr \eqn{2 = }Harmonic +#' mean\cr \eqn{3 = }Weighted arithmetic mean +#' @param MemSize Size of memory, given as the number of previous steps over which to calculate current direction to apply directional persistence +#' (\code{DP}). A maximum of \eqn{14} steps is supported, default is \eqn{1}. (integer) +#' @param DP Directional persistence. Corresponds to the tendency to follow a correlated random walk, must be \eqn{\ge 1.0}, defaults to \eqn{1.0}.\cr +#' If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}. +#' @param GoalType Goal bias type: \eqn{0 = } None (default), \eqn{2 = } Dispersal bias. +#' @param GoalBias Only if \code{GoalType=2}: Goal bias strength. Must be must be \eqn{\ge 1.0}, defaults to \eqn{1.0}. \cr If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}. +#' @param AlphaDB Required if \code{GoalType=2}: Dispersal bias decay rate. Must be must be \eqn{> 0.0}.\cr If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}. +#' @param BetaDB Required if \code{GoalType=2}: Dispersal bias decay inflection point (given in number of steps). Must be must be \eqn{> 0.0}.\cr If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}. +#' @param IndVar Individual variability in SMS traits (i.e. \code{DP}, \code{GoalBias}, \code{AlphaDB} and \code{BetaDB})? Defaults to \code{FALSE}. If \code{TRUE}, specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}. +#' @param Costs Describes the landscapes resistance to movement. Set either: \cr +#' - \emph{habitat-specific} costs for each habitat type, or\cr +#' - \code{"file" or "matrix"}, to indicate to use the \emph{cost raster} map(s) specified in the landscape module and import the cost values from them.\cr +#' In the first case of \emph{habitat-specific} costs a numeric vector is expected with, respectively, length \code{Nhabitats} for an \code{\link[RangeShiftR]{ImportedLandscape}} +#' with habitat codes (i.e. \code{HabPercent=FALSE})) or length \eqn{2} for an \code{\link[RangeShiftR]{ArtificialLandscape}} (matrix and habitat costs).\cr +#' In the second case of importing a \emph{cost raster} file or matrix, specify the file name(s) or matrices in the \code{\link[RangeShiftR]{ImportedLandscape}} module. +#' The specified map or matrix has to match the landscape raster/matrix in extent, coordinates and resolution, and each cell contains a cost value (\eqn{\ge 1}). +#' This is the only option for an imported landscape with habitat qualities / cover percentage (i.e. \code{HabPercent=TRUE}). +#' @param StepMort Per-step mortality probability. Can be either \emph{constant}, in which case a single numeric is expected (the default, with +#' value \eqn{0.0}) or \emph{habitat-specific}, in which case a numeric vector (with a length as described above for \code{Costs}) is expected. +#' All values must be within the half-open interval \eqn{[0,1)}. \cr +#' For an imported habitat quality landscape (\code{HabPercent=TRUE}), only constant per-step mortality is allowed. +#' @param StraightenPath Straighten path after decision not to settle in a patch? Defaults to \code{TRUE}, see Details below. +#' @details +#' SMS is a stochastic individual-based model where organisms move through grid-based, heterogeneous landscapes. The model uses similar cost +#' surfaces as the least cost path (LCP) \insertCite{adriaensen2003application,chardon2003incorporating,stevens2006gene,driezen2007evaluating}{RangeShiftR}, +#' but it relaxes two of the main assumptions/limitations of the latter. Firstly, individuals are not assumed to be omniscient, but move according to what they +#' can perceive of the landscape within their perceptual range. Secondly, individuals do not know a priori their final destination, which is a +#' reasonable assumption for dispersing individuals. Here, the core components of SMS are briefly described; +#' see \insertCite{palmer2011introducing;textual}{RangeShiftR} for a complete description of the method. +#' +#' SMS uses cost maps where a relative cost to movement is assigned to each habitat type. Costs are integer numbers and represent the cost of +#' moving through a particular land cover relative to the cost of moving through breeding habitat (which is conventionally set to a cost of \eqn{1}). +#' Individuals take single cell steps basing their decisions on three parameters: their perceptual range (\code{PR}) (given in number of cells), +#' the method used to evaluate the landscape within their perceptual range (\code{PRMethod}), and their directional persistence (\code{DP}), which corresponds to +#' their tendency to follow a correlated random walk. At each step, the individual evaluates the surrounding habitat in order to determine +#' the effective cost of taking a particular step to each of the eight neighbouring cells. The effective cost is a mean of the cost of the +#' neighbouring cell and the surrounding cells beyond it within the \code{PR}, and is calculated by one of three possible methods:\cr +#' - \emph{Arithmetic mean}\cr +#' - \emph{Harmonic mean} - The reciprocal of the arithmetic mean of the reciprocals of the observations (cell costs). This method increases the +#' detectability of low cost cells but performs less well than the arithmetic mean in detecting high cost cells. Therefore, the choice between +#' the two depends on whether the main driver of the animal movement is selecting for good habitat or avoiding costly habitat.\cr +#' - \emph{Weighted arithmetic mean} - The cost of each cell is weighted by its inverse distance from the individual (which is assumed to be in +#' the centre of the current cell). +#' +#' The effective cost of each neighbouring cell is weighted by the \code{DP}, which is lowest in the direction of travel. \code{DP} can be +#' calculated over more steps than just the previous one (up to a maximum of \eqn{14}), which is controlled by the memory size parameter (\code{MemSize}) +#' \insertCite{palmer2014inter,aben2014simple}{RangeShiftR}. Increasing the memory size means that an individual retains for longer its tendency to move in a +#' certain direction, and hence paths tend to become somewhat smoother. +#' +#' There is an option to include goal bias, i.e. a tendency to move towards a particular destination \insertCite{aben2014simple}{RangeShiftR}, +#' which is implemented in a similar way to \code{DP}. However, as dispersers in \emph{RangeShiftR} are naïve and have no goal, it may be applied only in the ‘negative’ +#' sense of moving away from the natal location (\code{GoalType=2}), i.e. as a dispersal bias, which is subject to a decay in strength as a +#' function of the total number of steps taken (set the decay rate \code{AlphaDB} and inflection point \code{BetaDB}). +#' This enables a dispersal path to follow a straighter trajectory initially, and later become more responsive to perceived landscape costs. +#' +#' The product of the reciprocals of effective cost, \code{DP} and dispersal bias, scaled to sum to one, +#' give the probabilities that the individual will move to each neighbouring cell. All the dispersing individuals move simultaneously, i.e. at +#' each time-step they all make one move. In the case of patch-based models, the individual is forced to leave the natal patch by increasing its +#' \code{DP} ten-fold until it has taken a number of steps (\eqn{=2*}\code{PR}) outside the natal patch. +#' +#' When an individual arrives in a non-natal patch and decides not to settle there (as a result of a density-dependent or mate-finding settlement +#' rule; see \code{\link[RangeShiftR]{Settlement}}), then there is the option that its path is straightened (\code{StraightenPath=TRUE}). This means +#' that it leaves the patch as soon as possible in order to search for another patch. This is achieved by increasing its \code{DP} ten-fold. However, in +#' certain types of model, e.g. when arbitrary contiguous patches have been defined for what is basically a continuous population, this can lead +#' to the path always being straightened, as an individual enters a new patch as soon as it has left the one it has rejected. In such cases, it is +#' advisable to disable the feature (\code{StraightenPath=FALSE}), although care must be taken that individuals do not become trapped in patches +#' surrounded by very high cost matrix. +#' +#' When inter-individual variability is activated (set \code{IndVar=TRUE}), the four SMS movement traits \code{DP}, as well as - if dispersal goal bias +#' is enabled - \code{GB}, \code{AlphaDB} and \code{BetaDB} can evolve. In this case, you must set the corresponding traits to \code{NULL} here and must specify them in the \code{\link[RangeShiftR]{SMSTraits}} module and set up the genetics +#' (see \code{\link[RangeShiftR]{Genetics}}).\cr +#' +#' As currently implemented, there is no sex- or stage- dependence of SMS traits. +#' +#' The production of the output ‘dispersal heat maps’, which show the total number of times each cell is visited by dispersing individuals within a +#' single replicate simulation, can be enabled with the option \code{SMSHeatMap} in \code{\link[RangeShiftR]{Simulation}}. +#' +#' \emph{Costs layer} \cr +#' Critical for the outcomes of SMS are the relative costs assigned to the different habitats (as it is also the case for +#' the LCP approach). Habitat costs or resistance to movement can be set manually for each habitat code or imported as a raster map, which +#' allows for costs to be a function of multiple variables instead of a simple value associated to the habitat type. +#' In the latter case, the file names/matrices are provided in the \code{\link[RangeShiftR]{ImportedLandscape}} module. +#' The specified map has to match the landscape raster/matrix in extent, coordinates and resolution, and each cell contains a cost value, with the minimal possible cost being \eqn{1}. +#' Importing a cost layer is the only option when the landscape comprises habitat coverage or quality. +#' +#' \emph{Mortality} \cr +#' There are two main sources of mortality: First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. Some individuals may fail +#' to find suitable habitat before they use up their maximum number of movement steps (\code{MaxSteps} in \code{\link[RangeShiftR]{Settlement}}). +#' In this first case, dispersal mortality clearly depends upon the proportion of suitable habitat in the landscape and will increase as the +#' availability of habitat declines.\cr +#' A second source of dispersal mortality can be specified by the user in form of a per-step probability of mortality (\code{StepMort}. +#' This can be useful for representing mortality risks that increase with distance or time spent travelling \insertCite{bonte2012costs}{RangeShiftR}. +#' Additionally, it is possible that the per-step mortality varies according to the nature of the local environment by providing the \code{CostMap}. +#' +#' Note that the total dispersal mortality +#' experienced will be the sum of the mortalities due to the two sources identified above and, in parameterising the model, it will be important +#' to recognize this such that dispersal mortality is not double-accounted. +#' +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "StochMove" +#' @author Anne-Kathleen Malchow +#' @name SMS +#' @export SMS +SMS <- setClass("StochMove", slots = c(PR = "integer_OR_numeric", + PRMethod = "integer_OR_numeric", # Perceptual range method: 1 = arithmetic mean; 2 = harmonic mean; 3 = weighted arithmtic mean + MemSize = "integer_OR_numeric", + GoalType = "integer_OR_numeric", # 0 (none) or 2 (dispersal bias) + IndVar = "logical", + DP = "ANY", # numeric", + GoalBias = "ANY", # "numeric", + AlphaDB = "ANY", # "numeric", + BetaDB = "ANY", # "integer_OR_numeric", + StraightenPath = "logical", + Costs = "numeric_OR_character", # will determine on C++ level the values of CostHab1 ... CostHabN, CostHabitat, CostMatrix, CostMap, CostMapFile + CostMap = "logical", + StepMort = "numeric") # will determine on C++ level the values of HabMort, MortConst, MortHab1 ... MortHabN, MortHabitat, MortMatrix + , prototype = list(PR = 1L, + PRMethod = 1L, + MemSize = 1L, + GoalType = 0L, + IndVar = FALSE, + DP = 1.0, + GoalBias = 1.0, + #AlphaDB = 1.0, + #BetaDB = 100000, + StraightenPath = TRUE, + #Costs, + StepMort = 0.0) + , contains = "TransferParams" +) +setValidity("StochMove", function(object) { + msg <- NULL + if (anyNA(object@PR) || length(object@PR)!=1) { + msg <- c(msg, "PR must be set and of length 1!") + } + else{ + if (object@PR < 1.0) { + msg <- c(msg, "PR must be >= 1!") + } + } + if (anyNA(object@PRMethod) || length(object@PRMethod)!=1) { + msg <- c(msg, "PRMethod must be set and of length 1!") + } + else{ + if (object@PRMethod != 1 && object@PRMethod != 2 && object@PRMethod != 3) { + msg <- c(msg, "PRMethod must be either 1, 2 or 3!") + } + } + if (anyNA(object@MemSize) || length(object@MemSize)!=1) { + msg <- c(msg, "MemSize must be set and of length 1!") + } + else{ + if (object@MemSize < 1 || object@MemSize > 14) { + msg <- c(msg, "MemSize must be between 1 and 14 !") + } + } + if (anyNA(object@GoalType) || length(object@GoalType)!=1) { + msg <- c(msg, "GoalType must be set and of length 1!") + } + else{ + if (object@GoalType != 0 && object@GoalType != 2) { + msg <- c(msg, "GoalType must be either 0 or 2!") + } + } + if (anyNA(object@IndVar) || length(object@IndVar)!=1) { + msg <- c(msg, "IndVar must be set and of length 1!") + } + if(is.null(msg)){ + if(object@IndVar){ + if(!is.null(object@DP)) + msg <- c(msg, "If IndVar=TRUE, DP must be set to NULL!") + } + else{ + if (anyNA(object@DP) || length(object@DP)==0) { + msg <- c(msg, "DP must be set!") + } + else { + if(length(object@DP)==1){ + if (object@DP < 1.0) { + msg <- c(msg, "DP must be >= 1.0 !") + } + } + else{ + msg <- c(msg, "DP must have length 1 if IndVar=FALSE!") + } + } + } + + if (object@GoalType) { # GoalType = 2 + if (object@IndVar) { + if (!is.null(object@GoalBias)) { + msg <- c(msg, "If IndVar=TRUE, GoalBias must be set to NULL!") + } + if (!is.null(object@AlphaDB)) { + msg <- c(msg, "If IndVar=TRUE, AlphaDB must be set to NULL!") + } + if (!is.null(object@BetaDB)) { + msg <- c(msg, "If IndVar=TRUE, BetaDB must be set to NULL!") + } + + } else + { + if (anyNA(object@GoalBias) || length(object@GoalBias)==0) { + msg <- c(msg, "GoalBias strength must be set!") + } + else{ + if(length(object@GoalBias)==1){ + if (object@GoalBias < 1.0 ) { + msg <- c(msg, "GoalBias strength must be >= 1.0 !") + } + } + else{ + msg <- c(msg, "GoalBias strength must have length 1 if IndVar=FALSE!") + } + } + if (anyNA(object@AlphaDB) || length(object@AlphaDB)==0) { + msg <- c(msg, "AlphaDB must be set!") + } + else{ + if(length(object@AlphaDB)==1){ + if (object@AlphaDB <= 0.0) { + msg <- c(msg, "AlphaDB must be strictly positive!") + } + } + else{ + msg <- c(msg, "AlphaDB must have length 1 if IndVar=FALSE!") + } + } + if (anyNA(object@BetaDB) || length(object@BetaDB)==0) { + msg <- c(msg, "BetaDB must be set!") + } + else{ + if(length(object@BetaDB)==1){ + if (object@BetaDB < 1.0) { + msg <- c(msg, "BetaDB must be >= 1 steps!") + } + } + else{ + msg <- c(msg, "BetaDB must have length 1 if IndVar=FALSE!") + } + } + } + + + + } + } + if (anyNA(object@StraightenPath) || length(object@StraightenPath)!=1) { + msg <- c(msg, "StraightenPath must be set and of length 1!") + } + if (anyNA(object@Costs) || length(object@Costs)==0) { + msg <- c(msg, "Costs must be set!") + } + else{ + if (class(object@Costs)=="numeric") { + if (any(object@Costs < 1) ) { + msg <- c(msg, "Costs must equal 1 (minimum cost) or be larger!") + } + } + else { + if (class(object@Costs)=="character") { + if (!(object@Costs %in% c("file", "matrix"))) { + msg <- c(msg, "Costs has a wrong format! Must be either numeric or the keyword \"file\" or \"matrix\".") + } + } + else{ # neither numeric nor character + msg <- c(msg, "Costs has a wrong format!") + } + } + } + if (anyNA(object@StepMort) || length(object@StepMort)==0) { + msg <- c(msg, "StepMort must be set!") + } + else{ + if (any(object@StepMort < 0.0 | object@StepMort >= 1.0) ) { + msg <- c(msg, "StepMort probabilities must be within the half-open interval [0,1) !") + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "StochMove", function(.Object,...) { + this_func = "SMS(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (!.Object@GoalType) { # GoalType = 0 + .Object@GoalBias = 1.0 + if (!is.null(args$GoalBias)) { + warning(this_func, "GoalBias", warn_msg_ignored, "since GoalType = 0.", call. = FALSE) + } + .Object@AlphaDB = -9L + if (!is.null(args$AlphaDB)) { + warning(this_func, "AlphaDB", warn_msg_ignored, "since GoalType = 0.", call. = FALSE) + } + .Object@BetaDB = -9L + if (!is.null(args$BetaDB)) { + warning(this_func, "BetaDB", warn_msg_ignored, "since GoalType = 0.", call. = FALSE) + } + } + if (class(.Object@Costs)=="character") { + if (.Object@Costs %in% c("file", "matrix")) .Object@CostMap = TRUE + } + else { + if (class(.Object@Costs)=="numeric") { + .Object@CostMap = FALSE + } + } + .Object} +) +setMethod("show", "StochMove", function(object){ + callNextMethod() + cat(" PR =", object@PR, ", MemSize =", object@MemSize, "\n") + if (object@PRMethod == 1) cat(" Method: Arithmetic mean \n") + if (object@PRMethod == 2) cat(" Method: Harmonic mean \n") + if (object@PRMethod == 3) cat(" Method: Weighted arithmetic mean \n") + + if (object@IndVar) { + cat(" DP =", object@DP[1], "\u00B1" , object@DP[2], ", scale \u03bc =", object@DP[3], "\n") + } + else { + cat(" DP =", object@DP, "\n") + } + + if (object@GoalType) { + cat(" GoalType: Dispersal bias:\n") + if (object@IndVar) { + cat(" GoalBias =", object@GoalBias[1], "\u00B1" , object@GoalBias[2], ", scale \u03bc =", object@GoalBias[3], "\n") + cat(" AlphaDB =", object@AlphaDB[1], "\u00B1" , object@AlphaDB[2], ", scale \u03bc =", object@AlphaDB[3], "\n") + cat(" BetaDB =", object@BetaDB[1], "\u00B1" , object@BetaDB[2], ", scale \u03bc =", object@BetaDB[3], "\n") + } + else { + cat(" GoalBias =", object@GoalBias, "\n") + cat(" AlphaDB =", object@AlphaDB, ", BetaDB =", object@BetaDB, "\n") + } + } + cat(" StraightenPath =", object@StraightenPath, "\n") + cat(" Costs ") + if (object@CostMap) cat(" read from file or matrix \n") + else cat("=", object@Costs, "\n") + cat(" StepMort =", object@StepMort, "\n") + } +) +setMethod("plotProbs", "StochMove", function(x, xmax = NULL, ymax = NULL){ + if (x@IndVar){ + print("Plotting of inter-individual variability in SMS traits is not implemented yet.") + return() + } else { + # get parameters + gb <- x@GoalBias + if (x@GoalType == 2) { + alp <- x@AlphaDB + bet <- x@BetaDB + main = "Dispersal Bias" + } else main = "Goal Bias is disabled" + # New plot + if (x@GoalType == 2) { + if (is.null(xmax)) xmax = 2*bet[1] + xvals = seq(0, xmax) + } + else {if(is.null(xmax)) xmax <- 100} + if (is.null(ymax)) {ymax = gb[1]*1.1} + plot(NULL, type = "n", main = main, xlab = "Nr of steps", ylab = "Bias strength", xlim = c(0,xmax), ylim = c(1.0,ymax)) + leg.txt <- c() + # add to plot: + # if (x@IndVar) { + # # plot shaded sd interval + # if (x@GoalType == 2) { + # res <- matrix(ncol = 8, nrow = length(xvals)) + # res[,1] <- 1+densdep(xvals, A0 = (gb[1]-gb[2]-1), alpha = -(alp[1]-alp[2]), beta = (bet[1]-bet[2])) + # res[,2] <- 1+densdep(xvals, A0 = (gb[1]-gb[2]-1), alpha = -(alp[1]-alp[2]), beta = (bet[1]+bet[2])) + # res[,3] <- 1+densdep(xvals, A0 = (gb[1]-gb[2]-1), alpha = -(alp[1]+alp[2]), beta = (bet[1]-bet[2])) + # res[,4] <- 1+densdep(xvals, A0 = (gb[1]-gb[2]-1), alpha = -(alp[1]+alp[2]), beta = (bet[1]+bet[2])) + # res[,5] <- 1+densdep(xvals, A0 = (gb[1]+gb[2]-1), alpha = -(alp[1]-alp[2]), beta = (bet[1]-bet[2])) + # res[,6] <- 1+densdep(xvals, A0 = (gb[1]+gb[2]-1), alpha = -(alp[1]-alp[2]), beta = (bet[1]+bet[2])) + # res[,7] <- 1+densdep(xvals, A0 = (gb[1]+gb[2]-1), alpha = -(alp[1]+alp[2]), beta = (bet[1]-bet[2])) + # res[,8] <- 1+densdep(xvals, A0 = (gb[1]+gb[2]-1), alpha = -(alp[1]+alp[2]), beta = (bet[1]+bet[2])) + # polygon(c(xvals,rev(xvals)), c(apply(res, 1, min), rev(apply(res, 1, max))), border=NA, col='grey80') + # } + # else {#constant + # polygon(c(0,xmax,xmax,0), c(rep(gb[1]-gb[2],2),rep(gb[1]+gb[2],2)), border=NA, col='grey80') + # } + # } + # plot lines + if (x@GoalType == 2) { + lines(xvals, 1+densdep(xvals, A0 = (gb[1]-1), alpha = -alp[1], beta = bet[1]), type = "b", lty = 1, col = "blue") + }else { # constant + lines(x=c(0,xmax), y=rep(gb[1],2), type = "b", lty = 1, col = "blue") + } + } + +}) + + +## Transfer-class CORRRW + +#' Set up a Correlated Random Walk +#' +#' A method to describe \code{\link[RangeShiftR]{Transfer}}: +#' A simple correlated random walk without any bias; implemented in continuous space on the top of the landscape grid. +#' +#' @usage CorrRW(StepLength = 1, Rho = 0.5, +#' IndVar = FALSE, +#' StraightenPath = FALSE, +#' StepMort = 0.0) +#' @param StepLength Step length given in meters, defaults to \eqn{1}.\cr If \code{IndVar=TRUE}, \code{NULL} and define the trait in \code{\link[RangeShiftR]{CorrRWTraits}}. +#' @param Rho Correlation parameter \eqn{ρ}, defaults to \eqn{0.5}. Must be in the open interval \eqn{(0,1)}.\cr If \code{IndVar=TRUE}, \code{NULL} and define the trait in \code{\link[RangeShiftR]{CorrRWTraits}} +#' @param IndVar Individual variability in CorrRW traits (i.e. \code{StepLength} and \code{Rho})? Defaults to \code{FALSE}. if \code{TRUE}, define CorrRWTraits in \code{\link[RangeShiftR]{CorrRWTraits}} +#' @param StraightenPath Straighten path after decision not to settle in a patch? Defaults to \code{TRUE}, see Details below. +#' @param StepMort Per-step mortality probability. Can be either \emph{constant}, in which case a single numeric is expected (the default, with +#' value \eqn{0.0}) or \emph{habitat-specific}, in which case a numeric vector is expected with a length of, respectively, \code{Nhabitats} for an +#' \code{\link[RangeShiftR]{ImportedLandscape}} with habitat codes (i.e. \code{HabPercent=FALSE})) or length \eqn{2} for an +#' \code{\link[RangeShiftR]{ArtificialLandscape}} (mortality probabilities for matrix and habitat cells).\cr +#' All values must be within the half-open interval \eqn{[0,1)}.\cr +#' For an imported habitat quality landscape (\code{HabPercent=TRUE}), only constant per-step mortality is allowed. +#' @details +#' Individuals take steps of a constant \code{StepLength}; the direction is sampled from a wrapped Cauchy distribution having a +#' correlation parameter \eqn{Rho} in the range \eqn{0} to \eqn{1} \insertCite{barton2009evolution,zollner1999search}{RangeShiftR}. +#' As for \code{\link[RangeShiftR]{SMS}}, all individuals take each step +#' simultaneously. In the case of patch-based models, +#' \eqn{Rho} is automatically set to \eqn{0.99} until the individual steps outside its natal patch, after which the value of +#' \eqn{Rho} set by the user is restored. \cr +#' The \code{StepLength} and \eqn{Rho} can be set to vary between individuals and evolve (set \code{IndVar=TRUE}). +#' In this case, \code{StepLength} and \eqn{Rho} must be set to \code{NULL} and the corresponding traits must be defined in \code{\link[RangeShiftR]{CorrRWTraits}} (see also \code{\link[RangeShiftR]{Genetics}}). \cr +#' Note that the step length may not evolve below one fifth of +#' the landscape resolution, and correlation may not evolve above \eqn{0.999}. \cr +#' Per-step mortality is not allowed to vary between individuals or to evolve. \cr +#' There is no implementation of sex- or stage-specific CRW. +#' +#' When an individual arrives in a non-natal patch and decides not to settle there (as a result of a density-dependent or mate-finding settlement +#' rule, see \code{\link[RangeShiftR]{Settlement}}), then there is the option that its path is straightened (\code{StraightenPath=TRUE}). This means +#' that it leaves the patch as soon as possible in order to search for another patch. This is achieved by increasing its path correlation to +#' \code{Rho}\eqn{=0.999}. However, in certain types of model, e.g. when arbitrary contiguous patches have been defined for what is basically a continuous +#' population, this can lead to the path always being straightened, as an individual enters a new patch as soon as it has left the one it has +#' rejected. In such cases, it is advisable to disable the feature (\code{StraightenPath=FALSE}), although care must be taken that individuals +#' do not become trapped in patches surrounded by very high cost matrix. +#' +#' \emph{Mortality}\cr +#' There are two main sources of mortality: First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. Some individuals may fail +#' to find suitable habitat before they use up their maximum number of movement steps (\code{MaxSteps} in \code{\link[RangeShiftR]{Settlement}}). +#' In this first case, dispersal mortality clearly depends upon the proportion of suitable habitat in the landscape and will increase as the +#' availability of habitat declines.\cr +#' A second source of dispersal mortality can be specified by the user in form of a per-step probability of mortality (\code{StepMort}. +#' This can be useful for representing mortality risks that increase with distance or time spent travelling \insertCite{bonte2012costs}{RangeShiftR}. +#' +#' Note that the total dispersal mortality experienced will be the sum of the mortalities due to the two sources identified above and, in parameterising the model, +#' it will be important to recognize this such that dispersal mortality is not double-accounted. +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "CorrRW" +#' @author Anne-Kathleen Malchow +#' @name CorrRW +#' @export CorrRW +CorrRW <- setClass("CorrRW", slots = c(IndVar = "logical", + StepLength = "ANY",#"numeric", NULL or numeric + Rho = "ANY",#"numeric", NULL or numeric + StraightenPath = "logical", + StepMort = "numeric") # will determine on C++ level the values of HabMort, MortConst, MortHab1 ... MortHabN, MortHabitat, MortMatrix + , prototype = list(IndVar = FALSE, + StepLength = 1L, + Rho = 0.5, + StraightenPath = FALSE, + StepMort = c(0.0)) + , contains = "TransferParams" +) +setValidity("CorrRW", function(object) { + msg <- NULL + if (anyNA(object@IndVar) || length(object@IndVar)!=1) { + msg <- c(msg, "IndVar must be set and of length 1!") + } + if (object@IndVar){ + if (!is.null(object@StepLength)){ + msg <- c(msg, "StepLength must be NULL is IndVar == TRUE!") + } + if (!is.null(object@Rho)){ + msg <- c(msg, "Rho must be NULL if IndVAR == TRUE!") + } + } else{ + if(!is.numeric(object@StepLength) && (anyNA(object@StepLength) || length(object@StepLength)==0)) { + msg <- c(msg, "StepLength must be set!") + } + else{ + if(length(object@StepLength)==1){ + if (object@StepLength <= 0.0) { + msg <- c(msg, "StepLength must be strictly positive!") + } + } + else{ + msg <- c(msg, "StepLength must have length 1 if IndVar=FALSE!") + } + } + if (!is.numeric(object@Rho) && (anyNA(object@Rho) || length(object@Rho)==0)) { + msg <- c(msg, "Rho must be set!") + } + else{ + if(length(object@Rho)==1){ + if (object@Rho <= 0.0 || object@Rho >= 1.0) { + msg <- c(msg, "Correlation coefficient (Rho) must be within the open interval (1,0)!") + } + } + else{ + msg <- c(msg, "Rho must have length 1 if IndVar=FALSE!") + } + } + } + + + + if (anyNA(object@StraightenPath) || length(object@StraightenPath)!=1) { + msg <- c(msg, "StraightenPath must be set and of length 1!") + } + if (anyNA(object@StepMort) || length(object@StepMort)==0) { + msg <- c(msg, "StepMort must be set!") + } + else{ + if (any(object@StepMort < 0.0 | object@StepMort >= 1.0) ) { + msg <- c(msg, "StepMort probabilities must be within the half-open interval [0,1) !") + } + } + if (is.null(msg)) TRUE else msg} +) +# setMethod("initialize", "CorrRW", function(.Object,...) { +# this_func = "CorrRW(): " +# args <- list(...) +# .Object <- callNextMethod() +# if ( length(args) == 0 ) { +# validObject(.Object) +# } +# .Object} +# ) +setMethod("show", "CorrRW", function(object){ + callNextMethod() + if (object@IndVar) { + cat(" Inter-individual variability enabled. \n") + } + else { + cat(" StepLength =", object@StepLength, "\n") + cat(" Rho =", object@Rho, "\n") + } + cat(" StraightenPath =", object@StraightenPath, "\n") + cat(" StepMort =", object@StepMort, "\n") + } +) + + +### SUBCLASS SETTLEMENTPARAMS + +# from RS 'Settlement' file + +#' Set Settlement Parameters +#' +#' Settlement, or immigration, is the last phase of dispersal, when the organism stops in a new cell or patch of breeding habitat. The +#' available settlement conditions vary depending on the used \code{\link[RangeShiftR]{Transfer}} type. In any case, dispersing individuals +#' are not allowed to settle in their natal cell or patch and can only settle in suitable habitat.\cr +#' \emph{RangeShiftR} incorporates some basic settlement rules that can be stage- or sex-specific or both (set \code{StageDep}, \code{SexDep}). +#' If a movement process is used, density-dependence (\code{DensDep}) and/or inter-individual variability (\code{IndVar}) are available. +#' @usage Settlement(StageDep = FALSE, SexDep = FALSE, +#' Settle = 0, FindMate = FALSE, +#' DensDep = FALSE, +#' IndVar = FALSE, TraitScaleFactor, +#' MinSteps = 0, MaxSteps = 0, MaxStepsYear = 0) +#' @param StageDep Stage-dependent settlement requirements? (default: \code{FALSE}) +#' @param SexDep Sex-dependent settlement requirements? (default: \code{FALSE}) +#' @param Settle Settlement codes (for \code{DispersalKernel}) or settlement probability parameters (for \emph{Movement process} if \code{DensDep=TRUE}) for all +#' stages/sexes, defaults to \eqn{0} (i.e. 'die when unsuitable' for \emph{DispersalKernel} and +#' 'always settle when suitable' for \emph{Movement process}). See the Details below. +#' @param FindMate Mating requirements to settle? Set for all stages/sexes. Must be \code{FALSE} (default) in a female-only model. +#' @param DensDep Movement process only: Density-dependent settlement probability? (default: \code{FALSE}) +#' @param IndVar Movement process only: Individual variability in settlement probability traits? Must be \code{FALSE} (default), +#' if \code{DensDep=FALSE} or \code{StageDep=TRUE}. If \code{TRUE} settlement traits are defined in \code{\link[RangeShiftR]{SettlementTraits}}. +#' @param MinSteps Movement process only: Minimum number of steps. Defaults to \eqn{0}. +#' @param MaxSteps Movement process only: Maximum number of steps. Must be \eqn{0} or more; set to \eqn{0} (default) for “per-step mortality only”. +#' @param MaxStepsYear Movement process and stage-structured population only: Maximum number of steps per year, if there are more than \eqn{1} reproductive seasons (option \code{RepSeasons} in \code{\link[RangeShiftR]{StageStructure}}). +#' Must be \eqn{0} or more. If \eqn{0}, every individual completes the dispersal phase in one year, i.e. between two successive reproduction phases. +#' @details +#' The settlement phase is determined by a suite of strategies, behaviours and reaction norms that lead individuals to the decision to stop +#' in a particular place. Habitat selection, mate finding and density dependence are probably three of the main processes involved, +#' but not the only ones. Like emigration, settlement is a complex process affected by multiple criteria including inter-individual +#' variability and context dependencies. +#' +#' The type of implemented settlement rules depends on the movement model utilized for the \code{\link[RangeShiftR]{Transfer}}. +#' In any case, dispersing individuals are not allowed to settle in their natal cell or patch.\cr +#' \emph{RangeShiftR} incorporates some basic settlement rules that can be stage- or sex-specific or both (set \code{StageDep}, \code{SexDep}). +#' Inter-individual variability (\code{IndVar}) is implemented only for movement processes and then for the three traits +#' determining density-dependent settlement (\ifelse{html}{\out{S0}}{\eqn{S_0}}, \ifelse{html}{\out{αS}}{\eqn{α_S}}, +#' \ifelse{html}{\out{βS}}{\eqn{β_S}}; see below). In this case, settlement may not be stage-dependent.\cr +#' +#' \emph{Settlement with dispersal kernels}\cr +#' When using a \code{\link[RangeShiftR]{DispersalKernel}}, individuals are displaced directly from the starting location to the arrival location. The suitability +#' of the arrival cell or patch determines whether the disperser is successful or not.\cr For species with \emph{non-overlapping generations}, +#' where individuals have only one chance to disperse and reproduce, the model has two options if the arrival cell is unsuitable: the +#' individual either dies (\code{Settle} code \eqn{0}) or it can move to one of the eight neighbouring cells in the case that at least one +#' of them is suitable (\code{Settle} code \eqn{2}). In +#' the latter case, if more than one of the neighbouring cells is suitable, the individual is placed in one of them chosen randomly. +#' For patch-based models, if the arrival patch is unsuitable, the individual either dies or can move to a randomly chosen neighbouring +#' suitable patch, provided that the new patch is only one cell apart from the arrival patch.\cr For species with \emph{overlapping generations} +#' (i.e. a \code{\link[RangeShiftR]{StageStructure}}d population), +#' where individuals can disperse over multiple seasons, there are two additional options: First, if the arrival cell/patch is unsuitable, +#' the individual can stay there waiting until the next dispersal event when it will disperse again according to the set kernel (\code{Settle} code \eqn{1}). Second, +#' if both the arrival cell/patch and all eight neighbouring cells, or all eventual neighbouring patches, are unsuitable the individual +#' can wait in the arrival cell/patch before moving again at the next dispersal event (\code{Settle} code \eqn{3}). The arrival cell/patch is considered suitable if +#' it contains breeding habitat. +#' +#' If the settlement condition is the same for the entire population (\code{StageDep=FALSE} and \code{SexDep=FALSE}), then the parameter +#' \code{Settle} takes a single integer, specifying the corresponding settlement condition code (\eqn{0,1,2} or \eqn{3}). +#' In case of stage- and/or sex-specific settlement conditions, \code{Settle} must be an integer matrix with the first one/two columns +#' stating 'stage' and/or 'sex' (\eqn{0} for \emph{female} and \eqn{1} for \emph{male}), and the last column giving the respective settlement condition. +#' Exactly one row for each stage/sex-combination is required, in no particular order. +#' +#' Settlement condition codes: If the individuals current step ends in unsuitable habitat, it:\cr +#' \eqn{0} = die (default),\cr +#' \eqn{1} = wait (stage-structured models only),\cr +#' \eqn{2} = randomly choose a suitable neighbouring cell or die,\cr +#' \eqn{3} = randomly choose a suitable neighbouring cell or wait (stage-structured models only).\cr +#' +#' Simple example for sex-dependence only: Females choose a neighbouring cell or wait, males wait: \tabular{cc}{\out{ } 0 \tab \out{ } 3 \cr \out{ } 1 \tab \out{ } 0 } +#' +#' \emph{Settlement with movement processes}\cr +#' If individuals are dispersing by one of the two movement processes implemented (\code{\link[RangeShiftR]{SMS}} or +#' \code{\link[RangeShiftR]{CorrRW}}), at each step (made simultaneously) they each evaluate their current cell or patch for the +#' possibility of settling. This allows for the implementation of more complex settlement rules. The simplest one is that the individual +#' decides to stop if there is suitable habitat; this is in any case a necessary condition (set \code{DensDep=FALSE}).\cr +#' If a Settlement module with a constant \eqn{S_0=0} (the default) is used in a model with \emph{movement process} and \code{IndVar=FALSE}, +#' it gets converted to \eqn{S_0=1.0}, i.e. 'always settle when habitat is suitable'. \cr +#' \cr +#' Furthermore, the settlement decision can be density-dependent (set \code{DensDep=TRUE}). In this case, the individual has a probability \ifelse{html}{\out{pS}}{\eqn{p_S}} +#' of settling in the cell or patch \eqn{i}, given by: +#' +#' \ifelse{html}{\out{   pS(i,t) = S0 / ( 1 + e-αS (N(i,t) / K(i,t) - βS) ) } }{\deqn{ p_S(i,t) = S_0 / ( 1 + exp[-α_S (N(i,t)/K(i,t) - β_S) ] ) } } +#' +#' In the case of stage-structured models the above equation is modified to: +#' +#' \ifelse{html}{\out{   pS(i,t) = S0 / ( 1 + e-αS (b(i,t) * N(i,t) - βS) ) } }{\deqn{ p_S(i,t) = S_0 / ( 1 + exp[-α_S (b(i,t) N(i,t) - β_S) ] ) } } +#' +#' In the first case, \eqn{K(i,t)} is the carrying capacity of the cell/patch \eqn{i} at time \eqn{t} given by \code{K_or_DensDep}. +#' In the latter case, \eqn{b(i,t)} represents the strength of density dependence that is given by the inverse of \code{K_or_DensDep}.\cr +#' Further, \ifelse{html}{\out{S0}}{\eqn{S_0}} is the maximum settlement probability, +#' \eqn{N(i,t)} is the number of individuals in the cell/patch \eqn{i} at time \eqn{t}, +#' \ifelse{html}{\out{βS}}{\eqn{β_S}} is the inflection point of the function and +#' \ifelse{html}{\out{αS}}{\eqn{α_S}} is the slope at the inflection point.\cr +#' +#' Inter-individual variability \code{IndVar=TRUE} and thus evolution is implemented only for the three traits determining density-dependent settlement +#' (\code{DensDep=TRUE}), and if so, it may not be stage-dependent (\code{StageDep=FALSE}). +#' Settlement traits must be set in \code{\link[RangeShiftR]{SettlementTraits}} and \code{Settle} must be 0. For details see also \code{\link[RangeShiftR]{Genetics}} and \code{\link[RangeShiftR]{Traits}} +#' +#' The parameters that determine the settlement probabilities have to be provided via the parameter \code{Settle}, which generally takes a numeric matrix, or - if only a single constant probability is +#' used (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}) - a single numeric. If individual variability is enabled, \code{Settle} must be \code{0}. +#' The format of the matrix is defined as follows: The number of required parameter depend on the option \code{DensDep}. If \code{DensDep=FALSE}, the +#' density-independent probability \ifelse{html}{\out{pS}}{\eqn{p_S}} must be specified. If \code{DensDep=TRUE}, the functional parameters \ifelse{html}{\out{S0}}{\eqn{S_0}}, +#' \ifelse{html}{\out{αS}}{\eqn{α_S}} and \ifelse{html}{\out{βS}}{\eqn{β_S}} (cf. equation above) must be specified. +#' +#' All parameters have to be given for each stage/sex if the respective dependency is enabled. If \code{StageDep=TRUE}, state the corresponding stage in the first column. +#' If \code{SexDep=TRUE}, state the corresponding stage in the next (i.e. first/second) column, with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. +#' +#' +#' The following table lists the required columns and their correct order for different settings: +#' +#' \tabular{ccccc}{DensDep \tab IndVar \tab StageDep \tab SexDep \tab columns \cr +# F \tab F \tab F \tab F \tab \ifelse{html}{\out{pS}}{\eqn{p_S}} \cr +#' F \tab F \tab F \tab F \tab - not applicable - \cr +#' F \tab F \tab T \tab F \tab stage, \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr +#' F \tab F \tab F \tab T \tab sex, \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr +#' F \tab F \tab T \tab T \tab stage, sex, \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr +#' T \tab F \tab F \tab F \tab \ifelse{html}{\out{S0}}{\eqn{S_0}}, \ifelse{html}{\out{αS}}{\eqn{α_S}}, \ifelse{html}{\out{βS}}{\eqn{β_S}} \cr +#' \out{⋮} \tab \out{⋮} \tab \out{⋮} \tab \out{⋮} \tab \out{⋮} \cr +#' T \tab F \tab T \tab T \tab stage, sex, \ifelse{html}{\out{S0}}{\eqn{S_0}}, \ifelse{html}{\out{αS}}{\eqn{α_S}}, \ifelse{html}{\out{βS}}{\eqn{β_S}} \cr +#' } +#' +#' The column headings need not be included, only the numeric matrix is required. The rows require no particular order, but they must match with the matrices provided for \code{FindMate, MaxSteps, MinSteps, MaxStepsYr}. There must be exactly one row for each stage/sex combination. +#' +#' For example, in the case of density-, stage- and sex-dependent settlement with no individual variability: +#' \tabular{ccccc}{ \out{ } 0 \tab \out{ } 0 \tab \out{ } 1.0 \tab \out{ } 0.2 \tab \out{ } 4.0 \cr +#' \out{ } 0 \tab \out{ } 1 \tab \out{ } 1.0 \tab \out{ } 0.1 \tab \out{ } 6.0 \cr +#' \out{ } 1 \tab \out{ } 0 \tab \out{ } 0.7 \tab \out{ } 0.5 \tab \out{ } 2.0 \cr +#' \out{ } 1 \tab \out{ } 1 \tab \out{ } 0.5 \tab \out{ } 0.5 \tab \out{ } 2.0 \cr +#' \out{ } 2 \tab \out{ } 0 \tab \out{ } 0.05 \tab \out{ } 1.0 \tab \out{ } 1.0 \cr +#' \out{ } 2 \tab \out{ } 1 \tab \out{ } 0.05 \tab \out{ } 1.0 \tab \out{ } 1.0 +#' } +#' +#' To avoid having individuals moving perpetually because they cannot find suitable conditions to settle, the model requires a maximum number +#' of steps (\code{MaxSteps}) or a per-step mortality (within the \code{Transfer} object), or both, to be set. +#' The maximum number of steps defines the maximum time length of the transfer period. +#' When an individual reaches the maximum number of steps, it stops where it is regardless of the suitability of the location. In +#' the case of \emph{non-overlapping generations} this results in automatic death if the individual stops in unsuitable habitat. For species that can disperse +#' over multiple seasons, i.e. a \emph{stage-structured population}, the model additionally requires a maximum number of steps per dispersal event (\code{MaxStepsYear}); on reaching that limit, the individual will +#' stop where it is and the next season, if still alive, it will move again. +#' +#' An additional rule that can be set constitutes a minimum number of steps (\code{MinSteps}) that each individual must take before settlement can take +#' place. This is useful for simulating situations where animals, in a ‘dispersal mode’, will keep moving and not consider settling even +#' if suitable conditions are available \insertCite{@e.g. @barton2012risky}{RangeShiftR}. +#' +#' Each of the three parameters \code{MinSteps, MaxSteps, MaxStepsYear} need to be provided as single integer (if \code{StageDep=FALSE} and \code{SexDep=FALSE}) or numeric matrix, providing the stage (if \code{StageDep=TRUE}) and sex (if \code{SexDep=TRUE}). +#' The rows require the same order as in \code{Settle}.There must be exactly one row for each stage/sex combination. +#' +#' \tabular{ccccc}{StageDep \tab SexDep \tab columns \cr +#' F \tab F \tab - not applicable only provide single numeric value - \cr +#' T \tab F \tab stage, \code{MinSteps/MaxSteps/MaxStepsYear} \cr +#' F \tab T \tab sex, \code{MinSteps/MaxSteps/MaxStepsYear}\cr +#' T \tab T \tab stage, sex, \code{MinSteps/MaxSteps/MaxStepsYear} \cr +#' } +#' +#' \emph{Mating requirements}\cr +#' Sexual species may be required to find a mate, i.e. there has to be at least one individual of the opposite sex present for the cell/patch to be considered suitable for settlement. +#' Density-dependence and mating requirements can also be combined together to determine the settlement decision. +#' +#' The application of this mating condition can be switched on or off using the parameter \code{FindMate}, which takes either a single +#' logical if \code{StageDep=FALSE} and \code{SexDep=FALSE} or, otherwise, a matrix of the similar structure as for \code{Settle, MinSteps, MaxSteps} and \code{MaxStepsYear}. +#' +#' #' \tabular{ccccc}{StageDep \tab SexDep \tab columns \cr +#' F \tab F \tab - not applicable only provide single logical value - \cr +#' T \tab F \tab stage, \code{FindMate} as logical value \cr +#' F \tab T \tab sex, \code{FindMate} as logical value\cr +#' T \tab T \tab stage, sex, \code{FindMate} as logical value \cr +#' } +#' +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "SettlementParams" +#' @author Anne-Kathleen Malchow +#' @name Settlement +#' @export Settlement +Settlement <- setClass("SettlementParams", slots = c(StageDep = "logical", + SexDep = "logical", + Settle = "matrix_OR_numeric", # Settlement conditions for all sexes/stages. Settlement rule if the arrival cell/patch is unsuitable: 0 = die, 1 = wait, 2 = randomly choose a suitable cell/patch or die, 3 = randomly choose a suitable cell/patch or wait + FindMate = "matrix_OR_logical", + DensDep = "logical", # For MovementProcess only! + IndVar = "logical", # For MovementProcess only! + MinSteps = "matrix_OR_numeric", # For MovementProcess only! + MaxSteps = "matrix_OR_numeric", # For MovementProcess only! + MaxStepsYear = "matrix_OR_numeric") # For MovementProcess only! + , prototype = list(StageDep = FALSE, + SexDep = FALSE, + Settle = 0L, # for DispKernel this is "die" + FindMate = FALSE, + DensDep = FALSE, + IndVar = FALSE, + MinSteps = 0L, + MaxSteps = 0L, + MaxStepsYear = 0L) +) + +setValidity("SettlementParams", function(object) { + msg <- NULL + if (anyNA(object@StageDep) || length(object@StageDep)!=1) { + msg <- c(msg, "StageDep must be set and of length 1!") + } + if (anyNA(object@SexDep) || length(object@SexDep)!=1) { + msg <- c(msg, "SexDep must be set and of length 1!") + } + if (anyNA(object@Settle) || length(object@Settle)==0) { + msg <- c(msg, "Settle must be set!") + } + else{ + if (class(object@Settle)[1]=="numeric" && length(object@Settle)!=1) { + msg <- c(msg, "Settle must be a single numeric or a numeric matrix!") + } + } + if (anyNA(object@DensDep) || length(object@DensDep)!=1) { + msg <- c(msg, "DensDep must be set and of length 1!") + } + if (anyNA(object@IndVar) || length(object@IndVar)!=1) { + msg <- c(msg, "IndVar must be set and of length 1!") + } + if (is.null(msg)) { + if ( object@IndVar && !object@DensDep ) { + msg <- c(msg, "Inter-individual variability (IndVar=TRUE) in settlement traits requires density-dependence (DensDep=TRUE) !") + } + if ( object@IndVar && object@StageDep ) { + msg <- c(msg, "Inter-individual variability (IndVar=TRUE) in stage-dependent (StageDep=TRUE) settlement traits is not implemented!") + } + } + if (anyNA(object@FindMate) || length(object@FindMate)==0) { + msg <- c(msg, "FindMate must be set!") + } + else { + if (is.null(msg)) { + if(object@IndVar){ + if (class(object@FindMate)[1]=="logical" && length(object@FindMate)!=1) { + msg <- c(msg, "FindMate must be a single logical value or a matrix!") + } + } else { + if(nrow(object@FindMate)!=nrow(object@Settle) && length(object@FindMate)!=1 ) { + msg <- c(msg, "FindMate must have either 1 entry or as many as rows in the Settle matrix!") + } + } + + } + } + if (anyNA(object@MinSteps) || length(object@MinSteps)==0) { + msg <- c(msg, "MinSteps must be set!") + } + else { + if (any(object@MinSteps < 0)){ + msg <- c(msg, "MinSteps can't be negative!") + } + } + if (anyNA(object@MaxSteps) || length(object@MaxSteps)==0) { + msg <- c(msg, "MaxSteps must be set!") + } + else { + if (any(object@MaxSteps < 0)){ + msg <- c(msg, "MaxSteps can't be negative!") + } + } + if (is.null(msg)) { + if(object@IndVar){ + if(object@SexDep){ # sex dependent -> constant or provide for both sexes + if(nrow(object@MinSteps)!=2 && length(object@MinSteps)!=1 ) { + msg <- c(msg, "MinSteps must have either 1 entry or 2 rows, one for each sex!") + } + if(nrow(object@MaxSteps)!=2 && length(object@MaxSteps)!=1 ) { + msg <- c(msg, "MaxSteps must have either 1 entry or 2 rows, one for each sex!") + } + } else{ # sex independent -> one value + if( length(object@MinSteps)!=1 ) { + msg <- c(msg, "MinSteps must have 1 entry!") + } + if( length(object@MaxSteps)!=1 ) { + msg <- c(msg, "MaxSteps must have 1 entry!") + } + } + + } else{ + if( nrow(object@MinSteps)!=nrow(object@Settle) && length(object@MinSteps)!=1 ) { + msg <- c(msg, "MinSteps must have either 1 entry or as many as rows in the Settle matrix!") + } + if( nrow(object@MaxSteps)!=nrow(object@Settle) && length(object@MaxSteps)!=1 ) { + msg <- c(msg, "MaxSteps must have either 1 entry or as many as rows in the Settle matrix!") + } + } + + } + if (object@StageDep) { + if (anyNA(object@MaxStepsYear) || length(object@MaxStepsYear)==0) { + msg <- c(msg, "MaxStepsYear must be set!") + } + else { + if (any(object@MaxStepsYear < 0)){ + msg <- c(msg, "MaxStepsYear can't be negative!") + } + else{ + if( nrow(object@MaxStepsYear)!=nrow(object@Settle) && length(object@MaxStepsYear)!=1 ) { + msg <- c(msg, "MaxStepsYear must have either 1 entry or as many as rows in the Settle matrix!") + } + else { + if (any(object@MaxStepsYear>object@MaxSteps)) { + msg <- c(msg, "MaxStepsYear can't be larger than MaxSteps!") + } + } + } + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "SettlementParams", function(.Object,...) { + this_func = "Settlement(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (!is.null(args$Settle)) { + if (class(args$Settle)[1]=="numeric" && length(args$Settle)==1) { + .Object@Settle <- as.matrix(args$Settle) + } + if (class(args$FindMate)[1]=="logical" && length(args$FindMate)==1) { + .Object@FindMate <- as.matrix(args$FindMate) + } + if (class(args$MinSteps)[1]=="logical" && length(args$MinSteps)==1) { + .Object@MinSteps <- as.matrix(args$MinSteps) + } + if (class(args$MaxSteps)[1]=="logical" && length(args$MaxSteps)==1) { + .Object@MaxSteps <- as.matrix(args$MaxSteps) + } + if (class(args$MaxStepsYear)[1]=="logical" && length(args$MaxStepsYear)==1) { + .Object@MaxStepsYear <- as.matrix(args$MaxStepsYear) + } + } + .Object} +) +setMethod("show", "SettlementParams", function(object){ + if (object@DensDep) { + cat(" DensDep =", object@DensDep, "\n") + } + if (object@IndVar) { + cat(" IndVar =", object@IndVar, "\n") + } + if (object@StageDep) { + cat(" StageDep =", object@StageDep, "\n") + } + if (object@SexDep) { + cat(" SexDep =", object@SexDep, "\n") + } + cat(" Settlement conditions:\n") + print(object@Settle) + cat(" FindMate =\n") + print(object@FindMate) + } +) +setMethod("plotProbs", "SettlementParams", function(x, stage = NULL, sex = NULL, xmax = NULL, ymax = NULL){ + sett <- x@Settle + if (x@DensDep && !x@IndVar) { + # error messages + if (!is.null(stage)){ + if (x@StageDep) { + sett <- subset(sett, sett[,1] %in% stage) + } + else{ print("This settlement module has no stage-dependency.\n") } + } + if (!is.null(sex)){ + if (x@SexDep) { + if (x@StageDep) sett <- subset(sett, sett[,2] %in% sex) + else sett <- subset(sett, sett[,1] %in% sex) + } + else{ print("This settlement module has no sex-dependency.\n") } + } + # get column indices + if (x@StageDep) { + if (x@SexDep) {ind_D0 <- 3} else {ind_D0 <- 2} + }else{ + if (x@SexDep) {ind_D0 <- 2} else {ind_D0 <- 1} + } + IV <- 1 + # New plot + if (is.null(xmax)) { + ind_max <- which.max(sett[,ind_D0+2*IV]) + xmax = min(2*sett[ind_max,ind_D0+2*IV], sett[ind_max,ind_D0+2*IV] + 6.0/abs(sett[ind_max,ind_D0+IV])) + } + xvals = seq(0, xmax, length.out = 100) + + if (is.null(ymax)) {ymax = 1} + + plot(NULL, type = "n", ylab = "Settlement probability", xlab = "relative population density (N/K or bN)", xlim = c(0,xmax), ylim = c(0,ymax)) + leg.txt <- c() + # Go through lines of distances matrix and add curves to plot + for(line in 1:nrow(sett)){ + # if (x@IndVar) { + # res <- matrix(ncol = 8, nrow = length(xvals)) + # res[,1] <- densdep(xvals, A0 = sett[line,ind_D0]-sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]-sett[line,ind_D0+3], beta = sett[line,ind_D0+4]-sett[line,ind_D0+5]) + # res[,2] <- densdep(xvals, A0 = sett[line,ind_D0]-sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]-sett[line,ind_D0+3], beta = sett[line,ind_D0+4]+sett[line,ind_D0+5]) + # res[,3] <- densdep(xvals, A0 = sett[line,ind_D0]-sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]+sett[line,ind_D0+3], beta = sett[line,ind_D0+4]-sett[line,ind_D0+5]) + # res[,4] <- densdep(xvals, A0 = sett[line,ind_D0]-sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]+sett[line,ind_D0+3], beta = sett[line,ind_D0+4]+sett[line,ind_D0+5]) + # res[,5] <- densdep(xvals, A0 = sett[line,ind_D0]+sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]-sett[line,ind_D0+3], beta = sett[line,ind_D0+4]-sett[line,ind_D0+5]) + # res[,6] <- densdep(xvals, A0 = sett[line,ind_D0]+sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]-sett[line,ind_D0+3], beta = sett[line,ind_D0+4]+sett[line,ind_D0+5]) + # res[,7] <- densdep(xvals, A0 = sett[line,ind_D0]+sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]+sett[line,ind_D0+3], beta = sett[line,ind_D0+4]-sett[line,ind_D0+5]) + # res[,8] <- densdep(xvals, A0 = sett[line,ind_D0]+sett[line,ind_D0+1], alpha = sett[line,ind_D0+2]+sett[line,ind_D0+3], beta = sett[line,ind_D0+4]+sett[line,ind_D0+5]) + # polygon(c(xvals,rev(xvals)), c(apply(res, 1, min), rev(apply(res, 1, max))), border=NA, col='grey80') + # } + lines(xvals, densdep(xvals, A0 = sett[line,ind_D0], alpha = sett[line,ind_D0+IV], beta = sett[line,ind_D0+2*IV]), type = "l", lty = 1, col = line) + + if (x@StageDep) { + if (x@SexDep) {leg.txt <- c(leg.txt, paste0("Stage ",sett[line,1], ifelse(sett[line,2]," male"," female")))} else {leg.txt <- c(leg.txt, paste0("Stage ",sett[line,1]))} + } + else { + if (x@SexDep) {leg.txt <- c(leg.txt, ifelse(sett[line,1],"male","female"))} + } + } + if (length(leg.txt)>0) { + legend("topright", leg.txt, col = 1:nrow(sett), lwd = 1.5) + } + } + else{ print("Plotting is only implemented for density-dependent settlement (in a movement process) without inter-individual variability.\n") } +}) + + +#### CLASS DISPERSALPARAMS + +# Superclass holding the sub-classes 'EmigrationParams', 'TransferParams' and 'SettlementParams' + +#' Set Dispersal Parameters +#' +#' Dispersal is defined as movement leading to spatial gene flow. It typically involves three phases, which are all modelled explicitly: +#' \code{\link[RangeShiftR]{Emigration}}, \code{\link[RangeShiftR]{Transfer}} and \code{\link[RangeShiftR]{Settlement}}.\cr +#' The specific parameters of each phase are set through their respective functions. For more details, see their documentation.\cr +#' \cr +#' The potential evolution of several key dispersal traits is implemented through the possibility of inter-individual variability and heritability. +#' This option (called \code{IndVar}) can be enabled for each dispersal phase in their respective modules. See the Details below for information on how +#' to set the associated parameters. Additionally, the \code{\link[RangeShiftR]{Genetics}} module must be defined. +#' +#' @usage Dispersal(Emigration = Emigration(), +#' Transfer = DispersalKernel(), +#' Settlement = Settlement()) +#' @param Emigration The first phase of dispersal; determines if an individual leaves its natal patch. +#' @param Transfer (or transience) The second phase of dispersal; consists of the movement of an individual departing from its natal patch towards +#' a potential new patch, ending with settlement or mortality. This movement can be modelled by one of three alternative processes:\cr +#' - Dispersal kernel: use \code{\link[RangeShiftR]{DispersalKernel}}\cr +#' - Stochastic movement simulator (SMS): use \code{\link[RangeShiftR]{SMS}}\cr +#' - Correlated random walk (CRW): use \code{\link[RangeShiftR]{CorrRW}} +#' @param Settlement (or immigration) The last phase of dispersal; determines when the individual stops in a new cell or patch of +#' breeding habitat. +#' @details +#' Dispersal is defined as movement leading to spatial gene flow, and it typically involves three phases: +#' emigration, transfer and settlement +#' \insertCite{stenseth1992,clobert2001,clobert2009,clobert2012,bowler2005,ronce2007}{RangeShiftR}.\cr +#' +#' The key role of dispersal in species persistence and responses to environmental change is increasingly recognized \insertCite{travis2013dispersal}{RangeShiftR}. +#' Moreover, the importance of modelling dispersal as a complex process, explicitly considering its three phases, each of which has +#' ´its own mechanisms and costs, has been recently highlighted \insertCite{bonte2012costs,travis2012modelling,travis2013dispersal}{RangeShiftR}. +#' The implementation of the dispersal process in \emph{RangeShiftR} is based on these recent frameworks and the substantial dispersal +#' theory that has been developed so far \insertCite{clobert2012}{RangeShiftR}. +#' +#' It is possible to model all three phases - emigration, transfer and settlement - with stage- and/or sex-specific parameters via the +#' switches \code{StageDep} and \code{SexDep} in the respective functions. In the case of sex-dependence, the number of traits is doubled, with +#' one set coding for the trait in females and the other for the trait in males. As well as being sex-biased, all dispersal phases can be +#' stage-biased, meaning that parameters can vary for different stage or age classes. +#' +#' The options of inter-individual variability in the various dispersal traits can be enabled by setting \code{IndVar=TRUE} for the respective dispersal phase +#' module and defining the genetic module to simulate heritability and evolution of traits (\code{\link[RangeShiftR]{Genetics}}).\cr +#' For each such heritable dispersal trait, this requires to set the mean and standard deviation of the distribution of trait values +#' in the initial population (instead of a constant value each, as in the case of \code{IndVar=FALSE}), +#' as well as the \code{TraitScaleFactor} for each heritable trait (see \code{\link[RangeShiftR]{Genetics}} documentaion).\cr +#' +#' Note, however, that not all combinations of sex-/stage-dependencies with inter-individual variability are implemented.\cr +#' +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "DispersalParams" +#' @author Anne-Kathleen Malchow +#' @name Dispersal +#' @export Dispersal +Dispersal <- setClass("DispersalParams", slots = c(Emigration = "EmigrationParams", + Transfer = "TransferParams", + Settlement = "SettlementParams") + , prototype = list(Emigration = Emigration(), + Transfer = DispersalKernel(), + Settlement = Settlement()) +) + ## add references to all sub-classes to this explanation of IndVar and TraitScaleFactor + +setValidity("DispersalParams", function(object) { + msg <- NULL + validObject(object@Emigration) + if (object@Emigration@UseFullKern) { + if (!class(object@Transfer)[1] == "DispersalKernel") { + msg <- c(msg, "Dispersal(): The emigration option \"UseFullKern\" can only be used if a dispersal kernel is used as transfer method!") + } + } + validObject(object@Transfer) + validObject(object@Settlement) + if (class(object@Transfer)[1] == "DispersalKernel") { + if (object@Settlement@DensDep) { + msg <- c(msg, "Dispersal(): Settlement can only be density-dependent (DensDep = TRUE) if a movement process is used as transfer method!") + } + }else{ + if (length(object@Settlement@MaxSteps) == 0){#MaxStep not provided + if(all(object@Transfer@StepMort<=0)){ + msg <- c(msg, "Dispersal(): If MaxSteps is not provided, StepMort must be set (>0) if a movement process is used as transfer method!") + } + } else { + if (length(object@Settlement@MaxSteps) == 1){ # MaxSteps only one value + if (object@Settlement@MaxSteps<=0 && all(object@Transfer@StepMort<=0) ) { + msg <- c(msg, "Dispersal(): At least one of the two options MaxSteps and StepMort must be set (>0) if a movement process is used as transfer method!") + } + + } else { + if (any(object@Settlement@MaxSteps[,ncol(object@Settlement@MaxSteps)]<=0) && all(object@Transfer@StepMort<=0) ) { + msg <- c(msg, "Dispersal(): At least one of the two options MaxSteps and StepMort must be set (>0) if a movement process is used as transfer method!") + } + } + } + + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "DispersalParams", function(.Object,...) { + this_func = "Dispersal(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object} +) +setMethod("show", "DispersalParams", function(object){ + cat(" Dispersal: \n Emigration:\n") + print(object@Emigration) + cat("\n Transfer:\n") + print(object@Transfer) + cat("\n Settlement:\n") + print(object@Settlement) + if (!class(object@Transfer)[1] == "DispersalKernel") { + cat(" MinSteps =\n") + print(object@Settlement@MinSteps) + cat(" MaxSteps =\n") + print(object@Settlement@MaxSteps) + cat(" MaxStepsYear =\n") + print(object@Settlement@MaxStepsYear) + } +}) + +# RS manual 2.5 (page 35) - 2.4.3 (page 34) diff --git a/RangeShiftR/R/class_GeneticsParams.R b/RangeShiftR/R/class_GeneticsParams.R new file mode 100644 index 0000000..140c737 --- /dev/null +++ b/RangeShiftR/R/class_GeneticsParams.R @@ -0,0 +1,2451 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + +### CLASS GENETICSPARAMS + +# from RS 'Traits' file + +### SUBCLASS NEUTRALTRAITS + +#' Set up structure of neutral traits +#' +#' A method to specify neutral traits in the genetic module. +#' +#' @usage NeutralTraits( +#' Positions = "random", +#' NbOfPositions = 10, +#' InitialPositions = "all", +#' InitialNbOfPositions = NULL, +#' InitialAlleleDistribution = NULL, +#' InitialAlleleParameters = 2, +#' MutationDistribution = "KAM", +#' MutationParameters = 2, +#' MutationRate = 0.0, +#' OutputValues = FALSE) +#' +#' @param Positions Loci positions coding for trait within genome. Must be in the +#' range 0-(\code{GenomeSize}-1), specified in \code{\link[RangeShiftR]{Genetics}}. Positions can overlap across +#' traits - there will be no pleiotropy, but this will influence genetic linkage., +#' @param NbOfPositions Only specify if \code{Positions} is set to \code{"random"}, else must be blank (\code{NULL}) +#' @param InitialPositions Specify which positions should be initialised. Must be "all", "random" or a vector of integers. If enabled, the remaining initial value parameters will only be applied to the selected positions, +#' and all other positions will be set to 0. Must be in the range of \code{Positions}. +#' @param InitialNbOfPositions Only specify if \code{InitialPositions} is set to \code{"random"}, else must be blank (\code{NULL}). Cannot be greater than \code{NbOfPositions} +#' @param InitialAlleleDistribution Distribution from which to draw initial allele values from. +#' If \code{uniform}. Initialise with random characters between 0 – \code{max}. Note that possible values start at 0, so \code{max=0} +#' specifies a monomorphic initial population. +#' @param InitialAlleleParameters Maximal value for the uniform distribution. +#' @param MutationDistribution Distribution for mutations to draw from. Can be either \code{"KAM"} or \code{"SSM"}. \code{KAM} (k-alleles model) is randomly +#' draw a value between 0 and \code{max} (see \code{MutationParameters}). +#' \code{SSM} (single-step mutation) is to move in a stepwise manner, A to B, B to C. +#' @param MutationParameters Parameters for the above distribution: maximal value for \code{KAM} or \code{SSM} (cannot exceed 255) +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0 +#' @param OutputValues If OutputGeneValues in \code{\link[RangeShiftR]{Genetics}} is +#' enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' +#' @details +#' +#' A neutral trait can be specified to track the evolution of population structure and neutral variation. +#' It is not expressed, and only used to compute neutral statistics. +#' +#' For neutral trait you must specify: +#' +#' - The number and positions of genes controlling the trait: \code{Positions} and \code{NbOfPositions} \cr +#' - Which positions should be initialized \code{InitialPositions} and in case of random positions the number of initial positions \code{InitialNbOfPositions}? \cr +#' - A distribution to sample initial allele values from: \code{InitialAlleleDistribution} and \code{InitialAlleleParameters} \cr +#' - A mutation rate for all genes controlling the trait. \code{MutationRate} \cr +#' - A distribution to sample mutations from. \code{MutationDistribution} and \code{MutationParameters} \cr +#' - Whether or not the allele values should be written to the output \code{OutputValues} \cr +#' +#' The user specifies the number of possible alleles for neutral loci (up to 256), via the maximum parameter of the mutation distribution. +#' Initial values are either identical for all sites (equal to the max value) or sampled in a uniform distribution (between 0 and the maximum value). +#' Mutations are either sampled in a uniform distribution between 0 and the max parameter (k-allele model, KAM, \insertCite{peng2012}{RangeShiftR}) or +#' added as increments (random -1 or +1 changes) of the previous value (symmetric stepwise model, SSM, \insertCite{peng2012}{RangeShiftR}). +#' +#' Dominance values and inheritance are not applicable for neutral traits. +#' +#'@references +#' \insertAllCited{} +#' @return a parameter object of class "NeutralTraitsParams" +#' @author Jette Wolff +#' @name NeutralTraits +#' @export NeutralTraits +NeutralTraits<- setClass("NeutralTraitsParams", slots = c(Positions = "ANY", # vector of numbers or "random" + NbOfPositions = "ANY", # integer value or NULL + InitialPositions = "ANY", # vector of numbers or "random" + InitialNbOfPositions = "ANY", # integer value or NULL + InitialAlleleDistribution = "character", # uniform + InitialAlleleParameters = "integer_OR_numeric", # max value + MutationDistribution = "character", # KAM or SSM + MutationParameters = "integer_OR_numeric", # max + MutationRate = "integer_OR_numeric", # float + OutputValues = "logical") + , prototype = list(Positions = "random", # "random" or list of integer values + NbOfPositions = 10, # numeric, only if positions random + InitialPositions = "all", # "random" or list of integer values + InitialNbOfPositions = NULL, # numeric, only if positions random + InitialAlleleDistribution = NULL, # uniform + InitialAlleleParameters = 2, # neutral traits: only max value; + MutationDistribution = "KAM", # neutral: "KAM" or "SSM" + MutationParameters = 2, # single value or 2 values + MutationRate = 0.0, # numeric + OutputValues = FALSE + )) +setValidity("NeutralTraitsParams", function(object) { + msg <- NULL + + # Check Position and NbOfPositions + isNumeric <- class(object@Positions) == "integer" + isCharacter <- class(object@Positions) == "character" + if (is.null(object@Positions) || (!isNumeric && !isCharacter)) { + msg <- c(msg, "Positions must be integer or character.") + } + if (!isNumeric){ + if(isCharacter && object@Positions != "random") { + msg <- c(msg, "Positions in neutral genetics must be either a vector of integers, or random.") + } + } + if (isCharacter && object@Positions == "random") { + if (is.null(object@NbOfPositions) || object@NbOfPositions <= 0) { + msg <- c(msg, "NbrOfPositions must be a strictly positive integrer.") + } + } else if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "If Positions is not random, NbrOfPositions must not be set (NULL).") + } + + # Check InitialPosition and InitialNbOfPositions + isNumeric <- class(object@InitialPositions) == "integer" + isCharacter <- class(object@InitialPositions) == "character" + if (is.null(object@InitialPositions) || (!isNumeric && !isCharacter)) { + msg <- c(msg, "Initial positions must be integer or character.") + } + if (!isNumeric){ + if(isCharacter && !(object@InitialPositions %in% c("random", "all"))) { + msg <- c(msg, "Initial positions in neutral genetics must be either a vector of integers, random or all.") + } + } + if (isCharacter && object@InitialPositions == "random") { + if (is.null(object@InitialNbOfPositions) || object@InitialNbOfPositions <= 0 || object@InitialNbOfPositions >= object@NbOfPositions) { + msg <- c(msg, "InitialNbOfPositions must be a strictly positive integrer smaller than the NbofPositions.") + } + } else if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "If InitialPositions is not random, InitialNbrOfPositions must not be set (NULL).") + } + + # Check InitialAlleleDistribution + if (object@InitialAlleleDistribution != "uniform") { + msg <- c(msg,"InitialAlleleDistribution must be uniform for the neutral trait.") + } + # Check InitialAlleleParameters + if (object@InitialAlleleDistribution == "uniform") { + # should only be one value (max) + if (length(object@InitialAlleleParameters)!=1) { + msg <- c(msg, "For neutral traits with uniform initialisation, InitialAlleleParameters must only supply the maximal value") + } + else { + if (object@InitialAlleleParameters > 255) { + msg <- c(msg, "For neutral trait with uniform initialisation, max parameter must be between 0 and 255.") + } + } + } + ## if not uniform then initDist must be blank, no params + else if (is.null(object@InitialAlleleDistribution)) { + msg <- c(msg, "For neutral trait InitialAlleleDistribution must be uniform.") + + } + # Check mutation rate + if (!is.null(object@MutationRate) && (any(object@MutationRate < 0) || any(object@MutationRate > 1))) { + msg <- c(msg, "MutationRate must be between 0 and 1.") + } + # Check MutationDistribution and MutationParameters + if (object@MutationDistribution == "KAM" || object@MutationDistribution == "SSM") { + if (length(object@MutationParameters) != 1) { + msg <- c(msg, "For a neutral trait, mutationParams must have form max=int.") + } + else { + if (object@MutationParameters > 255) { + msg <- c(msg, "For the neutral trait mutation max parameter must be between 0 and 255.") + } + } + } + else if (!is.null(object@MutationDistribution)){ + msg <- c(msg, "For a neutral trait, mutationDistribution must be either KAM or SSM.") + } + + if (object@OutputValues != TRUE && object@OutputValues != FALSE) { + msg <- c(msg, "OutputValues for neutral genetics must be either TRUE or FALSE.") + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "NeutralTraitsParams", function(.Object, ...) { + this_func = "NeutralTraits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "NeutralTraitsParams", function(object){ + cat(" Neutral Genetics: \n") + if(is.numeric(object@Positions)) cat(" Loci positions coding for trait: ", object@Positions, "\n") + if(!is.numeric(object@Positions) && object@Positions=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions, " positions\n") + if(is.numeric(object@InitialPositions)) cat(" Initial loci positions coding for trait: ", object@Positions, "\n") + if(!is.numeric(object@InitialPositions) && object@InitialPositions=="random") cat(" Initial loci positions coding for trait randomly chosen with ", object@NbOfPositions, " positions\n") + if(!is.numeric(object@InitialPositions) && object@InitialPositions=="all") cat(" All loci positions chosen for initial loci positions\n") + cat(" Initial distribution: ", object@InitialAlleleDistribution, "\n") + cat(" Initial parameters: ", object@InitialAlleleParameters, "\n") + cat(" Mutation distribution: ", object@MutationDistribution, "\n") + cat(" Mutation parameters: ", object@MutationParameters, "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues) cat(" Allel values for gene is written to output. \n") +}) + + +### SUBCLASS GENETICLOADTRAITS + +#' Set genetic structure for genetic fitness traits +#' +#' @description +#' A method to specify genetic fitness traits in the genetic module. You can specify up to 5 genetic loads. +#' +#' +#' @usage GeneticLoadTraits(NbGeneticLoads = 1, Positions = list("random"), NbOfPositions = 10, +#' InitialPositions = list("all"), InitialNbOfPositions = NULL, +#' InitialAlleleDistribution = "normal", InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), +#' InitialDomDistribution = "normal", InitialDomParameters = matrix(c(0.5,0.1), nrow=1), +#' DominanceDistribution = "normal", DominanceParameters = matrix(c(0.5,0.1), nrow=1), +#' MutationDistribution = "normal", MutationParameters = matrix(c(0.5,0.2), nrow=1), +#' MutationRate = 0.0001, OutputValues = FALSE) +#' +#' @param NbGeneticLoads Number of genetic loads +#' @param Positions Loci positions coding for that trait within genome. Should be provided as a list of strings (if random) and/or vectors of integers (if not random) +#' @param NbOfPositions Number of positions to randomly sample from across the genome for each specified genetic load. Only specify when the \code{Positions} of a genetic load trait are set to \code{"random"}, else must be blank (\code{NULL}) +#' @param InitialPositions Specify which positions should be initialised. Should be provided as a list of strings ("random" or "all") and/or vectors of integers (if not random). If enabled, the remaining initial value parameters will only be applied to the selected positions, +#' and all other positions will be set to 0. Must be in the range of \code{Positions}. +#' @param InitialNbOfPositions Only specify if \code{InitialPositions} for a genetic load is set to \code{"random"}, else must be blank (\code{NULL}). Cannot be greater than \code{NbOfPositions} +#' @param InitialAlleleDistribution Distribution from which to draw initial allele values from. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1} +#' @param InitialAlleleParameters Parameters for the initial distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: +#' min and max (\code{uniform}), mean and sd (\code{normal}) or shape and scale (\code{gamma}) or one column for \code{negExp}: mean +#' If genetic loads have different \code{InitialAlleleDistribution} and one requires two columns you need to set the second value to \code{NA} in case of \code{negExp} distribution. +#' Each row in the matrix corresponds to a genetic load trait. +#' @param InitialDomDistribution Distribution from which to draw initial dominance values. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}, \code{scaled}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1} +#' @param InitialDomParameters Parameters for the initial dominance distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: +#' min and max (\code{uniform}), mean and sd (\code{normal}) or shape and scale (\code{gamma}) or one column for \code{negExp}: mean +#' If genetic loads have different \code{InitialDomParameters} and one requires two columns you need to set the second value to \code{NA} in case of \code{negExp} distribution. +#' Each row in the matrix corresponds to a genetic load trait. +#' @param DominanceDistribution Distribution of dominance values. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}, \code{scaled}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1} +#' @param DominanceParameters Parameters for the dominance distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: +#' min and max (\code{uniform}), mean and sd (\code{normal}) or shape and scale (\code{gamma}) or one column for \code{negExp}, \code{scaled}: mean +#' If genetic loads have different \code{DominanceDistribution} and one requires two columns you need to set the second value to \code{NA} in case of \code{negExp} or \code{scaled} distribution. +#' Each row in the matrix corresponds to a genetic load trait. +#' @param MutationDistribution Distribution for mutations to draw from. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1} +#' @param MutationParameters Parameters for the mutation distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: min and max (\code{uniform}), mean and sd (\code{normal}) +#' or shape and scale (\code{gamma}) or one column for \code{negExp}: mean +#' If genetic loads have different \code{DominanceDistribution} and one require two columns you need to set the second value to \code{NA} in case of \code{negExp} distribution. +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between \code{0.0} and \code{1.0}. Should be provided as a vector if multiple genetic loads are specified. +#' @param OutputValues If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' Should be provided as a vector if multiple genetic loads are specified. +#' +#' @details +#' The alleles of genetic fitness traits represent deleterious mutations which combined expression reduce the viability of juveniles, +#' i.e. the genetic load. Immediately after birth, all newly born individuals are checked for viability via a Bernoulli trial. +#' The probability of an individual passing the test and surviving birth is equal to its genetic fitness. +#' Genetic fitness is 1 by default, but every allele reduces this value by an amount that depends on +#' its selection coefficient \eqn{s}, and (for diploid systems) the value of its dominance coefficient \eqn{h} relative +#' to that of the other allele it is paired with. +#' +#' More precisely, the genetic fitness \eqn{W} of an individual is the product of the contributions \eqn{w} of each genetic load locus. +#' The contribution \ifelse{html}{\out{wi}}{\eqn{w_i}} of locus \eqn{i} with alleles \eqn{A} and \eqn{B} is: +#' +#' \ifelse{html}{\out{   wi = 1 - hisA - (1 - hi)sB}}{\deqn{w_i = 1 - h_i s_A - (1 - h_i) s_b}} +#' +#' \ifelse{html}{\out{   hi = hA / (hA + hB)}}{\deqn{h_i = h_A / ( h_A + h_B )}} +#' +#' Selection and dominance coefficients for new alleles (mutations) are drawn from distributions specified by the user: +#' either a uniform, normal, gamma, or negative exponential, and are not additive. +#' Dominance coefficients can additionally be sampled from a scaled uniform distribution between zero and a maximum value +#' that depends on the selection coefficient. This maximum value is equal to \ifelse{html}{\out{e-ksi}}{\deqn{exp(-ks_i)}} where \ifelse{html}{\out{si}}{\eqn{s_i}}is the selection coefficient +#' for the locus and +#' +#' \ifelse{html}{\out{   k = -log (2hD)/sD;*hD}}{\deqn{k = -log(2h_D) / s_D}} +#' +#' \ifelse{html}{\out{hD}}{\eqn{h_D}} is the desired mean dominance coefficient; \ifelse{html}{\out{sD}}{\eqn{s_D}} is the mean of the selection coefficient distribution, +#' calculated after the parameters entered for the (selection coefficients) mutation distribution. +#' +#' While selection coefficients should typically be zero or positive, to represent the effect of deleterious mutations, +#' negative values up to -1 are allowed and may arise if the mutation distribution specified by the user allows it. +#' In this case, negative values would represent (universally) beneficial mutations that counteract the effect of genetic load. +#' The total genetic fitness is however bounded to 1. +#' +#' To allow more flexibility, there can be up to 5 such genetic load traits, each with a potentially different distribution +#' of mutations and/or dominance distribution and associated parameters. +#' +#' The expression type of genetic load traits is always multiplicative. +#' +#' Inheritance is not applicable for genetic load traits. +#' +#' @return a parameter object of class "GeneticLoadParams" +#' @author Jette Wolff +#' @name GeneticLoadTraits +#' @export GeneticLoadTraits +GeneticLoadTraits<- setClass("GeneticLoadParams", slots = c( + NbGeneticLoads = "integer_OR_numeric", # number of genetic loads + Positions = "list",# "random" or list of integer values + NbOfPositions = "ANY", # numeric, only where positions are random; otherwise NULL + InitialPositions = "list", # "random" or list of integer values + InitialNbOfPositions = "ANY", # numeric, only where initial positions are random; otherwise NULL + InitialAlleleDistribution = "ANY", #‘gamma’, ‘uniform’, ‘normal’,‘negExp’ + InitialAlleleParameters = "ANY", # 2 values for min/max, mean/sd, shape/scale or one value: mean + InitialDomDistribution = "ANY", # ‘gamma’, ‘uniform’, ‘normal’, ‘negExp’, ‘scaled’ + InitialDomParameters = "ANY", # 2 values for min/max, mean/sd, shape/scale or one value: mean + DominanceDistribution = "character", # ‘gamma’, ‘uniform’, ‘normal’, ‘negExp’, ‘scaled’ # character vector + DominanceParameters = "matrix", # 2 values for min/max, mean/sd, shape/scale or one value: mean + MutationDistribution = "character", # ‘gamma’, ‘uniform’, ‘normal’,‘negExp’ + MutationParameters = "matrix", # 2 values for min/max, mean/sd, shape/scale or one value: mean + MutationRate = "numeric", # float + OutputValues = "logical") + , prototype = list( + NbGeneticLoads = 1L, + Positions = list("random"), + NbOfPositions = 2L, + InitialPositions = list("all"), + InitialNbOfPositions = NULL, # + InitialAlleleDistribution = NULL, # "normal", + InitialAlleleParameters = NULL, # matrix(c(0.5,0.1), nrow=1), + InitialDomDistribution = NULL, # "normal", + InitialDomParameters = NULL, # matrix(c(0.5,0.1), nrow=1), + DominanceDistribution = "normal", + DominanceParameters = matrix(c(0.5,0.1), nrow=1), + MutationDistribution = "normal", + MutationParameters = matrix(c(0.5,0.2), nrow=1), + MutationRate = 0.001, + OutputValues = FALSE + )) +setValidity("GeneticLoadParams", function(object) { + msg <- NULL + # only 5 GeneticLoads are allowed + if (object@NbGeneticLoads < 1 || object@NbGeneticLoads > 5) { + msg <- c(msg, "Number of genetic loads must be between 1 and 5.") + } + # Check Position and NbOfPositions + # Positions must be of type list? + if(class(object@Positions) != "list") { + msg <- c(msg, "GeneticLoad(): Positions must be provided as a list.") + } + # NbOfPositions must be either numeric, integer or NULL + if (!is.null(object@NbOfPositions) && class(object@NbOfPositions) != "integer") { + msg <- c(msg, "GeneticLoad(): NbrOfPositions must be either NULL (if all positions are given) or a vector of integers (and NULL) (if at least one genetic load has random positions).") + } + + if (length(object@Positions) != object@NbGeneticLoads) { + msg <- c(msg, "For each genetic load you must provide the positions.") + } else if (all(object@Positions == "random")){ # if all positions are random + if(length(object@NbOfPositions[!is.na(object@NbOfPositions)]) != object@NbGeneticLoads ) { + msg <- c(msg, "GeneticLoad(): For each genetic load with random positions you must provide the number of positions.") + } + } else{ # if NOT all positions are random + isNumeric <- sapply(object@Positions, is.numeric) + if (!all(isNumeric)) { # if not all are numeric, + if(object@Positions[isNumeric==FALSE] != "random"){ # then those not numeric must be random + msg <- c(msg, "GeneticLoad(): Positions in genetic loads must be either a vector of integers or random.") + } + if (any(is.na(object@NbOfPositions[object@Positions == "random"])) || any(object@NbOfPositions[object@Positions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "GeneticLoad(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@NbOfPositions[object@Positions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "GeneticLoad(): if Positions is not random NbrOfPositions must be not be set (NA).") + } + } + else { # if all positions are not random + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "GeneticLoad(): If positions are not random, you must not specify the number of positions (NbOfPositions).") + } + } + } + + # Check InitialPositions and InitialNbOfPositions + + # InitialPositions must be of type list + if(class(object@InitialPositions) != "list") { + msg <- c(msg, "GeneticLoad(): Initial positions must be provided as a list.") + } + # InitialNbOfPositions must be a list of either numeric, integer or NULL, if it is not NULL for all genetic loads + if (!is.null(object@InitialNbOfPositions) && class(object@InitialNbOfPositions) != "integer") { + msg <- c(msg, "GeneticLoad(): InitialNbrOfPositions must be either NULL (if all positions are given) or integer (if at least one genetic load has random positions).") + } + + if (length(object@InitialPositions) != object@NbGeneticLoads) { + msg <- c(msg, "For each genetic load you must provide the initial positions.") + } else if (all(object@InitialPositions == "random")){ # if all positions are random + if(length(object@InitialNbOfPositions[!is.na(object@InitialNbOfPositions)]) != object@NbGeneticLoads ) { + msg <- c(msg, "GeneticLoad(): For each genetic load with initial random positions you must provide the number of initial positions.") + } + } else if (all(object@InitialPositions == "all")){ + if(!is.null(object@InitialNbOfPositions) ) { + msg <- c(msg, "GeneticLoad(): If all genetic loads initialse all positions, you must set the InitialNbOfPositions to NULL.") + } + + } else{ # if NOT all positions are random nor all + isInteger <- sapply(object@InitialPositions, is.integer) + if (!all(isInteger)) { # if not all are numeric, + if(!all(object@InitialPositions[isInteger==FALSE] %in% c("random", "all"))){ # then those not numeric must be random + msg <- c(msg, "GeneticLoad(): Initial positions in genetic loads must be either a vector of integers, random or all.") + } + if (any(is.na(object@InitialNbOfPositions[object@InitialPositions == "random"])) || any(object@InitialNbOfPositions[object@InitialPositions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "GeneticLoad(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@InitialNbOfPositions[object@InitialPositions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "GeneticLoad(): if initial positions is not random InitialNbrOfPositions must be not be set (NULL).") + } + } + else { # if all initial positions are provided + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "GeneticLoad(): If initial positions are not random or all, you must not specify the number of positions (InitialNbOfPositions).") + } + } + } + + # Check InitialAlleleDistribution given or NA + if (!is.null(object@InitialAlleleDistribution)){ + # if it is given, it should be character + if (class(object@InitialAlleleDistribution) != "character") { + msg <- c(msg, "InitialAlleleDistribution must be a character vector.") + } + # and also InitialAlleleParameters should be numeric + if (class(object@InitialAlleleParameters)[1] != "matrix") { + msg <- c(msg, "InitialAlleleParameters must be a matrix.") + } + if(length(object@InitialAlleleDistribution) != object@NbGeneticLoads) { + msg <- c(msg, "If you want to have initial allel distribution for one genetic load, you must provide it for all genetic load. If you don't want to set the initial allel value for some genetic loads, set it to NA for those.") + } else if (nrow(object@InitialAlleleParameters) != object@NbGeneticLoads) { + msg <- c(msg, "If you have set InitialAlleleDistributions for at least one genetic load you must provide the InitialAlleleParameters for each genetic load. Use one row for each genetic load.") + } else { + # if any InitialAlleleDistribution is not 'normal', 'gamma', 'uniform', 'negExp' or 'scaled' OR NA + if (!all(object@InitialAlleleDistribution %in% c("uniform", "normal", "gamma", "negExp", NA))) { + msg <- c(msg, "InitialAlleleDistribution must be either normal, gamma, uniform, negExp, scaled or NA (if not initialized for a genetic load) for genetic load traits.") + } + if (any(object@InitialAlleleDistribution[!is.na(object@InitialAlleleDistribution)] == "normal")) { # if any distribution is normal + # two values for mean and sd + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="normal"),])) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="normal"),]))) { # if entries are NA + msg <- c(msg,"For a normal initial distribution, InitialParams must provide two values for mean (first column) and sd (second column)") + } + } + if (any(object@InitialAlleleDistribution[!is.na(object@InitialAlleleDistribution)] == "gamma")) { + # two values for shape and scale + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="gamma"),])) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="gamma"),]))) { # if entries are NA + msg <- c(msg,"For a gamma initial distribution, InitialParams must provide two values for shape (first column) and scale (second column)") + } + } + if (any(object@InitialAlleleDistribution[!is.na(object@InitialAlleleDistribution)] == "uniform")) { + # two values for min and max + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="uniform"),])) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="uniform"),]))) { # if entries are NA + msg <- c(msg,"For a uniform initial distribution, InitialParams must provide two values for min (first column) and max (second column)") + } + } + if (all(object@InitialAlleleDistribution[!is.na(object@InitialAlleleDistribution)] == "negExp")) { # if it is only negExp or scaled + # one value for mean and one NA + if (ncol(object@InitialAlleleParameters) !=1 || # if DominanceParameters has more than 1 column + !is.numeric(object@InitialAlleleParameters[which(object@InitialAlleleDistribution == "negExp"),]) || + any(is.na(object@InitialAlleleParameters[which(object@InitialAlleleDistribution == "negExp"),])) + ) { + msg <- c(msg,"For negative exponential and scaled initial distribution, InitialParams must provide only one column for mean.") + } + } else{ + if (any(object@InitialAlleleDistribution[!is.na(object@InitialAlleleDistribution)] == "negExp")) { # if only some are scaled or negative exponential + # one value for mean and one NA if other distributions need 2 values + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + !is.numeric(object@InitialAlleleParameters) || # if entries are not numeric + !all(is.na(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="negExp"),2])) || # second column is not NA + any(is.na(object@InitialAlleleParameters[which(object@InitialAlleleDistribution=="negExp"),1])) # first column is NA + ) { + msg <- c(msg,"For the negative exponential initial distribution, InitialAlleleParameters must provide only one value for mean (first column) and the second column need to be NA if other genetic loads use other initial distributions.") + } + } + } + } + } + + # Check InitialDomDistribution + if (!is.null(object@InitialDomDistribution)){ + if (class(object@InitialDomDistribution) != "character") { + msg <- c(msg, "InitialAlleleDistribution must be a character vector.") + } + # and also InitialAlleleParameters should be numeric + if (class(object@InitialDomParameters)[1] != "matrix") { + msg <- c(msg, "InitialAlleleParameters must be a matrix.") + } + if(length(object@InitialDomDistribution) != object@NbGeneticLoads) { + msg <- c(msg, "If you want to have initial dominance distribution for one genetic load, you must provide it for all genetic load. If you don't want to set the initial dominance value for some genetic loads, set it to NA for those.") + } else if (nrow(object@InitialDomParameters) != object@NbGeneticLoads) { + msg <- c(msg, "If you have set InitialDomDistributions for at least one genetic load you must provide the InitialDomParameters for each genetic load. Use one row for each genetic load.") + } else { + # if any InitialDomDistribution is not 'normal', 'gamma', 'uniform', 'negExp' or 'scaled' OR NA + if (!all(object@InitialDomDistribution %in% c("uniform", "normal", "gamma", "negExp", "scaled", NA))) { + msg <- c(msg, "InitialDomDistribution must be either normal, gamma, uniform, negExp, scaled or NA (if not initialized for a genetic load) for genetic load traits.") + } + + if (any(object@InitialDomDistribution[!is.na(object@InitialDomDistribution)] == "normal")) { # if any distribution is normal + # two values for mean and sd + if (ncol(object@InitialDomParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialDomParameters[which(object@InitialDomDistribution=="normal"), ])) || # if entries are not numeric + any(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="normal"), ]))) { # if entries are NA + msg <- c(msg,"For a normal initial dominance distribution, InitialDomParameters must provide two values for mean (first column) and sd (second column)") + } + } + if (any(object@InitialDomDistribution[!is.na(object@InitialDomDistribution)] == "gamma")) { + # two values for shape and scale + if (ncol(object@InitialDomParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialDomParameters[which(object@InitialDomDistribution=="gamma"), ])) || # if entries are not numeric + any(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="gamma"), ]))) { # if entries are NA + msg <- c(msg,"For a gamma initial dominance distribution, InitialDomParameters must provide two values for shape (first column) and scale (second column)") + } + } + if (any(object@InitialDomDistribution[!is.na(object@InitialDomDistribution)] == "uniform")) { + # two values for min and max + if (ncol(object@InitialDomParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialDomParameters[which(object@InitialDomDistribution=="uniform"),])) || # if entries are not numeric + any(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="uniform"),]))) { # if entries are NA + msg <- c(msg,"For a uniform initial dominance distribution, InitialDomParameters must provide two values for min (first column) and max (second column)") + } + } + if (all(object@InitialDomDistribution[!is.na(object@InitialDomDistribution)] %in% c("negExp", "scaled"))) { # if it is only negExp or scaled + # one value for mean and one NA + if (ncol(object@InitialDomParameters) !=1 || # if DominanceParameters has more than 1 column + !is.numeric(object@InitialDomParameters[which(object@InitialDomDistribution %in% c("negExp", "scaled")),]) || + any(is.na(object@InitialDomParameters[which(object@InitialDomDistribution %in% c("negExp", "scaled")),])) + ) { + msg <- c(msg,"For negative exponential and scaled initial dominance distribution, InitialAlleleParameters must provide only one column for mean.") + } + } else{ + if (any(object@InitialDomDistribution[!is.na(object@InitialDomDistribution)] == "scaled" %in% c("negExp", "scaled"))) { # if only some are scaled or negative exponential + # one value for mean and one NA if other distributions need 2 values + if (ncol(object@InitialDomParameters) !=2 || # if DominanceParameters has not 2 columns OR + !is.numeric(object@InitialDomParameters) || # if entries are not numeric + !all(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="scaled"),2])) || # second column is not NA + !all(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="negExp"),2])) || # second column is not NA + any(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="scaled"),1])) || # first column is NA + any(is.na(object@InitialDomParameters[which(object@InitialDomDistribution=="negExp"),1])) # first column is NA + ) { + msg <- c(msg,"For the scaled or negative exponential initial dominance distribution, InitialAlleleParameters must provide only one value for mean (first column) and the second column need to be NA if other genetic loads use other initial dominance distributions.") + } + } + } + } + } + + # Check DominanceDistribution + if (!is.null(object@DominanceDistribution)){ + if(length(object@DominanceDistribution) != object@NbGeneticLoads) { + msg <- c(msg, "For each genetic load you must provide the DominanceDistribution.") + } else if (nrow(object@DominanceParameters) != object@NbGeneticLoads) { + msg <- c(msg, "If you have set DominanceDistributions you must provide the DominanceParameters for each genetic load. Use one row for each genetic load.") + } else { + # if any DominanceDistribution is not 'normal', 'gamma', 'uniform', 'negExp' or 'scaled' OR NA + if (!all(object@DominanceDistribution %in% c("uniform", "normal", "gamma", "negExp", "scaled"))) { + msg <- c(msg, "DominanceDistribution must be either normal, gamma, uniform, negExp, or scaled for genetic load traits.") + } + if (any(object@DominanceDistribution == "normal")) { # if any distribution is normal + # two values for mean and sd + if (ncol(object@DominanceParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@DominanceParameters[which(object@DominanceDistribution=="normal"),])) || # if entries are not numeric + any(is.na(object@DominanceParameters[which(object@DominanceDistribution=="normal"),]))) { # if entries are NA + msg <- c(msg,"For a normal dominance distribution, DominanceParams must provide two values for mean (first column) and sd (second column)") + } + } + if (any(object@DominanceDistribution == "gamma")) { + # two values for shape and scale + if (ncol(object@DominanceParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@DominanceParameters[which(object@DominanceDistribution=="gamma"),])) || # if entries are not numeric + any(is.na(object@DominanceParameters[which(object@DominanceDistribution=="gamma"),]))) { # if entries are NA + msg <- c(msg,"For a gamma dominance distribution, DominanceParams must provide two values for shape (first column) and scale (second column)") + } + } + if (any(object@DominanceDistribution == "uniform")) { + # two values for min and max + if (ncol(object@DominanceParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@DominanceParameters[which(object@DominanceDistribution=="uniform"),])) || # if entries are not numeric + any(is.na(object@DominanceParameters[which(object@DominanceDistribution=="uniform"),]))) { # if entries are NA + msg <- c(msg,"For a uniform dominance distribution, DominanceParams must provide two values for min (first column) and max (second column)") + } + } + if (all(object@DominanceDistribution %in% c("negExp", "scaled"))) { # if it is only negExp or scaled + # one value for mean and one NA + if (ncol(object@DominanceParameters) !=1 || # if DominanceParameters has more than 1 column + !is.numeric(object@DominanceParameters) || + any(is.na(object@DominanceParameters)) + ) { + msg <- c(msg,"For negative exponential and scaled dominance distribution, DominanceParams must provide only one column for mean.") + } + } else{ + if (any(object@DominanceDistribution %in% c("scaled", "negExp"))) { # if only some are scaled or negative exponential + # one value for mean and one NA if other distributions need 2 values + if (ncol(object@DominanceParameters) !=2 || # if DominanceParameters has not 2 columns OR + !is.numeric(object@DominanceParameters) || # if entries are not numeric + !all(is.na(object@DominanceParameters[which(object@DominanceDistribution=="scaled"),2])) || # second column is not NA + !all(is.na(object@DominanceParameters[which(object@DominanceDistribution=="negExp"),2])) || # second column is not NA + any(is.na(object@DominanceParameters[which(object@DominanceDistribution=="scaled"),1])) || # first column is NA + any(is.na(object@DominanceParameters[which(object@DominanceDistribution=="negExp"),1])) # first column is NA + ) { + msg <- c(msg,"For the scaled or negative exponential dominance distribution, DominanceParameters must provide only one value for mean (first column) and the second column need to be NA if other genetic loads use other dominance distributions.") + } + } + } + } + } else{ # cannot be NULL + msg <- c(msg, "You must provide the DominanceDistribution for each genetic load.") + } + + # Check mutation rate + if(!is.numeric(object@MutationRate) || length(object@MutationRate) != object@NbGeneticLoads){ + msg <- c(msg, "You must provide the mutation rate for each genetic load as a numeric vector.") + } else { + if (!is.numeric(object@MutationRate) || (any(object@MutationRate < 0.0) || any(object@MutationRate > 1.0))) { + msg <- c(msg, "MutationRate must be between 0.0 and 1.0.") + } + } + + # Check MutationDistribution and MutationParameters + if (!is.null(object@MutationDistribution)){ + if (length(object@MutationDistribution) != object@NbGeneticLoads){ + msg <- c(msg, "For each genetic load you must provide the MutationDistribution.") + } else if (nrow(object@MutationParameters) != object@NbGeneticLoads) { + msg <- c(msg, "For each genetic load you must provide the MutationParameters.") + } else { + if (!all(object@MutationDistribution %in% c("normal", "gamma", "uniform", "negExp"))) { + msg <- c(msg, "MutationDistribution must be either normal, gamma, uniform or negExp for genetic load traits.") + } + + if (any(object@MutationDistribution == "uniform", object@MutationDistribution == "normal", object@MutationDistribution == "gamma")){ + if (ncol(object@MutationParameters) !=2){ + msg <- c(msg,"MutationParams must provide two values for uniform/normal/gamma distribution: min/mean/shape (first column) and max/sd/scale (second column)") + } + } + if (any(object@MutationDistribution == "uniform")) { + # two values for min and max + if (any(!is.numeric(object@MutationParameters[which(object@MutationDistribution=="uniform"),])) || + any(is.na(object@MutationParameters[which(object@MutationDistribution=="uniform"),]))) { + msg <- c(msg,"For a uniform mutation distribution, MutationParams must provide two values for min (first column) and max (second column)") + } + } + if (any(object@MutationDistribution == "normal")) { + # two values for meand and sd + if (any(!is.numeric(object@MutationParameters[which(object@MutationDistribution=="normal"),])) || + any(is.na(object@MutationParameters[which(object@MutationDistribution=="normal"),]))) { + msg <- c(msg,"For a normal mutation distribution, MutationParams must provide two values for mean (first column) and sd (second column)") + } + } + if (any(object@MutationDistribution == "gamma")) { + # two values for shape and scale + if (any(!is.numeric(object@MutationParameters[which(object@MutationDistribution=="gamma"),])) || + any(is.na(object@MutationParameters[which(object@MutationDistribution=="gamma"),]))) { + msg <- c(msg,"For a gamma mutation distribution, MutationParams must provide two values for shape (first column) and scale (second column)") + } + } + if (all(object@MutationDistribution == "negExp")) { # if it is only negExp + # one value for mean + if (ncol(object@MutationParameters) !=1 || # if MutationParameters has more than 1 column + !is.numeric(object@DominanceParameters) || + any(is.na(object@DominanceParameters)) + ) { + msg <- c(msg,"For negative exponential mutation distribution, MutationParams must provide only one column for mean.") + } + } else{ + if (any(object@MutationDistribution == "negExp")) { # if only some are scaled or negative exponential + # one value for mean and one NA if other distributions need 2 values + if (ncol(object@MutationParameters) !=2 || # if DominanceParameters has not 2 columns OR + !is.numeric(object@MutationParameters) || # if entries are not numeric + !all(is.na(object@MutationParameters[which(object@MutationDistribution=="negExp"),2])) || # second column is not NA + any(is.na(object@MutationParameters[which(object@MutationDistribution=="negExp"),1])) # first column is NA + ) { + msg <- c(msg,"For the negative exponential mutation distribution, MutationParameters must provide only one value for mean (first column) and the second column need to be NA if other genetic loads use other mutation distributions.") + } + } + } + } + } + + if (!all(object@OutputValues %in% c(TRUE, FALSE))) { + msg <- c(msg, "OutputValues for genetic loads must be either TRUE or FALSE.") + } + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "GeneticLoadParams", function(.Object, ...) { + this_func = "GeneticLoad(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "GeneticLoadParams", function(object){ + cat(" Genetic Loads: \n") + cat(" Number of genetic loads: ", object@NbGeneticLoads, "\n") + for (i in 1:object@NbGeneticLoads){ + cat(" Configuration of genetic load ", i, ": \n") + if(is.numeric(object@Positions[i])) cat(" Loci positions coding for trait: ", object@Positions[i], "\n") + if(!is.numeric(object@Positions[i]) && object@Positions[i]=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions[i], " positions\n") + cat(" Initial allel distribution: ", object@InitialAlleleDistribution[i], "\n") + cat(" Initial allel distribution parameter: ", object@InitialAlleleParameters[i,], "\n") + cat(" Initial dominance distribution: ", object@InitialDomDistribution[i], "\n") + cat(" Initial dominance parameter: ", object@InitialDomParameters[i,], "\n") + cat(" Dominance distribution: ", object@DominanceDistribution[i], "\n") + cat(" Dominance parameter: ", object@DominanceParameters[i,], "\n") + cat(" Mutation distribution: ", object@MutationDistribution[i], "\n") + cat(" Mutation parameters: ", object@MutationParameters[i,], "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues[i]) cat(" Allel values for gene is written to output. \n") + } + +}) + +### SUBCLASS EMIGRATIONTRAITS + +#' Set genetic traits structure for emigration traits +#' +#' @description +#' +#' Depending of the settings in \code{\link[RangeShiftR]{Emigration}}, up to three emigration traits evolve: +#' +#' - The probability of emigration \ifelse{html}{\out{D0}}{\eqn{D_0}} / \eqn{d} \cr +#' - The slope of the density dependent emigration function (if \code{DensDep=TRUE}) \ifelse{html}{\out{α}}{\eqn{α}} \cr +#' - The density threshold of the density dependent emigration function (if \code{DensDep=TRUE}) \ifelse{html}{\out{β}}{\eqn{β}} \cr +#' +#' If emigration is sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. +#' +#' This results in following number of emigration traits that need to be specifed: +#' +#' - 1 entry if emigration is neither density dependent nor sex dependent (\code{DensDep=FALSE} and \code{SexDep=FALSE}): emgiration probability \eqn{d} \cr +#' - 2 entries if emigration is sex dependent (\code{SexDep=TRUE}): emigration probability of females \eqn{d(f)} and males \eqn{d(m)} \cr +#' - 3 entries if emigration probability is only density dependent \code{DensDep=TRUE}: \ifelse{html}{\out{D0}}{\eqn{D_0}}, \ifelse{html}{\out{α}}{\eqn{α}} and \ifelse{html}{\out{β}}{\eqn{β}} \cr +#' - 6 entries if emigration probability is both density dependent (\code{DensDep=TRUE}) and sex dependent (\code{SexDep=TRUE}): \ifelse{html}{\out{D0(f), D0(m)}}{\eqn{D_0(f),D_0(m)}}, \ifelse{html}{\out{α(f), α(m)}}{\eqn{α(f), α(m)}} and \ifelse{html}{\out{β(f), β(m)}}{\eqn{β(f), β(m)}} \cr +#' +#' The entries of the trait parameters must be provided in the same order as the emigration traits are listed above. If parameters expect a matrix, the rows must match the order of emigration traits listed above. +#' +#' +#' @details +#' +#' Traits set to evolve cannot simultaneously be stage-dependent. +#' +#' The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. +#' +#' Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. +#' +#' Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. +#' +#' Emigration traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. +#' +#' Dominance values are not applicable for emigration traits. +#' +#' @usage EmigrationTraits(Positions = list("random"), +#' NbOfPositions = 10, +#' ExpressionType = "additive", +#' InitialAlleleDistribution = "normal", +#' InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), +#' IsInherited = FALSE, +#' MutationDistribution = "normal", +#' MutationParameters = matrix(c(0.5,0.2), nrow=1), +#' MutationRate = 0.0001, +#' OutputValues = FALSE) +#' +#' @param Positions Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param NbOfPositions Only specify when the \code{Positions} of the emigration trait is set to \code{"random"}, else must be blank (\code{NULL}). +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param ExpressionType Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param InitialAlleleDistribution Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param InitialAlleleParameters Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param IsInherited Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param MutationDistribution Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param MutationParameters Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between \code{0.0} and \code{1.0}. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param OutputValues If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' + +#' +#' @return a parameter object of class "EmigrationTraitsParams" +#' @author Jette Wolff +#' @name EmigrationTraits +#' @export EmigrationTraits +EmigrationTraits<- setClass("EmigrationTraitsParams", slots = c(Positions = "list", # + NbOfPositions = "ANY", # random or list of integer values + ExpressionType = "character", # additive or average + InitialAlleleDistribution = "character", # uniform or normal + InitialAlleleParameters = "matrix", # min and max value or mean and sd + IsInherited = "logical", # T/F + MutationDistribution = "character", # uniform or normal + MutationParameters = "matrix", # min mx or mean sd + MutationRate = "numeric", # float + OutputValues = "logical") + , prototype = list( + # ExprSex = FALSE, # is TRUE as soon as Emigration is sexdependent + # TraitType = NULL, # dispersal: "E_0", "E_alpha", "E_beta"; cannot be 0 is determined by emigration settings + Positions = list("random"), # "random" or list of integer values + NbOfPositions = 2L, # numeric, only of positions random + ExpressionType = "average", # dispersal: "additive" or "average" + InitialAlleleDistribution = "uniform", # uniform , normal (dispersal) + InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), # dispersal: two values: either min/max oder mean+sd + IsInherited = FALSE, # only for dispersal + MutationDistribution = "uniform", # dispersal: uniform or normal + MutationParameters = matrix(c(0.5,0.1), nrow=1), # single value or 2 values + MutationRate = c(0.001), # numeric + OutputValues = FALSE + )) +setValidity("EmigrationTraitsParams", function(object) { + msg <- NULL + # Check Position and NbOfPositions + # Positions must be of type list? + if(class(object@Positions) != "list") { + msg <- c(msg, "In EmigrationTraits(): Positions must be provided as a list.") + } + # NbOfPositions must be either numeric, integer or NULL + if (!is.null(object@NbOfPositions) && class(object@NbOfPositions) != "numeric" && class(object@NbOfPositions) != "integer") { + msg <- c(msg, "In EmigrationTraits(): NbrOfPositions must be either NULL (if all positions are given) or numeric (if at least one emigration trait has random positions).") + } + + if (all(object@Positions == "random")){ # if all positions are random + if(length(object@NbOfPositions[!is.na(object@NbOfPositions)]) != length(object@Positions) ) { + msg <- c(msg, "In EmigrationTraits(): For each emigration trait with random positions you must provide the number of positions.") + } + } else{ # if NOT all positions are random + isNumeric <- sapply(object@Positions, is.numeric) + if (!all(isNumeric)) { # if not all positions are numeric, + if(object@Positions[isNumeric==FALSE] != "random"){ # then those not numeric must be random + msg <- c(msg, "In EmigrationTraits(): Positions in emigration traits must be either a vector of integers or random.") + } + if (any(is.na(object@NbOfPositions[object@Positions == "random"])) || any(object@NbOfPositions[object@Positions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "In EmigrationTraits(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@NbOfPositions[object@Positions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "In EmigrationTraits(): if Positions is not random NbrOfPositions must be not be set (NA).") + } + } + else { # if all positions are not random + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "In EmigrationTraits(): If positions are not random, you must not specify the number of positions (NbOfPositions).") + } + } + } + + # Check ExpressionType must be additive or average + if(length(object@ExpressionType) != length(object@Positions)){ + msg <- c(msg, "In EmigrationTraits(): You must provide the ExpressionType for each emigration trait.") + } + if (!all(object@ExpressionType %in% c("additive", "average"))) { + msg <- c(msg, "In EmigrationTraits(): ExpressionType must be either additive or average.") + } + + # Check InitialAlleleDistribution and InitialParameter: Distribution must be uniform or normal and the length of the list must be the same as the number of positions + if (!all(object@InitialAlleleDistribution %in% c("uniform", "normal"))) { + msg <- c(msg, "In EmigrationTraits(): InitialAlleleDistribution must be either normal, or uniform.") + } + + if(length(object@InitialAlleleDistribution) != length(object@Positions)) { + msg <- c(msg, "In EmigrationTraits(): For each emigration parameter you must provide the InitialAlleleDistribution.") + } else if (nrow(object@InitialAlleleParameters) != length(object@Positions)) { + msg <- c(msg, "In EmigrationTraits(): For each emigration parameter you must provide the InitialAlleleParameters. Use one row for each emigration parameter. Check the R help file ?EmigrationTraits for the structure of the matrix.") + } else { + # two columns are necessary for mean and sd or min and max + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters)) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters))) { # if entries are NA + msg <- c(msg,"In EmigrationTraits(): For the initial distributions, InitialParams must provide two values for mean (normal) or min (uniform) (first column) and sd (normal) or max (uniform) (second column)") + } + } + + # Check IsInherited: must be TRUE or FALSE + if (length(object@IsInherited) != length(object@Positions)){ + msg <- c(msg, "In EmigrationTraits(): You must provide IsInherited for each emigration trait.") + } + if (!all(is.logical(object@IsInherited))) { + msg <- c(msg, "In EmigrationTraits(): IsInherited must be either TRUE or FALSE." ) + } + + # Check mutation rate + if(!is.numeric(object@MutationRate) || length(object@MutationRate) != length(object@Positions)){ + msg <- c(msg, "In EmigrationTraits(): You must provide the mutation rate for each emigration trait as a numeric vector.") + } else { + if (!is.numeric(object@MutationRate) || (any(object@MutationRate < 0.0) || any(object@MutationRate > 1.0))) { + msg <- c(msg, "In EmigrationTraits(): MutationRate must be between 0.0 and 1.0.") + } + } + + # Check MutationDistribution and MutationParameters + if (!is.null(object@MutationDistribution)){ + if (length(object@MutationDistribution) != length(object@Positions)){ + msg <- c(msg, "In EmigrationTraits(): For each emigration trait you must provide the MutationDistribution.") + } else if (nrow(object@MutationParameters) != length(object@Positions)) { + msg <- c(msg, "In EmigrationTraits(): For each emigration trait you must provide the MutationParameters.") + } else if(!all(object@MutationDistribution %in% c("uniform", "normal"))){ + msg <- c(msg, "In EmigrationTraits(): MutationDistribution must be either normal or uniform for emigration traits.") + } else { + if (ncol(object@MutationParameters) !=2){ + msg <- c(msg,"In EmigrationTraits(): MutationParams must provide two values for uniform and normal distribution: min/mean (first column) and max/sd (second column)") + } + + if (any(!is.numeric(object@MutationParameters)) || + any(is.na(object@MutationParameters))) { + msg <- c(msg,"In EmigrationTraits(): For a uniform or normal mutation distribution, MutationParams must provide two values for min (first column) and max (second column)") + } + } + } + + + # Check OutputValues + if (length(object@OutputValues) != length(object@Positions) && !all(object@OutputValues %in% c(TRUE, FALSE))) { + msg <- c(msg, "In EmigrationTraits(): OutputValues must be provided for all emigration traits and must be either TRUE or FALSE.") + } + + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "EmigrationTraitsParams", function(.Object, ...) { + this_func = "EmigrationTraits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "EmigrationTraitsParams", function(object){ + cat(" Emigration traits: \n") + if (length(object@Positions) == 1) { + cat(" Trait type: (1) D0 \n") + } + if (length(object@Positions) == 2) { + cat(" Trait types: (1) D0 female, (2) D0 male \n") + } + if (length(object@Positions) == 3) { + cat(" Trait types: (1) D0, (2) Alpha, (3) Beta \n") + } + if (length(object@Positions) == 6) { + cat(" Trait types: (1) D0 female, (2) D0 male, (3) Alpha female, (4) Alpha male, (5) Beta female, (6) Beta male \n") + } + for (i in 1:length(object@Positions)){ + cat(" Configuration of emigration trait ", i, ": \n") + if(is.numeric(object@Positions[i])) cat(" Loci positions coding for trait: ", object@Positions[i], "\n") + if(!is.numeric(object@Positions[i]) && object@Positions[i]=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions[i], " positions\n") + cat(" Expression type: ", object@ExpressionType[i], "\n") + cat(" Initial distribution: ", object@InitialAlleleDistribution[i], "\n") + cat(" Initial parameter: ", object@InitialAlleleParameters[i,], "\n") + cat(" IsInherited: ", object@IsInherited[i], "\n") + cat(" Mutation distribution: ", object@MutationDistribution[i], "\n") + cat(" Mutation parameters: ", object@MutationParameters[i,], "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues[i]) cat(" Allel values for gene is written to output. \n") + } +}) + +### SUBCLASS SETTLEMENTTRAITS + +#' Set genetic traits structure for settlement traits +#' +#' @description +#' Only if settlement is density-dependent (\code{DensDep = TRUE}) in \code{\link[RangeShiftR]{Settlement}}, settlement traits can be evolvable. +#' +#' Three settlement traits can evolve: +#' +#' - The probability of settlement \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr +#' - The slope of the density-dependent settlement function \ifelse{html}{\out{α}}{\eqn{α}} \cr +#' - The density threshold of the density-dependent settlement function \ifelse{html}{\out{β}}{\eqn{β}} \cr +#' +#' If settlement is sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. +#' +#' This results in following number of settlement traits that need to be specifed: +#' +#' - 3 entries/rows if settlement probability is not sex dependent \code{SexDep=FALSE}: \ifelse{html}{\out{S0}}{\eqn{S_0}}, \eqn{α} and \eqn{β} \cr +#' - 6 entries/rows if settlement probability is sex dependent (\code{SexDep=TRUE}): \ifelse{html}{\out{S0(f), S0(m)}}{\eqn{S_0(f),S_0(m)}}, \ifelse{html}{\out{α(f), α(m)}}{\eqn{α(f), α(m)}} and \ifelse{html}{\out{β(f), β(m)}}{\eqn{β(f), β(m)}} \cr +#' +#' The entries of the trait parameters must be provided in the same order as the kernel traits are listed above. If parameters expect a matrix, the rows must match the order of settlement traits listed above. +#' +#' @details +#' +#' Traits set to evolve cannot simultaneously be stage-dependent. +#' +#' The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. +#' +#' Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. +#' +#' Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. +#' +#' Settlement traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. +#' +#' Dominance values are not applicable for settlement traits. +#' +#' +#' @usage SettlementTraits(Positions = list("random","random","random"), +#' NbOfPositions = c(10, 10, 10), +#' ExpressionType = rep("additive",3), +#' InitialAlleleDistribution = rep("normal",3), +#' InitialAlleleParameters = matrix(c(rep(0.5,3),(rep(0.1,3), nrow=3), +#' IsInherited = rep(FALSE,3), +#' MutationDistribution = rep("normal",3), +#' MutationParameters = matrix(c(rep(0.5,3),(rep(0.2,3), nrow=3), +#' MutationRate = rep(0.0001,3), +#' OutputValues = rep(FALSE,3)) +#' +#' @param Positions Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param NbOfPositions Only specify when the \code{Positions} of the settlement trait is set to \code{"random"}, else must be blank (\code{NULL}). +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param ExpressionType Type of expression for the settlement trait. Can be either \code{additive} or \code{average}. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param InitialAlleleDistribution Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param InitialAlleleParameters Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an settlement trait. The number of rows must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param IsInherited Should the settlement trait be inherited? Can be either TRUE or FALSE. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param MutationDistribution Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param MutationParameters Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an settlement trait. The number of rows must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' @param OutputValues If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above. +#' +#' +#' @return a parameter object of class "SettlementTraitsParams" +#' @author Jette Wolff +#' @name SettlementTraits +#' @export SettlementTraits +SettlementTraits<- setClass("SettlementTraitsParams", slots = c(Positions = "list", # + NbOfPositions = "ANY", # random or list of integer values + ExpressionType = "character", # additive or average + InitialAlleleDistribution = "character", # uniform or normal + InitialAlleleParameters = "matrix", # min and max value or mean and sd + IsInherited = "logical", # T/F + MutationDistribution = "character", # uniform or normal + MutationParameters = "matrix", # min mx or mean sd + MutationRate = "numeric", # float + OutputValues = "logical") + , prototype = list( + Positions = list("random", "random", "random"), # "random" or list of integer values + NbOfPositions = c(2, 2, 2), # numeric, only of positions random + ExpressionType = rep("additive",3), # dispersal: "additive" or "average" + InitialAlleleDistribution = rep("uniform",3), # uniform , normal (dispersal) + InitialAlleleParameters = matrix(c(0.5,0.5,0.5,0.1,0.1,0.1), nrow=3), # dispersal: two values: either min/max oder mean+sd + IsInherited = rep(FALSE, 3), # only for dispersal + MutationDistribution = rep("uniform",3), # dispersal: uniform or normal + MutationParameters = matrix(c(0.5,0.5,0.5,0.1,0.1,0.1), nrow=3), # single value or 2 values + MutationRate = rep(0.001,3), # numeric + OutputValues = rep(FALSE,3) + )) +setValidity("SettlementTraitsParams", function(object) { + msg <- NULL + # Check Position and NbOfPositions + # Positions must be of type list? + if(class(object@Positions) != "list") { + msg <- c(msg, "In SettlementTraits(): Positions must be provided as a list.") + } + # NbOfPositions must be either numeric, integer or NULL + if (!is.null(object@NbOfPositions) && class(object@NbOfPositions) != "numeric" && class(object@NbOfPositions) != "integer") { + msg <- c(msg, "In SettlementTraits(): NbrOfPositions must be either NULL (if all positions are given) or numeric (if at least one settlement trait has random positions).") + } + + if (all(object@Positions == "random")){ # if all positions are random + if(length(object@NbOfPositions[!is.na(object@NbOfPositions)]) != length(object@Positions) ) { + msg <- c(msg, "In SettlementTraits(): For each settlement trait with random positions you must provide the number of positions.") + } + } else{ # if NOT all positions are random + isNumeric <- sapply(object@Positions, is.numeric) + if (!all(isNumeric)) { # if not all positions are numeric, + if(object@Positions[isNumeric==FALSE] != "random"){ # then those not numeric must be random + msg <- c(msg, "In SettlementTraits(): Positions in settlement traits must be either a vector of integers or random.") + } + if (any(is.na(object@NbOfPositions[object@Positions == "random"])) || any(object@NbOfPositions[object@Positions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "In SettlementTraits(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@NbOfPositions[object@Positions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "In SettlementTraits(): if Positions is not random NbrOfPositions must be not be set (NA).") + } + } + else { # if all positions are not random + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "In SettlementTraits(): If positions are not random, you must not specify the number of positions (NbOfPositions).") + } + } + } + + # Check ExpressionType must be additive or average + if(length(object@ExpressionType) != length(object@Positions)){ + msg <- c(msg, "In SettlementTraits(): You must provide the ExpressionType for each settlement trait.") + } + if (!all(object@ExpressionType %in% c("additive", "average"))) { + msg <- c(msg, "In SettlementTraits(): ExpressionType must be either additive or average.") + } + + # Check InitialAlleleDistribution and InitialParameter: Distribution must be uniform or normal and the length of the list must be the same as the number of positions + if (!all(object@InitialAlleleDistribution %in% c("uniform", "normal"))) { + msg <- c(msg, "In SettlementTraits(): InitialAlleleDistribution must be either normal, or uniform.") + } + + if(length(object@InitialAlleleDistribution) != length(object@Positions)) { + msg <- c(msg, "In SettlementTraits(): For each settlement parameter you must provide the InitialAlleleDistribution.") + } else if (nrow(object@InitialAlleleParameters) != length(object@Positions)) { + msg <- c(msg, "In SettlementTraits(): For each settlement parameter you must provide the InitialAlleleParameters. Use one row for each settlement parameter. Check the R help file ?SettlementTraits for the structure of the matrix.") + } else { + # two columns are necessary for mean and sd or min and max + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters)) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters))) { # if entries are NA + msg <- c(msg,"In SettlementTraits(): For the initial distributions, InitialParams must provide two values for mean (normal) or min (uniform) (first column) and sd (normal) or max (uniform) (second column)") + } + } + + # Check IsInherited: must be TRUE or FALSE + if (length(object@IsInherited) != length(object@Positions)){ + msg <- c(msg, "In SettlementTraits(): You must provide IsInherited for each settlement trait.") + } + if (!all(is.logical(object@IsInherited))) { + msg <- c(msg, "In SettlementTraits(): IsInherited must be either TRUE or FALSE." ) + } + + # Check mutation rate + if(!is.numeric(object@MutationRate) || length(object@MutationRate) != length(object@Positions)){ + msg <- c(msg, "In SettlementTraits(): You must provide the mutation rate for each settlement trait as a numeric vector.") + } else { + if (!is.numeric(object@MutationRate) || (any(object@MutationRate < 0.0) || any(object@MutationRate > 1.0))) { + msg <- c(msg, "In SettlementTraits(): MutationRate must be between 0.0 and 1.0.") + } + } + + # Check MutationDistribution and MutationParameters + if (!is.null(object@MutationDistribution)){ + if (length(object@MutationDistribution) != length(object@Positions)){ + msg <- c(msg, "In SettlementTraits(): For each settlement trait you must provide the MutationDistribution.") + } else if (nrow(object@MutationParameters) != length(object@Positions)) { + msg <- c(msg, "In SettlementTraits(): For each settlement trait you must provide the MutationParameters.") + } else if(!all(object@MutationDistribution %in% c("uniform", "normal"))){ + msg <- c(msg, "In SettlementTraits(): MutationDistribution must be either normal or uniform for settlement traits.") + } else { + if (ncol(object@MutationParameters) !=2){ + msg <- c(msg,"In SettlementTraits(): MutationParams must provide two values for uniform and normal distribution: min/mean (first column) and max/sd (second column)") + } + + if (any(!is.numeric(object@MutationParameters)) || + any(is.na(object@MutationParameters))) { + msg <- c(msg,"In SettlementTraits(): For a uniform or normal mutation distribution, MutationParams must provide two values for min (first column) and max (second column)") + } + } + } + + + # Check OutputValues + if (length(object@OutputValues) != length(object@Positions) && !all(object@OutputValues %in% c(TRUE, FALSE))) { + msg <- c(msg, "In SettlementTraits(): OutputValues must be provided for all settlement traits and must be either TRUE or FALSE.") + } + + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "SettlementTraitsParams", function(.Object, ...) { + this_func = "SettlementTraits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "SettlementTraitsParams", function(object){ + cat(" Settlement traits: \n") + if (length(object@Positions) == 3) { + cat(" Trait types: (1) S0, (2) Alpha, (3) Beta \n") + } + if (length(object@Positions) == 6) { + cat(" Trait types: (1) S0 female, (2) S0 male, (3) Alpha female, (4) Alpha male, (5) Beta female, (6) Beta male \n") + } + for (i in 1:length(object@Positions)){ + cat(" Configuration of settlement trait ", i, ": \n") + if(is.numeric(object@Positions[i])) cat(" Loci positions coding for trait: ", object@Positions[i], "\n") + if(!is.numeric(object@Positions[i]) && object@Positions[i]=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions[i], " positions\n") + cat(" Expression type: ", object@ExpressionType[i], "\n") + cat(" Initial distribution: ", object@InitialAlleleDistribution[i], "\n") + cat(" Initial parameter: ", object@InitialAlleleParameters[i,], "\n") + cat(" IsInherited: ", object@IsInherited[i], "\n") + cat(" Mutation distribution: ", object@MutationDistribution[i], "\n") + cat(" Mutation parameters: ", object@MutationParameters[i,], "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues[i]) cat(" Allel values for gene is written to output. \n") + } +}) + +### SUBCLASS KERNELTRAITS + +#' Set genetic traits structure for kernel traits +#' +#' @description +#' +#' Depending on the settings of \code{\link[RangeShiftR]{DispersalKernel}}, the following traits can be evolvable: +#' +#' - The mean parameters(s) of the (two) dispersel kernel(s) \cr +#' - The probability of using the first kernel, if a double kernel is used (\code{DoubleKernel=TRUE}). \cr +#' +#' If dispersal kernels are sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. +#' +#' This results in the following number of dispersal kernel traits that need to be specified: +#' +#' - 1 if \code{DoubleKernel=FALSE} and \code{SexDep=FALSE}: \ifelse{html}{\out{δ}}{\eqn{δ}} \cr +#' - 2 if \code{DoubleKernel=FALSE} and \code{SexDep=TRUE}: \ifelse{html}{\out{δ(f)}}{\eqn{δ}(f)}, \ifelse{html}{\out{δ(m)}}{\eqn{δ}(m)}\cr +#' - 3 if \code{DoubleKernel=TRUE} and \code{SexDep=FALSE}: \ifelse{html}{\out{δ1, δ2, pI}}{\eqn{δ_1, δ_2, p_I}}\cr +#' - 6 if \code{DoubleKernel=TRUE} and \code{SexDep=TRUE}: \ifelse{html}{\out{δ1(f), δ1(m), δ2(f), δ2(m), pI(f), pI(m)}}{\eqn{δ_1(f), δ_1(m), δ_2(f), δ_2(m), p_I(f), p_I(m)}} \cr +#' +#' The entries of the trait parameters must be provided in the same order as the kernel traits are listed above. If parameters expect a matrix, the rows must match the order of kernel traits listed above. +#' +#' @details +#' +#' Traits set to evolve cannot simultaneously be stage-dependent. +#' +#' The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. +#' +#' Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. +#' +#' Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. +#' +#' Dispersal kernel traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. +#' +#' Dominance values are not applicable for dispersal kernel traits. +#' +#' @usage KernelTraits(Positions = list("random"), +#' NbOfPositions = c(10), +#' ExpressionType = rep("additive",1), +#' InitialAlleleDistribution = rep("normal",1), +#' InitialAlleleParameters = matrix(c(rep(0.5,1),(rep(0.1,1), nrow=1), +#' IsInherited = rep(FALSE,1), +#' MutationDistribution = rep("normal",1), +#' MutationParameters = matrix(c(rep(0.5,1),(rep(0.2,1), nrow=1), +#' MutationRate = rep(0.0001,1), +#' OutputValues = rep(FALSE,1)) +#' +#' @param Positions Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param NbOfPositions Only specify when the \code{Positions} of the kernel trait is set to ‘random’, else must be blank (\code{NULL}). +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param ExpressionType Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param InitialAlleleDistribution Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param InitialAlleleParameters Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param IsInherited Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param MutationDistribution Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param MutationParameters Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above. +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' @param OutputValues If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above. +#' +#' @return a parameter object of class "KernelTraitsParams" +#' @author Jette Wolff +#' @name KernelTraits +#' @export KernelTraits +KernelTraits<- setClass("KernelTraitsParams", slots = c(Positions = "list", # + NbOfPositions = "ANY", # random or list of integer values + ExpressionType = "character", # additive or average + InitialAlleleDistribution = "character", # uniform or normal + InitialAlleleParameters = "matrix", # min and max value or mean and sd + IsInherited = "logical", # T/F + MutationDistribution = "character", # uniform or normal + MutationParameters = "matrix", # min mx or mean sd + MutationRate = "numeric", # float + OutputValues = "logical") + , prototype = list( + Positions = list("random"), # "random" or list of integer values + NbOfPositions = 2L, # numeric, only of positions random + ExpressionType = "additive", # dispersal: "additive" or "average" + InitialAlleleDistribution = "uniform", # uniform , normal (dispersal) + InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), # dispersal: two values: either min/max oder mean+sd + IsInherited = FALSE, # only for dispersal + MutationDistribution = "uniform", # dispersal: uniform or normal + MutationParameters = matrix(c(0.5,0.1), nrow=1), # single value or 2 values + MutationRate = c(0.001), # numeric + OutputValues = FALSE + )) +setValidity("KernelTraitsParams", function(object) { + msg <- NULL + # Check Position and NbOfPositions + # Positions must be of type list? + if(class(object@Positions) != "list") { + msg <- c(msg, "In KernelTraits(): Positions must be provided as a list.") + } + # NbOfPositions must be either numeric, integer or NULL + if (!is.null(object@NbOfPositions) && class(object@NbOfPositions) != "numeric" && class(object@NbOfPositions) != "integer") { + msg <- c(msg, "In KernelTraits(): NbrOfPositions must be either NULL (if all positions are given) or numeric (if at least one kernel trait has random positions).") + } + if(!(length(object@Positions) %in% c(1,2,3,6))){ + msg <- c(msg, "In KernelTraits(): You must provide 1 (DoubleKernel=FALSE, SexDep=FALSE), 2 (SexDep=TRUE), 3 (DoubleKernel=TRUE, SexDep=FALSE) or (DoubleKernel=TRUE, SexDep=TRUE) positions for the kernel traits.") + } + if (all(object@Positions == "random")){ # if all positions are random + if(length(object@NbOfPositions[!is.na(object@NbOfPositions)]) != length(object@Positions) ) { + msg <- c(msg, "In KernelTraits(): For each kernel trait with random positions you must provide the number of positions.") + } + } else{ # if NOT all positions are random + isNumeric <- sapply(object@Positions, is.numeric) + if (!all(isNumeric)) { # if not all positions are numeric, + if(object@Positions[isNumeric==FALSE] != "random"){ # then those not numeric must be random + msg <- c(msg, "In KernelTraits(): Positions in kernel traits must be either a vector of integers or random.") + } + if (any(is.na(object@NbOfPositions[object@Positions == "random"])) || any(object@NbOfPositions[object@Positions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "In KernelTraits(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@NbOfPositions[object@Positions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "In KernelTraits(): if Positions is not random NbrOfPositions must be not be set (NA).") + } + } + else { # if all positions are not random + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "In KernelTraits(): If positions are not random, you must not specify the number of positions (NbOfPositions).") + } + } + } + + # Check ExpressionType must be additive or average + if(!(length(object@ExpressionType) %in% c(1,2,3,6))){ + msg <- c(msg, "In KernelTraits(): You must provide the ExpressionType for each kernel trait.") + } + if (!all(object@ExpressionType %in% c("additive", "average"))) { + msg <- c(msg, "In KernelTraits(): ExpressionType must be either additive or average.") + } + + # Check InitialAlleleDistribution and InitialParameter: Distribution must be uniform or normal and the length of the list must be the same as the number of positions + if (!(length(object@InitialAlleleDistribution) %in% c(1,2,3,6))){ + msg <- c(msg, "In KernelTraits(): You must provide the InitialAlleleDistribution for each kernel trait.") + } + if (!all(object@InitialAlleleDistribution %in% c("uniform", "normal"))) { + msg <- c(msg, "In KernelTraits(): InitialAlleleDistribution must be either normal, or uniform.") + } + + if (!(nrow(object@InitialAlleleParameters) %in% c(1,2,3,6))) { + msg <- c(msg, "In KernelTraits(): For each kernel parameter you must provide the InitialAlleleParameters. Use one row for each kernel parameter.") + } else { + # two columns are necessary for mean and sd or min and max + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters)) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters))) { # if entries are NA + msg <- c(msg,"In KernelTraits(): For the initial distributions, InitialParams must provide two values for mean (normal) or min (uniform) (first column) and sd (normal) or max (uniform) (second column)") + } + } + + # Check IsInherited: must be TRUE or FALSE + if (!(length(object@IsInherited) %in% c(1,2,3,6))){ + msg <- c(msg, "In KernelTraits(): You must provide IsInherited for each kernel trait.") + } + if (!all(is.logical(object@IsInherited))) { + msg <- c(msg, "In KernelTraits(): IsInherited must be either TRUE or FALSE." ) + } + + # Check mutation rate + if(!is.numeric(object@MutationRate) || !(length(object@MutationRate) %in% c(1,4))){ + msg <- c(msg, "In KernelTraits(): You must provide the mutation rate for each kernel trait as a numeric vector.") + } else { + if (!is.numeric(object@MutationRate) || (any(object@MutationRate < 0.0) || any(object@MutationRate > 1.0))) { + msg <- c(msg, "In KernelTraits(): MutationRate must be between 0.0 and 1.0.") + } + } + + # Check MutationDistribution and MutationParameters + if (!is.null(object@MutationDistribution)){ + if (!(length(object@MutationDistribution) %in% c(1,2,3,6))){ + msg <- c(msg, "In KernelTraits(): For each kernel trait you must provide the MutationDistribution.") + } else if (!(nrow(object@MutationParameters) %in% c(1,2,3,6))) { + msg <- c(msg, "In KernelTraits(): For each kernel trait you must provide the MutationParameters.") + } else if(!all(object@MutationDistribution %in% c("uniform", "normal"))){ + msg <- c(msg, "In KernelTraits(): MutationDistribution must be either normal or uniform for kernel traits.") + } else { + if (ncol(object@MutationParameters) !=2){ + msg <- c(msg,"In KernelTraits(): MutationParams must provide two values for uniform and normal distribution: min/mean (first column) and max/sd (second column)") + } + + if (any(!is.numeric(object@MutationParameters)) || + any(is.na(object@MutationParameters))) { + msg <- c(msg,"In KernelTraits(): For a uniform or normal mutation distribution, MutationParams must provide two values for min (first column) and max (second column)") + } + } + } + + # Check OutputValues + if (!(length(object@OutputValues) %in% c(1,2,3,6)) && !all(object@OutputValues %in% c(TRUE, FALSE))) { + msg <- c(msg, "In KernelTraits(): OutputValues must be provided for all kernel traits and must be either TRUE or FALSE.") + } + + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "KernelTraitsParams", function(.Object, ...) { + this_func = "CorrRWTraits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "KernelTraitsParams", function(object){ + cat(" Kernel traits: \n") + if (length(object@Positions) == 1) { + cat(" Trait types: (1) Delta \n") + } + if (length(object@Positions) == 2) { + cat(" Trait types: (1) Delta(f) (2) Delta(m) \n") + } + if (length(object@Positions) == 3) { + cat(" Trait types: (1) Delta_1 (2) Delta_2 (3) P_I \n") + } + if (length(object@Positions) == 6) { + cat(" Trait types: (1) Delta_1(f) (2) Delta_1(m) (3) Delta_2(f) (4) Delta_2(m) (5) P_I(f) (6) P_I(m) \n") + } + + for (i in 1:length(object@Positions)){ + cat(" Configuration of CorrRW trait ", i, ": \n") + if(is.numeric(object@Positions[i])) cat(" Loci positions coding for trait: ", object@Positions[i], "\n") + if(!is.numeric(object@Positions[i]) && object@Positions[i]=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions[i], " positions\n") + cat(" Expression type: ", object@ExpressionType[i], "\n") + cat(" Initial distribution: ", object@InitialAlleleDistribution[i], "\n") + cat(" Initial parameter: ", object@InitialAlleleParameters[i,], "\n") + cat(" IsInherited: ", object@IsInherited[i], "\n") + cat(" Mutation distribution: ", object@MutationDistribution[i], "\n") + cat(" Mutation parameters: ", object@MutationParameters[i,], "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues[i]) cat(" Allel values for gene is written to output. \n") + } +}) + +### SUBCLASS SMSTRAITS + + +#' Set genetic traits structure for SMS traits +#' +#' @description +#' +#' Depending on the settings of \code{\link[RangeShiftR]{SMS}}, the following traits can be evolvable: +#' +#' - The directional persistence of the individual \code{DP} \cr +#' - The \code{GoalBias}, that is the tendency for an individual to move away from its natal patch \cr +#' - The slope of the distance dependent decay of the goal bias \code{AlphaDB} \cr +#' - The distance threshold of the distance dependent devay of the goal bias \code{BetaDB} \cr +#' +#' If dispersal kernels are sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. +#' +#' This results in the following number of SMS traits that need to be specified: +#' +#' - 1 if \code{GoalType = 0}: directional persistence \code{DP} \cr +#' - 4 if \code{GoalType = 2}: \code{DP}, \code{GoalBias}, \code{AlphaDB}, \code{BetaDB} \cr +#' +#' The entries of the trait parameters must be provided in the same order as the SMS traits are listed above. If parameters expect a matrix, the rows must match the order of SMS traits listed above. +#' +#' @details +#' +#' Traits set to evolve cannot simultaneously be stage-dependent. +#' +#' The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. +#' +#' Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. +#' +#' Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. +#' +#' SMS traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. +#' +#' Dominance values are not applicable for SMS traits. +#' +#' @usage SMSTraits(Positions = list("random"), +#' NbOfPositions = c(10), +#' ExpressionType = rep("additive",1), +#' InitialAlleleDistribution = rep("normal",1), +#' InitialAlleleParameters = matrix(c(rep(0.5,1),(rep(0.1,1), nrow=1), +#' IsInherited = rep(FALSE,1), +#' MutationDistribution = rep("normal",1), +#' MutationParameters = matrix(c(rep(0.5,1),(rep(0.2,1), nrow=1), +#' MutationRate = rep(0.0001,1), +#' OutputValues = rep(FALSE,1)) +#' +#' @param Positions Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param NbOfPositions Only specify when the \code{Positions} of the SMS trait is set to ‘random’, else must be blank (\code{NULL}). +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param ExpressionType Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param InitialAlleleDistribution Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param InitialAlleleParameters Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an SMS trait. +#' The number of rows must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param IsInherited Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param MutationDistribution Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param MutationParameters Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an SMS trait. +#' The number of rows must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' @param OutputValues If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}. +#' +#' +#' @return a parameter object of class "SMSTraitsParams" +#' @author Jette Wolff +#' @name SMSTraits +#' @export SMSTraits +SMSTraits<- setClass("SMSTraitsParams", slots = c(Positions = "list", # + NbOfPositions = "ANY", # random or list of integer values + ExpressionType = "character", # additive or average + InitialAlleleDistribution = "character", # uniform or normal + InitialAlleleParameters = "matrix", # min and max value or mean and sd + IsInherited = "logical", # T/F + MutationDistribution = "character", # uniform or normal + MutationParameters = "matrix", # min mx or mean sd + MutationRate = "numeric", # float + OutputValues = "logical") + , prototype = list( + Positions = list("random"), # "random" or list of integer values + NbOfPositions = 2L, # numeric, only of positions random + ExpressionType = "additive", # dispersal: "additive" or "average" + InitialAlleleDistribution = "uniform", # uniform , normal (dispersal) + InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), # dispersal: two values: either min/max oder mean+sd + IsInherited = FALSE, # only for dispersal + MutationDistribution = "uniform", # dispersal: uniform or normal + MutationParameters = matrix(c(0.5,0.1), nrow=1), # single value or 2 values + MutationRate = c(0.001), # numeric + OutputValues = FALSE + )) +setValidity("SMSTraitsParams", function(object) { + msg <- NULL + # Check Position and NbOfPositions + # Positions must be of type list? + if(class(object@Positions) != "list") { + msg <- c(msg, "In SMSTraits(): Positions must be provided as a list.") + } + # NbOfPositions must be either numeric, integer or NULL + if (!is.null(object@NbOfPositions) && class(object@NbOfPositions) != "numeric" && class(object@NbOfPositions) != "integer") { + msg <- c(msg, "In SMSTraits(): NbrOfPositions must be either NULL (if all positions are given) or numeric (if at least one SMS trait has random positions).") + } + if(!(length(object@Positions) %in% c(1,4))){ + msg <- c(msg, "In SMSTraits(): You must provide 1 (GoalType=0) or 4 (GoalType=2) positions for the SMS traits DP and, if GoalType=2 GoalBias, AlphaDB and BetaDB.") + } + if (all(object@Positions == "random")){ # if all positions are random + if(length(object@NbOfPositions[!is.na(object@NbOfPositions)]) != length(object@Positions) ) { + msg <- c(msg, "In SMSTraits(): For each SMS trait with random positions you must provide the number of positions.") + } + } else{ # if NOT all positions are random + isNumeric <- sapply(object@Positions, is.numeric) + if (!all(isNumeric)) { # if not all positions are numeric, + if(object@Positions[isNumeric==FALSE] != "random"){ # then those not numeric must be random + msg <- c(msg, "In SMSTraits(): Positions in SMS traits must be either a vector of integers or random.") + } + if (any(is.na(object@NbOfPositions[object@Positions == "random"])) || any(object@NbOfPositions[object@Positions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "In SMSTraits(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@NbOfPositions[object@Positions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "In SMSTraits(): if Positions is not random NbrOfPositions must be not be set (NA).") + } + } + else { # if all positions are not random + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "In SMSTraits(): If positions are not random, you must not specify the number of positions (NbOfPositions).") + } + } + } + + # Check ExpressionType must be additive or average + if(!(length(object@ExpressionType) %in% c(1,4))){ + msg <- c(msg, "In SMSTraits(): You must provide the ExpressionType for each SMS trait.") + } + if (!all(object@ExpressionType %in% c("additive", "average"))) { + msg <- c(msg, "In SMSTraits(): ExpressionType must be either additive or average.") + } + + # Check InitialAlleleDistribution and InitialParameter: Distribution must be uniform or normal and the length of the list must be the same as the number of positions + if (!(length(object@InitialAlleleDistribution) %in% c(1,4))){ + msg <- c(msg, "In SMSTraits(): You must provide the InitialAlleleDistribution for each SMS trait.") + } + if (!all(object@InitialAlleleDistribution %in% c("uniform", "normal"))) { + msg <- c(msg, "In SMSTraits(): InitialAlleleDistribution must be either normal, or uniform.") + } + + if (!(nrow(object@InitialAlleleParameters) %in% c(1,4))) { + msg <- c(msg, "In SMSTraits(): For each SMS parameter you must provide the InitialAlleleParameters. Use one row for each SMS parameter.") + } else { + # two columns are necessary for mean and sd or min and max + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters)) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters))) { # if entries are NA + msg <- c(msg,"In SMSTraits(): For the initial distributions, InitialParams must provide two values for mean (normal) or min (uniform) (first column) and sd (normal) or max (uniform) (second column)") + } + } + + # Check IsInherited: must be TRUE or FALSE + if (!(length(object@IsInherited) %in% c(1,4))){ + msg <- c(msg, "In SMSTraits(): You must provide IsInherited for each SMS trait.") + } + if (!all(is.logical(object@IsInherited))) { + msg <- c(msg, "In SMSTraits(): IsInherited must be either TRUE or FALSE." ) + } + + # Check mutation rate + if(!is.numeric(object@MutationRate) || !(length(object@MutationRate) %in% c(1,4))){ + msg <- c(msg, "In SMSTraits(): You must provide the mutation rate for each SMS trait as a numeric vector.") + } else { + if (!is.numeric(object@MutationRate) || (any(object@MutationRate < 0.0) || any(object@MutationRate > 1.0))) { + msg <- c(msg, "In SMSTraits(): MutationRate must be between 0.0 and 1.0.") + } + } + + # Check MutationDistribution and MutationParameters + if (!is.null(object@MutationDistribution)){ + if (!(length(object@MutationDistribution) %in% c(1,4))){ + msg <- c(msg, "In SMSTraits(): For each SMS trait you must provide the MutationDistribution.") + } else if (!(nrow(object@MutationParameters) %in% c(1,4))) { + msg <- c(msg, "In SMSTraits(): For each SMS trait you must provide the MutationParameters.") + } else if(!all(object@MutationDistribution %in% c("uniform", "normal"))){ + msg <- c(msg, "In SMSTraits(): MutationDistribution must be either normal or uniform for SMS traits.") + } else { + if (ncol(object@MutationParameters) !=2){ + msg <- c(msg,"In SMSTraits(): MutationParams must provide two values for uniform and normal distribution: min/mean (first column) and max/sd (second column)") + } + + if (any(!is.numeric(object@MutationParameters)) || + any(is.na(object@MutationParameters))) { + msg <- c(msg,"In SMSTraits(): For a uniform or normal mutation distribution, MutationParams must provide two values for min (first column) and max (second column)") + } + } + } + + + # Check OutputValues + if (!(length(object@OutputValues) %in% c(1,4)) && !all(object@OutputValues %in% c(TRUE, FALSE))) { + msg <- c(msg, "In SMSTraits(): OutputValues must be provided for all SMS traits and must be either TRUE or FALSE.") + } + + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "SMSTraitsParams", function(.Object, ...) { + this_func = "SMSTraits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "SMSTraitsParams", function(object){ + cat(" SMS traits: \n") + if(length(object@Positions) == 1) cat(" Trait types: (1) DP \n") + if(length(object@Positions) == 4) cat(" Trait types: (1) DP, (2) GoalBias, (3) AlphaDB, (4) BetaDB \n") + + for (i in 1:length(object@Positions)){ + cat(" Configuration of SMS trait ", i, ": \n") + if(is.numeric(object@Positions[i])) cat(" Loci positions coding for trait: ", object@Positions[i], "\n") + if(!is.numeric(object@Positions[i]) && object@Positions[i]=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions[i], " positions\n") + cat(" Expression type: ", object@ExpressionType[i], "\n") + cat(" Initial distribution: ", object@InitialAlleleDistribution[i], "\n") + cat(" Initial parameter: ", object@InitialAlleleParameters[i,], "\n") + cat(" IsInherited: ", object@IsInherited[i], "\n") + cat(" Mutation distribution: ", object@MutationDistribution[i], "\n") + cat(" Mutation parameters: ", object@MutationParameters[i,], "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues[i]) cat(" Allel values for gene is written to output. \n") + } +}) + +### SUBCLASS CorrRWTRAITS + +#' Set genetic traits structure for CorrRW traits +#' +#' @description +#' +#' Depending on the settings of \code{\link[RangeShiftR]{CorrRW}}, the following traits can be evolvable: +#' +#' - The length of a single transfer step \code{Steplength} \cr +#' - The angle correlation parameter of the random walk \code{Rho} \cr +#' +#' The entries of the trait parameters must be provided in the same order as the CorrRW traits are listed above (first \code{StepLength} and second \code{Rho}). If parameters expect a matrix, the rows must match the order of CorrRW traits listed above. +#' +#' @details +#' +#' Traits set to evolve cannot simultaneously be stage-dependent. +#' +#' The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. +#' +#' Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. +#' +#' Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. +#' +#' CorrRW traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. +#' +#' Dominance values are not applicable for CorrRW traits. +#' +#' @usage CorrRWTraits(Positions = list("random","random"), +#' NbOfPositions = c(10, 10), +#' ExpressionType = rep("additive",2), +#' InitialAlleleDistribution = rep("normal",2), +#' InitialAlleleParameters = matrix(c(rep(0.5,2),(rep(0.1,2), nrow=2), +#' IsInherited = rep(FALSE,2), +#' MutationDistribution = rep("normal",2), +#' MutationParameters = matrix(c(rep(0.5,2),(rep(0.2,2), nrow=2), +#' MutationRate = rep(0.0001,2), +#' OutputValues = rep(FALSE,2)) +#' +#' @param Positions Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param NbOfPositions Only specify when the \code{Positions} of the CorrRW trait is set to ‘random’, else must be blank (NULL). +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param ExpressionType Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param InitialAlleleDistribution Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param InitialAlleleParameters Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an CorrRW trait. The number of rows must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param IsInherited Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param MutationDistribution Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param MutationParameters Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +#' Each row in the matrix corresponds to an CorrRW trait. The number of rows must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param MutationRate Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' @param OutputValues If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +#' The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}. +#' +#' +#' @return a parameter object of class "CorrRWTraitsParams" +#' @author Jette Wolff +#' @name CorrRWTraits +#' @export CorrRWTraits +CorrRWTraits<- setClass("CorrRWTraitsParams", slots = c(Positions = "list", # + NbOfPositions = "ANY", # random or list of integer values + ExpressionType = "character", # additive or average + InitialAlleleDistribution = "character", # uniform or normal + InitialAlleleParameters = "matrix", # min and max value or mean and sd + IsInherited = "logical", # T/F + MutationDistribution = "character", # uniform or normal + MutationParameters = "matrix", # min mx or mean sd + MutationRate = "numeric", # float + OutputValues = "logical") + , prototype = list( + Positions = list("random", "random"), # "random" or list of integer values + NbOfPositions = rep(2,2), # numeric, only of positions random + ExpressionType = rep("additive",2), # dispersal: "additive" or "average" + InitialAlleleDistribution = rep("uniform",2), # uniform , normal (dispersal) + InitialAlleleParameters = matrix(c(0.5,0.5,0.1,0.1), nrow=2), # dispersal: two values: either min/max oder mean+sd + IsInherited = rep(FALSE,2), # only for dispersal + MutationDistribution = rep("uniform",2), # dispersal: uniform or normal + MutationParameters = matrix(c(0.5,0.5,0.1,0.1), nrow=2), # single value or 2 values + MutationRate = rep(0.001,2), # numeric + OutputValues = rep(FALSE,2) + )) +setValidity("CorrRWTraitsParams", function(object) { + msg <- NULL + # Check Position and NbOfPositions + # Positions must be of type list? + if(class(object@Positions) != "list") { + msg <- c(msg, "In CorrRWTraits(): Positions must be provided as a list.") + } + # NbOfPositions must be either numeric, integer or NULL + if (!is.null(object@NbOfPositions) && class(object@NbOfPositions) != "numeric" && class(object@NbOfPositions) != "integer") { + msg <- c(msg, "In CorrRWTraits(): NbrOfPositions must be either NULL (if all positions are given) or numeric (if at least one CorrRW trait has random positions).") + } + if(length(object@Positions) != 2){ + msg <- c(msg, "In CorrRWTraits(): You must provide two positions for the CorrRW traits Steplength and Rho.") + } + if (all(object@Positions == "random")){ # if all positions are random + if(length(object@NbOfPositions[!is.na(object@NbOfPositions)]) != length(object@Positions) ) { + msg <- c(msg, "In CorrRWTraits(): For each CorrRW trait with random positions you must provide the number of positions.") + } + } else{ # if NOT all positions are random + isNumeric <- sapply(object@Positions, is.numeric) + if (!all(isNumeric)) { # if not all positions are numeric, + if(object@Positions[isNumeric==FALSE] != "random"){ # then those not numeric must be random + msg <- c(msg, "In CorrRWTraits(): Positions in CorrRW traits must be either a vector of integers or random.") + } + if (any(is.na(object@NbOfPositions[object@Positions == "random"])) || any(object@NbOfPositions[object@Positions == "random"] <= 0)){ # if number of positions are NA or smaller than 0 + msg <- c(msg, "In CorrRWTraits(): NbrOfPositions must be set to a strictly positive integer for random positions.") + } + if (any(!is.na(object@NbOfPositions[object@Positions != "random"]))) { # if there are NbOfPositions supplied for non-random positions + msg <- c(msg, "In CorrRWTraits(): if Positions is not random NbrOfPositions must be not be set (NA).") + } + } + else { # if all positions are not random + if (!is.null(object@NbOfPositions)) { + msg <- c(msg, "In CorrRWTraits(): If positions are not random, you must not specify the number of positions (NbOfPositions).") + } + } + } + + # Check ExpressionType must be additive or average + if(length(object@ExpressionType) != 2){ + msg <- c(msg, "In CorrRWTraits(): You must provide the ExpressionType for each CorrRW trait.") + } + if (!all(object@ExpressionType %in% c("additive", "average"))) { + msg <- c(msg, "In CorrRWTraits(): ExpressionType must be either additive or average.") + } + + # Check InitialAlleleDistribution and InitialParameter: Distribution must be uniform or normal and the length of the list must be the same as the number of positions + if (length(object@InitialAlleleDistribution) != 2){ + msg <- c(msg, "In CorrRWTraits(): You must provide the InitialAlleleDistribution for each CorrRW trait.") + } + if (!all(object@InitialAlleleDistribution %in% c("uniform", "normal"))) { + msg <- c(msg, "In CorrRWTraits(): InitialAlleleDistribution must be either normal, or uniform.") + } + + if (nrow(object@InitialAlleleParameters) != 2) { + msg <- c(msg, "In CorrRWTraits(): For each CorrRW parameter you must provide the InitialAlleleParameters. Use one row for each CorrRW parameter.") + } else { + # two columns are necessary for mean and sd or min and max + if (ncol(object@InitialAlleleParameters) !=2 || # if DominanceParameters has not 2 columns OR + any(!is.numeric(object@InitialAlleleParameters)) || # if entries are not numeric + any(is.na(object@InitialAlleleParameters))) { # if entries are NA + msg <- c(msg,"In CorrRWTraits(): For the initial distributions, InitialParams must provide two values for mean (normal) or min (uniform) (first column) and sd (normal) or max (uniform) (second column)") + } + } + + # Check IsInherited: must be TRUE or FALSE + if (length(object@IsInherited) != 2){ + msg <- c(msg, "In CorrRWTraits(): You must provide IsInherited for each CorrRW trait.") + } + if (!all(is.logical(object@IsInherited))) { + msg <- c(msg, "In CorrRWTraits(): IsInherited must be either TRUE or FALSE." ) + } + + # Check mutation rate + if(!is.numeric(object@MutationRate) || length(object@MutationRate) != 2){ + msg <- c(msg, "In CorrRWTraits(): You must provide the mutation rate for each CorrRW trait as a numeric vector.") + } else { + if (!is.numeric(object@MutationRate) || (any(object@MutationRate < 0.0) || any(object@MutationRate > 1.0))) { + msg <- c(msg, "In CorrRWTraits(): MutationRate must be between 0.0 and 1.0.") + } + } + + # Check MutationDistribution and MutationParameters + if (!is.null(object@MutationDistribution)){ + if (length(object@MutationDistribution) != 2){ + msg <- c(msg, "In CorrRWTraits(): For each CorrRW trait you must provide the MutationDistribution.") + } else if (nrow(object@MutationParameters) != 2) { + msg <- c(msg, "In CorrRWTraits(): For each CorrRW trait you must provide the MutationParameters.") + } else if(!all(object@MutationDistribution %in% c("uniform", "normal"))){ + msg <- c(msg, "In CorrRWTraits(): MutationDistribution must be either normal or uniform for CorrRW traits.") + } else { + if (ncol(object@MutationParameters) !=2){ + msg <- c(msg,"In CorrRWTraits(): MutationParams must provide two values for uniform and normal distribution: min/mean (first column) and max/sd (second column)") + } + + if (any(!is.numeric(object@MutationParameters)) || + any(is.na(object@MutationParameters))) { + msg <- c(msg,"In CorrRWTraits(): For a uniform or normal mutation distribution, MutationParams must provide two values for min (first column) and max (second column)") + } + } + } + + + # Check OutputValues + if (length(object@OutputValues) != 2 && !all(object@OutputValues %in% c(TRUE, FALSE))) { + msg <- c(msg, "In CorrRWTraits(): OutputValues must be provided for all CorrRW traits and must be either TRUE or FALSE.") + } + + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "CorrRWTraitsParams", function(.Object, ...) { + this_func = "CorrRWTraits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "CorrRWTraitsParams", function(object){ + cat(" CorrRW traits: \n") + cat(" Trait types: (1) StepLength, (2) Rho \n") + + for (i in 1:length(object@Positions)){ + cat(" Configuration of CorrRW trait ", i, ": \n") + if(is.numeric(object@Positions[i])) cat(" Loci positions coding for trait: ", object@Positions[i], "\n") + if(!is.numeric(object@Positions[i]) && object@Positions[i]=="random") cat(" Loci positions coding for trait randomly chosen with ", object@NbOfPositions[i], " positions\n") + cat(" Expression type: ", object@ExpressionType[i], "\n") + cat(" Initial distribution: ", object@InitialAlleleDistribution[i], "\n") + cat(" Initial parameter: ", object@InitialAlleleParameters[i,], "\n") + cat(" IsInherited: ", object@IsInherited[i], "\n") + cat(" Mutation distribution: ", object@MutationDistribution[i], "\n") + cat(" Mutation parameters: ", object@MutationParameters[i,], "\n") + cat(" Mutation rate: ", object@MutationRate, "\n") + if(object@OutputValues[i]) cat(" Allel values for gene is written to output. \n") + } +}) + +### SUBCLASS TRAITSPARAMS + +# define this ClassUnion so that the 'Neutral' slot in the genetic class 'GeneticParams' can be FALSE if neutral genetics should not be modelled, etc. +setClassUnion("NeutralSlot", c("logical", "NeutralTraitsParams")) +setClassUnion("GeneticLoadSlot", c("logical", "GeneticLoadParams")) +setClassUnion("EmigrationTraitsSlot", c("logical", "EmigrationTraitsParams")) +setClassUnion("SettlementTraitsSlot", c("logical", "SettlementTraitsParams")) +setClassUnion("CorrRWTraitsSlot", c("logical", "CorrRWTraitsParams")) +setClassUnion("SMSTraitsSlot", c("logical", "SMSTraitsParams")) +setClassUnion("KernelTraitsSlot", c("logical", "KernelTraitsParams")) + + +#' Set genetic traits structure +#' +#' @description +#' Three types of traits can be made evolvable and parameterised with their own genetic architecture: +#' +#' - Dispersal traits correspond to the main parameters controlling each phase of dispersal (emigration, transfer and settlement). \cr +#' - Genetic fitness traits represent genetic load, the accumulation of deleterious mutations and their effect on the viability of newborn offspring. \cr +#' - Neutral trait does not have any phenotypic effect during the simulation. It is used to compute F-statistics and other measures of neutral variation. \cr +#' +#' +#' @usage Traits(Neutral = FALSE, +#' GeneticLoad = FALSE, +#' EmigrationGenes = FALSE, +#' SettlementGenes = FALSE, +#' CorrRWGenes = FALSE, +#' SMSGenes = FALSE, +#' KernelGenes = FALSE) +#' +#' @param Neutral If neutral traits should be modelled, define \code{\link[RangeShiftR]{NeutralTraits}}. If \code{FALSE} (default), the neutral traits are not modelled. +#' @param GeneticLoad If genetic load should be modelled, define \code{\link[RangeShiftR]{GeneticLoadTraits}}. There can be up to 5 genetic loads. If \code{FALSE} (default), the genetic load is not modelled. +#' @param EmigrationGenes If evolvable emigration traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{Emigration}}), define \code{\link[RangeShiftR]{EmigrationTraits}}. If \code{FALSE} (default), the emigration traits are not modelled/evolvable. +#' @param SettlementGenes If evolvable settlement traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{Settlement}}), define \code{\link[RangeShiftR]{SettlementTraits}}. If \code{FALSE} (default), the settlement traits are not modelled/evolvable. +#' @param CorrRWGenes If evolvable CorrRW traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{CorrRW}}), define \code{\link[RangeShiftR]{CorrRWTraits}}. If \code{FALSE} (default), the CorrRW traits are not modelled/evolvable. +#' @param SMSGenes If evolvable SMS traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{SMS}}), define \code{\link[RangeShiftR]{SMSTraits}}. If \code{FALSE} (default), the SMS traits are not modelled/evolvable. +#' @param KernelGenes If evolvable Kernel traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{Kernel}}), define \code{\link[RangeShiftR]{KernelTraits}}. If \code{FALSE} (default), the Kernel traits are not modelled/evolvable. +#' +#' @details +#' The parameterisation structure for each type of trait is defined in the corresponding subclasses: +#' +#' - Dispersal traits: \code{\link[RangeShiftR]{EmigrationTraits}}, \code{\link[RangeShiftR]{SettlementTraits}}, \code{\link[RangeShiftR]{CorrRWTraits}}, \code{\link[RangeShiftR]{SMSTraits}} and \code{\link[RangeShiftR]{KernelTraits}} \cr +#' - Genetic fitness traits: \code{\link[RangeShiftR]{GeneticLoadTraits}} \cr +#' - Neutral traits: \code{\link[RangeShiftR]{NeutralTraits}} \cr +#' +#' They follow a similar structure, but some parameters and their specific options are specific to the type of trait. +#' +#' Parameters that need to be defined: +#' +#' - The number and positions of genes controlling the trait. \cr +#' - A rule for expression (restricted to dispersal traits, for genetic load it is fixed to 'multiplicative') \cr +#' - Initialized positions (restricted to neutral traits and genetic fitness traits, for dispersal traits it is fixed to 'all') \cr +#' - Option for inter-individual variability in without inheritance (restricted to dispersal traits) \cr +#' - A mutation rate for all genes controlling the trait. \cr +#' - A distribution to sample mutations from. \cr +#' - A distribution to sample initial allele values and dominance coefficients (the latter is restricted to genetic fitness traits) from. \cr +#' - A distribution to sample dominance coefficients from (restricted to genetic fitness traits). \cr +#' - Whether allele values should be written to output. +#' +#' +#' @return a parameter object of class "TraitsParams" +#' @author Jette Wolff +#' @name Traits +#' @export Traits +Traits <- setClass("TraitsParams", slots = c(Neutral = "NeutralSlot", + GeneticLoad = "GeneticLoadSlot", + EmigrationGenes = "EmigrationTraitsSlot", + SettlementGenes = "SettlementTraitsSlot", + CorrRWGenes = "CorrRWTraitsSlot", + SMSGenes = "SMSTraitsSlot", + KernelGenes = "KernelTraitsSlot" + ) + , prototype = list(Neutral = FALSE, # NeutralTraits(), + GeneticLoad = FALSE, # GeneticLoadTraits(), # could this also be a list of multiple GeneticLoads? + EmigrationGenes = FALSE, # EmigrationTraits(), # NULL E_D0, E_Alpha, E_Beta + SettlementGenes = FALSE, # SettlementTraits(), # NULL, S_S0, S_Alpha, S_Beta + CorrRWGenes = FALSE, # CorrRWTraits(), # NULL, # CRW_STEPLENGTH, CRW_STEPCORRELATION + SMSGenes = FALSE, # SMSTraits(), # NULL, # SMS_BETADB + KernelGenes = FALSE # KernelTraits() # NULL # KERNEL_MEANDIST_1, KERNEL_MEANDIST_2, KERNEL_PROBABILITY + )) +setValidity("TraitsParams", function(object) { + msg <- NULL + + # Check Neutral + if (!is.logical(object@Neutral) && !is(object@Neutral,"NeutralTraitsParams")) { + msg <- c(msg, "In Traits(): Neutral must be of class NeutralTraitsParams.") + } + # Check GeneticLoad + if (!is.logical(object@GeneticLoad) && !is(object@GeneticLoad, "GeneticLoadParams")) { + msg <- c(msg, "In Traits(): GeneticLoad must be of class GeneticLoadParams.") + } + # Check EmigrationGenes + if (!is.logical(object@EmigrationGenes) && !is(object@EmigrationGenes, "EmigrationTraitsParams")) { + msg <- c(msg, "In Traits(): EmigrationGenes must be of class EmigrationTraitsParams.") + } + # Check SettlementGenes + if (!is.logical(object@SettlementGenes) && !is(object@SettlementGenes, "SettlementTraitsParams")) { + msg <- c(msg, "In Traits(): SettlementGenes must be of class SettlementTraitsParams.") + } + # Check CorrRWGenes + if (!is.logical(object@CorrRWGenes) && !is(object@CorrRWGenes, "CorrRWTraitsParams")) { + msg <- c(msg, "In Traits(): CorrRWGenes must be of class CorrRWTraitsParams.") + } + # Check SMSGenes + if (!is.logical(object@SMSGenes) && !is(object@SMSGenes, "SMSTraitsParams")) { + msg <- c(msg, "In Traits(): SMSGenes must be of class SMSTraitsParams.") + } + # Check KernelGenes + if (!is.logical(object@KernelGenes) && !is(object@KernelGenes, "KernelTraitsParams")) { + msg <- c(msg, "In Traits(): KernelGenes must be of class KernelTraitsParams.") + } + if (is.null(msg)) TRUE else msg +}) +setMethod("initialize", "TraitsParams", function(.Object, ...) { + this_func = "Traits(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object +}) +setMethod("show", "TraitsParams", function(object){ + if(class(object@Neutral) == "NeutralTraitsParams") print(object@Neutral) + if(class(object@GeneticLoad) == "GeneticLoadParams") print(object@GeneticLoad) + if(class(object@EmigrationGenes) == "EmigrationTraitsParams") print(object@EmigrationGenes) + if(class(object@SettlementGenes) == "SettlementTraitsParams") print(object@SettlementGenes) + if(class(object@CorrRWGenes) == "CorrRWTraitsParams") print(object@CorrRWGenes) + if(class(object@SMSGenes) == "SMSTraitsParams") print(object@SMSGenes) + if(class(object@KernelGenes) == "KernelTraitsParams") print(object@KernelGenes) +}) + + +#' Set Genetics parameters +#' +#' @description +#' +#' Controls heritability and evolution of traits (in case of dispersal traits only if inter-individual variability is enabled (\code{IndVar=TRUE})). +#' Provides control over the genome size, the number of loci, the recombination rate, output options and the genetic traits to be modelled +#' +#' @usage Genetics(GenomeSize = 10, +#' ChromosomeEnds = 1, +#' RecombinationRate = 0.0, +#' OutputGeneValues = FALSE, +#' OutputGenesStart = NULL, +#' OutputGenesInterval = NULL, +#' OutputGlobalFst = NULL, +#' OutputGlobalFstStart = NULL, +#' OutputGlobalFstInterval = NULL, +#' OutputPairwiseFst = NULL, +#' OutputPairwiseFstStart = NULL, +#' OutputPairwiseFstInterval = NULL, +#' OutputPerLocusFst = NULL, +#' PatchList = NULL, +#' NbrPatchesToSample = NULL, +#' nIndividualsToSample = NULL, +#' Stages = NULL, +#' Traits = Traits() +#' ) +#' +#' @param GenomeSize Maximum size of genome (number of loci). Should be an integer number. +#' @param ChromosomeEnds Where the genome is split into chromosomes, if empty it is +#' assumed that one chromosome is equal to GenomeSize. These areas recombine with a +#' probability of 0.5. Disabled for haploid organisms (no recombination). It should be a vector of integers. +#' @param RecombinationRate Recombination rate (through chromosomal crossover) +#' across the whole genome (in addition to the chromosomeEnds above). Disabled for haploid organisms (no recombination). +#' @param OutputGeneValues TRUE or FALSE. Output the values of all alleles for all genes of all sampled individuals. +#' Does not output the resulting trait values: mean and SD of dispersal and genetic fitness traits are +#' output in the TraitsXPatch, TraitsXCell and/or TraitsXrow output files. Enables the geneValues output files. +#' @param OutputGenesStart Which year should RangeShifter start to produce the output files listed above? Positive integer if any output is \code{TRUE}, otherwise \code{NULL}. +#' @param OutputGenesInterval How frequently to output gene values output. Positive integer if any output is \code{TRUE}, otherwise \code{NULL}. +#' @param OutputGlobalFst Calculate global F-statistics according to Weir & Cockerham (1984)'s method-of-moments approach. Enables the neutralGenetics output file. \code{TRUE} or \code{FALSE}. +#' @param OutputGlobalFstStart Which year should RangeShifter start to produce the global Fst output? Positive integer if \code{OutputGlobalFst} is \code{TRUE}, otherwise \code{NULL}. +#' @param OutputGlobalFstInterval How frequently to output global F-statistics. Positive integer if \code{OutputGlobalFst} is \code{TRUE}, otherwise \code{NULL}. +#' @param OutputPairwiseFst Calculate pairwise F-statistics according to Weir & Cockerham (1984)'s method-of-moments approach. Enables the pairwisePatchNeutralGenetics output files. \code{TRUE} or \code{FALSE}. +#' @param OutputPairwiseFstStart Which year should RangeShifter start to produce the pairwise Fst output? Positive integer if \code{OutputPairwiseFst} is \code{TRUE}, otherwise \code{NULL}. +#' @param OutputPairwiseFstInterval How frequently to output pairwise F-statistics? Positive integer if \code{OutputPairwiseFst} is \code{TRUE}, otherwise \code{NULL}. +#' @param OutputPerLocusFst Calculate F-statistics per-locus estimates according to Weir & Cockerham (1984)'s method-of-moments approach, only if \code{OutputGlobalFst} is \code{TRUE}, for the same interval as the global fst. Enables the perLocusNeutralGenetics output files. \code{TRUE} or \code{FALSE}. +#' @param PatchList Which patches are to be sampled for output. Patches can be +#' specified according to their patch number, as per the patch layer in a patch-based +#' model. Or sampled randomly or all patches can be chosen. In a cell-based landscape +#' random is the only option with number of patches (=cells) specified. Can take "all", "random", "random_occupied" or a vector of integers. +#' @param NbrPatchesToSample If PatchList=random or random_occupied then this specifies +#' the number of patches to sample randomly. Random: The chosen sample patches remain +#' the same throughout the simulation, i.e. do not vary between years or replicates +#' unless artificially generated landscape that is generated afresh between replicates. +#' Random_occupied: patches are re-sampled every generation among all patches containing at least 1 individual. +#' @param nIndividualsToSample The number of individuals to sample in a patch. If nInds < nIndividualsToSample then sampled individuals = nInds +#' @param Stages The age stages to sample from. Should be a vector of integers. Should be a vector of integers or "all". If NULL, all stages are sampled. +#' @param Traits The genetic traits to be modelled. See \code{\link[RangeShiftR]{Traits}} for more information. + +#' @details +#' The genome itself is not modelled explicitly, and is instead represented by a genome size, +#' the set of gene positions and a set of positions for the chromosome breaks (hence determining the number of chromosomes). +#' +#' The rate of recombination applies to the entire genome. Genetic linkage does occur, based on the distances between genes controlling different traits. +#' Multiple traits can use the same position, making the alleles of such genes completely linked, but mutations and expression of different traits are resolved independently, +#' such that pleiotropy is not possible. +#' If either option for sexual reproduction is selected, all individuals are diploid. Otherwise, asexual individuals are always haploid (and do not recombine). +#' +#' \emph{Output} \cr +#' +#' \emph{Sampling} \cr +#' The volume of genetic output grows quickly with the number of individuals in the simulation, +#' and it is therefore crucial to first constitute an appropriate sample of the community. +#' First, a set of patches is sampled from either a random subset of all patches in the landscape, or a pre-specified list of patches. +#' In either case, the same patches will be sampled through the simulation, and no check is conducted to verify if each patch does contain a +#' population or is empty. There is an additional option to sample patches from a random subset of occupied patches, +#' which will change from one generation to the next. +#' Second, a number of individuals are sampled from the population of each sampled patch. In stage-structured populations, +#' it is possible to select only certain stages to be sampled. \cr +#' +#' \emph{Allele values}\cr +#' +#' This output, if enabled (\code{OutputGeneValues = TRUE}), will write all alleles values of the sampled individuals for the selected trait(s) to \emph{Sim_Land_Rep_geneValues}, +#' along with some contextual information.\cr +#' +#' Each row corresponds to a single gene:\cr +#' +#' 1. Year\cr +#' 2. Generation\cr +#' 3. Individual ID\cr +#' 4. Trait type (e.g. “kernel_meanDist1”, matching the value given as input)\cr +#' 5. Position in the genome\cr +#' 6. Value of the allele on the first chromosome\cr +#' 7. Dominance coefficient for the allele on the first chromosome (this will be 0 except for genetic fitness traits)\cr +#' 8. (If diploid) Value of the allele on the second chromosome\cr +#' 9. (If diploid) Dominance coefficient for the allele on the second chromosome\cr +#' +#' \emph{Neutral genetics} \cr +#' +#' The standard neutral genetics output, \emph{Sim_Land_neutralGenetics}, writes the following entries (one row per generation): \cr +#' 1. Replicate number \cr +#' 2. Year \cr +#' 3. Generation \cr +#' 4. Number of sampled patches with a non-zero population \cr +#' 5. Total number of sampled individuals \cr +#' 6. Weir & Cockerham’s \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} (if enabled) \cr +#' 7. Weir & Cockerham’s \emph{\ifelse{html}{\out{Fis}}{\eqn{F_is}}} (if enabled) \cr +#' 8. Weir & Cockerham’s \emph{\ifelse{html}{\out{Fit}}{\eqn{F_it}}} (if enabled) \cr +#' 9. Global allelic diversity, calculated as the mean number of alleles per locus for the entire sample. \cr +#' 10. Local allelic diversity, calculated as the mean number of alleles per locus for each sampled patch, then averaged over patches. \cr +#' 11. Number of globally fixed alleles. \cr +#' 12. Mean number of fixed alleles per patch. Note that this may differ from the number of globally fixed alleles, for example if an allele is fixed in one patch but polymorphism exists in other patches. \cr +#' 13. Observed heterozygosity Ho, calculated as the mean number of heterozygous loci per individual per locus. \cr + +#' +#' RangeShifter estimates standard F-statistics as \insertCite{cockerham1969}{RangeShiftR}’s \ifelse{html}{\out{θ}}{\eqn{θ}} statistics, using the classic method-of-moments estimator +#' of \insertCite{weir1984}{RangeShiftR}. \cr +#' +#' In short, \emph{\ifelse{html}{\out{θ}}{\eqn{θ}}} \emph{(\ifelse{html}{\out{Fst}}{\eqn{F_st}})} measures the correlation between alleles within sub-populations (patches) +#' relative to the complete sampled population, +#' \emph{f(\ifelse{html}{\out{Fis}}{\eqn{F_is}})} the correlation between alleles within individuals relative to the sub-population and \emph{F(\ifelse{html}{\out{Fit}}{\eqn{F_it}})} the correlation between alleles +#' within individuals relative to the complete sampled population (see \insertCite{holsinger2009}{RangeShiftR} for an introduction). \cr +#' +#' While the methods are designed for diploid systems, it is possible to compute F-stats for haploid organisms – in this case, +#' heterozygosity terms evaluate to zero. Reminder: in RangeShifter, asexual species are always haploid, and sexual organisms are always diploid! +#' +#' See the RangeShifter manual for more details on the calculation of these statistics. \cr +#' +#' \emph{Per-locus neutral genetics} \cr +#' +#' If the per locus \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} parameter is enabled \code{OutputPerLocusFst==TRUE}, RangeShifter outputs an additional file +#' \emph{Sim_Land_perLocusNeutralGenetics} with one entry for each neutral locus: \cr +#' +#' 1. Year \cr +#' 2. RepSeason \cr +#' 3. Locus, the ID of locus \eqn{l} \cr +#' 4. \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}}, the value of \emph{\ifelse{html}{\out{Fst,l}}{\eqn{F_st,l}}} for locus \emph{l} \cr +#' 5. \emph{\ifelse{html}{\out{Fis}}{\eqn{F_is}}}, the value of \emph{\ifelse{html}{\out{Fis}}{\eqn{F_is,l}}} for locus \emph{l} \cr +#' 6. \emph{\ifelse{html}{\out{Fit}}{\eqn{F_it}}}, the value of \emph{\ifelse{html}{\out{Fit}}{\eqn{F_it,l}}} for locus \emph{l} \cr +#' 7. Het, the sample-level observed heterozygosity (\emph{\ifelse{html}{\out{Ho}}{\eqn{H_o}}}) for locus \eqn{l} \cr +#' 8. One column \emph{patch__het} for each patch \emph{i} in the sample, indicating \emph{\ifelse{html}{\out{Ho}}{\eqn{H_o}}} for patch \emph{i} and locus \emph{l}. +#' If patches have been sampled with the “random_occupied” option, then the patches number will not correspond to the sampled patches, instead ranging from 1 to the number +#' of patches sampled. This is because it is not known which patches will be sampled (and they may change) at the time of writing the headers.\cr +#' +#' \emph{Pairwise patch neutral genetics}\cr +#' +#' If the pariwise \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} parameter is enabled (\code{OutputPairwiseFst=TRUE}), a pairwise \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} matrix is constituted and filled with the corresponding +#' values of \emph{\ifelse{html}{\out{βii’}}{\eqn{β_ii’}}} for each pair of patches in the sample. Values along the diagonal are set to zero. \cr +#' +#' In this case, there is one row of output for each pair: \cr +#' 1. Year\cr +#' 2. Generation\cr +#' 3. Patch ID of the first patch \cr +#' 4. X coordinate of first patch \cr +#' 5. Y coordinate of first patch \cr +#' 6. Patch ID of the second patch (same as 3. along the diagonal of the matrix) \cr +#' 7. X coordinate of second patch \cr +#' 8. Y coordinate of second patch \cr +#' 9. Pairwise \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} \cr +#' +#' \emph{Traits} \cr +#' +#' In the case of inter-individual variability and evolution of the dispersal traits, +#' it is possible to output the mean traits of the population. There are two types of traits output:\cr +#' +#' 1. \emph{Mean traits by cell/patch (Sim0_TraitsXcell.txt or Sim0_TraitsXpatch.txt}). This file reports mean and standard deviation of the varying traits for each cell/patch, +#' for each replicate and reproductive season at the set year interval. \cr +#' 2. \emph{Mean traits by row (Sim0_TraitsXrow.txt)}. The mean and standard deviation of the varying traits are computed at the row (\emph{y}) level, +#' pulling together all the populations occupying cells in \emph{y}. Values are reported for each replicate and reproductive season at the specified yearly interval. +#' This is particularly useful for analysing the structuring of traits along latitudinal gradients. It is possible to compute this output only for cell-based models. \cr +#' +#' Data for these outputs are collected at the same time as for the range and population outputs, i.e. before reproduction at each reproductive season at the set year interval and at the end of the simulation. \cr +#' +#' @references +#' \insertAllCited{} +#' +#' @return a parameter object of class "GeneticsParams" +#' @author Jette Wolff +#' @name Genetics +#' @export Genetics +Genetics <- setClass("GeneticsParams", slots = c(GenomeSize = "integer_OR_numeric", + ChromosomeEnds = "ANY", # NULL or vector + RecombinationRate = "integer_OR_numeric", # NULL or numeric + OutputGeneValues = "logical", + OutputGenesStart = "ANY", # positive integer if OutputGeneValues is TRUE or NULL + OutputGenesInterval = "ANY", # positive integer if OutputGeneValues is TRUE or NULL + OutputGlobalFst = "logical", + OutputGlobalFstStart = "ANY", # positive integer if OutputGlobalFst is TRUE or NULL + OutputGlobalFstInterval = "ANY", # positive integer if OutputGlobalFst is TRUE or NULL + OutputPairwiseFst = "logical", + OutputPairwiseFstStart = "ANY", # positive integer if OutputPairwiseFst is TRUE or NULL + OutputPairwiseFstInterval = "ANY", # positive integer if OutputPairwiseFst is TRUE or NULL + OutputPerLocusFst = "logical", + PatchList = "ANY", # vector of integers or a string + NbrPatchesToSample = "ANY", # NULL or integer + nIndividualsToSample = "ANY", # "character_OR_integer", # character or integer + Stages = "ANY", # "character_OR_integer", # vector + Traits = "TraitsParams") + , prototype = list(GenomeSize = 1L, + ChromosomeEnds = 0L, # NULL or vector + RecombinationRate = 0.0, # NULL or numeric + OutputGeneValues = FALSE, + OutputGenesStart = NULL, # positive integer if OutputGeneValues is TRUE or NULL + OutputGenesInterval = NULL, # positive integer if OutputGeneValues is TRUE or NULL + OutputGlobalFst = FALSE, + OutputGlobalFstStart = NULL, # positive integer if OutputGlobalFst is TRUE + OutputGlobalFstInterval = NULL, # positive integer if OutputGlobalFst is TRUE + OutputPairwiseFst = FALSE, + OutputPairwiseFstStart = NULL, # positive integer if OutputPairwiseFst is TRUE + OutputPairwiseFstInterval = NULL, # positive integer if OutputPairwiseFst + OutputPerLocusFst = FALSE, + PatchList = NULL, #"all", # vector or string + NbrPatchesToSample = NULL, #0L, # NULL or integer + nIndividualsToSample = NULL, # "all", # NULL or integer + Stages = NULL, #"all", # vector + Traits = Traits()) + +) +setValidity('GeneticsParams', function(object){ + msg <- NULL + # Genome Size + # must be numeric and >0 + if (!is.numeric(object@GenomeSize) || object@GenomeSize <= 0) { + msg <- c(msg, "In Genetics(): GenomeSize must be a positive integer.") + } + # Chromosome Ends + # must be NULL or numeric vector + if (!is.null(object@ChromosomeEnds) && !is.numeric(object@ChromosomeEnds)) { + msg <- c(msg, "In Genetics(): ChromosomeEnds must be a numeric vector or NULL.") + } + + # Recombination Rate + # should be checked in RSparams: should not be set for asexual models + # should be between 0 and 0.5 + if (!is.numeric(object@RecombinationRate) || object@RecombinationRate < 0.0 || object@RecombinationRate > 0.5) { + msg <- c(msg, "In Genetics(): RecombinationRate must be a float between 0.0 and 0.5.") + } + + # OutputGeneValues + # must be a boolean + if (!is.logical(object@OutputGeneValues)) { + msg <- c(msg, "In Genetics(): OutputGeneValues must be true or false.") + } + + # OutputGlobalFst + # must be a boolean + if (!is.logical(object@OutputGlobalFst)) { + msg <- c(msg, "In Genetics(): OutputGlobalFst must be true or false.") + } + + # if TRUE, OutputGlobalFstStart and OutputGlobalFstInterval must be positive integers + if (object@OutputGlobalFst) { + if (is.null(object@OutputGlobalFstStart) || object@OutputGlobalFstStart <= 0) { + msg <- c(msg, "OutputGlobalFstStart must be a positive integer if OutputGlobalFst is TRUE.") + } + if (is.null(object@OutputGlobalFstInterval) || object@OutputGlobalFstInterval <= 0) { + msg <- c(msg, "OutputGlobalFstInterval must be a positive integer if OutputGlobalFst is TRUE.") + } + } + + # OutputPairwiseFst + # must be a boolean + if (!is.logical(object@OutputPairwiseFst)) { + msg <- c(msg, "In Genetics(): OutputPairwiseFst must be true or false.") + } + + # if true, OutputPairwiseFstStart and OutputPairwiseFstInterval must be positive integers + if (object@OutputPairwiseFst) { + if (is.null(object@OutputPairwiseFstStart) || object@OutputPairwiseFstStart <= 0) { + msg <- c(msg, "OutputPairwiseFstStart must be a positive integer if OutputPairwiseFst is TRUE.") + } + if (is.null(object@OutputPairwiseFstInterval) || object@OutputPairwiseFstInterval <= 0) { + msg <- c(msg, "OutputPairwiseFstInterval must be a positive integer if OutputPairwiseFst is TRUE.") + } + } + + # OutputPerLocusFst + if(!is.logical(object@OutputPerLocusFst)) { + msg <- c(msg, "In Genetics(): OutputPerLocusFst must be true or false.") + } + + # if OutputGlobalFst is false, OutputPerLocusFst must be false + if (object@OutputPerLocusFst && !object@OutputGlobalFst) { + msg <- c(msg, "OutputPerLocusFst cannot be TRUE if OutputGlobalFst is FALSE.") + } + + + anyNeutral = object@OutputGlobalFst || object@OutputPairwiseFst + + anyGeneticsOutput = object@OutputGeneValues == "TRUE" || anyNeutral + + if (anyGeneticsOutput) { + if (is.null(object@OutputGenesStart) || object@OutputGenesStart < 0) { + msg <- c(msg, "OutputGenesStart must be greateror equal to 0 if any genetic output option is TRUE.") + } + + if (is.null(object@OutputGenesInterval) || object@OutputGenesInterval <= 0) { # check whether is.null() + msg <- c(msg,"OutputInterval must be at least 1 if any genetic output option is TRUE.") + } + } + else if (!is.null(object@OutputGenesInterval) || !is.null(object@OutputGenesStart)){ + msg <- c(msg, "OutputGenesStart and OutputGenesInterval should be NULL if all genetic output options are FALSE.") + } + + # Check PatchList + if (anyGeneticsOutput) { + if(!is.null(object@PatchList)){ + if (is.character(object@PatchList) || is.numeric(object@PatchList)) { + if (!is.numeric(object@PatchList) && object@PatchList != "random" && object@PatchList != "all" && object@PatchList != "random_occupied") { + msg <- c(msg,"PatchList must be either a vector of integers, or \"random\", \"random_occupied\" or \"all\".") + } + } + } else{ + msg <- c(msg, "PatchList cannot be NULL if any genetic output option is TRUE.") + } + + } + else if (!is.null(object@PatchList)) { + msg <- c(msg, "PatchList should be NULL if all genetic output options are FALSE.") + } + + # Check NbrPatchesToSample + if (anyGeneticsOutput) { + if (is.character(object@PatchList)){ + if (object@PatchList == "random" || object@PatchList == "random_occupied") { + if (is.null(object@NbrPatchesToSample) || object@NbrPatchesToSample == 0) { + msg <- c(msg, "NbrPatchesToSample cannot be NULL or 0 if PatchList is \"random\" or \"random_occupied\".") + } + else { + if (object@NbrPatchesToSample <= 0) { + msg <- c(msg, "NbrPatchesToSample must be a positive integer if PatchList is \"random\" or \"random_occupied\".") + } + } + } + } + else if (!is.null(object@NbrPatchesToSample) && object@NbrPatchesToSample != 0) { + msg <- c(msg, "NbrPatchesToSample must be NULL or zero if PatchList is not \"random\" or \"random_occupied\".") + } + } + + # Check IndividualsToSample + if (anyGeneticsOutput) { + if (is.null(object@nIndividualsToSample) || (is.numeric(object@nIndividualsToSample) && object@nIndividualsToSample == 0)) { + msg <- c(msg, "nIndividualsToSample cannot be NULL or zero if any genetics output option is TRUE.") + } + else if ((is.character(object@nIndividualsToSample) && object@nIndividualsToSample != "all") || (is.numeric(object@nIndividualsToSample) && object@nIndividualsToSample <= 0)) { + msg <- c(msg, "nIndividualsToSample must be either a positive integer or \"all\".") + } + } + else if (!is.null(object@nIndividualsToSample)) { + msg <- c(msg, "numberIndividualsToSample must be NULL if all genetics output options are FALSE.") + } + + # Check Stages + if (anyGeneticsOutput) { + if (is.null(object@Stages)) { + msg <- c(msg, "Stages cannot be NULL if any genetic output option is TRUE.") + } + else { + if (!is.numeric(object@Stages) && (is.character(object@Stages) && object@Stages != "all")) { + msg <- c(msg, "Stages must be either a vector of integers, or \"all\".") + } + } + } + else if (!is.null(object@Stages)) { + msg <- c(msg, "Stages must be NULL if all genetic output options are FALSE.") + } + if (is.null(msg)) TRUE else msg +}) +setMethod('initialize', 'GeneticsParams', function(.Object, ...) { + this_func = "Genetics(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object + }) +setMethod("show", "GeneticsParams", function(object){ + cat(" Genetics: \n") + cat(" Genome size =", object@GenomeSize, "\n ") + if(length(object@ChromosomeEnds) > 0){ + cat(" Genome is slitted into chromosomes at =", object@ChromosomeEnds, "\n ") + } else cat( " Genome is not slitted into chromosomes \n") + + cat(" Recombination rate: ", object@RecombinationRate, "\n") + cat(" Output genetic values: ", object@OutputGeneValues, "\n") + cat(" Output global Fst: ", object@OutputGlobalFst, "\n") + cat(" Output Pairwise Fst: ", object@OutputPairwiseFst, "\n") + if(any(object@OutputGeneValues || object@OutputGlobalFst || object@OutputPairwiseFst)){ + if(object@OutputGeneValues){ + cat(" Start gene values output at year: ", object@OutputGenesStart, "and output every ",object@OutputGenesInterval ," year \n") + } + if(object@OutputGlobalFst){ + cat(" Start global Fst output at year: ", object@OutputGlobalFstStart, "and output every ",object@OutputGlobalFstInterval ," year \n") + } + if(object@OutputPairwiseFst){ + cat(" Start pairwise Fst output at year: ", object@OutputPairwiseFstStart, "and output every ",object@OutputPairwiseFstInterval ," year \n") + } + + cat(" Patches to sample: ", object@PatchList, "\n") + if(object@PatchList=="random" || object@PatchList=="random_occupied"){ + cat(" Number of patches to sample: ", object@NbrPatchesToSample, "\n") + } + cat(" Number of individuals to sample: ", object@nIndividualsToSample, "\n") + cat(" Stages to sample: ", object@Stages, "\n") + } else{ + cat(" No genetic output. \n") + } + print(object@Traits) +}) diff --git a/RangeShiftR/R/class_InitialisationParams.R b/RangeShiftR/R/class_InitialisationParams.R new file mode 100644 index 0000000..4086b7e --- /dev/null +++ b/RangeShiftR/R/class_InitialisationParams.R @@ -0,0 +1,587 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#### CLASS INITIALISATIONPARAMS + +# from RS 'Initialisation' file + +#' Set Initialisation Parameters +#' +#' Initialisation rules define the way in which initial individuals are placed in the landscape at the start of the simulation. +#' There are three initialisation types:\cr +#' Free initialisation according to the habitat map (\code{InitType}\eqn{= 0}), +#' initialisation from a loaded species distribution map (\code{InitType} \eqn{= 1}), +#' and the initialisation from an initial individuals list (\code{InitType} \eqn{= 2}), +#' with additional options for each type, see the Details.\cr +#' Additionally, initial density and, if applicable, initial stage and age distributions can be set. +#' +#' @include plotProbs.R +#' @include Rfunctions.R +#' @usage Initialise(InitType = 0, FreeType = 1, SpType = 0, NrCells, InitIndsFile = NULL, InitIndsList = list(), +#' InitDens = 1, IndsHaCell, PropStages = 0, InitAge = 2, minX, minY, maxX, maxY, +#' InitFreezeYear = 0, RestrictRows = 0, RestrictFreq = 0, FinalFreezeYear = 0) +#' @param InitType Type of initialisation:\cr +#' \code{InitType} = \eqn{0}: Free initialisation according to habitat map (default) (set \code{FreeType}), \cr +#' \code{InitType} = \eqn{1}: From loaded species distribution map (set \code{SpType}),\cr +#' \code{InitType} = \eqn{2}: From initial individuals list file (set \code{InitIndsFile} or \code{InitIndsList}, respectively). +#' \cr Must to be \eqn{0} for an \code{\link[RangeShiftR]{ArtificialLandscape}}. +#' @param FreeType,NrCells Option for \emph{free initialisation}, i.e. required only if \code{InitType}\eqn{ = 0}:\cr +#' \code{FreeType} = \eqn{0}: Random; provide number of cells/patches to initialise in \code{NrCells}. \cr +#' \code{FreeType} = \eqn{1}: All suitable cells/patches (default). +#' @param SpType,NrCells Option for \emph{initialisation from species distribution map}, i.e. required only if \code{InitType}\eqn{ = 1}:\cr +#' \code{SpType} = \eqn{0}: All suitable cells within all distribution presence cells (default), \cr +#' \code{SpType} = \eqn{1}: All suitable cells within some randomly chosen presence cells; set number of cells to initialise in \code{NrCells}. +#' @param InitIndsFile Name of \emph{initial individuals list file}, required only if \code{InitType}\eqn{ = 2}.\cr +#' For informaton on the required file format see the Details below. +#' @param InitIndsList The list of initial individuals given as a list of data.frames - one for each replicate simulation (instead of as file name in \code{InitIndsFile}), using the same format (see Details). +#' @param InitDens,IndsHaCell Number of individuals to be seeded in each cell/patch:\cr +#' \code{InitDens} = \eqn{0}: At \code{K_or_DensDep},\cr +#' \code{InitDens} = \eqn{1}: At half \code{K_or_DensDep} (default),\cr +#' \code{InitDens} = \eqn{2}: Set the number of individuals per cell/hectare to initialise in \code{IndsHaCell}. +#' @param PropStages For \code{\link[RangeShiftR]{StageStructure}}d models only: Proportion of individuals initialised in each stage. +#' Requires a vector of length equal to the number of stages; its entries must be \eqn{\ge 0} and sum to \eqn{1.0}. However, juveniles +#' can't be initialised and thus stage \eqn{0} (first entry) must have a value of \eqn{0.0}. +#' @param InitAge For \code{StageStructure}d models only: Initial age distribution within each stage:\cr +#' \code{InitAge} = \eqn{0}: Minimum age for the respective stage.\cr +#' \code{InitAge} = \eqn{1}: Age randomly sampled between the minimum and the maximum age for the respective stage.\cr +#' \code{InitAge} = \eqn{2}: According to a quasi-equilibrium distribution (default). +#' @param minX,maxX,minY,maxY Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): Restrict initial range in X- and/or Y- coordinates, given in number of cells. +#' All must be \eqn{\ge 0} and (\code{maxX,maxY})\eqn{>}(\code{minX,minY}). (Integer) +#' @param InitFreezeYear Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): The year until which species is confined to +#' its initial range limits. +#' @param RestrictRows Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): The number of rows at northern front to restrict range. +#' If set to \eqn{0}, the range restriction turned off. +#' @param RestrictFreq Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): Frequency in years at which range is restricted to northern front. +#' @param FinalFreezeYear Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): The year after which species is confined to its new, current range limits, after a +#' period of range expansion. Will be ignored if set to \eqn{0}, otherwise must be \eqn{>} \code{InitFreezeYear}. +#' @details +#' \emph{Initialisation Types}\cr +#' \itemize{ +#' \item \emph{Free Initialisation.} (\code{InitType}\eqn{ = 0})\cr The population is initialised according to suitable habitat in the landscape. +#' Either all (\code{FreeType}\eqn{=1}), or a specified number (\code{NrCells}) of randomly selected (\code{FreeType}\eqn{=0}) cells/patches +#' will be seeded. When using an artificial landscape, this is the only option available. +#' \item \emph{From loaded species distribution map.} (\code{InitType}\eqn{ = 1})\cr The population is initialised according to a loaded +#' species distribution map/matrix, which needs to be provided through the module \code{\link[RangeShiftR]{ImportedLandscape}}, option \code{SpDistFile} or \code{SpDistMatrix}. +#' All habitat cells/patches within either all (\code{SpType}\eqn{=0}), or a specified number (\code{NrCells}) of randomly selected +#' (\code{SpType}\eqn{=1}) presence cells (which can have a lower resolution) specified by this distribution map will seeded. +#' \item \emph{From initial individuals list file.} (\code{InitType}\eqn{ = 2})\cr The population is initialised according to a list of specific +#' individuals (of given sex, age and stage, if appropriate) in specified cells/patches. This option allows simulation of a reintroduction +#' scenario.\cr The list has to be loaded from a file in the path given by \code{InitIndsFile} or given as a list of dataframes in \code{InitIndsList}. +#' It must be a tab-separated list with +#' explicit column headers and one row for each individual to be initialized. The expected column headers depend on the model settings and +#' must match the following order exactly: 'Year', 'Species' (must \eqn{= 0}), for cell-/patch-based: 'X', 'Y' / 'PatchID', 'Ninds', for sexual model: 'Sex', +#' for stage-structured population: 'Age', 'Stage'. The sex is specified with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. +#' } +#' +#' \emph{Initialial density, stage, and age}\cr +#' For \code{InitType}\eqn{ = {0,1}}, the number of individuals that should be seeded in each cell or patch has to be set. +#' There are three options: +#' \itemize{ +#' \item \emph{At} \code{K_or_DensDep}. (\code{InitDens}\eqn{=0})\cr The cell/patch will be saturated at its respective \eqn{K} or \eqn{1/b}. +#' \item \emph{At half} \code{K_or_DensDep}. (\code{InitDens}\eqn{=1})\cr The cell/patch will be initialised at half its \eqn{K} or \eqn{1/b}. +#' \item \emph{Set value} \code{IndsHaCell}. (\code{InitDens}\eqn{=2})\cr Set the number of individuals to be seeded in each cell or the density +#' in each patch (in units of individuals per hectare). +#' } +#' (These settings have no effect for \code{InitType}\eqn{ = 2}.) +#' +#' In the case of \code{\link[RangeShiftR]{StageStructure}}d models, the initial stage and age distributions must be specified. +#' If \code{InitType}\eqn{ = 2}, this is done via the \code{InitIndsFile} or \code{InitIndsList}, whereas for \code{InitType}\eqn{ = {0,1}}, +#' the proportion of individuals that should be initialised at each stage class is set via the numeric vector \code{PropStages}. It needs +#' to have as many entries as number of stages, starting from the juvenile stage (\eqn{0}). Note that these proportions must sum up to \eqn{1.0}, +#' however the proportion of juveniles must be \eqn{0.0}. +#' +#' Options for initial age distributions: +#' \itemize{ +#' \item \emph{Minimal age} of respective stage. (\code{InitAge}=0) +#' \item \emph{Randomise.} (\code{InitAge}=1)\cr Individuals initialised in each stage will get an age randomly sampled between +#' the minimum and the maximum age for their respective stage. +#' \item \emph{Quasi-equilibrium.} (\code{InitAge}=2)\cr Initial age distribution is set approximately in accordance with the number of years +#' taken to pass through the stage and the (female) survival rate of the respective stage. +#' } +#' (These settings have no effect for \code{InitType}\eqn{ = 2}.) +#' +#' \emph{Additional options for free initialisation}\cr +#' In the case of free initialisation, either all or a specified number of randomly selected cells/patches will be seeded. +#' It is possible to restrict the landscape area available for initialisation by setting limits to the x- and y- coordinates using +#' \code{minX,maxX,minY} and \code{maxY}). +#' +#' Additionally, for all free initialisation methods, it is possible to restrict the available landscape to the initialised range for +#' a specified period, specifically until year \code{InitFreezeYear}. This option may be particularly useful in an evolutionary model, +#' to allow a population to reach equilibrium in its original range before being allowed to expand into the remainder of the landscape. +#' +#' \emph{Restrict range to northern front} is a further option provided as an additional feature for models of range expansion. Whilst not +#' strictly an initialisation option, it is provided in this context as it will typically be applied together with restriction of the +#' initial range in theoretical eco-evolutional models, where the population is firstly allowed to evolve certain traits in a stable range, +#' then allowed to expand its range during a period of environmental change (when dispersal traits can come under strong selection), and +#' finally further restricted to a stable range (set \code{FinalFreezeYear}). During the period of range expansion, the population can build up to very large numbers +#' of individuals in the core of the range, but the area of interest, where strong selection occurs, lies close to the range front. +#' Therefore, individuals in the core can be discarded, and this is achieved by progressively restricting the suitable range to a number +#' of rows behind the current range front (set \code{RestrictRows}) so that local populations in the core go extinct. This occurs at +#' a frequency \code{RestrictFreq} specified in years. The parameter \code{FinalFreezeYear} sets the year after which the range will be +#' frozen to its new, current limits. It must either be zero, in which case range expansion continues until either the end of the simulation or the northern edge of the +#' landscape is reached, or set to a year after the year specified in \code{InitFreezeYear}. +#' +#' This feature is provided only for expansion in a northerly direction (increasing Y); the initial population should therefore be +#' established in the southern part of the landscape (low Y values). To turn it off, set \code{RestrictRows = 0}. +# +# For Instance a population is firstly allowed to evolve certain traits in a stable range of 1000 years (\code{InitFreezeYear}=1000). +# Then allowed to expand its range during a period of environmental change and is finally further restricted +# to a stable range in the year 5000 (\code{FinalFreezeYear}=5000). During the period of range expansion, the population +# can build up to very large numbers of individuals in the core of the range, but the area of interest, lies close +# to the range front (i.e. 50 rows). Therefore, individuals in the core can be discarded. This is achieved +# by progressively restricting the suitable range to a number of rows behind the front (\code{RestrictRows}=50), +# so that local populations outside of the area of interest go extinct. Note that \code{RestrictRows} is provided +# only for expansion in a northerly direction (increasing \eqn{y}-axis). Thus the initial population should be established in the +# southern part of the landscape (low value on the \eqn{y}-axis). +# +#' @examples init <- Initialise() # use all defaults (a stage-structured model requires setting PropStages) +#' @return a parameter object of class "InitialisationParams" +#' @author Anne-Kathleen Malchow +#' @name Initialise +#' @export Initialise +Initialise <- setClass("InitialisationParams", slots = c(InitType = "integer_OR_numeric", + FreeType = "integer_OR_numeric", + SpType = "integer_OR_numeric", + NrCells = "integer_OR_numeric", + InitIndsFile = "ANY", + InitIndsList = "list", # "data.frame", + InitDens = "integer_OR_numeric", + IndsHaCell = "integer_OR_numeric", + PropStages = "numeric", + InitAge = "integer_OR_numeric", + minX = "integer_OR_numeric", + minY = "integer_OR_numeric", + maxX = "integer_OR_numeric", + maxY = "integer_OR_numeric", + InitFreezeYear = "integer_OR_numeric", + RestrictRows = "integer_OR_numeric", + RestrictFreq = "integer_OR_numeric", + FinalFreezeYear = "integer_OR_numeric") + , prototype = list(InitType = 0L, #free initialisation + FreeType = 1L, #all + SpType = 0L, #all + #NrCells, + InitIndsFile = NULL, + InitIndsList = list(), # data.frame(), + InitDens = 1L, #K/2 + #IndsHaCell, + PropStages = 0.0, + InitAge = 2L, #quasi-eq + #minX, + #minY, + #maxX, + #maxY, + InitFreezeYear = 0L, + RestrictRows = 0L, + RestrictFreq = 0L, + FinalFreezeYear = 0L) +) + +setValidity('InitialisationParams', function(object){ + msg <- NULL + if(!is.null(object@InitIndsFile)){ + if (anyNA(object@InitIndsFile) || length(object@InitIndsFile) != 1){ + msg <- c(msg, 'InitIndsFile must contain exactly one element.') + } + } + + if (anyNA(object@InitType) || length(object@InitType)!=1){ + msg <- c(msg, 'Type of initialisation (InitType) must be set and of length 1!') + } + else { + if (!object@InitType %in% c(0,1,2)){ + msg <- c(msg, 'Type of initialisation (InitType) must be 0, 1 or 2!') + } + else { # Valid InitType + if (object@InitType == 0){ # Free Init + if (anyNA(object@FreeType) || length(object@FreeType)!=1){ + msg <- c(msg, 'FreeType is required if InitType = 0 (Free initialisation).') + } + else{ + if (!object@FreeType %in% c(0,1)){ + msg <- c(msg, 'FreeType must be 0 or 1.') + } + else { # Valid FreeType + if (object@FreeType == 0){ #random + if (anyNA(object@NrCells) || length(object@NrCells)!=1){ + msg <- c(msg, 'NrCells is required if FreeType = 0 (Random Free initialisation).') + } + else { # Valid NrCells + if (object@NrCells < 1){ + msg <- c(msg, 'NrCells must be positive.') + } + } + } + } + } + min.set = FALSE + max.set = FALSE + if (length(object@minX) > 1){ + msg <- c(msg, 'Minimum X coordinate (minX) must be of length 1 or missing!') + } + else{ + if (length(object@minX) == 1){ + if (object@minX < 0 && object@minX != -9L){ + msg <- c(msg, 'Minimum X coordinate (minX) has to be greater or equal 0!') + } + else min.set = ifelse(object@minX==-9L,FALSE,TRUE) + } + # else min.set = TRUE + } + if (length(object@maxX) > 1){ + msg <- c(msg, 'Maximum X coordinate (maxX) must be of length 1 or missing!') + } + else{ + if (length(object@maxX) == 1){ + if (object@maxX < 0 && object@maxX != -9L){ + msg <- c(msg, 'Maximum X coordinate (maxX) has to be greater or equal 0!') + } + else max.set = ifelse(object@maxX==-9L,FALSE,TRUE) + } + # else max.set = TRUE + } + if(min.set && max.set){ + Xextend = object@maxX - object@minX + if (Xextend <= 0){ + msg <- c(msg, 'maxX has to be larger than minX!') + Xextend = FALSE + } + } + else {Xextend = FALSE} + min.set = FALSE + max.set = FALSE + if (length(object@minY) > 1){ + msg <- c(msg, 'Minimum Y coordinate (minY) must be of length 1 or missing!') + } + else{ + if (length(object@minY) == 1){ + if (object@minY < 0 && object@minY != -9L){ + msg <- c(msg, 'Minimum Y coordinate (minY) has to be greater or equal 0!') + } + else min.set = ifelse(object@minY==-9L,FALSE,TRUE) + } + # else min.set = TRUE + } + if (length(object@maxY) > 1){ + msg <- c(msg, 'Maximum Y coordinate (maxY) must be of length 1 or missing!') + } + else{ + if (length(object@maxY) == 1){ + if (object@maxY < 0 && object@maxY != -9L){ + msg <- c(msg, 'Maximum Y coordinate (maxY) has to be greater or equal 0!') + } + else max.set = ifelse(object@maxY==-9L,FALSE,TRUE) + } + # else max.set = TRUE + } + if(min.set && max.set){ + Yextend = object@maxY - object@minY + if (Yextend <= 0){ + msg <- c(msg, 'maxY has to be larger than minY!') + Yextend = FALSE + } + } + else {Yextend = FALSE} + if(Xextend && Yextend && length(object@NrCells) > 0){ + if (object@NrCells > Xextend*Yextend){ + msg <- c(msg, 'The area bounded by (minX, maxX, minY, maxY) contains less cells than required by NrCells.') + } + } + } + if (object@InitType == 1){ # Init Distmap + if (anyNA(object@SpType) || length(object@SpType)!=1){ + msg <- c(msg, 'SpType is required if InitType = 1 (from loaded species distribution map).') + } + else{ + if (!object@SpType %in% c(0,1)){ + msg <- c(msg, 'SpType must be 0 or 1.') + } + else { # Valid SpType + if (object@SpType == 1){ #random + if (anyNA(object@NrCells) || length(object@NrCells)!=1){ + msg <- c(msg, 'NrCells is required if SpType = 1 (Random initialisation from loaded species distribution map).') + } + else { # Valid NrCells + if (object@NrCells < 1){ + msg <- c(msg, 'NrCells must be positive.') + } + } + } + } + } + } + if (object@InitType == 2){ # Init IndsList + if (is.null(object@InitIndsFile) & length(object@InitIndsList)==0){ + msg <- c(msg, 'InitIndsFile or InitIndsList is required if InitType = 2 (from loaded initial individuals list).') + } + else { + if (!is.null(object@InitIndsFile) & length(object@InitIndsList)!=0){ # both are given + msg <- c(msg, 'Both InitIndsFile and InitIndsList are given, but only one can be used.') + } + } + } + } + } + if (anyNA(object@InitDens) || length(object@InitDens)!=1) { + msg <- c(msg, 'InitDens must be set and of length 1!') + } + else { + if (!object@InitDens %in% c(0,1,2)) { + msg <- c(msg, 'InitDens must be 0, 1 or 2!') + } + else { + if (object@InitDens == 2){ + if(anyNA(object@IndsHaCell) || length(object@IndsHaCell)!=1) { + msg <- c(msg, 'IndsHaCell is required if InitDens = 2') + } + else { + if (object@IndsHaCell <= 0){ + msg <- c(msg, 'IndsHaCell must be positive.') + } + } + } + } + } + if (object@InitType != 2) { + if (length(object@InitAge) != 0){ + if (!object@InitAge %in% c(0,1,2)){ + msg <- c(msg, 'InitAge must be 0, 1 or 2!') + } + } + if (length(object@PropStages) != 0){ + if(any(object@PropStages < 0.0) || any(object@PropStages > 1.0)) { + msg <- c(msg, 'All elements of PropStages must be in the closed interval [0,1]!') + } + else{ + if (object@PropStages[1] != 0.0) { + msg <- c(msg, 'Initial proportion of the juvenile stage (PropStages[1]) must be 0.0!') + } + else{ + if (length(object@PropStages)>1 && sum(object@PropStages) != 1.0) { + msg <- c(msg, 'The elements of PropStages must sum to 1!') + } + } + } + } + } + if (anyNA(object@InitFreezeYear) || length(object@InitFreezeYear)!=1) { + msg <- c(msg, 'InitFreezeYear must be set and of length 1!') + } + else { + if(object@InitFreezeYear < 0) { + msg <- c(msg, 'InitFreezeYear must be greater or equal 0!') + } + } + if (anyNA(object@RestrictRows) || length(object@RestrictRows)!=1) { + msg <- c(msg, 'RestrictRows must be set and of length 1!') + } + else { + if(object@RestrictRows < 0) { + msg <- c(msg, 'RestrictRows must be greater or equal 0!') + } + } + if (anyNA(object@RestrictFreq) || length(object@RestrictFreq)!=1) { + msg <- c(msg, 'RestrictFreq must be set and of length 1!') + } + else { + if(object@RestrictFreq <= 0 && object@RestrictRows > 0) { + msg <- c(msg, 'RestrictFreq must be strictly positive!') + } + } + if (anyNA(object@FinalFreezeYear) || length(object@FinalFreezeYear)!=1) { + msg <- c(msg, 'FinalFreezeYear must be set and of length 1!') + } + else { + if(object@FinalFreezeYear < 0) { + msg <- c(msg, 'FinalFreezeYear must be greater or equal 0!') + } + else { + if(object@FinalFreezeYear > 0 && object@FinalFreezeYear <= object@InitFreezeYear) { + msg <- c(msg, 'FinalFreezeYear must be greater than InitFreezeYear!') + } + } + } + if (is.null(msg)) TRUE else msg} +) + +setMethod('initialize', 'InitialisationParams', function(.Object, ...) { + this_func = "Initialise(): " + args <- list(...) + .Object <- callNextMethod() + if (.Object@InitType != 0) { + .Object@FreeType = -9L + if (!is.null(args$FreeType)) { + warning(this_func, "FreeType", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + } + if (.Object@InitType != 1) { + .Object@SpType = -9L + if (!is.null(args$SpType)) { + warning(this_func, "SpType", warn_msg_ignored, "since InitType != 1.", call. = FALSE) + } + } + if (.Object@InitType == 2) { + .Object@InitDens <- 0 + .Object@PropStages <- -9L + .Object@InitAge <- -9L + if (!is.null(args$InitDens)) { + warning(this_func, "InitDens", warn_msg_ignored, "since InitType = 2.", call. = FALSE) + } + if (!is.null(args$PropStages)) { + warning(this_func, "PropStages", warn_msg_ignored, "since InitType = 2.", call. = FALSE) + } + if (!is.null(args$InitAge)) { + warning(this_func, "InitAge", warn_msg_ignored, "since InitType = 2.", call. = FALSE) + } + } + else{ + .Object@InitIndsFile = NULL + .Object@InitIndsList = list() # data.frame() + if (!is.null(args$InitIndsFile)) { + warning(this_func, "InitIndsFile", warn_msg_ignored, "since InitType != 2.", call. = FALSE) + } + if (length(args$InitIndsList)>0) { + warning(this_func, "InitIndsList", warn_msg_ignored, "since InitType != 2.", call. = FALSE) + } + } + if (!((.Object@InitType == 0 && .Object@FreeType == 0) || (.Object@InitType == 1 && .Object@SpType == 1))) { + .Object@NrCells = -9L + if (!is.null(args$NrCells)) { + warning(this_func, "NrCells", warn_msg_ignored, "since its not used.", call. = FALSE) + } + } + if (.Object@InitDens != 2) { + .Object@IndsHaCell = -9L + if (!is.null(args$IndsHaCell)) { + warning(this_func, "IndsHaCell", warn_msg_ignored, "since InitDens != 2.", call. = FALSE) + } + } + if (.Object@InitType == 0) { + # if (minX, maxX, minY, maxY) are negative, they will be set to their default values on C++ level + if (is.null(args$minX)) { + .Object@minX = -9L + } + if (is.null(args$minY)) { + .Object@minY = -9L + } + if (is.null(args$maxX)) { + .Object@maxX = -9L + } + if (is.null(args$maxY)) { + .Object@maxY = -9L + } + if (!.Object@RestrictRows) { + .Object@RestrictFreq = -9L + if (!is.null(args$RestrictFreq)) { + warning(this_func, "RestrictFreq", warn_msg_ignored, "since RestrictRows = 0.", call. = FALSE) + } + } + } + else { + .Object@minX = -9L + .Object@minY = -9L + .Object@maxX = -9L + .Object@maxY = -9L + if (!is.null(args$minX)) { + warning(this_func, "minX", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$minY)) { + warning(this_func, "minY", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$maxX)) { + warning(this_func, "maxX", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$maxY)) { + warning(this_func, "maxY", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$InitFreezeYear)) { + .Object@InitFreezeYear = 0L + warning(this_func, "InitFreezeYear", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$RestrictRows)) { + .Object@RestrictRows = 0L + warning(this_func, "RestrictRows", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$RestrictFreq)) { + .Object@RestrictFreq = 0L + warning(this_func, "RestrictFreq", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + if (!is.null(args$FinalFreezeYear)) { + .Object@FinalFreezeYear = 0L + warning(this_func, "FinalFreezeYear", warn_msg_ignored, "since InitType != 0.", call. = FALSE) + } + } + return(.Object) + } +) +setMethod("show", "InitialisationParams", function(object){ + cat(" Initialisation: \n") + cat(" InitType =", object@InitType, ": ") + if (object@InitType == 0) { + cat("Free initialisation \n") + if (object@FreeType == 0) {cat(" of", object@NrCells, "random suitable cells/patches.")} + else{cat(" of all suitable cells/patches.")} + } + if (object@InitType == 1) { + cat("Initialisation from loaded species distribution map\n") + if (object@FreeType == 0) {cat(" ", object@NrCells, "random presence cells/patches.")} + else{cat(" all presence cells/patches.")} + } + if (object@InitType == 2) { + if (object@InitIndsFile != "NULL") cat("Initialisation from initial individuals list\n from file:",object@InitIndsFile) + if (length(object@InitIndsList) != 0) cat("Initialisation from initial individuals list given as list of data.frames") + } + cat("\n") + + if (object@InitType != 2) { + cat(" InitDens =", object@InitDens, ": ") + if (object@InitDens == 0) { + cat("At K_or_DensDep \n") + } + if (object@InitDens == 1) { + cat("At half K_or_DensDep \n") + } + if (object@InitDens == 2) { + cat(object@IndsHaCell," individuals per cell/hectare \n") + } + if (length(object@PropStages) > 2) { + cat(" PropStages =", object@PropStages, "\n") + cat(" InitAge =", object@InitAge, " : ") + if (object@InitAge == 0) { cat("Minimum age \n") } + if (object@InitAge == 1) { cat("Random between min and max \n") } + if (object@InitAge == 2) { cat("Quasi-equilibrium \n") } + } + } + if (object@InitType == 0) { + if (object@minX >= 0 || object@minY >= 0 || object@maxX >= 0 || object@maxY >= 0) {cat(" ")} + if (object@minX >= 0) { cat("MinX =",object@minX, " ") } + if (object@maxX >= 0) { cat("MaxX =",object@maxX, " ") } + if (object@minY >= 0) { cat("MinY =",object@minY, " ") } + if (object@maxY >= 0) { cat("MaxY =",object@maxY, " ") } + if (object@minX >= 0 || object@minY >= 0 || object@maxX >= 0 || object@maxY >= 0) {cat("\n")} + if (object@InitFreezeYear > 0) { cat("InitFreezeYear =",object@InitFreezeYear,"\n") } + if (object@RestrictRows > 0) { cat("RestrictRows =",object@RestrictRows,", RestrictFreq =",object@RestrictFreq,"\n") } + if (object@FinalFreezeYear > 0) { cat("FinalFreezeYear =",object@FinalFreezeYear,"\n") } + } + cat("\n")} +) diff --git a/RangeShiftR/R/class_LandParams.R b/RangeShiftR/R/class_LandParams.R new file mode 100644 index 0000000..72e7864 --- /dev/null +++ b/RangeShiftR/R/class_LandParams.R @@ -0,0 +1,966 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#### CLASS LANDPARAMS + +# from RS 'Land' file +# can take one of two forms: 'ArtificialLandscape' or 'ImportedLandscape' + +LandParams <- setClass("LandParams", slots = c(LandNum = "integer_OR_numeric") + , prototype = list(LandNum = 1L) + ) + # landscape number must be unique + +setValidity("LandParams", function(object) { + msg <- NULL + if (anyNA(object@LandNum) || length(object@LandNum)!=1) { + msg <- c(msg, "LandNum must be set and of length 1!") + } + else { + if (object@LandNum < 1) { + msg <- c(msg, "Landscape number must be positive.") + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "LandParams", function(.Object, ...) { + .Object <- callNextMethod() + .Object} +) + + + +### CLASS ARTIFICIALLANDSCAPE + +#' Create an Artificial Landscape +#' +#' An artificial landscape can be generated with a random or fractal spatial structure, and may be using binary or continuous habitat values to characterise each cell. +#' +#' @usage ArtificialLandscape(propSuit = 0.5, K_or_DensDep = 10, Resolution = 100, dimX = 65, dimY = 65, +#' fractal = FALSE, hurst, continuous = FALSE, minPct, maxPct) +#' @param propSuit Proportion of suitable habitat cells, defaults to \eqn{0.5}. +#' @param K_or_DensDep determines the demographic density dependence of the modelled species and is given in units of the number of individuals per hectare (defaults to \eqn{10}). +#' Its precise interpretation depends on the structure of the species' \code{\link[RangeShiftR]{Demography}}:\cr +#' If combined with a \code{\link[RangeShiftR]{StageStructure}}d model, \code{K_or_DensDep} will be used as the \emph{strength of demographic density dependence} \ifelse{html}{\out{b-1}}{\eqn{1/b}}. +#' If combined with a non-structured model, \code{K_or_DensDep} will be interpreted as \emph{limiting carrying capacity} \eqn{K}.\cr +#' @param Resolution Cell size in meters, defaults to \eqn{100}. (integer) +#' @param dimX,dimY Number of cells along the x- and y-axis, both default to \eqn{65}. (integer) \cr +#' If \code{fractal=TRUE}, \code{dimX} and \code{dimY} must be powers of \eqn{2} plus \eqn{1} (\eqn{2^n+1}) and \code{dimX} \eqn{\le} \code{dimY} . +#' @param fractal If \code{FALSE} (default), a random landscape is generated. Each cell has a certain probability of being a habitat.\cr +#' If \code{TRUE}, a fractal landscape is generated. These landscapes contain a greater structure than random landscapes but less than a completely deterministic one. +#' @param hurst Required if \code{fractal=TRUE}: Hurst exponent. Can be any number in the open interval \eqn{(0,1)}. +#' @param continuous Use continuous or binary habitat values to describe each cell?\cr If \code{FALSE} (default), the resulting landscape +#' is binary, with the two values \emph{Habitat} and \emph{Matrix} (i.e. Non-habitat).\cr If \code{TRUE}, each cell is given a continuous value +#' between \eqn{0} and \eqn{1}, which describes the percentage of habitat cover or habitat quality. +#' within a cell. The effective \code{K_or_DensDep} of that cell is calculated as the respective fraction of the value of \eqn{K_or_DensDep}. +#' @param minPct,maxPct Required if \code{continuous=TRUE}: Minimum and Maximum percentage of habitat cover within a cell. Can be any number in the open interval \eqn{(0,1)}, +#' \code{maxPct} may be exactly \eqn{1}. \code{minPct} must be smaller than \code{maxPct}. +#' @details For theoretical studies which might be related to fundamental questions in eco-evolutionary dynamics or strategic questions concerning +#' conservation ecology, it is often desirable to use artificial landscapes.\cr +#' Fractal landscapes are characterised by possessing greater structure than a completely random landscape, but less than a +#' completely deterministic one \insertCite{with1997application}{RangeShiftR} – but note that the spatial structure of landscapes fragmented +#' by human activities is often not fractal in nature and, depending upon the research question, other landscape generators may be more +#' appropriate \insertCite{@see review by @pe2013simple}{RangeShiftR}. +#' +#' Internally generated artificial landscapes may not be dynamic. +#' +#' The fractal landscape generator implemented in \emph{RangeShiftR} uses the midpoint displacemeant algorithm \insertCite{saupe1988algorithms}{RangeShiftR}. +#' The Hurst exponent, often referred to as \eqn{H}, describes the degree of spatial autocorrelation of the landscape configuration. +#' Values close to \eqn{0} represent a low autocorrelation but the generated landscapes still aren't completely spatially independent. +#' On the contrary, values close to \eqn{1} represent high autocorrelation, i.e. high habitat aggregation.\cr +#' +#' Note that more complex algorithms are available for providing fractals where setting \eqn{H = 0.0} results in no spatial autocorrelation +#' \insertCite{@see @chipperfield2011updated}{RangeShiftR}. For applications where the embedded algorithm is not sufficient, we recommend +#' to import landscapes generated by these alternative algorithms. +#' +#' +#' @references +#' \insertAllCited{} +#' @return A parameter object of class "ArtificialLandscape" +#' @author Anne-Kathleen Malchow +#' @name ArtificialLandscape +#' @export ArtificialLandscape +ArtificialLandscape <- setClass("ArtificialLandscape", slots = c(propSuit = "numeric", + K_or_DensDep = "integer_OR_numeric", + Resolution = "integer_OR_numeric", + dimX = "integer_OR_numeric", + dimY = "integer_OR_numeric", + fractal = "logical", + hurst = "numeric", + continuous = "logical", + minPct = "numeric", + maxPct = "numeric") + , prototype = list(propSuit = 0.5, + K_or_DensDep = 10L, + Resolution = 100L, + dimX = 65L, + dimY = 65L, + fractal = FALSE, + #hurst, + continuous = FALSE) + #minPct, + #maxPct, + , contains = "LandParams") + +setValidity("ArtificialLandscape", function(object) { + msg <- NULL + if (anyNA(object@propSuit) || length(object@propSuit)!=1) { + msg <- c(msg, "Proportion of suitable habitat must be set and of length 1!") + } + else { + if (object@propSuit<0 || object@propSuit>1) { + msg <- c(msg, "Proportion of suitable habitat must be in the interval [0,1].") + } + } + if (anyNA(object@K_or_DensDep) || length(object@K_or_DensDep)==0) { + msg <- c(msg, "K_or_DensDep must be set!") + } + else { + if (object@K_or_DensDep<0) { + msg <- c(msg, "K_or_DensDep must not be smaller than 0.") + } + } + if (anyNA(object@Resolution) || length(object@Resolution)!=1) { + msg <- c(msg, "Resolution of landscape must be set and of length 1!") + } + else { + if (object@Resolution < 1) { + msg <- c(msg, "Resolution of landscape must be positive.") + } + } + if (anyNA(object@dimX) || length(object@dimX)!=1) { + msg <- c(msg, "dimX must be set!") + } + if (anyNA(object@dimY) || length(object@dimY)!=1) { + msg <- c(msg, "dimY must be set!") + } + if (anyNA(object@fractal) || length(object@fractal)!=1) { + msg <- c(msg, "fractal must be set!") + } + if (anyNA(object@continuous) || length(object@continuous)!=1) { + msg <- c(msg, "continuous must be set!") + } + if (is.null(msg)) { + if (object@fractal) { + if (object@dimX < 3) { + msg <- c(msg, "Number of cells in any direction must be at least 3 for a fractal landscape.") + } + else { + if (!isPowerOf2(object@dimX-1)) { + msg <- c(msg, "Number of cells in any direction must be a power of 2 plus 1 for a fractal landscape.") + } + } + if (object@dimY < 3) { + msg <- c(msg, "Number of cells in any direction must be at least 3 for a fractal landscape.") + } + else { + if (!isPowerOf2(object@dimY-1)) { + msg <- c(msg, "Number of cells in any direction must be a power of 2 plus 1 for a fractal landscape.") + } + } + if (object@dimY < object@dimX) { + msg <- c(msg, "Y-dimension may not be less than X-dimension for a fractal landscape.") + } + if (anyNA(object@hurst) || length(object@hurst)!=1) { + msg <- c(msg, "Hurst exponent must be set for a fractal landscape.") + } + else { + if (object@hurst<0 || object@hurst>1) { + msg <- c(msg, "Hurst exponent must be in the open interval (0,1).") + } + if (object@hurst==0 || object@hurst==1) { + msg <- c(msg, "Hurst exponent must be in the open interval (0,1). It can't be exactly 0 or 1.") + } + } + } + else { # non-fractal landscape + if (object@dimX < 1) { + msg <- c(msg, "Number of cells in any direction must be at least 1 for a non-fractal landscape.") + } + if (object@dimY < 1) { + msg <- c(msg, "Number of cells in any direction must be at least 1 for a non-fractal landscape.") + } + } + if(object@continuous) { + if (anyNA(object@minPct) || length(object@minPct)!=1) { + minP.ok = FALSE + msg <- c(msg, "Minimum habitat percentage must be set for a continuous landscape.") + } + else { + if (object@minPct<=0 || object@minPct>=1) { + minP.ok = FALSE + msg <- c(msg, "Minimum habitat percentage must be in the open interval (0,1).") + } + else {minP.ok = TRUE} + } + if (anyNA(object@maxPct) || length(object@maxPct)!=1) { + maxP.ok = FALSE + msg <- c(msg, "Maximum habitat percentage must be set for a continuous landscape.") + } + else { + if (object@maxPct<=0 || object@maxPct>1) { + maxP.ok = FALSE + msg <- c(msg, "Maximum habitat percentage must be in the half-open interval (0,1].") + } + else {maxP.ok = TRUE} + } + if (minP.ok && maxP.ok) { + if (object@maxPct <= object@minPct) { + msg <- c(msg, "Maximum habitat percentage may not be less than Minimum habitat percentage.") + } + } + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "ArtificialLandscape", function(.Object,...) { + this_func = "ArtificialLandscape(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (!.Object@fractal) { + .Object@hurst = -9L + if (!is.null(args$hurst)) { + warning(this_func, "Hurst exponent", warn_msg_ignored, "for a non-fractal landscape.", call. = FALSE) + } + } + if(!.Object@continuous) { + .Object@minPct = -9L + if (!is.null(args$minPct)) { + warning(this_func, "Minimum habitat percentage", warn_msg_ignored, "for a discrete landscape.", call. = FALSE) + } + .Object@maxPct = -9L + if (!is.null(args$maxPct)) { + warning(this_func, "Maximum habitat percentage", warn_msg_ignored, "for a discrete landscape.", call. = FALSE) + } + } + .Object} +) +setMethod("show", "ArtificialLandscape", function(object){ + cat(" Artificial landscape: ") + #cat(" Artificial landscape #", object@LandNum, ": ") + if(object@fractal) { + cat("fractal structure, ") + } + else { + cat("random structure, ") + } + if(object@continuous) { + cat("continuous habitat cover/quality\n") + } + else { + cat("binary habitat/matrix code\n") + } + cat (" Size :", paste(object@dimX), "x", paste(object@dimY), "cells\n") + cat (" Resolution : ", paste(object@Resolution) , "meters\n") + cat (" Proportion of suitable habitat:", object@propSuit,"\n") + cat (" K or 1/b :", object@K_or_DensDep,"\n") + if(object@fractal) { + cat (" Hurst exponent : H =", object@hurst, "\n") + } + if(object@continuous) { + cat (" Minimum habitat percentage: minPct =", object@minPct, "\n") + cat (" Maximum habitat percentage: maxPct =", object@maxPct, "\n") + } +}) + + +### CLASS IMPORTEDLANDSCAPE + +#' Import a Landscape from file +#' +#' @description Provide the filename(s) (\code{LandscapeFile}) or the matrices (\code{LandscapeMatrix}) of the map(s) to be imported, their +#' resolution, origin coordinates in case you use matrices and, if applicable, the number of habitat codes (\code{Nhabitats}) +#' as well as their respective demographic density dependence (\code{K_or_DensDep}). +#' +#' For a dynamic landscape, the year in which each landscape is loaded has to be provided. +#' +#' Other, optional input maps are:\cr +#' - Patch map(s) to define habitat patches - as filenames or matrices,\cr +#' - SMS cost map(s) to define landscape resistance to - as filenames or matrices,\cr +#' - a distribution map to define an initial species distribution - as filenames or matrices, \cr +#' - demographic scaling layers - as filenames or matrices. +#' +#' @usage ImportedLandscape(LandscapeFile, +#' LandscapeMatrix, +#' Resolution = 100, +#' OriginCoords = c(0,0), +#' HabPercent = FALSE, +#' Nhabitats, K_or_DensDep = 10, +#' PatchFile = NULL, +#' PatchMatrix = list(), +#' CostsFile = NULL, +#' CostsMatrix = list(), +#' DynamicLandYears = 0, +#' SpDistFile = NULL, +#' SpDistMatrix = list(), +#' SpDistResolution, +#' demogScaleLayersFile, +#' demogScaleLayersMatrix, nrDemogScaleLayers) +#' @param LandscapeFile Filename(s) of the landscape habitat map(s) which shall be imported from the Inputs-folder. See the Details for information on the required format. +#' @param LandscapeMatrix List of matrices of the landscape habitat raster(s); contains each cells' habitat suitability or land cover index. +#' @param Resolution Cell size in meters, defaults to \eqn{100}. (integer) +#' @param OriginCoords X- and Y-coordinates of the map origin given in meters as a vector of length 2. Defaults to \eqn{0,0}. +#' @param HabPercent If \code{FALSE} (default), unique integer habitat codes are expected in the imported map to characterise the habitat of each cell. This requires to set \code{Nhabitats}. \cr +#' If \code{TRUE}, continuous values are expected, ranging from \eqn{0.0} to \eqn{100.0}, that represent percentages of habitat cover or quality.\cr +#' Make sure your imported landscape file uses the specified standard (see Details below). +#' @param Nhabitats Required if \code{HabPercent=FALSE}: Number of habitats in the imported landscape if unique integer habitat codes are used. (integer) +#' @param K_or_DensDep determines the demographic density dependence of the modelled species and is given in units of the number of individuals per hectare (defaults to \eqn{10}). +#' Its precise interpretation depends on the structure of the species' \code{\link[RangeShiftR]{Demography}}:\cr +#' If combined with a \code{\link[RangeShiftR]{StageStructure}}d model, \code{K_or_DensDep} will be used as the \emph{strength of demographic density dependence} \ifelse{html}{\out{b-1}}{\eqn{1/b}}. +#' If combined with a non-structured model, \code{K_or_DensDep} will be interpreted as \emph{limiting carrying capacity} \eqn{K}.\cr +#' The expected format:\cr +#' If \code{HabPercent=FALSE}: a vector of length \code{Nhabitats}, specifying the respective \code{K_or_DensDep} for every habitat code.\cr +#' If \code{HabPercent=TRUE}: \code{K_or_DensDep} is interpreted as the maximum \code{K_or_DensDep} reached in cells with \eqn{100}\% habitat. All other cells hold the respective fraction of \eqn{K_or_DensDep}. +#' @param PatchFile Filename(s) of the patch map(s) which shall be imported, default is \code{NULL}. +#' @param PatchMatrix List of matrices of the patch raster(s); contains each cells' patch index. +#' @param CostsFile Filename(s) of the SMS cost map(s) which shall be imported, default is \code{NULL}. +#' @param CostsMatrix List of matrices of the SMS cost raster(s); contains each cells' SMS cost. +#' @param DynamicLandYears Integer vector indicating the years of landscape changes. For a non-dynamic landscape its only entry is \eqn{0} (default). +#' For a dynamic landscape, \code{DynamicLandYears} lists the years in which the corresponding habitat maps in \code{LandscapeFile} and - if applicable - their respective patch and/or costs +#' maps (in \code{PatchFile},\code{CostsFile}) are loaded and used in the simulation. More details below. +#' @param SpDistFile Filename of the species initial distribution map which shall be imported (*.txt). Default is \code{NULL}. +#' @param SpDistMatrix List of one matrix containing the species' initial distribution raster. +#' @param SpDistResolution Required if \code{SpDistFile} is given: Cell size of the distribution map in meters. (integer) Must be an integer multiple of the landscape resolution. +#' @param demogScaleLayersFile List of vectors with file names of additional landscape layers which can be used to locally scale certain demographic rates and thus allow them to vary spatially. +#' The list must contain equally sized vectors providing file names, one vector for each element in \code{DynamicLandYears}, which are interpreted as stacked layers. +#' The files must match the landscape in resolution and dimension. The size of each vector corresponds to the various layers (of which there are \code{nrDemogScaleLayers}). +#' Can only be used in combination with habitat quality maps, i.e. when \code{HabPercent=TRUE}. It must contain percentage values ranging from \eqn{0.0} to \eqn{100.0}. +#' @param demogScaleLayersMatrix List of arrays that describe additional landscape layers which can be used to locally scale certain demographic rates and thus allow them to vary spatially. +#' The list must contain equally sized 3D-arrays, one for each element in \code{DynamicLandYears}, which are interpreted as stacked layers. +#' The arrays' first two dimensions correspond to the x- and y-dimensions of the maps in \code{LandscapeMatrix} and must match in resolution and offset; +#' the third dimension indexes the various layers (of which there are \code{nrDemogScaleLayers}). +#' Can only be used in combination with habitat quality maps, i.e. when \code{HabPercent=TRUE}. Contain percentage values ranging from \eqn{0.0} to \eqn{100.0}. +#' @param nrDemogScaleLayers number of additional landscape layers for spatial demographic scaling +#' +#' +#' @details \emph{RangeShiftR} requires all landscape related inputs to be either text files in ESRI ASCII raster format or matrices. +#' +#' Text files must have the following six header lines: +#' \tabular{ll}{\code{ncols} \tab Number of columns \cr +#' \code{nrows} \tab Number of rows \cr +#' \code{xllcorner} \tab x-coordinate (longitude) of the lower-left corner \cr +#' \code{yllcorner} \tab y-coordinate (latitude) of the lower-left corner \cr +#' \code{cellsize} \tab Resolution (in meters) \cr +#' \code{NODATA_value} \tab Value for cells having missing data (usually -9999) } +#' +#' The rest of the file is a grid containing a value for each cell, one line per row. +#' +#' If you want to use matrices for landscape inputs, you must provide the origin coordinates \code{OriginCoords}. +#' \code{OriginCoords} is the map origin given as a vector of length 2 where the first entry is the x-coordinate (longitude) of the lower-left corner and +#' the second entry is the y-coordinate (latitude) of the lower-left corner.\cr +#' +#' \code{RangeShiftR} can use two different types of habitat maps:\cr +#' \itemize{ +#' \item \emph{Raster with habitat codes} (\code{HabPercent=FALSE})\cr In this option each habitat or land-cover type has a unique integer code. Each cell in the file contains a single habitat code and \eqn{100} percent coverage is assumed for the cell. The landscape is therefore composed of discrete habitat cells. The codes are required to be sequential integers starting from \eqn{1} and ranging to \code{Nhabitats}.\cr +#' \item \emph{Raster with habitat quality} (\code{HabPercent=TRUE})\cr Each cell in the landscape is assigned a continuous percentage value between \eqn{0.0} and \eqn{100.0} of the maximum \code{K_or_DensDep}. There are no explicit habitat or land-cover types. This allows integrating different methods for calculating the habitat suitability for a given species. For example, qualities can result from +#' different methods of suitability modelling, which incorporate multiple variables like habitat types, elevation, climate, etc. In the current version of the program, a straight-line relationship between the habitat quality and the actual density-dependence of the population dynamics (i.e. \eqn{K} or \eqn{1/b} in a non-structured or structured population, respectively) is assumed. +#' Therefore, the quality should be scaled accordingly in case of a curvilinear relationship. +#' } +#' +#' \emph{Patch map} \cr +#' The simulation can be run as a \emph{patch-based model} on the same habitat map described above. An additional file/matrix must be provided through \code{PatchFile} / \code{PatchMatrix}: a raster map of the same landscape, where +#' each cell contains the ID number of the patch to which it belongs. Each patch must have a unique positive integer ID. The ID of every cell that does not belong to a patch (i.e. non-habitat/matrix) must be zero. +#' Note that a single patch is the unit at which the density dependence in the population dynamics acts. Therefore, a patch can be discontinuous, i.e. it can contain cells that do not belong to the patch if they +#' are assumed not to affect the dynamics, or on the other hand, patch cells that are not physically contiguous to the rest of the patch cells. +#' +#' \emph{Costs layer} \cr +#' Only used if the simulation is run with \code{\link[RangeShiftR]{SMS}} as its transfer module and the landscapes resistance to movement is given via a costs raster map (see argument \code{Costs} in \code{SMS()}). +#' In this case, the specified raster \code{CostsFile} / \code{CostsMatrix} has to match the landscape raster in extent, coordinates and resolution, and each cell contains a cost value, with the minimal possible cost being \eqn{1}. +#' Importing a cost layer is the only option when the landscape comprises habitat coverage or quality. +#' +#' \emph{Initial distribution} \cr +#' A \emph{species distribution map} can be overlaid on top of the habitat map and can be used to define an initial distribution. The map or raster matrix is provided through \code{SpDistFile} / \code{SpDistMatrix} and must be aligned with the landscape map. The extent of the map does not have to be necessarily +#' the same as the landscape. The resolution can be the same or coarser, provided that it is a multiple of the landscape resolution. For example, if the landscape cell size is \eqn{250m}, the species distribution can be at the resolution of \eqn{250m}, \eqn{500m}, \eqn{750m}, \eqn{1000m} etc. +#' Each cell of the species distribution map must contain either \eqn{0} (species absent or not recorded) or \eqn{1} (species present). +#' +#' \emph{Demographic scaling layers} \cr +#' A number of additional landscape layers can be provided in \code{demogScaleLayersMatrix} or \code{demogScaleLayersFiles}, depending on what input type you choose, to locally scale certain demographic rates and thus allow them to vary spatially. +#' This can only be used in combination with habitat quality maps, i.e. when \code{HabPercent=TRUE}, and with a stage-structured population model. +#' The additional layers contain percentage values ranging from \eqn{0.0} to \eqn{100.0}. Chosen demographic rates for a specified stage and sex can be mapped to one of these scaling layers using the +#' parameters \code{FecLayer}, \code{DevLayer}, and \code{SurvLayer} in \code{\link[RangeShiftR]{StageStructure}}. If a demographic rate varies spatially, its value in the transition matrix \code{TransMatrix}) +#' is now interpreted as a maximum value, while the realised local value in each cell or patch is determined as this maximum value scaled by the percentage given in the respective mapped scaling layer. +#' For a patch-based landscape, the scaling percentage of a patch is given by the average percentage of its constituent cells. +#' Potential density-dependence mediated by the strength 1/b still takes effect also for spatially-varying demographic rates. The respective base values φ_0, σ_0 or γ_0 are then replaced by their locally scaled values. +#' +#' \emph{Dynamic landscapes} \cr +#' An imported landscape may be dynamic, i.e. the attributes of cells (either habitat class or quality index) and its patch number (if the model is patch-based) may be changed at specified years during the course of +#' a simulation. Note that any landscape change occurs at the start of the year, i.e. before the first/only reproductive season. In a patch-based model, the shape of patches may change, patches may +#' be removed and new patches may be created where there was previously inter-patch matrix. Thus some populations may be extirpated (in a non-structured population, all individuals die; in a stage-structured population, +#' all individuals either die or have an immediate opportunity to disperse), and new populations may arise from colonisation of newly suitable areas. +#' +#' However, there are certain restrictions. Any part of the original landscape which was a ‘no-data’ region (e.g. the sea or land beyond a study area boundary) must remain in that state for the whole simulation. +#' The identity of patches is not cross-checked between changes, and care must therefore be taken to ensure consistency; otherwise, a patch (and its resident population) can jump to a distant location or be split into +#' two or more disjunct parts, with unpredictable and possibly weird consequences. It is legitimate for a patch to be split into two or more separate patches (e.g. by construction of a motorway or some other barrier), +#' but any existing population will remain with the part (if any) which retains the original patch number, and populations within the other parts (having a new patch number) must arise through colonisation. +#' Possible ways to work around this restriction include: +#' \itemize{ +#' \item Assign to all post-change parts of the original patch a new, unique patch number and specify that dispersal is allowed after population destruction (which is possible only for a structured population), in which +#' case some colonisation of the new patches should occur. Note that the connectivity matrix will be misleading in such cases, as every successful ‘disperser’ will appear to have moved from patch N to patch M (where M +#' is the new patch number). +#' \item Instead of a single original patch, define two (or more) distinct but adjacent patches in the original landscape, so that they each retain their own populations when they become separated by the landscape change. +#' } +#' +#' A dynamic landscape can be specified using the slots \code{LandscapeFile} / \code{LandscapeMatrix} (, \code{PatchFile} / \code{PatchMatrix}, \code{CostsFile}) / \code{CostsMatrix} and \code{DynamicLandYears}. +#' \code{LandscapeFile} (and \code{PatchFile}, \code{CostsFile}) take a character vector with the file names of the maps to be loaded. +#' \code{LandscapeMatrix} (and \code{PatchMatrix}, \code{CostsMatrix}) take a list with the matrices representing the raster maps to be used. +#' +#' Please be aware, that all landscape related input must be either matrices or file names. You cannot mix both types of inputs. +#' +#' All provided maps must agree in resolution, extent and origin. \code{DynamicLandYears} is a number vector that contains the years, in which these landscapes shall be loaded; it must have the same ordering so +#' that years and maps can be matched. If a specific map is used multiple times, it must be listed each time nevertheless. +#' +#' @return A parameter object of class ImportedLandscape +#' @author Anne-Kathleen Malchow, Jette Wolff +#' @name ImportedLandscape +#' @export ImportedLandscape +ImportedLandscape <- setClass("ImportedLandscape", slots = c(LandscapeFile = "character", + LandscapeMatrix = "list", + OriginCoords = "ANY", + Resolution = "integer_OR_numeric", + HabPercent = "logical", + Nhabitats = "integer_OR_numeric", # not used in RS anymore. In R is used to define maxNhab in ControlParams + K_or_DensDep = "integer_OR_numeric", + PatchFile = "ANY", # sets the patchmodel -switch in class ControlParams when added + PatchMatrix = "list", + CostsFile = "ANY", + CostsMatrix = "list", + SpDistFile = "ANY", # sets the speciesdist -switch in class ControlParams when added + SpDistMatrix = "list", + SpDistResolution = "integer_OR_numeric", + DynamicLandYears = "integer_OR_numeric", + nrDemogScaleLayers = "integer_OR_numeric", + demogScaleLayersMatrix = "list", + demogScaleLayersFile = "list") # should be a list of character(=filenames) vectors + , prototype = list(#LandscapeFile, + LandscapeMatrix = list(), + Resolution = 100L, + HabPercent = FALSE, + OriginCoords = NULL, + #Nhabitats, + K_or_DensDep = 10L, + PatchFile = NULL, + PatchMatrix = list(), + CostsFile = NULL, + CostsMatrix = list(), + SpDistFile = NULL, + SpDistMatrix = list(), + #SpDistResolution, + DynamicLandYears = 0L, + nrDemogScaleLayers = 0L, + demogScaleLayersMatrix= list(), + demogScaleLayersFile = list()) #= data.frame()) + , contains = "LandParams") + +setValidity("ImportedLandscape", function(object) { + msg <- NULL + + land_ncol <- 0 + land_nrow <- 0 + if ((anyNA(object@LandscapeFile) || length(object@LandscapeFile)==0) && # No LandscapeFile provided + (anyNA(object@LandscapeMatrix) || length(object@LandscapeMatrix)==0)) { # No Landscape Matrix provided + msg <- c(msg, "No landscape filename nor matrix was given.") + } + else { + if (length(object@LandscapeMatrix) > 0) { # matrix input + if(any(sapply(object@LandscapeMatrix, class)[1,] != "matrix")){ + msg <- c(msg, "All elements of LandscapeMatrix list must be of class matrix.") + } + else{ + land_ncol <- ncol(object@LandscapeMatrix[[1]]) + land_nrow <- nrow(object@LandscapeMatrix[[1]]) + if( (any(sapply(object@LandscapeMatrix, ncol) != land_ncol)) || (any(sapply(object@LandscapeMatrix, nrow) != land_nrow)) ){ + msg <- c(msg, "All elements of LandscapeMatrix list must have the same ncol and nrow.") + } + } + } + } + + if (anyNA(object@Resolution) || length(object@Resolution)!=1) { + msg <- c(msg, "Resolution of landscape must be given and of length 1!") + } + else { + if (object@Resolution < 1) { + msg <- c(msg, "Resolution of landscape must be positive.") + } + } + if (anyNA(object@HabPercent) || length(object@HabPercent)!=1) { + msg <- c(msg, "HabPercent must be set!") + } + if (length(object@LandscapeMatrix) > 0) { + if (!is.numeric(object@OriginCoords) || anyNA(object@OriginCoords) || length(object@OriginCoords)!=2) { + msg <- c(msg, "Origin coordinates must be set and of length 2!") + } else{ + # if ( any(object@OriginCoords < 0) ) { + # msg <- c(msg, "OriginCoords of landscape must be positive.") + # } + } + }else{ + if (!is.null(object@OriginCoords)) { + msg <- c(msg, "OriginCoords must be NULL if you use files as landscape inputs!") + } + } + if (anyNA(object@K_or_DensDep) || length(object@K_or_DensDep)==0) { + msg <- c(msg, "K_or_DensDep must be set!") + } + else { + if (any(object@K_or_DensDep<0)) { + msg <- c(msg, "K_or_DensDep must not be smaller than zero for any habitat type.") + } + } + if (!object@HabPercent) { + if (anyNA(object@Nhabitats) || length(object@Nhabitats)!=1) { + msg <- c(msg, "Number of habitat codes must be given for the imported landscape. If your landscape is specified by a habitat cover percentage, please set \"HabPercent = TRUE\". ") + } + else { + if (object@Nhabitats < 2){ + msg <- c(msg, "Number of habitat codes must be at least 2 when habitat codes are used.") + } + } + } + if (is.null(msg)) { + if (object@HabPercent) { + if (length(object@K_or_DensDep) != 1) { + msg <- c(msg, "K_or_DensDep must be of length 1, specifying the maximum K or 1/b for 100% habitat.") + } + } + else { + if (length(object@K_or_DensDep) != object@Nhabitats) { + msg <- c(msg, "K_or_DensDep must be a vector of length 'Nhabitats', specifying the respective K or 1/b for every habitat code.") + } + } + } + # if LandscapeFile is not NULL (aka given), PatchMatrix must be an empty list and PatchFile must be either + # ALL NULL (cell-based) or has the same length as LandscapeFile (patch-based, potentially dynamic) + if(length(object@LandscapeFile) > 0) { #or is.null(object@LandscapeFile)? + if(length(object@PatchMatrix) > 0) { + msg <- c(msg, "If LandscapeFile is given, you must provide all landscape inputs as files. PatchMatrix must be an empty list!") + } + if(length(object@PatchFile) > 0) { # if patch-based + if (anyNA(object@PatchFile) || length(object@PatchFile)!=length(object@LandscapeFile)) { + msg <- c(msg, "If patch-based, PatchFile must be the same length as LandscapeFile!") + } + } + } else{ # if length(LandscapeFile==0) -> LandscapeMatrix! + if(length(object@PatchFile) > 0) { + msg <- c(msg, "If LandscapeMatrix is given, you must provide all landscape inputs as matrices. PatchFile must be NULL!") + } + if(length(object@PatchMatrix) > 0) { + if (anyNA(object@PatchMatrix) || length(object@PatchMatrix)!=length(object@LandscapeMatrix)) { + msg <- c(msg, "If patch-based, PatchMatrix must be the same length as LandscapeMatrix!") + } + if(any(sapply(object@PatchMatrix, class)[1,] != "matrix")){ + msg <- c(msg, "All elements of the PatchMatrix list must be of class matrix.") + } + else{ + if( (any(sapply(object@PatchMatrix, ncol) != land_ncol)) || (any(sapply(object@PatchMatrix, nrow) != land_nrow)) ){ + msg <- c(msg, "All elements of PatchMatrix list must have the same ncol and nrow as the LandscapeMatrix list") + } + } + } + } + # if LandscapeFile is not NULL (aka given), CostsMatrix must be an empty list and CostsFile must be either + # NULL (no SMS) or has the same length as LandscapeFile (SMS costs, potentially dynamic) + if(length(object@LandscapeFile) > 0) { #or is.null(object@LandscapeFile)? + if(length(object@CostsMatrix) > 0) { + msg <- c(msg, "If LandscapeFile is given, you must provide all landscape inputs as files. CostsMatrix must be an empty list!") + } + if(length(object@CostsFile) > 0) { # if SMS costs are given + if (anyNA(object@CostsFile) || length(object@CostsFile)!=length(object@LandscapeFile)) { + msg <- c(msg, "If SMS costs are given, CostsFile must be the same length as LandscapeFile!") + } + } + } else{ # if length(LandscapeFile==0) -> LandscapeMatrix! + if(length(object@CostsFile) > 0) { + msg <- c(msg, "If LandscapeMatrix is given, you must provide all landscape inputs as matrices. CostsFile must be NULL!") + } + if(length(object@CostsMatrix) > 0) { + if (anyNA(object@CostsMatrix) || length(object@CostsMatrix)!=length(object@LandscapeMatrix)) { + msg <- c(msg, "If SMS costs are given, CostsMatrix must be the same length as LandscapeMatrix!") + } else{ + if(any(sapply(object@CostsMatrix, class)[1,] != "matrix")){ + msg <- c(msg, "All elements of CostsMatrix list must be of class matrix.") + } + else{ + if( (any(sapply(object@CostsMatrix, ncol) != land_ncol)) || (any(sapply(object@CostsMatrix, nrow) != land_nrow)) ){ + msg <- c(msg, "All elements of CostsMatrix list must have the same ncol and nrow as the LandscapeMatrix list") + } + } + } + } + } + + if(length(object@LandscapeFile) > 0) { # File input + if(length(object@SpDistMatrix) > 0) { + msg <- c(msg, "If LandscapeFile is given, you must provide all landscape inputs as files. SpDistMatrix must be an empty list!") + } else{ # SpDistFile can be used + if(!is.null(object@SpDistFile) && length(object@SpDistFile) != 1){ + msg <- c(msg, "Only one Species distribution file may be given.") + } + } + + } else{ # Matrix input + if(length(object@SpDistFile) > 0) { + msg <- c(msg, "If LandscapeMatrix is given, you must provide all landscape inputs as matrices. SpDistFile must be NULL!") + } else{ # SpDistMatrix can be used + if(length(object@SpDistMatrix) > 0){ + if(length(object@SpDistMatrix) != 1){ + msg <- c(msg, "Only one Species distribution matrix may be given.") + } else{ + if( class(object@SpDistMatrix[[1]])[1] != "matrix") { + msg <- c(msg, "Species distribution must be of class matrix.") + } + else{ + coarse <- object@SpDistResolution / object@Resolution + if( (ncol(object@SpDistMatrix[[1]]) != ceiling(land_ncol/coarse)) || (nrow(object@SpDistMatrix[[1]]) != ceiling(land_nrow/coarse)) ){ + msg <- c(msg, "Extent of SpDistMatrix must match that of the LandscapeMatrix.") + } + } + } + } + } + } + + if (!is.null(object@SpDistFile) || length(object@SpDistMatrix)>0) { + if (anyNA(object@SpDistResolution) || length(object@SpDistResolution)!=1) { + msg <- c(msg, "Resolution of Species distribution must be set and of length 1!") + } + else { + if (object@SpDistResolution < 1) { + msg <- c(msg, "Resolution of Species distribution must be positive.") + } + else { + if (object@SpDistResolution < object@Resolution) { + msg <- c(msg, "Resolution of Species distribution may not be less than Landscape Resolution.") + } + else { + if (object@SpDistResolution %% object@Resolution) { + msg <- c(msg, "SpDistResolution must be an integer multiple of Resolution.") + } + } + } + } + } + + if(anyNA(object@DynamicLandYears) || length(object@DynamicLandYears)==0) { + msg <- c(msg, "DynamicLandYears must be set!") + } + else { + if(length(object@LandscapeFile) > 0){ + if(length(object@LandscapeFile) != length(object@DynamicLandYears)){ + msg <- c(msg, "LandscapeFile and DynamicLandYears must have the same number of entries!") + } + else{ + if(object@DynamicLandYears[1] != 0){ + msg <- c(msg, "The first entry of DynamicLandYears must be 0!") + } + else{ + if(!all(sort(object@DynamicLandYears) == object@DynamicLandYears)){ + msg <- c(msg, "DynamicLandYears must contain subsequent years!") + } + } + } + } else { + if(length(object@LandscapeMatrix) != length(object@DynamicLandYears)){ + msg <- c(msg, "LandscapeMatrix and DynamicLandYears must have the same number of entries!") + } + else{ + if(object@DynamicLandYears[1] != 0){ + msg <- c(msg, "The first entry of DynamicLandYears must be 0!") + } + else{ + if(!all(sort(object@DynamicLandYears) == object@DynamicLandYears)){ + msg <- c(msg, "DynamicLandYears must contain subsequent years!") + } + } + } + + } + } + + # demographic spatial variation + # only valid for LandscapeMatrix and HabPercent=TRUE + if(object@HabPercent){ + if(length(object@nrDemogScaleLayers) != 1){ + msg <- c(msg, "nrDemogScaleLayers must be of length 1.") + } + else { + if( object@nrDemogScaleLayers < 0){ + msg <- c(msg, "nrDemogScaleLayers must be positive.") + } + else { + if (length(object@demogScaleLayersMatrix) > 0){ # scaling layers are given + # for matrix input: + if(length(object@LandscapeFile) > 0) { # File input + # demogScaleLayersMatrix should be NULL (not provided) + if(length(object@demogScaleLayersMatrix) > 0){ + msg <- c(msg, "If LandscapeFile is given, you must provide all landscape inputs including the demographic scaling layers as files. demogScaleLayersMatrix must be an empty list!") + } + else { + # but demogScaleLayersFile must be a list of character vectors + if(length(object@demogScaleLayersFile) == 0 || anyNA(object@demogScaleLayersFile) || !is.list(object@demogScaleLayersFile)){ + msg <- c(msg, "demogScaleLayersFile must be a list of character vectors with file names of the demographic scaling layers.") + } + else{ + if(length(object@demogScaleLayersFile) != length(object@DynamicLandYears)){ + msg <- c(msg, "demogScaleLayersFile must be a list that contains a vector of file names for each element in DynamicLandYears.") + } + else{ + if( any(sapply(object@demogScaleLayersFile, class) != "character") ){ + msg <- c(msg, "All elements of demogScaleLayersFile must be character vectors.") + } + else{ + if( any(sapply(object@demogScaleLayersFile, length) != object@nrDemogScaleLayers) ){ + msg <- c(msg, "Each element of demogScaleLayersFile must contain a vector with the same number of entries as nrDemogScaleLayers.") + } + } + } + } + } + } else { # Matrix input + # demogScaleLayersFile should be NULL (not provided) + if(!is.null(object@demogScaleLayersFile) && length(object@demogScaleLayersFile) > 0){ + msg <- c(msg, "If LandscapeMatrix is given, you must provide all landscape inputs including the demographic scaling layers as matrices. demogScaleLayersFile must be NULL!") + } + else { + if( any( sapply(object@demogScaleLayersMatrix, class) != "array")){ + msg <- c(msg, "demogScaleLayersMatrix must be a list of arrays.") + } + else{ + if( length(object@demogScaleLayersMatrix) != length(object@DynamicLandYears) ){ + msg <- c(msg, "demogScaleLayersMatrix must be a list that contains an array for each element in DynamicLandYears.") + } + else{ + ds_dims <- sapply(object@demogScaleLayersMatrix, dim) # (size of dimensions per array) + if( !"matrix" %in% class(ds_dims) ){ + msg <- c(msg, "the arrays in demogScaleLayersMatrix must have the same dimensionality.") + } + else{ + if( dim(ds_dims)[1] != 3 ){ + msg <- c(msg, "demogScaleLayersMatrix must be a list that contains 3-dimensional arrays.") + } + else{ + if( !all(apply(ds_dims, 2, function(col) identical(col, ds_dims[,1]))) ){ + msg <- c(msg, "all arrays in demogScaleLayersMatrix must have the same size.") + } + else{ + if( object@nrDemogScaleLayers > 0 && ds_dims[3,1] != object@nrDemogScaleLayers ){ + msg <- c(msg, "nrDemogScaleLayers must give the number of layers contained in each element (array) of demogScaleLayersMatrix.") + } + else{ + if( ds_dims[1,1] != land_nrow || ds_dims[2,1] != land_ncol ){ + msg <- c(msg, "All elements of demogScaleLayersMatrix list must have the same ncol and nrow as the LandscapeFile list") + } + else{ + ds_vals <- c(unlist(object@demogScaleLayersMatrix)) + ds_vals <- ds_vals[!is.na(ds_vals)] + if( any( ds_vals < 0) || any( ds_vals > 100 ) ){ + msg <- c(msg, "All elements of the arrays in demogScaleLayersMatrix must be values between 0 and 100.") + } + } + } + } + } + } + } + } + } + + } + } + } + } + } else{ + if(length(object@demogScaleLayersMatrix) > 0 || length(object@demogScaleLayersFile) > 0 || object@nrDemogScaleLayers > 0){ + msg <- c(msg, "Demographic scaling layers can only be used with habitat quality maps (HabPercent=TRUE).") + } + } + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "ImportedLandscape", function(.Object, ...) { + this_func = "ImportedLandscape(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if (.Object@HabPercent) { + .Object@Nhabitats = 1L + if (!is.null(args$Nhabitats)) { + warning(this_func, "Nhabitats", warn_msg_ignored, "for continuous habitat percentage landscape.", call. = FALSE) + } + } + if (is.null(.Object@SpDistFile) && length(.Object@SpDistMatrix) == 0) { + .Object@SpDistResolution = -9 + if (!is.null(args$SpDistResolution)) { + warning(this_func, "Resolution of Species distribution", warn_msg_ignored, "since no map file is given.", call. = FALSE) + } + } + if (.Object@HabPercent && (length(.Object@LandscapeMatrix) > 0 || length(.Object@LandscapeFile) > 0)) { + if (is.null(args$nrDemogScaleLayers)) { + if (length(.Object@demogScaleLayersMatrix) > 0) { + .Object@nrDemogScaleLayers = dim(.Object@demogScaleLayersMatrix[[1]])[3] + } + else { + if (length(.Object@demogScaleLayersFile) > 0) { + .Object@nrDemogScaleLayers = length(.Object@demogScaleLayersFile[[1]]) + } + } + } + else { + if (length(.Object@demogScaleLayersMatrix) == 0 && length(.Object@demogScaleLayersFile) == 0) { + warning(this_func, "nrDemogScaleLayers", warn_msg_ignored, "since no demogScaleLayersMatrix or demogScaleLayersFile maps are given.", call. = FALSE) + } + } + } + else { + if ( (!is.null(args$demogScaleLayersMatrix) && !is.null(args$demogScaleLayersFile)) | !is.null(args$nrDemogScaleLayers)) { + warning(this_func, "demogScaleLayersMatrix", warn_msg_ignored, "since they can only be used in combination with habitat quality maps and landscape matrices as inputs.", call. = FALSE) + } + } + .Object} +) +setMethod("show", "ImportedLandscape", function(object){ + cat(" Landscape imported from file") + if(length(object@DynamicLandYears)==1) { + if(!is.null(object@LandscapeFile)) cat(":\n ", paste(object@LandscapeFile)) + else cat(":\n used a landscape matrix") + } + cat("\n") + if(object@HabPercent) { + cat(" with continuous habitat percentages,\n") + cat(" at 100%: K or 1/b =", paste(object@K_or_DensDep), "[inds per ha].\n") + } + else { + cat(" with", paste(object@Nhabitats), "unique integer habitat code(s)\n") + cat(" K or 1/b : ", paste(object@K_or_DensDep), "[inds per ha].\n") + } + if (!is.null(object@PatchFile[1])) { + cat(" Patches imported from file \n") + if(length(object@DynamicLandYears)==1) { + cat(paste(object@PatchFile),"\n") + } + } + if(length(object@PatchMatrix)>0) { + cat(" Patches imported from matrix\n") + } + if (!is.null(object@CostsFile[1])) { + cat(" SMS costs imported from file \n") + if(length(object@DynamicLandYears)==1) { + cat(paste(object@CostsFile),"\n") + } + } + if(length(object@CostsMatrix)>0) { + cat(" SMS costs imported from matrix\n") + } + cat (" Resolution :", paste(object@Resolution),"\n") + if(length(object@DynamicLandYears)>1) { + if(!is.null(object@LandscapeFile)){ + if (is.null(object@PatchFile[1])) { + if (is.null(object@CostsFile[1])) { + cat(" Land changes in\n Year to Habitat file:\n") + } + else { + cat(" Land changes in\n Year to Habitat file Costs file:\n") + } + } + else { + if (is.null(object@CostsFile[1])) { + cat(" Land changes in\n Year to Habitat file Patch file:\n") + } + else { + cat(" Land changes in\n Year to Habitat file Patch file Costs file:\n") + } + } + } + else { + if (length(object@PatchMatrix)>0) { + if (length(object@CostsMatrix)>0) { + cat(" Land changes in\n Year to Habitat matrix, patch matrix and costs matrix:\n") + } + else { + cat(" Land changes in\n Year to Habitat matrix and patch matrix:\n") + } + } + else { + if (length(object@CostsMatrix)>0) { + cat(" Land changes in\n Year to Habitat matrix and costs matrix:\n") + } + else { + cat(" Land changes in\n Year to Habitat matrix:\n") + } + } + } + + for (a in 1:length(object@DynamicLandYears)) { + if(!is.null(object@LandscapeFile)){ + if (is.null(object@PatchFile[1])) { + if (is.null(object@CostsFile[1])) { + cat(" ",paste(object@DynamicLandYears[a])," ",paste(object@LandscapeFile[a]),"\n") + } + else { + cat(" ",paste(object@DynamicLandYears[a])," ",paste(object@LandscapeFile[a])," ",paste(object@CostsFile[a]),"\n") + } + } + else { + if (is.null(object@CostsFile[1] )) { + cat(" ",paste(object@DynamicLandYears[a])," ",paste(object@LandscapeFile[a])," ",paste(object@PatchFile[a]),"\n") + } + else { + cat(" ",paste(object@DynamicLandYears[a])," ",paste(object@LandscapeFile[a])," ",paste(object@PatchFile[a])," ",paste(object@CostsFile[a]),"\n") + } + } + } + else { + cat(" ", paste(object@DynamicLandYears[a]), "\n") + } + + } + } + if(!is.null(object@SpDistFile)) { + cat(" Initial Species Distribution imported from file:\n ", paste(object@SpDistFile), "\n") + cat (" Resolution :", paste(object@SpDistResolution),"\n") + } + if(length(object@SpDistMatrix)>0) { + cat(" Initial Species Distribution imported from matrix\n") + } + #cat ("\n") + } +) + + +### Helper functions + +## Check if a number is a power of 2 +isPowerOf2 <- function(x) { + n1s <- sum(as.numeric(intToBits(x))) + if (n1s == 1) { + return(TRUE) + } else { + return(FALSE) + } +} + +# RS manual 3.1.1 (page 51) - 3.1.2 (page 54) diff --git a/RangeShiftR/R/class_ManagementParams.R b/RangeShiftR/R/class_ManagementParams.R new file mode 100644 index 0000000..fbed823 --- /dev/null +++ b/RangeShiftR/R/class_ManagementParams.R @@ -0,0 +1,237 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2024 Jette Wolff, Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + +# Subclass holding the 'Translocation 'parameter + +#' Translocation Parameters +#' +#' Translocation is a conservation management strategy to reintroduce species in areas where they have been extirpated, +#' stabilize metapopulations or enhance (genetic) connectivity between fragmented habitats. +#' Translocations aim to increase the survival probabilities of species, boost genetic diversity, +#' and restore ecological balance. Success depends on careful selection of suitable source and destination sites, as well as +#' appropriate selection of individuals to be relocated. +#' +#' @usage Translocation(years = 1, +#' TransLocMat = 0, +#' catching_rate = 0.5 +#' ) +#' +#' @param years Vector of years in which translocation events should take place +#' @param TransLocMat Matrix of translocation events. Each row represents a translocation event. Columns represent: +#' +#' - the year of the event,\cr +#' - the source location (\code{Patch_ID} in case of cell-based models or \code{X} and \code{Y} location in case of cell-based models),\cr +#' - the destination location (\code{Patch_ID} in case of cell-based models or \code{X} and \code{Y} location in case of cell-based models),\cr +#' - the number of individuals which are tried to be caught,\cr +#' - minimal age of each individual,\cr +#' - maximal age of the individual,\cr +#' - stage of the individual,\cr +#' - sex of the individual\cr +#' @param catching_rate Catching success rate +#' +#' @details +#' +#' \strong{General information} +#' +#' This function translocates a specified number of individuals with given characteristics from a source site +#' to a destination site in a specified year representing a translocation event. +#' In other words, a translocation event is defined by a unique combination of the year, source and +#' destination site, and the number and characteristics of selected individuals. +#' +#' You must set at least one translocation event, but there is no upper limit. Multiple translocation events can occur +#' per year (differing in either the characteristics of the individuals selected or +#' the source and destination sites), or across different years. +#' +#' Individuals can be selected according to their age, stage and sex, depending on the type of demographic model applied. +#' Only individuals which are currently not in the transfer phase are eligible for translocation. +#' After being translocated, individuals are assumed to not disperse further. +#' +#' Additionally, you can define a constant catching success rate to determine the likelihood of successfully capturing a selected individual. +#' +#' \strong{Setting translocation parameters} +#' +#' You need to create a Translocation Matrix \code{TransLocMat} which hold the information for each translocation event in each row. +#' +#' In the columns of the \code{TransLocMat} the year, source and destination site as well as the number of individuals and the characteristics are +#' defined in the following order: +#' +#' - \code{year} of the translocation event \cr +#' - \code{Patch_ID} or \code{X} and \code{Y} location of the source site from which individuals are caught. \cr +#' - \code{Patch_ID} or \code{X} and \code{Y} location of the destintation site to which individuals are relocated. \cr +#' - \code{nb_catch} how many individuals of the given set of characteristics are tried to be caught \cr +#' - \code{min_age} minimal age of the individual in the interval of 0-MaxAge. Set to -9 to ignore. \cr +#' - \code{max_age} maximal age of the individual in the interval of \code{min_age}-MaxAge. Set to -9 to ignore.\cr +#' - \code{stage} of the individual. Set to -9 to ignore. \cr +#' - \code{sex} of the individual: Only for sexual models, otherwise set to -9 to ignore \cr +#' +#' \code{min_age}, \code{max_age} and \code{stage} can only be defined for stage structured models. +#' For non stage structured models, or to ignore the characteristic, set the value to -9. +#' +#' \code{sex} can only be defined for sexual models. For non sexual models, or to ignore the characteristic, set the value to -9. +#' +#' To avoid unsuccessful translocation events, you should set the range of allowed characteristics as broad as possible. +#' +#' Each row of the translocation matrix \code{TransLocMat} should hold a unique combination of a source and a destination location, +#' the number of individuals to catch as well as characteristics of these individuals. +#' You may add more than one translocation event per year, i.e. there may be multiple source and destination sites for each year of a translocation +#' event or multiple individual characteristics for a certain pair of source and destination site. +#' +#' In each \code{year} of a translocation event, individuals matching the given criteria in the source site are collected and a given number of individuals \code{nb_catch} +#' are sampled from this subset. The success of catching one of these sampled individuals in the source location is defined by the \code{catching_rate}. +#' Successfully caught individuals are then translocated to the destination site and the individual will be assigned the status 10 (translocated) and will not further disperse. +#' +#' The source as well as the destination sites are required to be habitat patches or cells of the landscape. Otherwise the translocation event will be skipped. +#' +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "ManagementParams" +#' @author Jette Wolff +#' @name Translocation +#' @export Translocation +Translocation <- setClass("TranslocationParams", slots = c(years = "numeric", + TransLocMat = "matrix", + catching_rate = "numeric") + , prototype = list(years = -9L, + TransLocMat = matrix(0, nrow = 8, ncol = 8), + catching_rate = 1L + ) +) + +setValidity("TranslocationParams", function(object) { + msg <- NULL + # Check if years is not NA, has at least one entry and is either a numeric or integer + if (any(is.na(object@years)) || length(object@years)==0) { + msg <- c(msg, "Years must be defined") + }else{ + if (!is.integer(object@years) && !is.numeric(object@years)) { + msg <- c(msg, "Years must be numeric or integer") + } + } + + # Check if TransLocMat is not NA, is a matrix and has at least as many rows and years + if (any(is.na(object@TransLocMat)) && !is.matrix(object@TransLocMat)){ + msg <- c(msg, "TransLocMat must be defined and be a matrix") + }else { + if(nrow(object@TransLocMat) < length(object@years)) { + msg <- c(msg, "TransLocMat must have at least as many rows as years of Transclocation events") + } else { + if(!all(sort(object@TransLocMat[,1]) == object@TransLocMat[,1])){ + msg <- c(msg, "Translocation matrix must contain subsequent years!") + } else{ + if (ncol(object@TransLocMat) != 8 && ncol(object@TransLocMat) != 10) { # 8 is only true for patch-based models; for cell based models it should be 10 + msg <- c(msg, "TransLocMat must have 8 or 10 columns: year, source location (patch ID OR 2 columns X and Y), target location (patch ID OR 2 columns X and Y), number of individuals, min age, max age, stage.") + } + } + # check if unique values of first column of TransLocMat are equal to years + if (!all(unique(object@TransLocMat[,1]) %in% object@years)) { + msg <- c(msg, "You must provide define at least one translocation event for each year of translocation.") + } + } + } + + # Check if catching_rate is not NA and is a numeric + if (is.na(object@catching_rate)) { + msg <- c(msg, "Catching rate must be defined") + }else{ + if (!is.numeric(object@catching_rate)) { + msg <- c(msg, "Catching rate must be numeric") + } + } + + if (is.null(msg)) TRUE else msg} +) + +setMethod("initialize", "TranslocationParams", function(.Object,...) { + this_func = "Translocation(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object} +) + + +setMethod("show", "TranslocationParams", function(object){ + cat(" Translocation:\n") + cat(" Years of translocation events: ", object@years, "\n") + cat(" Catching rate: ", object@catching_rate, "\n") + cat(" Translocation Matrix: \n") + print(object@TransLocMat) +}) + + + +#### MANAGEMENT #### + +# define this ClassUnion so that the 'Translocation' slot in the parameter master class 'RSparams' can be FALSE for not considering translocations +setClassUnion("TranslocationSlot", c("logical", "TranslocationParams")) + +# Superclass holding the subclasses 'Translocation', but eventually also 'Hunting' and 'Poaching' + +#' Management Parameters +#' +#' With this function you can set all management strategies you wish to apply to your simulations. +#' This function includes for now only the translocation of individuals (see details below). +#' +#' @usage Management(Translocation = Translocation()) +#' +#' @param Translocation Set translocation events. See \code{\link{Translocation}} for more details. +#' +#' @details +#' +#' \strong{Translocation} +#' +#' Translocation is a conservation management strategy to reintroduce species in areas where they have been extirpated, +#' stabilize metapopulations or enhance (genetic) connectivity between fragmented habitats. Translocations are applied +#' to increase survival probabilities of species, increase genetic diversity or restore ecological balance.The selection of +#' suitable source and destination sites as well as selection of suitable individuals is crucial for the success of the strategy. +#' +#' +#' @references +#' \insertAllCited{} +#' @return a parameter object of class "ManagementParams" +#' @author Jette Wolff +#' @name Management +#' @export Management +Management <- setClass("ManagementParams", slots = c(Translocation = "TranslocationSlot") + , prototype = list(Translocation = FALSE) +) + +setValidity("ManagementParams", function(object) { + msg <- NULL + validObject(object@Translocation) + if (is.null(msg)) TRUE else msg} +) +setMethod("initialize", "ManagementParams", function(.Object,...) { + this_func = "Management(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + .Object} +) +setMethod("show", "ManagementParams", function(object){ + cat(" Management: \n ") + print(object@Translocation) +}) + diff --git a/RangeShiftR/R/class_RSparams.R b/RangeShiftR/R/class_RSparams.R new file mode 100644 index 0000000..f01f5d3 --- /dev/null +++ b/RangeShiftR/R/class_RSparams.R @@ -0,0 +1,1126 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#### PARAMETER MASTER CLASS #### + +#' @include class_ControlParams.R +#' @include class_SimulationParams.R +#' @include class_LandParams.R +#' @include class_DemogParams.R +#' @include class_DispersalParams.R +#' @include class_GeneticsParams.R +#' @include class_InitialisationParams.R +#' @include class_ManagementParams.R +RSparams <- setClass("RSparams", slots = c(control = "ControlParams", + simul = "SimulationParams", + land = "LandParams", + demog = "DemogParams", + dispersal = "DispersalParams", + gene = "GeneticsParams", + management = "ManagementParams", + init = "InitialisationParams") +) +setValidity("RSparams", function(object) { + msg <- NULL + #CONTROL + validObject(object@control) + #SIMULATION + validObject(object@simul) + if (object@control@patchmodel) { + if (object@simul@Gradient) { + msg <- c(msg, "Environmental gradients are not implemented for patch-based models!") + } + if (object@simul@LocalExt) { + msg <- c(msg, "Local extinction is not implemented for patch-based models!") + } + if (object@simul@EnvStoch==2) { + msg <- c(msg, "Local environmental stochasticity (EnvStoch=2) is not implemented for patch-based models!") + } + if (object@simul@OutIntTraitRow) { # or rather both: (object@simul@OutIntTraitCell || object@simul@OutIntTraitRow) ??? + msg <- c(msg, "Traits output by row is only applicable for a cell-based model!") + } + } + else { + if (object@simul@OutIntConn) { + msg <- c(msg, " Connectivity output is only applicable for a patch-based model!") + } + } + if (object@simul@EnvStochType==1) { + if (object@control@landtype==0 || object@control@landtype==2) { + msg <- c(msg, "Environmental stochasticity in carrying capacity (EnvStochType=1) is implemented for artificial landscapes only!") + } + } + if (object@simul@OutIntTraitCell || object@simul@OutIntTraitRow) { + if (!object@dispersal@Emigration@IndVar && !object@dispersal@Transfer@IndVar && !object@dispersal@Settlement@IndVar) { + msg <- c(msg, "Traits output is only applicable for a model with inter-individual variability in (at least one) dispersal trait(s)!") + } + } + if (class(object@dispersal@Transfer)[1] != "StochMove"){ + if (object@simul@OutIntPaths) { + msg <- c(msg, "SMS paths output is only applicable for a model with the SMS transfer method!") + } + if (object@simul@SMSHeatMap){ + msg <- c(msg, "SMS heat map output is only applicable for a model with the SMS transfer method!") + } + } + #LAND + validObject(object@land) + if (any(object@control@landtype==c(0,2))){ + if (any(object@land@DynamicLandYears>object@simul@Years)) { + warning("ImportedLandscape(): Dynamic landscape contains years that exceed the simulated years, so that some land changes will not apply.", call. = FALSE) + } + if (!is.null(object@land@CostsFile[1]) || length(object@land@CostsMatrix)>0) { # for threadsafe: length(object@land@CostsFile)>0 + if (class(object@dispersal@Transfer)[1] == "StochMove") { + if (!(object@dispersal@Transfer@Costs[1] %in% c("file", "matrix"))) { + warning("ImportedLandscape(): Landscape module contains SMS cost layers, but SMS module does not use them.", call. = FALSE) + } + } + else{ + warning("ImportedLandscape(): Landscape module contains SMS cost layers, but Transfer module does not use SMS().", call. = FALSE) + } + } + } + #DEMOGRAPHY + validObject(object@demog) + if (object@control@landtype == 2L){ # habitat quality + varydemogixs <- (length(object@demog@StageStruct@FecLayer)+length(object@demog@StageStruct@DevLayer)+length(object@demog@StageStruct@SurvLayer)>0) + varydemoglyr <- (length(object@land@demogScaleLayersMatrix)>0 || length(object@land@demogScaleLayersFile)>0) + if(varydemogixs & !varydemoglyr){ + msg <- c(msg, "RSsim(): If FecLayer, DevLayer and/or SurvLayer are used, the demographic scaling layers must be given in ImportedLandscape.") + } + if(varydemoglyr & !varydemogixs){ + msg <- c(msg, "RSsim(): If deographic scaling layers are given, the demographic rates they correspond to must be defined with FecLayer, DevLayer and/or SurvLayer in StageStructure().") + } + if(varydemoglyr & varydemogixs){ + if ((length(object@demog@StageStruct@FecLayer) + length(object@demog@StageStruct@DevLayer) + length(object@demog@StageStruct@SurvLayer)) > 0 ){ # spatially varying demographic rates + ixs <- c(object@demog@StageStruct@FecLayer,object@demog@StageStruct@DevLayer,object@demog@StageStruct@SurvLayer) + ixs[is.na(ixs)] <- -9 + if ( any( ixs > object@land@nrDemogScaleLayers )){ + msg <- c(msg, "StageStructure(): Entries of FecLayer, DevLayer and SurvLayer must not exceed the number of layers in demogScaleLayers (of ImportedLandscape) !") + } + } + } + } + + #DISPERSAL + validObject(object@dispersal) + ## Emigration: check dimensions and values of EmigProb and EmigStage: + # check StageDep and SexDep but only if IndVar is false + dim_ok = TRUE + if (!object@dispersal@Emigration@IndVar){ + if (object@dispersal@Emigration@StageDep) { + if (object@control@stagestruct) { + rows = object@control@stages + offset = 1 + if (object@dispersal@Emigration@IndVar) { + if (anyNA(object@dispersal@Emigration@EmigStage) || length(object@dispersal@Emigration@EmigStage)!=1) { + msg <- c(msg, "Emigration(): EmigStage (exactly 1) must be set!") + } + else { + if (object@dispersal@Emigration@EmigStage<0 || object@dispersal@Emigration@EmigStage>rows) { + msg <- c(msg, "Emigration(): EmigStage must be within [0, #stages]!") + } + } + } + } + else { + dim_ok = FALSE + msg <- c(msg, "Emigration can only be stage-dependent in a stage-structured model (StageStruct = StageStructure()) !") + } + } + else { + rows = 1 + offset = 0 + } + if (object@dispersal@Emigration@SexDep) { + if (object@control@reproductn) { + rows = 2*rows + offset = 1+offset + } + else { + dim_ok = FALSE + msg <- c(msg, "Emigration can only be sex-dependent in a sexually explicit model (ReproductionType = {1,2}) !") + } + } + # check dimensions of EmigProb + if (dim_ok) { + if (object@dispersal@Emigration@DensDep) { + cols = 3 + } + else { + cols = 1 + } + if (object@dispersal@Emigration@IndVar) { + cols = 1 + rows = 1 + offset = 0 + } + if (dim(object@dispersal@Emigration@EmigProb)[1]!=rows) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of emigration probability traits (EmigProb) must have ", rows ," rows (with the current settings)!")) + } + if (dim(object@dispersal@Emigration@EmigProb)[2]!=(offset+cols)) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of emigration probability traits (EmigProb) must have ", (offset+cols) ," columns (with the current settings)!")) + } + } + if (dim_ok) { + # check stage column of EmigProb + if (object@dispersal@Emigration@StageDep) { + if(any(object@dispersal@Emigration@EmigProb[,1]%%1!=0)){ + msg <- c(msg, "First column of emigration probability traits matrix (EmigProb) must contain the stage numbers (but non-integer number(s) found)!") + } + else { + if(any(object@dispersal@Emigration@EmigProb[,1]<0 | object@dispersal@Emigration@EmigProb[,1]>object@control@stages)){ + msg <- c(msg, "First column of emigration probability traits matrix (EmigProb) must contain the stage numbers (found <0 or >#stages)!") + } + else{ + if(length(unique(object@dispersal@Emigration@EmigProb[,1])) != object@control@stages){ + msg <- c(msg, "First column of emigration probability traits matrix (EmigProb) must contain the stage numbers (but found incorrect stage numbers)!") + } + } + } + } + # check sex column of EmigProb + if (object@dispersal@Emigration@SexDep) { + if(any( !object@dispersal@Emigration@EmigProb[,offset] %in% c(0,1) )){ + msg <- c(msg, paste0(offset,". column of emigration probability traits matrix (EmigProb) must contain the sex numbers (0 for female, 1 for male)!")) + } + else { + if (object@dispersal@Emigration@StageDep) { + comb_ok = TRUE + for(i in 0:(object@control@stages-1)) { + if (length(unique(object@dispersal@Emigration@EmigProb[object@dispersal@Emigration@EmigProb[,1]==i, offset])) != 2) { + comb_ok = FALSE + } + } + if (!comb_ok) { + dim_ok = FALSE + msg <- c(msg, "The emigration probability traits matrix (EmigProb) must contain exactly one row for each stage (1. column) and sex (2. column) combination!") + } + } + else { + if (length(unique(object@dispersal@Emigration@EmigProb[, offset])) != 2) { + dim_ok = FALSE + msg <- c(msg, "The emigration probability traits matrix (EmigProb) must contain exactly one row for each sex (1. column)!") + } + } + } + } + } + } + + if (dim_ok) { + # check value columns of EmigProb + if (!object@dispersal@Emigration@IndVar) { + if (object@dispersal@Emigration@DensDep) { + if(any(object@dispersal@Emigration@EmigProb[,(offset+1)]<0 | object@dispersal@Emigration@EmigProb[,(offset+1)]>1)){ + msg <- c(msg, paste0("Column ", (offset+1), " of emigration traits matrix (EmigProb) must contain the maximum emigration probability D0, with values in the closed inerval [0,1] !")) + } + #// NB alpha and beta may take any value + } + else { + if(any(object@dispersal@Emigration@EmigProb[,(offset+1)]<0 | object@dispersal@Emigration@EmigProb[,(offset+1)]>1)){ + msg <- c(msg, paste0("Column ", (offset+1), " of emigration traits matrix (EmigProb) must contain the constant emigration probability d, with values in the closed inerval [0,1] !")) + } + } + } + } + ## Transfer / DispersalKernel: + # check StageDep and SexDep + dim_ok = TRUE + if (class(object@dispersal@Transfer)[1] == "DispersalKernel") { + if (object@control@transfer != 0) { + msg <- c(msg, "DispersalKernel(): Something went wrong adding a DispersalKernel to the Parameter Master!") + } + else { + if (object@dispersal@Transfer@StageDep) { + if (object@control@stagestruct) { + rows = object@control@stages + offset = 1 + } + else { + dim_ok = FALSE + msg <- c(msg, "Transfer (DispersalKernel) can only be stage-dependent in a stage-structured model (use Demography(StageStruct = StageStructure()) ) !") + } + } + else { + rows = 1 + offset = 0 + } + if (object@dispersal@Transfer@SexDep) { + if (object@control@reproductn) { + rows = 2*rows + offset = 1+offset + } + else { + dim_ok = FALSE + msg <- c(msg, "Transfer (DispersalKernel) can only be sex-dependent in a sexually explicit model (ReproductionType = {1,2}) !") + } + } + if (dim_ok) { + if (object@dispersal@Transfer@DoubleKernel) { + cols = 3 + } + else { + cols = 1 + } + if (!object@dispersal@Transfer@IndVar) { + if (dim(object@dispersal@Transfer@Distances)[1]!=rows) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of dispersal kernel traits (Distances) must have ", rows ," rows (with the current settings)!")) + } + if (dim(object@dispersal@Transfer@Distances)[2]!=(offset+cols)) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of dispersal kernel traits (Distances) must have ", (offset+cols) ," columns (with the current settings)!")) + } + } + } + if(!object@dispersal@Transfer@IndVar){ + if (dim_ok) { + # check stage column of Distances matrix + if (object@dispersal@Transfer@StageDep) { + if(any(object@dispersal@Transfer@Distances[,1]%%1!=0)){ + msg <- c(msg, "First column of dispersal kernel traits (Distances) matrix must contain the stage numbers (but non-integer number(s) found)!") + } + else { + if(any(object@dispersal@Transfer@Distances[,1]<0 | object@dispersal@Transfer@Distances[,1]>object@control@stages)){ + msg <- c(msg, "First column of dispersal kernel traits (Distances) matrix must contain the stage numbers (found <0 or >#stages)!") + } + else{ + if(length(unique(object@dispersal@Transfer@Distances[,1])) != object@control@stages){ + msg <- c(msg, "First column of dispersal kernel traits (Distances) matrix must contain the stage numbers (but found incorrect stage numbers)!") + } + } + } + } + if (object@dispersal@Transfer@SexDep) { + # check sex column of Distances matrix + if(any( !object@dispersal@Transfer@Distances[,offset] %in% c(0,1) )){ + msg <- c(msg, paste0(offset,". column of dispersal kernel traits (Distances) matrix must contain the sex numbers (0 for female, 1 for male)!")) + } + else { + if (object@dispersal@Transfer@StageDep) { + comb_ok = TRUE + for(i in 0:(object@control@stages-1)) { + if (length(unique(object@dispersal@Transfer@Distances[object@dispersal@Transfer@Distances[,1]==i, offset])) != 2) { + comb_ok = FALSE + } + } + if (!comb_ok) { + dim_ok = FALSE + msg <- c(msg, "The dispersal kernel traits (Distances) matrix must contain exactly one row for each stage (1. column) and sex (2. column) combination!") + } + } + else { + if (length(unique(object@dispersal@Transfer@Distances[, offset])) != 2) { + dim_ok = FALSE + msg <- c(msg, "The emigration dispersal kernel traits (Distances) matrix must contain exactly one row for each sex (1. column) !") + } + } + } + } + } + if (dim_ok) { + # check value columns of Distances matrix + if (object@dispersal@Emigration@UseFullKern) { + resol = 0.0000000000001 + } + else { + resol = object@control@resolution + } + if (object@dispersal@Transfer@DoubleKernel) { + if(any(object@dispersal@Transfer@Distances[,(offset+1):(offset+2)]= ", (resol), " (=landscape resolution (unless UseFullKernel=TRUE)) !")) + } + if(any(object@dispersal@Transfer@Distances[,(offset+3)]<=0 | object@dispersal@Transfer@Distances[,(offset+3)]>=1)) { + msg <- c(msg, paste0("Column ", (offset+3), " of dispersal kernel traits (Distances) matrix must contain the probability p of using kernel 1, with values in the open interval (0,1) !")) + } + } + else{ + if(any(object@dispersal@Transfer@Distances[,(offset+1)]= ", (resol), " (=landscape resolution (unless UseFullKernel=TRUE)) !")) + } + } + } + } + } + } + ## Transfer / StochMove: + if (class(object@dispersal@Transfer)[1] == "StochMove") { + if (object@control@transfer != 1) { + msg <- c(msg, "SMS(): Something went wrong adding a SMS Transfer method to the Parameter Master!") + } + else { + # check transfer cost parameters + if (object@control@landtype==0) { # imported land with habitat codes + if (!any(length(object@dispersal@Transfer@StepMort) == c(1,object@control@maxNhab) )) { + msg <- c(msg, "SMS(): Per-step mortality probability must have either 1 or Nhabitat entries for an imported landscape with habitat codes!") + } + if (class(object@dispersal@Transfer@Costs)=="numeric") { + if (length(object@dispersal@Transfer@Costs) != object@control@maxNhab) { + msg <- c(msg, "SMS(): Costs must have Nhabitat entries for an imported landscape with habitat codes!") + } + } + if (class(object@dispersal@Transfer@Costs)=="character") { + if (object@dispersal@Transfer@Costs %in% c("file", "matrix")) { + if (is.null(object@land@CostsFile[1]) && length(object@land@CostsMatrix)==0) { # for threadsafe: length(object@land@CostsFile)==0 + msg <- c(msg, "SMS(): No cost map filenames or list of matrices found in the landscape module!") + } + } + else{ + msg <- c(msg, "SMS(): Costs has a wrong format! Must be either numeric or the keyword \"file\".") + } + } + } + else { + if (object@control@landtype==2) { # imported land with habitat quality + if (length(object@dispersal@Transfer@StepMort)!=1) { + msg <- c(msg, "SMS(): Per-step mortality probability must be a constant for an imported habitat percentage landscape!") + } + if (class(object@dispersal@Transfer@Costs)=="character") { + if (object@dispersal@Transfer@Costs %in% c("file", "matrix")) { + if (is.null(object@land@CostsFile[1]) && length(object@land@CostsMatrix)==0) { # threadsafe: length(object@land@CostsFile)==0 + msg <- c(msg, "SMS(): No cost map filenames or list of matrices found in the landscape module!") + } + } + else{ + msg <- c(msg, "SMS(): Costs has a wrong format! Must be either numeric or the keyword \"file\" or \"matrix\".") + } + } + else{ + msg <- c(msg, "SMS(): Costs must be imported from a raster map for an imported habitat percentage landscape!") + } + } + else { + if (object@control@landtype==9) { # artificial landscape + if (!any(length(object@dispersal@Transfer@StepMort) == c(1,2)) ) { + msg <- c(msg, "SMS(): Per-step mortality probability must have one or two (i.e. for matrix and habitat) entries for an artificial landscape!") + } + if (class(object@dispersal@Transfer@Costs)=="numeric") { + if (length(object@dispersal@Transfer@Costs) != 2) { + msg <- c(msg, "SMS(): Costs must have two entries (i.e. for matrix and habitat) for an artificial landscape!") + } + else { + if (class(object@dispersal@Transfer@Costs)=="character") { + msg <- c(msg, "SMS(): Costs can not be imported from a raster map for an artificial landscape!") + } + } + } + } + else { # no valid land code + msg <- c(msg, "SMS(): Something went wrong adding a SMS Transfer method to the Parameter Master: No valid landscape code.") + } + } + } + if(length(object@dispersal@Transfer@CostMap)==0) { + msg <- c(msg, "SMS(): Something went wrong adding a SMS Transfer method to the Parameter Master: No set CostMap switch.") + } + else{ + if(object@dispersal@Transfer@CostMap){ + if(!(object@dispersal@Transfer@Costs[1] %in% c("file", "matrix"))) { + msg <- c(msg, "SMS(): Something went wrong adding a SMS Transfer method to the Parameter Master: CostMap switch incorrect.") + } + } + else{ + if(object@dispersal@Transfer@Costs[1] == "file") { + msg <- c(msg, "SMS(): Something went wrong adding a SMS Transfer method to the Parameter Master: CostMap switch incorrect.") + } + + } + } + } + } + ## Transfer / CorrRW: + if (class(object@dispersal@Transfer)[1] == "CorrRW") { + if (object@control@transfer != 2) { + msg <- c(msg, "CorrRW(): Something went wrong adding a Correlated RW Transfer method to the Parameter Master!") + } + } + + ## Settlement: + # check StageDep and SexDep + dim_ok = TRUE + rows = 0 # if no dependency, there are only single values + if (object@dispersal@Settlement@StageDep) { + if (object@control@stagestruct) { + rows = object@control@stages + offset = 1 + } + else { + dim_ok = FALSE + msg <- c(msg, "Settlement can only be stage-dependent in a stage-structured model (StageStruct = StageStructure()) !") + } + } + else { + # rows = 1 + offset = 0 + } + if (object@dispersal@Settlement@SexDep) { + if (object@control@reproductn) { + if (rows==0) rows=1 + rows = 2*rows + offset = 1+offset + } + else { + dim_ok = FALSE + msg <- c(msg, "Settlement can only be sex-dependent in a sexually explicit model (ReproductionType = {1,2}) !") + if (any(FindMate)){ + msg <- c(msg, "FindMate can only be TRUE in a sexually explicit model (ReproductionType = {1,2}) !") + } + } + } + #check dimensions and values of matrix Settle: + # if there is some kind of dependency: + if (rows != 0){ + if (dim_ok && !object@dispersal@Settlement@IndVar) { + if (object@dispersal@Settlement@DensDep) { + cols = 3 + } + else { + if (object@control@transfer) cols = 1 + else cols = 1 + } + if (dim(object@dispersal@Settlement@Settle)[1]!=rows) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of Settlement traits (Settle) must have ", rows ," rows (with the current settings)!")) + } + if((offset+cols) == 0){ + if (any(dim(object@dispersal@Settlement@Settle)!=c(1,1) )) { + msg <- c(msg, paste0("Matrix of Settlement traits is not needed with the current settings!")) + } + } + else{ + if (dim(object@dispersal@Settlement@Settle)[2]!=(offset+cols)) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of Settlement traits (Settle) must have ", (offset+cols) ," columns (with the current settings)!")) + } + } + } + if (dim_ok && !object@dispersal@Settlement@IndVar) { + # check stage column of Settle + if (object@dispersal@Settlement@StageDep) { + if(any(object@dispersal@Settlement@Settle[,1]%%1!=0)){ + msg <- c(msg, "First column of Settlement traits matrix (Settle) must contain the stage numbers (but non-integer number(s) found)!") + } + else { + if(any(object@dispersal@Settlement@Settle[,1]<0 | object@dispersal@Settlement@Settle[,1]>object@control@stages)){ + msg <- c(msg, "First column of Settlement traits matrix (Settle) must contain the stage numbers (found <0 or >#stages)!") + } + else{ + if(length(unique(object@dispersal@Settlement@Settle[,1])) != object@control@stages){ + msg <- c(msg, "First column of Settlement traits matrix (Settle) must contain the stage numbers (but found incorrect stage numbers)!") + } + } + } + } + # check sex column of Settle + if (object@dispersal@Settlement@SexDep) { + if(!all(object@dispersal@Settlement@Settle[,offset] %in% c(0,1))){ + msg <- c(msg, paste0(offset,". column of Settlement traits matrix (Settle) must contain the sex numbers (0 for female, 1 for male)!")) + } + else { + if (object@dispersal@Settlement@StageDep) { + comb_ok = TRUE + for(i in 0:(object@control@stages-1)) { + if (length(unique(object@dispersal@Settlement@Settle[object@dispersal@Settlement@Settle[,1]==i, offset])) != 2) { + comb_ok = FALSE + } + } + if (!comb_ok) { + dim_ok = FALSE + msg <- c(msg, "The Settlement traits matrix (Settle) must contain exactly one row for each stage (1. column) and sex (2. column) combination!") + } + } + else { + if (length(unique(object@dispersal@Settlement@Settle[, offset])) != 2) { + dim_ok = FALSE + msg <- c(msg, "The Settlement traits matrix (Settle) must contain exactly one row for each sex (1. column)!") + } + } + } + } + } + if (dim_ok) { + if(!object@dispersal@Settlement@IndVar){ + # check value columns of Settle + if (object@control@transfer) { #if Movemodel: + if(any(object@dispersal@Settlement@Settle[,(offset+1)]<=0 | object@dispersal@Settlement@Settle[,(offset+1)]>1)){ + msg <- c(msg, paste0("Column ", (offset+1), " of settlement traits matrix (Settle) must contain the maximum settlement probability S0, with values in the half-open inerval (0,1] !")) + } + #// NB alpha and beta may take any value + #else {} // no more columns required other than stage and sex if applicable + } + else { # DispersalKernel + if (object@control@stagestruct) { + if(!all(object@dispersal@Settlement@Settle[,(offset+1)] %in% c(0,1,2,3))){ + msg <- c(msg, paste0("Column ", (offset+1), " of settlement traits matrix (Settle) must contain the settlement condition codes, with valid values: 0, 1, 2 or 3.")) + } + } + else{ + if(!all(object@dispersal@Settlement@Settle[,(offset+1)] %in% c(0,2))){ + msg <- c(msg, paste0("Column ", (offset+1), " of settlement traits matrix (Settle) must contain the settlement condition codes; for a non-StageStructured population the only valid values are 0 and 2.")) + } + } + } + } + + #if Movemodel, check its additional parameters: + if (object@control@transfer) { + if (!is.null(nrow(object@dispersal@Settlement@MinSteps))){ + if (nrow(object@dispersal@Settlement@MinSteps)!= rows){ + msg <- c(msg, paste0("Settlement(): MinSteps must have ", rows ," rows (with the current settings)!")) + } + } + + if (!is.null(nrow(object@dispersal@Settlement@MaxSteps))){ + if(nrow(object@dispersal@Settlement@MaxSteps) != rows ){ + msg <- c(msg, paste0("Settlement(): MaxSteps must have ", rows ," rows (with the current settings)!")) + } + } + if (object@dispersal@Settlement@StageDep) { + if (!is.null(nrow(object@dispersal@Settlement@MaxStepsYear))){ + if(nrow(object@dispersal@Settlement@MaxStepsYear) != rows ){ + msg <- c(msg, paste0("Settlement(): MaxStepsYear must have ", rows ," rows (with the current settings)!")) + } + } + } + } + } + } else { + if(object@dispersal@Settlement@DensDep){ + rows = 1 + cols = 3 + if (dim(object@dispersal@Settlement@Settle)[1]!=rows) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of Settlement traits (Settle) must have ", rows ," rows (with the current settings)!")) + } + if (dim(object@dispersal@Settlement@Settle)[2]!=(offset+cols)) { + dim_ok = FALSE + msg <- c(msg, paste0("Matrix of Settlement traits (Settle) must have ", (offset+cols) ," columns (with the current settings)!")) + } + if(any(object@dispersal@Settlement@Settle[,(offset+1)]<=0 | object@dispersal@Settlement@Settle[,(offset+1)]>1)){ + msg <- c(msg, paste0("Column ", (offset+1), " of settlement traits matrix (Settle) must contain the maximum settlement probability S0, with values in the half-open interval (0,1] !")) + } + #// NB alpha and beta may take any value + } else { + if(length(object@dispersal@Settlement@Settle) != 1) { + dim_ok = FALSE + msg <- c(msg, paste0("Settle must only have one value (with the current settings)!")) + } else { + if (object@control@transfer) { + # Settle between 0 and 1 + if(object@dispersal@Settlement@Settle<0 | object@dispersal@Settlement@Settle>1){ + msg <- c(msg, "Settle must be between 0 and 1!") + } + } else { + if (object@control@stagestruct) { + if(!(object@dispersal@Settlement@Settle %in% c(0,1,2,3))){ + msg <- c(msg, "Settle must contain the settlement condition codes, with valid values: 0, 1, 2 or 3.") + } + } + else{ + if(!(object@dispersal@Settlement@Settle %in% c(0,2))){ + msg <- c(msg, "Settle must contain the settlement condition codes; for a non-StageStructured population the only valid values are 0 and 2.") + } + } + } + } + } + # Settle, FindMate, MinSteps, MaxSteps, MaxStepsYear must be one single value + + if(object@control@transfer){ + if(any(c(length(object@dispersal@Settlement@MinSteps) != 1, length(object@dispersal@Settlement@MaxSteps) != 1, length(object@dispersal@Settlement@MaxStepsYear) != 1, length(object@dispersal@Settlement@FindMate) != 1))){ + msg <- c(msg, "MinSteps, MaxSteps, MaxStepsYear and FindMate must be a single value with the current settings.") + } + } + } + + + #GENETICS + validObject(object@gene) + # Check if output is correct: Fstats should only be activated if neutral genetics is set + if(object@gene@OutputFstatsWeirCockerham || object@gene@OutputPairwiseFst){ + if(class(object@gene@Traits@Neutral)[1] != "NeutralTraitsParams"){ + msg <- c(msg, "FstatsWeirCockerham or PairwiseFst can only be activated if NeutralTraits is set!") + } + } + + if(class(object@gene@Traits@Neutral)[1] == "NeutralTraitsParams" && (!object@gene@OutputFstatsWeirCockerham && !object@gene@OutputPairwiseFst)){ + msg <- c(msg, "If NeutralTraits are set, at least one of the neutrall stats outputs (FstatsWeirCockerham or PairwiseFst) must be true!") + } + + # Dispersal Traits + if(any(object@dispersal@Emigration@IndVar,object@dispersal@Transfer@IndVar,object@dispersal@Settlement@IndVar)) anyIndVar <- TRUE + else anyIndVar <- FALSE + ## Emigration: if IndVar is set, check if corresponding genetics module is set correctly + if (object@dispersal@Emigration@IndVar) { + if (class(object@gene@Traits@EmigrationGenes)[1]=="logical") { + if (!object@gene@Traits@EmigrationGenes) { + msg <- c(msg, 'Traits() and EmigrationGenes(): IndVar is set for Emigration, but EmigrationGenes() module is not set!') + } else { + msg <- c(msg, "EmigrationGenes must be an object of class \"EmigrationTraitsParams\" !") + } + } else if (class(object@gene@Traits@EmigrationGenes)[1]=="EmigrationTraitsParams"){ + # Determine matrix layout for all parameters according to sexdep and densdep + if (object@dispersal@Emigration@DensDep) { + # it should be 3 rows: E_D0, E_Alpha, E_beta + nbrows <- 3 + } else { + # it should be 1 row E_D0 + nbrows <- 1 + } + if (object@dispersal@Emigration@SexDep) { + nbrows = nbrows * 2 # it should be two rows + } + + # Positions + if(length(object@gene@Traits@EmigrationGenes@Positions)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): Positions must have ", nbrows ," entries with the current settings!")) + } + + # NbOfPositions + if(!is.null(object@gene@Traits@EmigrationGenes@NbOfPositions) && length(object@gene@Traits@EmigrationGenes@NbOfPositions)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): NbOfPositions must have ", nbrows ," entries with the current settings!")) + } + + # ExpressionType + if(length(object@gene@Traits@EmigrationGenes@ExpressionType)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): ExpressionType must have ", nbrows ," entries with the current settings!")) + } + + # InitialAlleleDistribution + if(length(object@gene@Traits@EmigrationGenes@InitialAlleleDistribution)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): InitialAlleleDistribution must have ", nbrow ," entries with the current settings!")) + } + + # InitialAlleleParameters + if(nrow(object@gene@Traits@EmigrationGenes@InitialAlleleParameters)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): InitialAlleleParameters matrix must have ", nbrow ," rows with the current settings!")) + } + + # IsInherited + if(length(object@gene@Traits@EmigrationGenes@IsInherited)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): IsInherited must have ", nbrows ," entries with the current settings!")) + } + + # MutationDistribution + if(length(object@gene@Traits@EmigrationGenes@MutationDistribution)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): MutationDistribution must have ", nbrows ," entries with the current settings!")) + } + + # MutationParameters + if(nrow(object@gene@Traits@EmigrationGenes@MutationParameters)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): MutationParameters matrix must have ", nbrows ," rows with the current settings!")) + } + + # MutationRate + if(length(object@gene@Traits@EmigrationGenes@MutationRate)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): MutationRate must have ",nbrows ," entries with the current settings!")) + } + + # OutputValues + if(length(object@gene@Traits@EmigrationGenes@OutputValues)!=nbrows){ + msg <- c(msg, paste0("EmigrationGenes(): OutputValues must have ", nbrows ," entries with the current settings!")) + } + + } + } + ## Transfer: if IndVar is set, check if corresponding genetics module (CRW, SMS, Kernel) is set correctly + if (object@dispersal@Transfer@IndVar) { + # check transfer mode + if (class(object@dispersal@Transfer)[1] == "CorrRW") { + if (class(object@gene@Traits@CorrRWGenes)[1]=="logical") { + if (!object@gene@Traits@CorrRWGenes) { + msg <- c(msg, 'Traits() and CorrRWGenes(): IndVar is set for CorrRW, but CorrRWGenes() module is not set!') + } else { + msg <- c(msg, "CorrRWGenes must be an object of class \"CorrRWTraitsParams\" !") + } + } else if (class(object@gene@Traits@CorrRWGenes)[1]=="CorrRWTraitsParams"){ + # Determine matrix layout for all parameters according to sexdep and densdep + nbrows <- 2 + + # Positions + if(length(object@gene@Traits@CorrRWGenes@Positions)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): Positions must have ", nbrows ," entries!")) + } + + # NbOfPositions + if(!is.null(object@gene@Traits@CorrRWGenes@NbOfPositions) && length(object@gene@Traits@CorrRWGenes@NbOfPositions)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): NbOfPositions must have ", nbrows ," entries!")) + } + + # ExpressionType + if(length(object@gene@Traits@CorrRWGenes@ExpressionType)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): ExpressionType must have ", nbrows ," entries!")) + } + + # InitialAlleleDistribution + if(length(object@gene@Traits@CorrRWGenes@InitialAlleleDistribution)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): InitialAlleleDistribution must have ", nbrow ," entries!")) + } + + # InitialAlleleParameters + if(nrow(object@gene@Traits@CorrRWGenes@InitialAlleleParameters)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): InitialAlleleParameters matrix must have ", nbrow ," rows!")) + } + + # IsInherited + if(length(object@gene@Traits@CorrRWGenes@IsInherited)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): IsInherited must have ", nbrows ," entries!")) + } + + # MutationDistribution + if(length(object@gene@Traits@CorrRWGenes@MutationDistribution)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): MutationDistribution must have ", nbrows ," entries!")) + } + + # MutationParameters + if(nrow(object@gene@Traits@CorrRWGenes@MutationParameters)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): MutationParameters matrix must have ", nbrows ," rows!")) + } + + # MutationRate + if(length(object@gene@Traits@CorrRWGenes@MutationRate)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): MutationRate must have ",nbrows ," entries!")) + } + + # OutputValues + if(length(object@gene@Traits@CorrRWGenes@OutputValues)!=nbrows){ + msg <- c(msg, paste0("CorrRWGenes(): OutputValues must have ", nbrows ," entries!")) + } + + } + } + if (class(object@dispersal@Transfer)[1] == "StochMove") { + if (class(object@gene@Traits@SMSGenes)[1]=="logical") { + if (!object@gene@Traits@SMSGenes) { + msg <- c(msg, 'Traits() and SMSGenes(): IndVar is set for Transfer, but SMSGenes() module is not set!') + } else { + msg <- c(msg, "SMSGenes must be an object of class \"SMSTraitsParams\" !") + } + } else if (class(object@gene@Traits@SMSGenes)[1]=="SMSTraitsParams") { + # DP or (if GoalBias =T) DP + goalBias + alphaDB + betaDB + if (object@dispersal@Transfer@GoalType == 2){ + nbrows <- 4 + } else { + nbrows <- 1 + } + + # Positions + if(length(object@gene@Traits@SMSGenes@Positions)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): Positions must have ", nbrows ," entries with the current settings!")) + } + + # NbOfPositions + if(!is.null(object@gene@Traits@SMSGenes@NbOfPositions) && length(object@gene@Traits@SMSGenes@NbOfPositions)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): NbOfPositions must have ", nbrows ," entries with the current settings!")) + } + + # ExpressionType + if(length(object@gene@Traits@SMSGenes@ExpressionType)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): ExpressionType must have ", nbrows ," entries with the current settings!")) + } + + # InitialAlleleDistribution + if(length(object@gene@Traits@SMSGenes@InitialAlleleDistribution)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): InitialAlleleDistribution must have ", nbrow ," entries with the current settings!")) + } + + # InitialAlleleParameters + if(nrow(object@gene@Traits@SMSGenes@InitialAlleleParameters)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): InitialAlleleParameters matrix must have ", nbrow ," rows with the current settings!")) + } + + # IsInherited + if(length(object@gene@Traits@SMSGenes@IsInherited)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): IsInherited must have ", nbrows ," entries with the current settings!")) + } + + # MutationDistribution + if(length(object@gene@Traits@SMSGenes@MutationDistribution)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): MutationDistribution must have ", nbrows ," entries with the current settings!")) + } + + # MutationParameters + if(nrow(object@gene@Traits@SMSGenes@MutationParameters)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): MutationParameters matrix must have ", nbrows ," rows with the current settings!")) + } + + # MutationRate + if(length(object@gene@Traits@SMSGenes@MutationRate)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): MutationRate must have ",nbrows ," entries with the current settings!")) + } + + # OutputValues + if(length(object@gene@Traits@SMSGenes@OutputValues)!=nbrows){ + msg <- c(msg, paste0("SMSGenes(): OutputValues must have ", nbrows ," entries with the current settings!")) + } + + } + } + + if (class(object@dispersal@Transfer)[1] == "DispersalKernel") { + if (class(object@gene@Traits@KernelGenes)[1]=="logical") { + if (!object@gene@Traits@KernelGenes) { + msg <- c(msg, 'Traits() and KernelGenes(): IndVar is set for Transfer, but KernelGenes() module is not set!') + } else { + msg <- c(msg, "KernelGenes must be an object of class \"KernelTraitsParams\" !") + } + } else if (class(object@gene@Traits@SMSGenes)[1]=="KernelTraitsParams") { + # DoubleKernel: Kernel1 Kernel2 Kernel_probability + if (object@dispersal@Transfer@DoubleKernel == TRUE){ + nbrows <- 3 + } else { + nbrows <- 1 + } + if (object@dispersal@Transfer@SexDep) { + nbrows = nbrows * 2 # it should be two rows + } else { + nbrows = nbrows * 1 + } + + # Positions + if(length(object@gene@Traits@KernelGenes@Positions)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): Positions must have ", nbrows ," entries with the current settings!")) + } + + # NbOfPositions + if(!is.null(object@gene@Traits@KernelGenes@NbOfPositions) && length(object@gene@Traits@KernelGenes@NbOfPositions)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): NbOfPositions must have ", nbrows ," entries with the current settings!")) + } + + # ExpressionType + if(length(object@gene@Traits@KernelGenes@ExpressionType)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): ExpressionType must have ", nbrows ," entries with the current settings!")) + } + + # InitialAlleleDistribution + if(length(object@gene@Traits@KernelGenes@InitialAlleleDistribution)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): InitialAlleleDistribution must have ", nbrow ," entries with the current settings!")) + } + + # InitialAlleleParameters + if(nrow(object@gene@Traits@KernelGenes@InitialAlleleParameters)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): InitialAlleleParameters matrix must have ", nbrow ," rows with the current settings!")) + } + + # IsInherited + if(length(object@gene@Traits@KernelGenes@IsInherited)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): IsInherited must have ", nbrows ," entries with the current settings!")) + } + + # MutationDistribution + if(length(object@gene@Traits@KernelGenes@MutationDistribution)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): MutationDistribution must have ", nbrows ," entries with the current settings!")) + } + + # MutationParameters + if(nrow(object@gene@Traits@KernelGenes@MutationParameters)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): MutationParameters matrix must have ", nbrows ," rows with the current settings!")) + } + + # MutationRate + if(length(object@gene@Traits@KernelGenes@MutationRate)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): MutationRate must have ",nbrows ," entries with the current settings!")) + } + + # OutputValues + if(length(object@gene@Traits@KernelGenes@OutputValues)!=nbrows){ + msg <- c(msg, paste0("KernelGenes(): OutputValues must have ", nbrows ," entries with the current settings!")) + } + + + } + } + + + } + ## Settlement: if IndVar is set, check if corresponding genetics module is set correctly + if (object@dispersal@Settlement@IndVar) { + if (class(object@gene@Traits@SettlementGenes)[1]=="logical") { + if (!object@gene@Traits@SettlementGenes) { + msg <- c(msg, 'Traits() and SettlementGenes(): IndVar is set for Settlement, but SettlementGenes() module is not set!') + } else { + msg <- c(msg, "SettlementGenes must be an object of class \"SettlementTraitsParams\" !") + } + } else if (class(object@gene@Traits@SettlementGenes)[1]=="SettlementTraitsParams"){ + # Determine matrix layout for all parameters according to sexdep and densdep + nbrows <- 3 + if (object@dispersal@Settlement@SexDep) { + nbrows = nbrows * 2 # it should be two rows + } + + # Positions + if(length(object@gene@Traits@SettlementGenes@Positions)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): Positions must have ", nbrows ," entries with the current settings!")) + } + + # NbOfPositions + if(!is.null(object@gene@Traits@SettlementGenes@NbOfPositions) && length(object@gene@Traits@SettlementGenes@NbOfPositions)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): NbOfPositions must have ", nbrows ," entries with the current settings!")) + } + + # ExpressionType + if(length(object@gene@Traits@SettlementGenes@ExpressionType)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): ExpressionType must have ", nbrows ," entries with the current settings!")) + } + + # InitialAlleleDistribution + if(length(object@gene@Traits@SettlementGenes@InitialAlleleDistribution)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): InitialAlleleDistribution must have ", nbrow ," entries with the current settings!")) + } + + # InitialAlleleParameters + if(nrow(object@gene@Traits@SettlementGenes@InitialAlleleParameters)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): InitialAlleleParameters matrix must have ", nbrow ," rows with the current settings!")) + } + + # IsInherited + if(length(object@gene@Traits@SettlementGenes@IsInherited)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): IsInherited must have ", nbrows ," entries with the current settings!")) + } + + # MutationDistribution + if(length(object@gene@Traits@SettlementGenes@MutationDistribution)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): MutationDistribution must have ", nbrows ," entries with the current settings!")) + } + + # MutationParameters + if(nrow(object@gene@Traits@SettlementGenes@MutationParameters)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): MutationParameters matrix must have ", nbrows ," rows with the current settings!")) + } + + # MutationRate + if(length(object@gene@Traits@SettlementGenes@MutationRate)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): MutationRate must have ",nbrows ," entries with the current settings!")) + } + + # OutputValues + if(length(object@gene@Traits@SettlementGenes@OutputValues)!=nbrows){ + msg <- c(msg, paste0("SettlementGenes(): OutputValues must have ", nbrows ," entries with the current settings!")) + } + + } + } + # if( ...(object@gene) & !anyIndVar) # TODO: check if genetics module is set but no variable traits -> give warning in this case + + #INITIALISATION + validObject(object@init) + if (object@control@landtype == 9) { # artificial land + if (object@init@InitType) { + msg <- c(msg, 'Initialise(): InitType must be set to 0 (Free initialisation) for an artificial landscape!') + } + else { + if (object@init@minX > object@land@dimX) { + msg <- c(msg, 'Initialise(): minX exceeds the landscape dimensions!') + } + else { + if (object@init@maxX > object@land@dimX) { + msg <- c(msg, 'Initialise(): maxX exceeds the landscape dimensions!') + } + } + if (object@init@minY > object@land@dimY) { + msg <- c(msg, 'Initialise(): minY exceeds the landscape dimensions!') + } + else { + if (object@init@maxY > object@land@dimY) { + msg <- c(msg, 'Initialise(): maxY exceeds the landscape dimensions!') + } + } + } + } + else { # imported land + if (object@init@InitType == 1 && !object@control@speciesdist) { + msg <- c(msg, 'Initialise(): A species distribution map has to be loaded via the \'land\' module if InitType = 1 (initialisation from loaded species distribution map) !') + } + if (object@init@InitType == 2 && is.null(object@init@InitIndsFile)) { # from initial individuals list from list of data.frames in 'InitIndsList'; NOTE:was != "NULL" in public repo + if(length(object@init@InitIndsList)!=object@simul@Replicates) { + msg <- c(msg, 'Initialise(): Number of elements in InitIndsList must equal the number of Replicates!') + } + } + } + if (object@control@stagestruct) { + if (anyNA(object@init@InitAge) || length(object@init@InitAge) == 0){ + msg <- c(msg, 'Initialise(): InitAge must be set!') + } + else { + if (!object@init@InitAge %in% c(0,1,2) && object@init@InitType != 2){ + msg <- c(msg, 'Initialise(): InitAge must be 0, 1 or 2!') + } + } + if (object@init@InitType != 2) { + if ( anyNA(object@init@PropStages) || length(object@init@PropStages) == 0 ){ + msg <- c(msg, 'Initialise(): PropStages must be set!') + } + else { + if(length(object@init@PropStages) != object@control@stages) { + msg <- c(msg, 'Initialise(): PropStages must have a length equal to number of stages!') + } + else{ + if(any(object@init@PropStages < 0.0) | any(object@init@PropStages > 1.0)) { + msg <- c(msg, 'Initialise(): All elements of PropStages must be in the closed interval [0,1]!') + } + else{ + if (object@init@PropStages[1] != 0.0) { + msg <- c(msg, 'Initialise(): Initial proportion of the juvenile stage (PropStages[1]) must be 0.0!') + } + else{ + if (length(object@init@PropStages)>1 && sum(object@init@PropStages) != 1.0) { + msg <- c(msg, 'Initialise(): The elements of PropStages must sum to 1!') + } + } + } + } + } + } + } + else{ + if (length(object@init@PropStages)>1 || !(object@init@PropStages[1] %in% c(0,-9))) { + msg <- c(msg, 'PropStages is not used for a population without stage structure.') + } + } + ## Management + validObject(object@management) + if (is.null(msg)) TRUE else msg} +) +setMethod("show", "RSparams", function(object){ + print(object@control) + cat("\n") + print(object@simul) + cat("\n") + print(object@land) + cat("\n") + print(object@demog) + cat("\n") + print(object@dispersal) + cat("\n") + hasGenetics <- any(object@control@neutralgenetics, object@control@geneticload, object@dispersal@Emigration@IndVar, object@dispersal@Transfer@IndVar, object@dispersal@Settlement@IndVar) + if(hasGenetics){ + print(object@gene) + cat("\n") + } + print(object@management) + cat("\n") + print(object@init)} +) diff --git a/RangeShiftR/R/class_SimulationParams.R b/RangeShiftR/R/class_SimulationParams.R new file mode 100644 index 0000000..b53a38f --- /dev/null +++ b/RangeShiftR/R/class_SimulationParams.R @@ -0,0 +1,1048 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +### CLASS SIMULATIONPARAMS + +# from RS 'Parameter' file + +#' Set Simulation parameters +#' +#' @description Set basic simulation parameters and control output types.\cr +#' Furthermore, optionally define a (\code{Shifting}) Environmental \code{Gradient}, Environmental Stochasticity (\code{EnvStoch}) and/or Local extinction (\code{LocalExt}). +#' (These options are to be moved to separate classes in future versions.) +#' +#' @author Anne-Kathleen Malchow +#' @usage Simulation(Simulation = 1, Replicates = 2, Years = 50, Absorbing = FALSE, +#' Gradient = 0, GradSteep, Optimum, f, ExtinctOptim, +#' Shifting = FALSE, ShiftRate, ShiftStart, ShiftEnd, +#' LocalExt = FALSE, LocalExtProb, +#' EnvStoch = 0, EnvStochType, std, ac, minR, maxR, minK, maxK, +#' OutIntRange = 1, OutIntOcc = 0, +#' OutIntPop = 1, OutIntInd = 0, +#' OutIntTraitCell = 0, OutIntTraitRow = 0, +#' OutIntConn = 0, OutIntPaths = 0, +#' OutStartPop = 0, OutStartInd = 0, +#' OutStartTraitCell = 0, OutStartTraitRow = 0, +#' OutStartConn = 0, OutStartPaths = 0, +# #' SaveMaps = FALSE, MapsInterval, DrawLoadedSp = FALSE, +#' ReturnPopMatrix = FALSE, ReturnPopDataFrame = FALSE, ReturnStages = FALSE, +#' CreatePopFile = TRUE, +#' ReturnStages = FALSE, +#' SMSHeatMap = FALSE) +#' @param Simulation ID number of current simulation, defaults to \eqn{1}. (integer) +#' @param Replicates Number of simulation iterations, defaults to \eqn{2}. (integer) +#' @param Years The number of simulated years, defaults to \eqn{50}. (integer) +#' @param Absorbing If \code{FALSE} (default), every move in the \code{\link[RangeShiftR]{Transfer}} process will be +#' repeated until a valid cell is met.\cr +#' If \code{TRUE}, an individual which hits a non-valid cell or +#' transgresses the landscape boundary during the dispersal act is eliminated from the simulation. +#' @param Gradient Whether to apply north-south gradient: +#' \eqn{0} = None (default), \cr +#' \eqn{1} = decreasing \code{K_or_DensDep}\cr +#' \eqn{2} = decreasing growth rate \eqn{r} or, for a \code{\link[RangeShiftR]{StageStructure}}d population, +#' fecundity \ifelse{html}{\out{φ}}{\eqn{\phi}}, \cr +#' \eqn{3} = increasing local extinction probability \eqn{e}. \cr +#' If activated, a gradient will be imposed along the north-south (\eqn{y}-) axis in which the selected parameter varies linearly with distance from the +#' optimum \eqn{y}-value \code{Optimum}. Note that a \code{Gradient} can not be applied in for patch-based models (must be \code{Gradient}\eqn{=0}). +#' @param GradSteep Required if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: gradient steepness in units of (fraction of local value) per cell. Must be \eqn{\ge 0}. +#' @param Optimum Required if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: \eqn{y}-value at which the extremum is obtained. Must be \eqn{\ge 0}. +#' @param f Required if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: local scaling factor that determines the magnitude of stochastic local heterogeneity relative to the optimal value. Must be \eqn{\ge 0}. +#' @param ExtinctOptim Required if \code{Gradient} \eqn{= 3}: optimum (i.e. minimal) local extinction probability at \code{Optimum}. Must be between \eqn{0} and \eqn{1}. +#' @param Shifting Only applicable if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}:\cr +#' If \code{FALSE} (default), the gradient is stationary.\cr +#' If \code{TRUE}, the \code{Gradient} shifts along the \eqn{y}-axis towards increasing \eqn{y} (northwards). Requires to set \code{ShiftRate}, \code{ShiftStart} and \code{ShiftEnd}, +#' @param ShiftRate Required if \code{Shifting=TRUE}: shift rate of the gradient in units of rows per year. (integer) +#' @param ShiftStart Required if \code{Shifting=TRUE}: year in which the gradient shifting starts (integer) +#' @param ShiftEnd Required if \code{Shifting=TRUE}: year in which the gradient shifting stops. (integer) +#' @param LocalExt If \code{FALSE} (default), no additional extinction probability is applied.\cr +#' If \code{TRUE}, an independent constant extinction probability \code{LocalExtProb} is applied, defined as +#' the probability that each population goes extinct at each year. +#' Note that \code{LocalExt} must be \code{FALSE} for a patch-based model or if \code{Gradient}\eqn{=3}. +#' @param LocalExtProb Required if \code{LocalExt=TRUE}: independent yearly extinction probability of populations. +#' @param EnvStoch Scale of environmental stochasticity:\cr +#' \eqn{0} = none (default),\cr +#' \eqn{1} = global (a single time series for entire landscape),\cr +#' \eqn{2} = local (each cell fluctuates independently, only permitted for cell-based model).\cr +#' Environmental stochasticity is always applied on a yearly basis. +#' @param EnvStochType Required if \code{EnvStoch} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: Parameter to which environmental stochasticity is applied:\cr +#' \eqn{0} = growth rate \eqn{r} or, for a \code{\link[RangeShiftR]{StageStructure}}d population, fecundity (\eqn{\phi}).\cr +#' \eqn{1} = demographic density dependence \code{K_or_DensDep} (carrying capacity or 1/b) (allowed for artificial landscapes only!). +#' @param std Required if \code{EnvStoch} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: magnitude of stochastic fluctuations. Must be \eqn{> 0.0} and \eqn{\le 1.0}. +#' @param ac Required if \code{EnvStoch} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: temporal autocorrelation coefficient. Must be \eqn{\ge 0.0} and \eqn{<1.0}. +#' @param minR,maxR Required if \code{EnvStochType}\eqn{=0}: minimum and maximum growth rates. +#' @param minK,maxK Required if \code{EnvStochType}\eqn{=1}: minimum and maximum value of \eqn{K} or \eqn{1/b}, respectively. +#' @param OutIntRange,OutIntOcc,OutIntPop,OutIntInd,OutIntTraitCell,OutIntTraitRow,OutIntConn,OutIntPaths Control the various types +#' of Output files, i.e. range, occupancy, populations, individuals, traits (by cell or by row), connectivity and SMS paths:\cr +#' \eqn{=0 }: Output disabled.\cr +#' \eqn{>0 }: Output enabled; sets interval (in years) in which output is generated.\cr +#' If the output is enabled, start values are required. By default, only the output of Range and Population are enabled.\cr +#' Occupancy output is only applicable if \code{Replicates>1}. +#' Traits output is only applicable for a cell-based model with inter-individual variability. +#' Connectivity output is only applicable for a patch-based model. +#' SMS paths is only applicable for a model with SMS transfer method. +#' +#' Please note that with RangeShiftR version 2.0, the output of genetic data is no longer controlled within this function. +#' Instead, genetic data output is controlled within the \code{\link[RangeShiftR]{Genetics}}. +#' +#' @param OutStartPop,OutStartInd,OutStartTraitCell,OutStartTraitRow,OutStartConn,OutStartPaths +#' Starting years for output generation. Note that the first year is year \eqn{0}. Defaults to \eqn{0} for all output types. (integer) +# #' @param SaveMaps If \code{FALSE} (default), no maps will be created.\cr If \code{TRUE}, maps will be generated. +# #' beginning in the first year in accordance to \code{MapsInterval}. +# #' @param MapsInterval Required if \code{SaveMaps=TRUE}: save maps every \eqn{n} reproductive seasons. (integer) +# #' @param DrawLoadedSp If \code{FALSE} (default), only the simulated distribution is drawn into the output map.\cr +# #' If \code{TRUE}, the initial species distribution is drawn additionally. +#' @param SMSHeatMap Produce SMS heat map raster as output? Defaults to \code{FALSE}. +#' @param ReturnPopMatrix Return population data to R as matrix (only for cell-based models)? Defaults to \code{FALSE}. +#' @param ReturnPopDataFrame Return population data to R as data frame (most suitable for patch based models)? Defaults to \code{FALSE}. +#' @param ReturnStages Return also stage-specific population data? Only applicable for stage-structured models if \code{ReturnPopMatrix = TRUE} or \code{ReturnPopDataFrame = TRUE}. If \code{FALSE} only total abundance is recorded. +#' @param CreatePopFile Create population output file? Defaults to \code{TRUE}. +#' @details \emph{Environmental Gradient}\cr +#' In \emph{RangeShiftR}, it is possible to superimpose an artificial gradient on top of the landscape map (real or artificial). +#' Gradients are implemented for cell-based models only.\cr +#' An environmental gradient can be superimposed on the habitat map to describe gradual change in abiotic factors through space. Use the option \code{Gradient} +#' and choose one of three implemented parameter gradients. These are, respectively for non-structured / stage-structured population models:\cr +#' \itemize{ +#' \item{Decreasing values of \code{K_or_DensDep}, that mediates demographic density dependence (stronger with lower values) and is interpreted as +#' the \emph{carrying capacity} \eqn{K} / the \emph{strength of density dependence} \ifelse{html}{\out{b-1}}{\eqn{1/b}} (set \code{Gradient=1});} +#' \item{Decreasing growth rate \eqn{r} / fecundity (\eqn{\phi}) (set \code{Gradient=2});} +#' \item {Increasing local extinction probability \eqn{e} (set \code{Gradient=3}).} +#' } +#' The gradient is restrictively implemented along the north-south (\eqn{y})-axis and the selected parameter declines linearly with (\eqn{y})-distance from +#' an optimum location (\code{Optimum}). +#' +#' Gradients are implemented following the method of \insertCite{travis2004;textual}{RangeShiftR}, which combines linear variability with local heterogeneity. +#' If \eqn{Z} is one of the gradient variables listed above, \eqn{Z={K, 1/b, r, \phi, e}}, the value of \eqn{Z(x,y)} for a cell with \eqn{x} and \eqn{y}-coordinates +#' is given by the following equation: +#' +#' \ifelse{html}{\out{    Z(x,y) = Z0 * z(x,y)       for K and r,}}{\deqn{Z(x,y)=Z_0 * z(x,y)} for K and r,} +#' or\cr +#' \ifelse{html}{\out{    Z(x,y) = 1 - z(x,y) + eopt     for e}}{\deqn{Z(x,y)= 1 - z(x,y) + e_{opt}} for e} +#' \cr +#' +#' with \cr +#' \ifelse{html}{\out{    z(x,y) = 1 - |y - yopt| G + U(-1,1) f }}{\deqn{z(x,y) = 1 - |y - y_{opt}| G + U(-1,1) f }} +#' , constrained to \eqn{\ge 0} +#' +#' where \ifelse{html}{\out{Z0}}{Z_0} is the original parameter value at \eqn{(x,y)}, +#' \ifelse{html}{\out{eopt}}{e_{opt}} (\code{ExtinctOptim}) the minimum extinction probability. +#' The linear variability is specified by +#' \ifelse{html}{\out{yopt}}{y_{opt}} (\code{Optimum}), the \eqn{y}-value at which the extremum (i.e. \ifelse{html}{\out{Z0}}{Z_0} or \ifelse{html}{\out{eopt}}{e_{opt}}) is obtained, +#' and \eqn{G} (\code{GradSteep}), the gradient steepness in units of fraction of the local value per cell. +#' The local heterogeneity is determined by a random number drawn from a uniform distribution between \eqn{-1} and \eqn{1} for each cell +#' and \code{f}, the local scaling factor that determines the magnitude of this stochastic local variation relative to the extremal value. +#' +#' The gradient in fecundity φ applies to the fecundity of each stage. Negative local values in \eqn{z(x,y)} are set to \eqn{0}. +#' +#' It is also possible to simulate the shifting of the gradient by setting the option \code{Shifting}. Here the position \eqn{y} of the species’ +#' optimum is shifted northwards (increasing \eqn{y}) at a given rate \code{ShiftRate} (in units of rows per year), +#' starting from year \code{ShiftStart} to year \code{ShiftEnd}. +#' +#' Environmental gradients are available for cell-based models only, due to the cell-based character of operations and therefore \code{Gradient} +#' has to be \eqn{0} for patch-based models. +#' +#' \emph{Local Extinctions}\cr +#' An additional, independent extinction probability can be added using the option \code{LocalExt}. If set, +#' in each year, every population has an identical probability \code{LocalExtProb} of going extinct. +#' This does not affect any demographic parameters but simply kills off the local population. +#' +#' \emph{Environmental Stochasticity}\cr +#' It is possible to model environmental stochasticity via the option \code{EnvStoch} acting at a global or local scale +#' and can be applied to \code{K_or_DensDep}, the demographic density dependence (\code{EnvStoch=1}), or to growth rate / fecundity (\code{EnvStoch=0}). +#' It is implemented using a first order autoregressive process to generate time series of the noise value \eqn{ε} +#' \insertCite{ruokolainen2009}{RangeShiftR}: +#' +#' \deqn{ε(t+1) = κ ε(t) + \omega(t) \sqrt(1-\kappa^2)} +#' +#' where κ is the autocorrelation coefficient (\code{ac}) and ω is a random normal variable drawn from \eqn{N(0,σ)}. +#' Changing σ (\code{std}) changes the magnitude of the fluctuations. The spatial scale of the variation can either be global (a single time series +#' for the entire landscape) or local (each cell fluctuates independently), and is always applied on a yearly basis. +#' Different degrees of spatial autocorrelation are not implemented in the current version. +#' +#' The noise affects the species' selected parameter \eqn{Z} as follows: +#' \deqn{Z(x,y,t) = Z(x,y,0) + Z ε(t)} +#' where \eqn{x} and \eqn{y} are the cell coordinates and \eqn{Z} is the original parameter value in absence of stochasticity and gradients. +#' In the presence of an environmental gradient, \eqn{Z(x,y,0)} is the gradient value at the cell location, otherwise its equal to \eqn{Z}. +#' The resulting values \eqn{Z(x,y,t)} are limited to the maximum and minimum values \code{minR,maxR} or \code{minK,maxK}, respectively. +#' +#' \emph{Output files}\cr +#' Seven different types of outputs can be produced, plus one more for patch-based models. +#' All the output files will be named with a standard name reporting the simulation ID number and +#' the type of output. The file name will start with the batch number, and also indicate the number +#' of the landscape to which the output refers. Additionally, for each simulation all the set parameters +#' will be automatically written to a text file named \"Sim0_Parameters.txt\" in the case of simulation\eqn{#=0}. +#' +#' - \emph{Species range} (\code{Sim0_Range.txt}) \cr +#' contains the following general information regarding the species’ range:\cr +#' Replicate number (Rep), Year (Year), Reproductive season within the year (RepSeason), Total number of individuals (NInds), +#' Total number of individuals in each stage (NInd_stageX; only in case of stage-structured models), +#' Total number of juveniles born (NJuvs; only in case of stage-structured models), +#' Total number of occupied cells (NOccupCells) or total number of occupied patches (NOccupPatches), +#' Ratio between occupied and suitable cells or patches (OccupSuit), +#' Species’ range, in terms of maximum and minimum coordinates (min_X, max_X, min_Y, max_Y).\cr +#' Data are written before reproduction at each reproductive season at the specified yearly interval. An extra line is written +#' at the end of the simulation. +#' +#' - \emph{Occupancy} \cr +#' reports the cell/patch probability of occupancy. This is only possible if the number of replicates is greater than \eqn{1}. +#' Two files will be produced:\cr +#' +#' 1) \code{Sim0_Occupancy.txt}: contains a list of all the cells in the landscape (\eqn{x-} and \eqn{y-}coordinates) or +#' of all the patches (PatchID). The remaining columns give the occupancy probability of the cell/patch at defined time steps. +#' The occupancy probability is obtained by dividing the number of times (replicates) that the cell/patch has been occupied in +#' a given year, by the total number of replicates. +#' +#' 2) \code{Sim0_Occupancy_Stats.txt}: Summary occupancy statistics, i.e. the mean ratio between occupied and suitable cells +#' (Mean_OccupSuit) and its standard error (Std_error) at the set time interval. +#' +#' Data will be recorded at the beginning of the year before any other process (and only once a year no matter the number +#' of reproductive seasons per year). +#' +#' - \emph{Populations} (\code{Sim0_Pop.txt}) \cr +#' contains statistics regarding each population present in the landscape at a given time interval:\cr +#' Replicate number (Rep), Year (Year), Reproductive season within the year (RepSeason), Cell location (\eqn{x-} and \eqn{y-}coordinates) or +#' patch ID (PatchID), Species number (Species; not yet used, always \eqn{0}), Number of individuals in the population (NInd), +#' Number of individuals in each stage (NInd_stageX; only in case of stage-structured models). If the reproduction is sexual, +#' these columns will be replaced by the number of females (Nfemales_stageX) and of males (Nmales_stageX) in each stage. In the case +#' of sexual model without stage structure, two columns will indicate the number of females (Nfemales) and of males (Nmales) in +#' the population. In the case of a stage-structured population, the number of juveniles born (NJuvs). If the reproduction is sexual, +#' these columns will be replaced by the number of females juveniles (NJuvFemales) and males (NJuvMales).\cr +#' As for the species’ range output, data are collected before reproduction at each reproductive +#' season at the specified yearly interval and at the end of the simulation. +#' +#' - \emph{Individuals} (\code{Sim0_Rep0_Inds.txt}) \cr +#' contains information regarding each individual at a given time step. To avoid the production of huge files, a separate file is +#' saved for each replicate. Data are recorded after settlement and before aging (in the case of overlapping generations). For each +#' individual the following data are saved: \cr +#' Replicate number (Rep), Year, Reproductive season within the year (RepSeason), Species ID (always \eqn{0}), +#' Individual ID (IndID), the individual’s Status (Status), Natal cell (Natal_X and Natal_Y) and current cell (\eqn{x} and +#' \eqn{y}) coordinates or natal and current patch IDs (Natal_patch and PatchID), Sex (0 = female, 1 = male), Age in years +#' (in case of overlapping generations), Stage (in case of stage structure), Emigration traits, Transfer traits (depending on +#' transfer method). +#' +#' - \emph{Genetics} \cr +#' From RangeShiftR 2.0, the output of the genetic data is controlled within \code{\link[RangeShiftR]{Genetics}}. You can find a detailed describtion of available oputput files there. +#' +#' - \emph{Traits} \cr +#' In the case of inter-individual variability and evolution of the dispersal traits, it is possible to output the mean traits of +#' the population. There are two types of traits output:\cr +#' +#' 1) \code{Sim0_TraitsXcell.txt / Sim0_TraitsXpatch.txt} reports mean and standard deviation of the varying/evolving traits for each +#' cell/patch, for each replicate and reproductive season at the set year interval.\cr +#' +#' 2) \code{Sim0_TraitsXrow.txt} mean and standard deviation of the varying/evolving traits computed at the row (\eqn{y}) level, +#' pulling together all the populations occupying cells in \eqn{y}. Values are reported for each replicate and reproductive season +#' at the specified yearly interval. This is particularly useful for analyzing the structuring of traits along latitudinal gradients. +#' It is possible to compute this output only for cell-based models. \cr +#' +#' Data for these outputs are collected at the same time as for the +#' range and population outputs, i.e. before reproduction at each reproductive season at the set year interval and at the end of the +#' simulation. For sexual models, the standard deviation relates to the variation between all alleles in the local population (which +#' is greater than the variation in phenotypic expression; if the phenotypic s.d. is required, it must be calculated from +#' individual-level output data). +#' +#' - \emph{Connectivity matrix} (\code{Sim0_Connect.txt}) \cr +#' is available for a patch-based model only. It presents counts of the number of individuals successfully dispersing from each patch +#' to each other patch for each year specified by \code{OutIntConn}, starting from \code{OutStartConn}. If there is more than one +#' reproductive season during the year, cumulative year-end totals are reported. Although the file contains the data required for +#' true \eqn{NxN} matrices, the data are presented in list format:\cr +#' Replicate number (Rep), Year (Year), ID number of natal patch (StartPatch), ID number of settlement patch (EndPatch), Number of +#' individuals dispersing from StartPatch to EndPatch (NInds). +#' +#' - \emph{SMS paths} (\code{Sim0_Rep0_SMSpaths.txt}) \cr +#' is available for a model with transfer method SMS only. It lists the cell-based trajectories of all (successfully or unsuccessfully) +#' dispersed individuals from the natal to the final (settlement or fatal) patch for each year specified by \code{OutIntPaths}, starting +#' from \code{OutStartPaths}. The data are presented in list format with the columns:\cr +#' Year (Year), Individual ID (IndID), consecutive step number (Step), coordinates of cell at this step (\eqn{x} and \eqn{y}), +#' status of individual (Status). +#' The status is an integer number that codes for the following possible states:\cr +#' 0 = natal patch,\cr +#' 1 = disperser,\cr +#' 2 = disperser awaiting settlement in possible suitable patch,\cr +#' 3 = waiting between dispersal events,\cr +#' 4 = completed settlement,\cr +#' 5 = completed settlement in a suitable neighbouring cell,\cr +#' 6 = died during transfer by failing to find a suitable patch (includes exceeding maximum number of steps or crossing absorbing boundary),\cr +#' 7 = died during transfer by constant, step-dependent, habitat-dependent or distance-dependent mortality,\cr +#' 8 = failed to survive annual (demographic) mortality,\cr +#' 9 = exceeded maximum age.\cr\cr +#' +#' - \emph{SMS Heat map} (\code{OutputMaps/Sim0_Land0_Rep0_Visits.txt}) \cr +#' When the transfer model is \emph{SMS}, an additional optional output is a series of maps in ASCII raster format, showing how many times each +#' cell has been visited by a dispersing individual across the whole time period of the simulation. These heat maps may be useful, for example, +#' for identifying corridors which are heavily used during the dispersal phase. One raster map is created in the \emph{Output_Maps} folder for +#' each replicate simulation, and is in the same format as the input habitat file. +#' +#' - \emph{Log file} (\code{Batch1_RS_log.csv}) \cr +#' An additional log file will be created automatically. In it is listed the time taken (in seconds) to run the simulation. +#' It may also possibly include error codes, which can occur in rare occasions when the batch input files are in themselves valid, +#' but there is an inconsistency between files or an invalid habitat code or patch number occurs in an input map file. +#' Error codes are listed in the \emph{Batch_error_codes.xlsx} file. +#' +#' @references +#' \insertAllCited{} +#' @name Simulation +#' @export Simulation +Simulation <- setClass("SimulationParams", slots = c(Simulation = "integer_OR_numeric", + Replicates = "integer_OR_numeric", + Years = "integer_OR_numeric", + Absorbing = "logical", + Gradient = "integer_OR_numeric", #Environmental gradient: 0 = none, 1 = K or 1/b, 2 = growth rate (or fecundity), 3 = local extinction probability. + GradSteep = "numeric", + Optimum = "numeric", + f = "numeric", + ExtinctOptim = "numeric", + Shifting = "logical", + ShiftRate = "numeric", + ShiftStart = "integer_OR_numeric", + ShiftEnd = "integer_OR_numeric", + LocalExt = "logical", + LocalExtProb = "numeric", + EnvStoch = "integer_OR_numeric", #Environmental stochasticity: 0 = none, 1 = global, 2 = local + EnvStochType = "integer_OR_numeric", #Environmental stochasticity type: FALSE = in growth rate, TRUE = in K or 1/b + std = "numeric", + ac = "numeric", + minR = "numeric", + maxR = "numeric", + minK = "numeric", + maxK = "numeric", + OutIntRange = "integer_OR_numeric", + OutIntOcc = "integer_OR_numeric", + OutIntPop = "integer_OR_numeric", + OutIntInd = "integer_OR_numeric", + OutIntTraitCell = "integer_OR_numeric", + OutIntTraitRow = "integer_OR_numeric", + OutIntConn = "integer_OR_numeric", + OutIntPaths = "integer_OR_numeric", + OutStartPop = "integer_OR_numeric", + OutStartInd = "integer_OR_numeric", + OutStartTraitCell = "integer_OR_numeric", + OutStartTraitRow = "integer_OR_numeric", + OutStartConn = "integer_OR_numeric", + OutStartPaths = "integer_OR_numeric", + SaveMaps = "logical", + MapsInterval = "integer_OR_numeric", + DrawLoadedSp = "logical", + SMSHeatMap = "logical", + ReturnPopMatrix = "logical", + ReturnPopDataFrame = "logical", + ReturnStages = "logical", + CreatePopFile = "logical" + #moved! PropMales = "integer_OR_numeric", #move to Demography + #moved! Harem = "integer_OR_numeric", #move to Demography + #moved! bc = "integer_OR_numeric", #move to Demography - determines density dependence + #moved! Rmax = "integer_OR_numeric", #move to Demography -> dem.lambda + #moved! K = "integer_OR_numeric", #move to Land + ) + , prototype = list(Simulation = 1L, + Replicates = 2L, + Years = 50L, + Absorbing = FALSE, + Gradient = 0L, + #GradSteep, + #Optimum, + #f, + #ExtinctOptim, + Shifting = FALSE, + #ShiftRate, + #ShiftStart, + #ShiftEnd, + LocalExt = FALSE, + #LocalExtProb, + EnvStoch = 0L, + #EnvStochType, + #std, + #ac, + #minR, + #maxR, + #minK, + #maxK, + OutIntRange = 1L, + OutIntOcc = 0L, + OutIntPop = 1L, + OutIntInd = 0L, + OutIntTraitCell = 0L, + OutIntTraitRow = 0L, + OutIntConn = 0L, + OutIntPaths = 0L, + OutStartPop = 0L, + OutStartInd = 0L, + OutStartTraitCell = 0L, + OutStartTraitRow = 0L, + OutStartConn = 0L, + OutStartPaths = 0L, + SaveMaps = FALSE, + #MapsInterval, + DrawLoadedSp = FALSE, + SMSHeatMap = FALSE, + ReturnPopMatrix = FALSE, ReturnPopDataFrame = FALSE, + ReturnStages = FALSE, + CreatePopFile = TRUE + #moved! PropMales, + #moved! Harem, + #moved! bc, + #moved! Rmax, + #moved! K, + ) +) +setValidity('SimulationParams', function(object){ + msg <- NULL + if (anyNA(object@Simulation || length(object@Simulation)!=1 )){ + msg <- c(msg, 'ID Number of current simulation must be set and of length 1!') + } + else { + if (object@Simulation<0){ + msg <- c(msg, 'Simulation ID Number must be positive or 0.') + } + } + if (anyNA(object@Replicates || length(object@Replicates)!=1 )){ + msg <- c(msg, 'Number of replicates must be set and of length 1!') + } + else { + if (object@Replicates<=0) { + msg <- c(msg, 'Number of replicates must be positive.') + } + } + if (anyNA(object@Years) || length(object@Years)!=1 ){ + msg <- c(msg,'Number of years must be set and of length 1!') + } + else { + if (object@Years<=0){ + msg <- c(msg, 'Number of year must be positive.') + } + } + if (anyNA(object@Absorbing) || length(object@Absorbing)!=1 ){ + msg <- c(msg, 'Absorbing must be set!') + } + if (anyNA(object@Gradient) || length(object@Gradient)!=1 ){ + msg <- c(msg, 'Gradient option must be set!') + } + else{ + if (object@Gradient!=0 && object@Gradient!=1 && object@Gradient!=2 && object@Gradient!=3){ + msg <- c(msg, 'Gradient must be set to 0, 1, 2 or 3!') + } + else{ + if (object@Gradient){ # Gradient = {1,2,3} + if (anyNA(object@GradSteep) || length(object@GradSteep)!=1 ){ + msg <- c(msg, 'GradSteep is required if Gradient is > 0.') + } + else { + if (object@GradSteep<0){ + msg <- c(msg, 'GradSteep has to be >= 0.') + } + } + if (anyNA(object@Optimum) || length(object@Optimum)!=1 ){ + msg <- c(msg, 'Optimum is required if Gradient is > 0.') + } + else { + if (object@Optimum<0){ + msg <- c(msg, 'Optimum has to be >= 0.') + } + } + if (anyNA(object@f) || length(object@f)!=1){ + msg <- c(msg, 'Local scaling factor f is required if Gradient is > 0.') + } + else { + if (object@f<0){ + msg <- c(msg, 'Local scaling factor f has to be >= 0.') + } + } + if (object@Gradient == 3){ + if (anyNA(object@ExtinctOptim) || length(object@ExtinctOptim)!=1){ + msg <- c(msg, 'ExtinctOptim must be set.') + } + else{ + if (object@ExtinctOptim<0 || object@ExtinctOptim>=1){ + msg <- c(msg, 'Value of ExtinctOptim mustlie in the half-open interval [0,1).') + } + } + } + if (anyNA(object@Shifting) || length(object@Shifting)!=1 ){ + msg <- c(msg, 'Shifting must be set.') + } + else{ + if (object@Shifting){ + if (anyNA(object@ShiftRate) || length(object@ShiftRate)!=1 ) { + msg <- c(msg, 'ShiftRate must be set.') + } + else{ + if (object@ShiftRate <= 0){ + msg <- c(msg, 'ShiftRate has to be > 0, if Shifting is = TRUE.') + } + } + if (anyNA(object@ShiftStart) || length(object@ShiftStart)!=1 ){ + msg <- c(msg, 'ShiftStart must be set.') + } + else{ + if (object@ShiftStart <= 0){ + msg <- c(msg, 'ShiftStart has to be > 0, if Shifting is = TRUE.') + } + } + if (anyNA(object@ShiftEnd)|| length(object@ShiftEnd)!=1 ){ + msg <- c(msg, 'ShiftEnd must be set.') + } + else{ + if(object@ShiftEnd <= 0) + msg <- c(msg, 'ShiftEnd has to be > 0, if Shifting is = TRUE.') + } + if (is.null(msg)) { + if (object@ShiftEnd <= object@ShiftStart ){ + msg <- c(msg, 'ShiftEnd must be greater than ShiftStart.') + } + } + } + } + } + else { # no gradient + if (anyNA(object@Shifting) || length(object@Shifting)!=1 ){ + msg <- c(msg, 'Shifting must be set.') + } + else{ + if (object@Shifting){ + msg <- c(msg, 'Shifting is not applicable if there is no gradient! (Gradient = 0).') + + } + } + } + } + } + if (anyNA(object@LocalExt || length(object@LocalExt)!=1)){ + msg <- c(msg, 'LocalExt must be set!') + } + else{ + if (object@LocalExt){ # LocalExt = TRUE + if (object@Gradient == 3){ + msg <- c(msg, 'LocalExt has to be FALSE if Gradient = 3 (i.e. environmental gradient in extinction probability)') + } + else { + if (anyNA(object@LocalExtProb) || length(object@LocalExtProb)!=1 ){ + msg <- c(msg, 'LocalExtProb has to be set.') + } + else{ + if (object@LocalExtProb<=0 || object@LocalExtProb>=1){ + msg <- c(msg, 'Value of LocalExtProb must be between 0 and 1.') + } + } + } + } + } + if (anyNA(object@EnvStoch) || length(object@EnvStoch)!=1){ + msg <- c(msg, 'Environmental stochasticity has to be set.') + } + else{ + if (! object@EnvStoch %in% (0:2) ) { + msg <- c(msg, 'Environmental stochasticity option (EnvStoch) has to be 0, 1 or 2.') + } + else{ + if (object@EnvStoch){ #EnvStoch = 1 or 2 + if (anyNA(object@ac) || length(object@ac)!=1 ){ + msg <- c(msg, 'Autocorrelation coefficient (ac) has to be set if environmental stochasticity is set.') + } + else { + if (object@ac < 0.0 || object@ac >= 1.0){ + msg <- c(msg, 'Autocorrelation coefficient (ac) must be in the half-open interval [0,1).') + } + } + if (anyNA(object@std) || length(object@std)!=1 ){ + msg <- c(msg, 'std has to be set if environmental stochasticity is set.') + } + else { + if (object@std <= 0.0 || object@std > 1.0){ + msg <- c(msg, 'std must be in the half-open interval (0,1].') + } + } + if (anyNA(object@EnvStochType) || length(object@EnvStochType)!=1 ){ + msg <- c(msg, 'Type of environmental stochasticity (EnvStochType) must be set.') + } + else { + if (object@EnvStochType != 1 & object@EnvStochType != 0 ){ + msg <- c(msg, 'Type of environmental stochasticity (EnvStochType) must be 0 or 1.') + } + else{ + if (object@EnvStochType == 0){ + if (anyNA(object@minR) || length(object@minR)!=1){ + msg <- c(msg, 'Minimum growth rate (minR) has to be set.') + } + else { + if (object@minR <= 0){ + msg <- c(msg, 'Minimum growth rate (minR) must be positive.') + } + else { + if (anyNA(object@maxR) || length(object@maxR)!=1){ + msg <- c(msg, 'Maximum growth rate (maxR) has to be set.') + } + else { + if (object@maxR <= object@minR){ + msg <- c(msg, 'Maximum growth rate (maxR) must be greater than minR.') + } + } + } + } + } + if (object@EnvStochType == 1){ + if (anyNA(object@minK) || length(object@minK)!=1){ + msg <- c(msg, 'Minimum growth rate (minK) has to be set.') + } + else { + if (object@minK <= 0){ + msg <- c(msg, 'Minimum growth rate (minK) must be positive.') + } + else { + if (anyNA(object@maxK) || length(object@maxK)!=1){ + msg <- c(msg, 'Maximum growth rate (maxK) has to be set.') + } + else { + if (object@maxK < 0){ + msg <- c(msg, 'Maximum growth rate (maxK) must be greater than minK.') + } + } + } + } + } + } + } + } + } + } + # Range + if (anyNA(object@OutIntRange) || length(object@OutIntRange)!=1 ){ + msg <- c(msg, 'Output interval of range (OutIntRange) has to be set.') + } + else{ + if (object@OutIntRange < 0){ + msg <- c(msg, 'Output interval of range (OutIntRange) must be positive or zero.') + } + } + # Occupancy + if (anyNA(object@OutIntOcc) || length(object@OutIntOcc)!=1 ){ + msg <- c(msg, 'Output interval of occupancy (OutIntOcc) has to be set.') + } + else{ + if (object@OutIntOcc > 0){ + if (object@Replicates < 2){ + msg <- c(msg, 'For Occupancy output, Replicates must be at least 2.') + } + } + else{ + if (object@OutIntOcc){ + msg <- c(msg, 'Output interval of occupancy (OutIntOcc) must be positive or zero.') + } + } + } + # Population + if (anyNA(object@OutIntPop) || length(object@OutIntPop)!=1 ){ + msg <- c(msg, 'Output interval of population (OutIntPop) has to be set.') + } + else { + if (object@OutIntPop > 0){ + if (anyNA(object@OutStartPop) || length(object@OutStartPop)!=1 ){ + msg <- c(msg, 'Start year of population output (OutStartPop) has to be set.') + } + else{ + if (object@OutStartPop < 0 || object@OutStartPop > object@Years){ + msg <- c(msg, 'Invalid value of output parameter OutStartPop: Value has to be positive and less than simulated Years') + } + } + } + else { + if (object@OutIntPop){ + msg <- c(msg, 'Output interval of population (OutIntPop) must be positive or zero.') + } + } + } + # Individuals + if (anyNA(object@OutIntInd) || length(object@OutIntInd)!=1 ){ + msg <- c(msg, 'Output interval of individuals (OutIntInd) has to be set.') + } + else { + if (object@OutIntInd > 0){ + if (anyNA(object@OutStartInd) || length(object@OutStartInd)!=1 ){ + msg <- c(msg, 'Start year of individuals output (OutStartInd) has to be set.') + } + else{ + if (object@OutStartInd < 0 || object@OutStartInd > object@Years){ + msg <- c(msg, 'Invalid value of output parameter OutStartInd: Value has to be positive and less than simulated Years') + } + } + } + else { + if (object@OutIntInd){ + msg <- c(msg, 'Output interval of individuals (OutIntInd) must be positive or zero.') + } + } + } + + # TraitCell + if (anyNA(object@OutIntTraitCell) || length(object@OutIntTraitCell)!=1 ){ + msg <- c(msg, 'Output interval of traits per cell (OutIntTraitCell) has to be set.') + } + else { + if (object@OutIntTraitCell > 0){ + if (anyNA(object@OutStartTraitCell) || length(object@OutStartTraitCell)!=1){ + msg <- c(msg, 'Start year of traits (per cell) output (OutStartTraitCell) has to be set.') + } + else { + if (object@OutStartTraitCell < 0 || object@OutStartTraitCell > object@Years){ + msg <- c(msg, 'Invalid value of output parameter OutStartTraitCell: Value has to be positive and less than simulated Years') + } + } + } + else{ + if(object@OutIntTraitCell){ + msg <- c(msg, 'Output interval of traits per cell (OutIntTraitCell) must be positive or zero.') + } + } + } + # TraitRow + if (anyNA(object@OutIntTraitRow) || length(object@OutIntTraitRow)!=1 ){ + msg <- c(msg, 'Output interval of traits per row (OutIntTraitRow) has to be set.') + } + else { + if (object@OutIntTraitRow > 0){ + if (anyNA(object@OutStartTraitRow) || length(object@OutStartTraitRow)!=1){ + msg <- c(msg, 'Start year of traits (per row) output (OutStartTraitRow) has to be set.') + } + else { + if (object@OutStartTraitRow < 0 || object@OutStartTraitRow > object@Years){ + msg <- c(msg, 'Invalid value of output parameter OutStartTraitRow: Value has to be positive and less than simulated Years') + } + } + } + else { + if(object@OutIntTraitRow){ + msg <- c(msg, 'Interval of traits per row output (OutIntTraitRow) must be positive or zero.') + } + } + } + # Connectivity matrix + if (anyNA(object@OutIntConn || length(object@OutIntConn)!=1 )){ + msg <- c(msg, 'Output interval of connectivity matrix (OutIntConn) has to be set.') + } + else { + if (object@OutIntConn > 0){ + if (anyNA(object@OutStartConn) || length(object@OutStartConn)!=1 ){ + msg <- c(msg, 'Start year of connectivity matrix output (OutStartConn) has to be set.') + } + else { + if (object@OutStartConn < 0 || object@OutStartConn > object@Years){ + msg <- c(msg, 'Invalid value of output parameter OutStartConn: Value has to be positive and less than simulated Years') + } + } + } + else { + if(object@OutIntConn){ + msg <- c(msg, 'Interval of connectivity output (OutIntConn) must be positive or zero.') + } + } + } + # Paths record + if (anyNA(object@OutIntPaths || length(object@OutIntPaths)!=1 )){ + msg <- c(msg, 'Output interval of SMS paths (OutIntPaths) has to be set.') + } + else { + if (object@OutIntPaths > 0){ + if (anyNA(object@OutStartPaths) || length(object@OutStartPaths)!=1 ){ + msg <- c(msg, 'Start year of SMS paths output (OutStartPaths) has to be set.') + } + else { + if (object@OutStartPaths < 0 || object@OutStartPaths > object@Years){ + msg <- c(msg, 'Invalid value of output parameter OutStartPaths: Value has to be positive and less than simulated Years') + } + } + } + else { + if(object@OutIntPaths){ + msg <- c(msg, 'Interval of SMS paths output (OutIntConn) must be positive or zero.') + } + } + } + # Maps + if (anyNA(object@SaveMaps) || length(object@SaveMaps)!=1 ){ + msg <- c(msg, 'SaveMaps has to be set') + } + else { + if (object@SaveMaps){ # TRUE + if (anyNA(object@MapsInterval) || length(object@MapsInterval)!=1 ){ + msg <- c(msg, 'MapsInterval has to be set.') + } + else{ + if(object@MapsInterval < 1){ + msg <- c(msg, 'MapsInterval must be positive.') + } + } + if (anyNA(object@DrawLoadedSp) || length(object@DrawLoadedSp)!=1 ){ + msg <- c(msg, 'DrawLoadedSp has to be set.') + } + } + } + if (anyNA(object@SMSHeatMap) || length(object@SMSHeatMap)!=1 ){ + msg <- c(msg, 'SMSHeatMap has to be set') + } + # R Output + if (anyNA(object@ReturnPopMatrix) || length(object@ReturnPopMatrix)!=1 || anyNA(object@ReturnPopDataFrame) || length(object@ReturnPopDataFrame)!=1){ + msg <- c(msg, 'ReturnPopMatrix or ReturnPopDataFrame has to be set') + } + + # ReturnStages must be logical + if(anyNA(object@ReturnStages)){ + msg <- c(msg, 'ReturnStages has to be set') + } + if (anyNA(object@CreatePopFile) || length(object@CreatePopFile)!=1 ){ + msg <- c(msg, 'CreatePopFile has to be set') + } + if (is.null(msg)) TRUE else msg +}) + +setMethod("initialize", "SimulationParams", function(.Object, ...) { + this_func = "Simulation(): " + args <- list(...) + .Object <- callNextMethod() + if ( length(args) == 0 ) { + validObject(.Object) + } + if(.Object@Gradient == 0){ + .Object@GradSteep = -9L + if (!is.null(args$GradSteep)) { + warning(this_func, 'GradSteep', warn_msg_ignored, 'since Gradient is 0.', call. = FALSE) + } + .Object@Optimum = -9L + if (!is.null(args$Optimum)) { + warning(this_func, 'Optimum', warn_msg_ignored, 'since Gradient is 0.', call. = FALSE) + } + .Object@f = -9L + if (!is.null(args$f)) { + warning(this_func, 'f', warn_msg_ignored, 'since Gradient is 0.', call. = FALSE) + } + } + if (.Object@Gradient != 3){ + .Object@ExtinctOptim = -9L + if (!is.null(args$ExtinctOptim)) { + warning(this_func, 'ExtinctOptim is only used if Gradient is 3 and thus ', warn_msg_ignored , call. = FALSE) + } + } + if (!.Object@Shifting){ + .Object@ShiftRate = -9L + if (!is.null(args$ShiftRate)) { + warning(this_func, 'ShiftRate', warn_msg_ignored, 'since Shifting is = FALSE', call. = FALSE) + } + .Object@ShiftStart = -9L + if (!is.null(args$ShiftStart)) { + warning(this_func, 'ShiftStart', warn_msg_ignored, 'since Shifting is = FALSE', call. = FALSE) + } + .Object@ShiftEnd = -9L + if (!is.null(args$ShiftEnd)) { + warning(this_func, 'ShiftEnd', warn_msg_ignored, 'since Shifting is = FALSE', call. = FALSE) + } + } + if (!.Object@LocalExt){ + .Object@LocalExtProb = -9L + if (!is.null(args$LocalExtProb)) { + warning(this_func, 'LocalExtProb', warn_msg_ignored, 'since LocalExt is = FALSE', call. = FALSE) + } + } + if (.Object@EnvStoch){ # EnvStoch = {1,2} + if (.Object@EnvStochType == 1) { # EnvStoch in K + .Object@minR = -9L + if (!is.null(args$minR)) { + warning(this_func, 'minR', warn_msg_ignored, 'since EnvStochType is 1.', call. = FALSE) + } + .Object@maxR = -9L + if (!is.null(args$maxR)) { + warning(this_func, 'maxR', warn_msg_ignored, 'since EnvStochType is 1.', call. = FALSE) + } + } + if (.Object@EnvStochType == 0){ # EnvStoch in r + .Object@minK = -9L + if (!is.null(args$minK)) { + warning(this_func, 'minK', warn_msg_ignored, 'since EnvStochType is 0.', call. = FALSE) + } + .Object@maxK = -9L + if (!is.null(args$maxK)) { + warning(this_func, 'maxK', warn_msg_ignored, 'since EnvStochType is 0.', call. = FALSE) + } + } + } + else{ # EnvStoch = 0 + .Object@EnvStochType = -9L + if (!is.null(args$EnvStochType)) { + warning(this_func, 'EnvStochType', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + .Object@ac = -9L + if (!is.null(args$ac)) { + warning(this_func, 'ac', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + .Object@std = -9L + if (!is.null(args$std)) { + warning(this_func, 'std', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + .Object@minR = -9L + if (!is.null(args$minR)) { + warning(this_func, 'minR', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + .Object@maxR = -9L + if (!is.null(args$maxR)) { + warning(this_func, 'maxR', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + .Object@minK = -9L + if (!is.null(args$minK)) { + warning(this_func, 'minK', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + .Object@maxK = -9L + if (!is.null(args$maxK)) { + warning(this_func, 'maxK', warn_msg_ignored, 'since EnvStoch is 0.', call. = FALSE) + } + } + if (!.Object@OutIntPop){ + .Object@OutStartPop = 0L + if(!is.null(args$OutStartPop)){ + warning(this_func, 'OutStartPop', warn_msg_ignored, 'since OutIntPop is zero (output disabled).', call. = FALSE) + } + } + if (!.Object@OutIntInd){ + .Object@OutStartInd = 0L + if(!is.null(args$OutStartInd)){ + warning(this_func, 'OutStartInd', warn_msg_ignored, 'since OutIntInd is zero (output disabled).', call. = FALSE) + } + } + if (!.Object@OutIntTraitCell){ + .Object@OutStartTraitCell = 0L + if(!is.null(args$OutStartTraitCell)){ + warning(this_func, 'OutStartTraitCell', warn_msg_ignored, 'since OutIntTraitCell is zero (output disabled).', call. = FALSE) + } + } + if (!.Object@OutIntTraitRow) { + .Object@OutStartTraitRow = 0L + if(!is.null(args$OutStartTraitRow)){ + warning(this_func, 'OutStartTraitRow', warn_msg_ignored, 'since OutIntTraitRow is zero (output disabled).', call. = FALSE) + } + } + if (!.Object@OutIntConn){ + .Object@OutStartConn = 0L + if(!is.null(args$OutStartConn)){ + warning(this_func, 'OutStartConn', warn_msg_ignored, 'since OutIntConn is zero (output disabled).', call. = FALSE) + } + } + if (!.Object@OutIntPaths){ + .Object@OutStartPaths = 0L + if(!is.null(args$OutStartPaths)){ + warning(this_func, 'OutStartPaths', warn_msg_ignored, 'since OutIntPaths is zero (output disabled).', call. = FALSE) + } + } + + if (!.Object@SaveMaps){ + .Object@MapsInterval = -9L + if(!is.null(args$MapsInterval)){ + warning(this_func, 'MapsInterval', warn_msg_ignored, 'since SaveMaps = FALSE.', call. = FALSE) + } + if(!is.null(args$DrawLoadedSp)){ + warning(this_func, 'DrawLoadedSp', warn_msg_ignored, 'since SaveMaps = FALSE.', call. = FALSE) + } + } + return(.Object) +}) +setMethod("show", "SimulationParams", function(object) { + cat(" Simulation #", object@Simulation, "\n") + cat(" -----------------\n") + cat(" Replicates = ", object@Replicates, "\n") + cat(" Years = ", object@Years, "\n") + cat(" Absorbing = ", object@Absorbing, "\n") + if (object@Gradient) { + if (object@Shifting) cat(" Shifting Environmental Gradient in") + else cat(" Environmental Gradient in") + if (object@Gradient==1) cat(" K_or_DensDep:\n") + if (object@Gradient==2) cat(" r/phi:\n") + if (object@Gradient==3) cat(" e:\n") + cat(" G = ", object@GradSteep, ", y_opt = ", object@Optimum , sep = "") + if (object@Gradient==3) cat(", e_opt =", object@ExtinctOptim, "\n") else cat("\n") + cat(" f =", object@f, "\n") + } + if (object@Shifting) { + cat(" ShiftRate =", object@ShiftRate, "rows per year; from year", object@ShiftStart, "to", object@ShiftEnd, "\n") + } + if (object@LocalExt) { + cat(" Local Extinction probalitity =", object@LocalExtProb, "\n") + } + if (object@EnvStoch) { + if (object@EnvStoch==1) cat(" Global") + if (object@EnvStoch==2) cat(" Local") + cat(" Environmental Stochasticity in:") + if (object@EnvStochType) cat(" K_or_DensDep\n") else cat(" r/phi \n") + cat(" Std = ", object@std, "\n") + cat(" ac = ", object@ac, "\n Min/Max limits = ") + if (object@EnvStochType) cat(object@minK, object@maxK, "\n") else cat(object@minR, object@maxR, "\n") + } + cat(" File Outputs:\n") + if (object@OutIntRange) { + cat(" Range, every", object@OutIntRange, "years\n") + } + if (object@OutIntOcc) { + cat(" Occupancy, every", object@OutIntOcc, "years\n") + } + if (object@OutIntPop) { + cat(" Populations, every", object@OutIntPop, "years, starting year", object@OutStartPop) + if (object@ReturnPopMatrix) { + cat("\n R output: Matrix of") + if (length(object@ReturnStages)==1) { + cat("\n total population size") + } else { + cat("\n population size for stage ") + for (i in 1:length(object@ReturnStages)) { + if (object@ReturnStages[i]) { + cat("\n ", i) + } + } + } + } + if (object@ReturnPopDataFrame) { + cat("\n R output: data.frame of") + if (length(object@ReturnStages)==1) { + cat("\n total population size") + } else { + cat("\n population size for stage ") + for (i in 1:length(object@ReturnStages)) { + if (object@ReturnStages[i]) { + cat("\n ", i) + } + } + } + } + cat("\n") + } + if (object@OutIntInd) { + cat(" Individuals, every", object@OutIntInd, "years, starting year", object@OutStartInd, "\n") + } + if (object@OutIntTraitCell) { + cat(" Traits/cell, every", object@OutIntTraitCell, "years, starting year", object@OutStartTraitCell, "\n") + } + if (object@OutIntTraitRow) { + cat(" Traits/row, every", object@OutIntTraitRow, "years, starting year", object@OutStartTraitRow, "\n") + } + if (object@OutIntConn) { + cat(" Connectivity, every", object@OutIntConn, "years, starting year", object@OutStartConn, "\n") + } + if (object@OutIntPaths) { + cat(" SMS paths, every", object@OutIntPaths, "years, starting year", object@OutStartPaths, "\n") + } + if (object@SMSHeatMap) { + cat(" SMS heat map\n") + } +}) diff --git a/RangeShiftR/R/output_handling.R b/RangeShiftR/R/output_handling.R new file mode 100644 index 0000000..a20d2e6 --- /dev/null +++ b/RangeShiftR/R/output_handling.R @@ -0,0 +1,950 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +#------------------- +# Output handling and plotting functions +#------------------- + + +#--------------------------------------------------------- + +### READING OUTPUT FILES + + +#' Read 'range' file +#' +#' Read the RangeShiftR output file 'range' into a data.frame, if it was generated. +#' @param s RSmaster parameter object +#' @param dirpath RS directory path +#' @return a data.frame +#' @export +setGeneric("readRange", function(s,dirpath) standardGeneric("readRange") ) + +setMethod("readRange", c(s="RSparams", dirpath="character"), function(s,dirpath) { + path <- paste0(dirpath, "Outputs/Batch", s@control@batchnum, "_Sim", s@simul@Simulation, "_Land", s@land@LandNum, "_Range.txt") + if(file.exists(path)){ + return(read.table(path, h = T, sep = "\t")) + }else { + warning("The 'range' output file for this simulation does not exist.", call. = FALSE) + } +}) + + +#' Read 'pop' file +#' +#' Read the RangeShiftR output file 'pop' into a data.frame, if it was generated. +#' @param s RSmaster parameter object +#' @param dirpath RS directory path +#' @param center In a cell-based model, the x- and y- coordinates will be converted from *nrow* and *ncol* (as in the 'pop' output file) +#' to true coordinates of the center of the cell measured in metres. +#' @return a data.frame +#' @export +setGeneric("readPop", function(s,dirpath,...) standardGeneric("readPop") ) + +setMethod("readPop", c(s="RSparams", dirpath="character"), function(s,dirpath,center=TRUE) { + path <- paste0(dirpath, "Outputs/Batch", s@control@batchnum, "_Sim", s@simul@Simulation, "_Land", s@land@LandNum, "_Pop.txt") + if(file.exists(path)){ + pop_table <- read.table(path, h = T, sep = "\t") + if (sum(grepl('x',names(pop_table))) & center){ + pop_table$x <- (pop_table$x+0.5)*s@land@Resolution + pop_table$y <- (pop_table$y+0.5)*s@land@Resolution + } + return(pop_table) + }else { + warning("The 'pop' output file for this simulation does not exist.", call. = FALSE) + } +}) + + +#--------------------------------------------------------- + +### PROCESS OUTPUT + + +#' ColonisationStats +#' +#' This function produces patch statistics and maps on occupancy probability and mean time to colonisation. +#' +#' It uses the RangeShiftR 'population' output data. +#' @usage ColonisationStats(x, y = getwd(), years = numeric(0), maps = FALSE) +#' ColonisationStats(x, y = NULL, years = numeric(0)) +#' @param x,y Either the parameter master (\code{x}) and RS directory path (\code{y}) of the simulation or, alternatively,\cr +#' the population output as a dataframe (\code{x}). In this case \code{y} is an optional parameter taking the patch map(s) as a raster layer (stack), +#' which will then be used to produce maps of the patch statistics. For more info on this, see the Details. +#' @param years Years at which the probabilty of occupancy over all replicates will be calculated. +#' @param maps Only in the parameter master (=\code{x}) notation: For each given \code{year}, uses the current patch map (in case of a dynamic landscape, otherwise the static patch map) +#' to produce a raster of occupancy probabilties. For time to colonisation, uses the current patch map of last year of population record. +#' @details In the population dataframe (=\code{x}) notation, there are 3 options on how many maps to produce: +#' (1) y = NULL: no raster maps produced. +#' (2) y is a RasterLayer: All statistics projected onto the same patch map. +#' (3) y is a RasterStack with 2 layers: The first will be used for probabilty of occupancy for all years, the second will be used for time to colonisation. +#' (4) y is a RasterStack with length(years)+1 layers: The first ones will be used for probabilty of occupancy on each year, the last for time to colonisation. +#' @return a list with the elements +#' \code{occ_prob} (a dataframe with mean (over all replicates) probabilty of occupancy for each patch (in rows) at the given year(s) in columns),\cr +#' \code{col_time} (a dataframe with first recorded year of colonisation for each patch; with replicates in columns and rows named by patch-IDs),\cr +#' Optional:\cr\cr +#' \code{patch_occ_prob} (a raster (stack) with the data from \code{occ_prob} stored in the respective patch cells per given year),\cr +#' \code{patch_col_time} (a raster with the data from \code{col_time_mean} stored in their respective patch cells) +#' @export +setGeneric("ColonisationStats", function(x, ...) standardGeneric("ColonisationStats") ) + +setMethod("ColonisationStats", "data.frame", function(x, y = NULL, years = numeric(0)) { +#test <- function(x, y = NULL, years = numeric(0)) { + if(class(years) %in% c("integer","numeric") ){ + if(length(years)==0) { + years <- max(x$Year) + }else{ + # check that requested years are in dataset + if(!all(years %in% unique(x$Year))){ + years <- sort(years[years %in% unique(x$Year)]) + warning("ColonisationStats(): Some of the given years are not included in the population dataframe. They will be ignored.", call. = FALSE) + } + } + }else{ + warning("ColonisationStats(): Years must be of class numeric or integer.", call. = FALSE) + return(NULL) + } + + if("PatchID" %in% names(x)) { + patchbased <- TRUE + x <- x[x$PatchID!=0,] # exclude matrix patch + } else { # cell-based -> create PatchIDs from (x,y)-coordinates: + patchbased <- FALSE + x[c("x","y")] <- x[c("x","y")]+1 # have counting start at 1 + maxX <- max(x$x) + maxY <- max(x$y) + digitsY <- ifelse(maxY < 1, 0, floor(log10(maxY)) + 1) + x$PatchID <- (x$x*(10^digitsY)) + (x$y) #+ (maxY+1-x$y) + } + + x <- subset(x, NInd>0, select = c("Rep","PatchID","Year","NInd") ) + reps <- sort(unique(x$Rep)) + n=length(reps) + + # calculate per patch + patchstats <- sapply(split(x, f=x$PatchID), + FUN=function(xs){ + return(list(occprob = sapply(years, + FUN=function(year){ + sum(xs$Year==year)/n + }), + coltime = sapply(reps, + FUN=function(rep){ + xxs <- xs[xs$Rep==rep,"Year"] + ifelse(length(xxs),min(xxs),NA) + } + ) + )) + } + ) + patches <- as.integer(colnames(patchstats)) + + # Occupancy Probability + occ_prob <- data.frame(patchstats["occprob",]) + rownames(occ_prob) <- years + if(patchbased) occ_prob <- cbind(data.frame(patch=patches), t(occ_prob)) + else occ_prob <- cbind(data.frame(x=floor(patches/(10^digitsY)),y=patches%%(10^digitsY)), t(occ_prob)) + rownames(occ_prob) <- NULL + + # Time to Colonisation + col_time <- data.frame(patchstats["coltime",]) + if(patchbased){ + col_time <- cbind(data.frame(patch=patches), t(col_time)) + names(col_time) <- c("patch",paste0("rep.",as.character(reps))) + }else{ + col_time <- cbind(data.frame(x=occ_prob$x,y=occ_prob$y), t(col_time)) + names(col_time) <- c("x","y",paste0("rep.",as.character(reps))) + } + rownames(col_time) <- NULL + + + # create maps + if(!is.null(y)){ + if(patchbased){ + col_time_mean <- rowMeans(col_time[,-1], na.rm = TRUE) + names(col_time_mean) <- patches + }else{ + col_time_mean <- rowMeans(col_time[,-(1:2)], na.rm = TRUE) + } + #require('raster') + + # if(class(y) == "RasterLayer" || class(y) == "RasterStack" ){ # old raster + if(class(y) == "RasterLayer" || class(y) == "RasterStack" ){ # if users use raster package, transform to SpatRaster + y <- terra::rast(y) + } + if( class(y) == "SpatRaster" ){ + onelayer = FALSE + # if(class(y) == "RasterLayer") onelayer = TRUE + # if(class(y) == "RasterStack") if(length(y@layers)==1 ) onelayer = TRUE + if(length(names(y)) == 1) onelayer = TRUE + # if(length(y) > 1) if(length(y@layers)==1 ) onelayer = TRUE + + + if(patchbased){ + # non-dynamic landscape + if(onelayer){ + # initialise output rasters + if(class(y) == "SpatRaster") y <- y[[1]] + patch_occ_prob <- patch_col_time <- y + # denote matrix with NA + terra::values(patch_occ_prob)[terra::values(y)==0] <- terra::values(patch_col_time)[terra::values(y)==0] <- NA + # init all habitat patches to also address those that never had a population (these don't occur in RS output) + terra::values(patch_occ_prob)[terra::values(y) >0] <- 0 + terra::values(patch_col_time)[terra::values(y) >0] <- -9 + + # fill output rasters + #if(length(years)>1){ + patch_outstack <- terra::rast() + for (j in 1:length(years)){ + patch_outstack <- c(patch_outstack, patch_occ_prob) + for (i in patches){ + terra::values(patch_outstack[[j]])[terra::values(y)==i] <- occ_prob[occ_prob$patch==i,paste(years[j])] + } + } + #} + #else{ + # for (i in patches){ + # raster::values(patch_occ_prob)[raster::values(y)==i] <- occ_prob[occ_prob$patch==i,"occ_prob"] + # } + # patch_outstack <- patch_occ_prob + #} + + for (i in patches){ + terra::values(patch_col_time)[terra::values(y)==i] <- ifelse(is.na(col_time_mean[paste(i)]),-9,col_time_mean[paste(i)]) + } + + return(list(occ_prob=occ_prob, col_time=col_time, map_occ_prob=patch_outstack, map_col_time=patch_col_time)) + + }#else warning("ColonisationStats(): The given map raster stack must have only one layer for a non-dynamic landscape.", call. = FALSE) + + # dynamic landscape + if(!onelayer){ + + N_layers <- length(years)+1 + if( length(names(y)) != N_layers ){ + warning("ColonisationStats(): Number of raster layers must be either 1 or number of years plus 1.", call. = FALSE) + } + else{ + # initialise output rasters + patch_outstack <- y + # denote matrix with NA + terra::values(patch_outstack)[terra::values(y)==0] <- NA + # all habitat patches to address those that never had a population + terra::values(patch_outstack)[terra::values(y)>0] <- 0.0 + terra::values(patch_outstack[[N_layers]])[terra::values(y[[N_layers]])>0] <- -9 + + # fill output rasters + for (i in patches){ + #if(N_layers==2){ + # raster::values(patch_outstack[[1]])[raster::values(y[[1]])==i] <- occ_prob[occ_prob$patch==i,"occ_prob"] + #}else { + for (j in 1:length(years)){ + terra::values(patch_outstack[[j]])[terra::values(y[[j]])==i] <- occ_prob[occ_prob$patch==i,paste(years[j])] + } + #} + terra::values(patch_outstack[[N_layers]])[terra::values(y[[N_layers]])==i] <- ifelse(is.na(col_time_mean[paste(i)]),-9,col_time_mean[paste(i)]) + } + return(list(occ_prob=occ_prob, col_time=col_time, map_occ_prob=patch_outstack[[-N_layers]], map_col_time=patch_outstack[[N_layers]])) + + } + }#else warning("ColonisationStats(): Given map must be a raster stack for a dynamic landscape.", call. = FALSE) + + }else{ # cell-based + if(onelayer){ + + # initialise output rasters + if(class(y) == "SpatRaster") y <- y[[1]] + patch_occ_prob <- patch_col_time <- y + # init all habitat patches to also address those that never had a population (these don't occur in RS output) + terra::values(patch_occ_prob)[!is.na(terra::values(y))] <- 0 + terra::values(patch_col_time)[!is.na(terra::values(y))] <- -9 + # make value index from patchIDs + value_ix <- floor(patches/(10^digitsY))+(nrow(y)-patches%%(10^digitsY))*ncol(y) + + # fill output rasters + #if(length(years)>1){ + patch_outstack <- terra::rast() + for (j in 1:length(years)){ + patch_outstack <- c(patch_outstack, patch_occ_prob) + terra::values(patch_outstack[[j]])[value_ix] <- occ_prob[,j+2] + } + crs(patch_outstack) <- NA + #} else{ + # raster::values(patch_occ_prob)[value_ix] <- occ_prob[,1] + # patch_outstack <- patch_occ_prob + #} + terra::values(patch_col_time)[value_ix] <- ifelse(is.na(col_time_mean[]),-9,col_time_mean[]) + crs(patch_col_time) <- NA + + return(list(occ_prob=occ_prob, col_time=col_time, map_occ_prob=patch_outstack, map_col_time=patch_col_time)) + + }else warning("ColonisationStats(): The given map raster stack must have only one layer for a cell-based landscape.", call. = FALSE) + } + + }else warning("ColonisationStats(): Given map is not a raster layer or raster stack.", call. = FALSE) + } + return(list(occ_prob=occ_prob, col_time=col_time)) +}) + +setMethod("ColonisationStats", "RSparams", function(x, y = getwd(), years = numeric(0), maps = FALSE) { + res <- NULL + if(class(x@land)=="ImportedLandscape" || class(maps)=="logical") { + if(x@simul@OutIntPop>0){ + if(!is.null(y) & class(y)=="character" ){ + if(class(years) %in% c("integer","numeric") ){ + + # read population output + pop_df <- try(readPop(x, y, center=FALSE)) + if ( class(pop_df) == "try-error" ) { # try() returned a warning + warning("ColonisationStats(): Couldn't read population output for this simulation.", call. = FALSE) + return(NULL) + } + if ( class(pop_df) == "character" ) return(NULL) # readPop() returned a warning + + # set year to last recorded year if none is given + if(length(years)==0) years <- max(pop_df$Year) + + # read patch rasters if needed + if(maps){ + #require('raster') + if(x@control@patchmodel){ # for patch-based model, read all relevant patch-maps + # non-dynamic landscape + if(length(x@land@LandscapeFile)==1){ + + patch_r <- try(terra::rast(paste0(dirpath, "Inputs/", x@land@PatchFile))) + if( class(patch_r) == "try-error" ) warning("ColonisationStats(): Couldn't read patch raster file ", x@land@PatchFile , call. = FALSE) + + if( class(pop_df) == "data.frame" & class(patch_r) == "SpatRaster" ) res <- ColonisationStats(pop_df,patch_r,years) + + } + # dynamic landscape + else{ + patch_r <- terra::rast() + # rasters for occ_prob output + for(year in years){ + current <- which(x@land@DynamicLandYears == max(x@land@DynamicLandYears[x@land@DynamicLandYears<=year]) ) + patch_curr <- try(terra::rast(paste0(dirpath, "Inputs/", x@land@PatchFile[current]))) + if ( class(patch_curr) == "try-error" ) warning("ColonisationStats(): Couldn't read patch raster file nr ", current , " for this simulation.", call. = FALSE) + else patch_r <- c(patch_r, patch_curr) + } + # rasters for col_time output + year <- max(pop_df$Year) + current <- which(x@land@DynamicLandYears == max(x@land@DynamicLandYears[x@land@DynamicLandYears<=year]) ) + patch_curr <- try(terra::rast(paste0(dirpath, "Inputs/", x@land@PatchFile[current]))) + if ( class(patch_curr) == "try-error" ) warning("ColonisationStats(): Couldn't read patch raster file nr ", current , " for this simulation.", call. = FALSE) + else patch_r <- c(patch_r , patch_curr) + + if(class(pop_df) == "data.frame" & nlyr(patch_r)==(length(years)+1) ) res <- ColonisationStats(pop_df,patch_r,years) + } + }else{ + # for cell-based model, read only main habitat maps to use as raster template + patch_r <- try(terra::rast(paste0(dirpath, "Inputs/", x@land@LandscapeFile[1]))) + if ( class(patch_r) == "try-error" ) warning("ColonisationStats(): Couldn't read patch raster file nr ", current , " for this simulation.", call. = FALSE) + if(class(pop_df) == "data.frame" & class(patch_r) == "SpatRaster" ) res <- ColonisationStats(pop_df,patch_r,years) + } + }else { # no maps requested + if(class(pop_df) == "data.frame") res <- ColonisationStats(pop_df,NULL,years) + } + + if(is.null(res)) warning("ColonisationStats(): Couldn't get population output or patch raster file.", call. = FALSE) + else return(res) + + }else { + warning("ColonisationStats(): Years must be of class numeric or integer.", call. = FALSE)} + }else { + warning("ColonisationStats(): dirpath must be set", call. = FALSE)} + }else{ + warning("ColonisationStats(): This simulation has population output turned off (OutIntPop=0), but that is needed to calculate the colonisation statistics.", call. = FALSE)} + }else { + warning("ColonisationStats(): For Artificial Landscape models, maps must be FALSE", call. = FALSE)} +}) + + + + +#--------------------------------------------------------- + +### PLOTTING + + +#' Plot Abundance +#' +#' Uses the RangeShiftR output data 'range' to generate abundance time series. +#' Plots the mean abundance over all replicates, and optionally the standard deviation and/or the single replicates. +#' @param s RSparams object or a data.frame in the 'range' file format +#' @param dirpath RS directory path; required if \code{s} is a \code{RSparams} +#' @param sd plot standard deviation? (default is \code{FALSE}) +#' @param replicates plot the replicates? (default is \code{TRUE}) +#' @param ylim upper limit to the y-axis +#' @export +setGeneric("plotAbundance", function(s,...) standardGeneric("plotAbundance") ) + +setMethod("plotAbundance", "data.frame", function(s, sd = FALSE, replicates = TRUE, ylim=NULL, ...) { + # Calculate means + rep_means <- aggregate(NInds~Year, data = s, FUN = "mean") + # Calculate standard deviation + if (sd) { + rep_sd <- aggregate(NInds~Year, data = s, FUN = "sd") + rep_sd[is.na(rep_sd)] <- 0 + } + # Set y-limits + if (is.null(ylim)) { + if (replicates) { + ylim <- c(min(s$NInds),max(s$NInds)) + }else { + if (sd) { + ylim <- c(max(0,min(rep_means$NInds-rep_sd$NInds)), max(rep_means$NInds+rep_sd$NInds)) + }else{ + ylim <- c(min(rep_means$NInds),max(rep_means$NInds)) + } + } + } + # New plot + plot(NULL, type = "n", ylab = "Abundance", xlab = "Year", xlim=c(0, max(s$Year)), ylim=ylim, ...) + # Plot standard deviation + if (sd) { + polygon(c(rep_sd$Year,rev(rep_sd$Year)), c(rep_means$NInds+rep_sd$NInds, rev(pmax(0,rep_means$NInds-rep_sd$NInds))), border=NA, col='grey80') + } + # Plot replicates + if (replicates) { + for (i in 0:max(s$Rep)) { + lines(s$Year[s$Rep==i], s$NInds[s$Rep==i], type = "l", lwd = 0.5) + } + } + # Plot abundance + lines(rep_means$Year, rep_means$NInds, type = "l", lwd = 3, col = "red") +}) +setMethod("plotAbundance", "RSparams", function(s, dirpath, ...) { + if (class(dirpath)=="character"){ + range_table <- try(readRange(s, dirpath)) + if ( class(range_table) == "data.frame") { + plotAbundance(range_table, ...) + } + }else{ + warning("plotAbundance(): dirpath must be of type character.", call. = TRUE) + } +}) + + +#' Plot Occupancy +#' +#' Uses the RangeShiftR output data 'range' to generate occupancy time series. +#' Plots the mean occupancy over all replicates, and optionally the standard deviation and/or the single replicates. +#' @param s RSparams object or a data.frame in the 'range' file format +#' @param dirpath RS directory path; required if \code{s} is a \code{RSparams} +#' @param sd plot standard deviation? (default is \code{FALSE}) +#' @param replicates plot the replicates? (default is \code{TRUE}) +#' @param ylim upper limit to the y-axis +#' @export +setGeneric("plotOccupancy", function(s,...) standardGeneric("plotOccupancy") ) + +setMethod("plotOccupancy", "data.frame", function(s, sd = FALSE, replicates = TRUE, ylim=NULL, ...) { + names(s)[grep('NOccup',names(s))] <- 'NOccup' + # Calculate means + rep_means <- aggregate(NOccup~Year, data = s, FUN = "mean") + # Calculate standard deviation + if (sd) { + rep_sd <- aggregate(NOccup~Year, data = s, FUN = "sd") + rep_sd[is.na(rep_sd)] <- 0 + } + # Set y-limits + if (is.null(ylim)) { + if (replicates) { + ylim <- c(min(s$NOccup),max(s$NOccup)) + } else { + if (sd) { + ylim <- c(max(0,min(rep_means$NOccup-rep_sd$NOccup)), max(rep_means$NOccup+rep_sd$NOccup)) + } else { + ylim <- c(min(rep_means$NOccup),max(rep_means$NOccup)) + } + } + } + # New plot + plot(NULL, type = "n", ylab = "Occupancy", xlab = "Year", xlim=c(0, max(s$Year)), ylim=ylim, ...) + # Plot standard deviation + if (sd) { + polygon(c(rep_sd$Year,rev(rep_sd$Year)), c(rep_means$NOccup+rep_sd$NOccup, rev(pmax(0,rep_means$NOccup-rep_sd$NOccup))), border=NA, col='grey80') + } + # plot replicates + if (replicates) { + for (i in 0:max(s$Rep)) { + lines(s$Year[s$Rep==i], s$NOccup[s$Rep==i], type = "l", lwd = 0.5) + } + } + # Plot occupancy + lines(rep_means$Year, rep_means$NOccup, type = "l", lwd = 3, col = "blue") +}) +setMethod("plotOccupancy", "RSparams", function(s, dirpath, ...) { + if (class(dirpath)=="character"){ + range_table <- try(readRange(s, dirpath)) + if ( class(range_table) == "data.frame") { + plotOccupancy(range_table, ...) + } + }else{ + warning("plotOccupancy(): dirpath must be of type character.", call. = TRUE) + } +}) + + +#--------------------------------------------------------- + +#--- SMS PathLenghts + +#' Get the distribution of SMS Path Lengths +#' +#' Reads the RangeShiftR output files 'MovePaths' (if they were generated) to get the distribution of lengths of SMS +#' paths taken in all recorded years. +#' @param s RSmaster parameter object +#' @param dirpath RS directory path +#' @return a data.frame that contains the mean (over replicates) number of SNS paths of a given length (rows) per simulated map (columns) +#' @export +setGeneric("SMSpathLengths", function(s,dirpath,...) standardGeneric("SMSpathLengths") ) + +setMethod("SMSpathLengths", c(s="RSparams", dirpath="character"), function(s,dirpath) { + if(class(s@dispersal@Transfer)!="StochMove"){ + warning("SMSpathLengths(): Transfer must be of type SMS.", call. = TRUE) + return(NULL) + } + if(s@simul@OutIntPaths<1){ + warning("SMSpathLengths(): Output of SMS paths ('OutIntPaths') is disabled in this RS simulation.", call. = TRUE) + return(NULL) + } + + maxLength = s@dispersal@Settlement@MaxSteps + if(maxLength<1) maxLength = as.integer(log(.015)/log(1-s@dispersal@Transfer@StepMort)) + 1 + year_blocks = s@land@DynamicLandYears + nr_maps = length(year_blocks) + + steps_sum <- matrix(0, nrow = maxLength, ncol = nr_maps) + rownames(steps_sum) <- sapply(1:maxLength, FUN=paste0) + null_tb <- rep(0,maxLength) + names(null_tb) <- sapply(1:maxLength, FUN=paste0) + for(i in 0:(s@simul@Replicates-1)){ + steps <- try(read.table(paste0(dirpath, + "Outputs/Batch",s@control@batchnum, + "_Sim",s@simul@Simulation, + "_Land",s@land@LandNum, + "_Rep",i, + "_MovePaths.txt"), + header = T)) + if ( class(steps) == "try-error" ) { + warning(cat("SMSpathLengths(): Couldn't read MovePaths output for replicate",i,", skipping it."), call. = FALSE) + #return(NULL) + }else{ + steps_y <- sapply(seq(nr_maps), FUN = function(y){ + tb <- null_tb + lo <- year_blocks[y] + if (y==nr_maps) tb_n <- table(aggregate(Step~IndID, data=subset(steps, Year >= lo), FUN = max)$Step) + else { + up <- year_blocks[y+1] + tb_n <- table(aggregate(Step~IndID, data=subset(steps, Year >= lo & Year < up), FUN = max)$Step) + } + ix <- names(tb) %in% names(tb_n) + tb[ix] <- tb_n[1:sum(ix)] + tb + }) + steps_sum <- steps_sum + steps_y + } + } + colnames(steps_sum) <- sapply(1:nr_maps, function(m){paste0('Map_',m)}) + # mean over replicates + steps_sum <- data.frame(steps_sum / s@simul@Replicates) + + return(steps_sum) +}) + + + + +#--------------------------------------------------------- + +### B FUNCTION + + +## ---- Backend matrix model simulation function ----- + +get_eq_pop <- function(b, demog, N_0 = NULL, t_max = 1000, t_rec = 1, delta = .1, diagnostics = FALSE, rm.stage0 = TRUE){ + if(class(demog)!="DemogParams"){ + warning("This function expects an object of class DemogParams.", call. = FALSE) + return(NULL) + } + else{ + if(class(demog@StageStruct)!="StagesParams"){ + warning("demog needs to have a StageStructure", call. = FALSE) + return(NULL) + } + } + + TraMa <- demog@StageStruct@TransMatrix + + if(demog@ReproductionType>1){ + # for sex-specific (ReproductionType = 2) need to include Sex-ratio to weigh fecundities and make transition matrix quadratic + SexDep <- TRUE + TraMa <- rbind(TraMa[1,]*demog@PropMales,TraMa) + TraMa[2,] <- TraMa[2,]*(1-demog@PropMales) + } + else SexDep <- FALSE + TraMa_t <- TraMa + lines <- nrow(TraMa) + N_rec <- matrix(0, ncol = t_rec, nrow = lines-rm.stage0*(1+SexDep)) + + if(demog@StageStruct@FecDensDep){ + FecDensDep <- TRUE + if(demog@StageStruct@FecStageWts) { + FecStageDep <- TRUE + FecStageWts <- demog@StageStruct@FecStageWtsMatrix + } + else FecStageDep <- FALSE + } + else FecDensDep <- FALSE + + if(demog@StageStruct@DevDensDep){ + DevDensDep <- TRUE + C_dev <- demog@StageStruct@DevDensCoeff + if(demog@StageStruct@DevStageWts) { + DevStageDep <- TRUE + DevStageWts <- demog@StageStruct@DevStageWtsMatrix + } + else DevStageDep <- FALSE + # disentangle survival and development rates: + surv <- devs <- rep(0,lines) + for(s in 1:lines ){ + ss <- TraMa[s,s] + if (SexDep) if((s+2)>lines) dd <- 0 else dd <- TraMa[s+2,s] + else if(s==lines) dd <- 0 else dd <- TraMa[s+1,s] + surv[s] <- ss+dd + devs[s] <- dd/(ss+dd) + } + surv_t <- surv + devs_t <- devs + } + else DevDensDep <- FALSE + + if(demog@StageStruct@SurvDensDep){ + SurvDensDep <- TRUE + C_surv <- demog@StageStruct@SurvDensCoeff + if(demog@StageStruct@SurvStageWts) { + SurvStageDep <- TRUE + SurvStageWts <- demog@StageStruct@SurvStageWtsMatrix + } + else SurvStageDep <- FALSE + } + else SurvDensDep <- FALSE + + if(is.null(N_0)) N_0 <- matrix( rep(1/b/lines, lines), ncol = 1) + N_t2 <- N_0 + t <- 0 + repeat{ + # reset abundance vector and time-dependent transition matrix + N_t1 <- N_t2 + TraMa_t <- TraMa + # calculate density-dependent rates + abund <- sum(N_t1) + if(SexDep){ + if(FecDensDep) { + if(FecStageDep) { + TraMa_t[1:2,] <- TraMa[1:2,]*rep(exp(-b*FecStageWts%*%N_t1),each=2) + } + else TraMa_t[1:2,] <- TraMa[1:2,]*exp(-b*abund) + } + if(DevDensDep) { + if(DevStageDep) { + # dev diagonals + devs_t <- devs*exp(-C_dev*b*DevStageWts%*%N_t1) + diag(TraMa_t) <- surv*(1-devs_t) + # dev off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+2] <- TraMa[row(TraMa)==col(TraMa)+2]*exp(-C_dev*b*(DevStageWts%*%N_t1)[-c(lines-1,lines)]) + } + else { + # dev diagonals + devs_t <- devs*exp(-C_dev*b*abund) + diag(TraMa_t) <- surv*(1-devs_t) + # dev off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+2] <- TraMa[row(TraMa)==col(TraMa)+2]*exp(-C_dev*b*abund) + } + if(SurvDensDep) { + if(SurvStageDep){ + # surv diagonals + diag(TraMa_t) <- diag(TraMa_t)*exp(-C_surv*b*SurvStageWts%*%N_t1) + # surv off-diagonals + TraMa_t[row(TraMa_t)==col(TraMa_t)+2] <- TraMa_t[row(TraMa_t)==col(TraMa_t)+2]*exp(-C_surv*b*(SurvStageWts%*%N_t1)[-c(lines-1,lines)]) + } + else { + # surv diagonals + diag(TraMa_t) <- diag(TraMa_t)*exp(-C_surv*b*abund) + # surv off-diagonals + TraMa_t[row(TraMa_t)==col(TraMa_t)+2] <- TraMa_t[row(TraMa_t)==col(TraMa_t)+2]*exp(-C_surv*b*abund) + } + } + } + else{ + if(SurvDensDep) { + if(SurvStageDep){ + # surv diagonals + diag(TraMa_t) <- diag(TraMa)*exp(-C_surv*b*SurvStageWts%*%N_t1) + # surv off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+2] <- TraMa[row(TraMa)==col(TraMa)+2]*exp(-C_surv*b*(SurvStageWts%*%N_t1)[-c(lines-1,lines)]) + } + else { + # surv diagonals + diag(TraMa_t) <- diag(TraMa)*exp(-C_surv*b*abund) + # surv off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+2] <- TraMa[row(TraMa)==col(TraMa)+2]*exp(-C_surv*b*abund) + } + } + } + } + else{ # !SexDep + if(FecDensDep) { + if(FecStageDep) TraMa_t[1,] <- TraMa[1,]*exp(-b*FecStageWts%*%N_t1) + else TraMa_t[1,] <- TraMa[1,]*exp(-b*abund) + } + if(DevDensDep) { + if(DevStageDep) { + # dev diagonals + devs_t <- devs*exp(-C_dev*b*DevStageWts%*%N_t1) + diag(TraMa_t) <- surv*(1-devs_t) + # dev off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+1] <- TraMa[row(TraMa)==col(TraMa)+1]*exp(-C_dev*b*(DevStageWts%*%N_t1)[-lines]) + } + else { + # dev diagonals + devs_t <- devs*exp(-C_dev*b*abund) + diag(TraMa_t) <- surv*(1-devs_t) + # dev off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+1] <- TraMa[row(TraMa)==col(TraMa)+1]*exp(-C_dev*b*abund) + } + if(SurvDensDep) { + if(SurvStageDep){ + # surv diagonals + diag(TraMa_t) <- diag(TraMa_t)*exp(-C_surv*b*SurvStageWts%*%N_t1) + # surv off-diagonals + TraMa_t[row(TraMa_t)==col(TraMa_t)+1] <- TraMa_t[row(TraMa_t)==col(TraMa_t)+1]*exp(-C_surv*b*(SurvStageWts%*%N_t1)[-lines]) + } + else { + # surv diagonals + diag(TraMa_t) <- diag(TraMa_t)*exp(-C_surv*b*abund) + # surv off-diagonals + TraMa_t[row(TraMa_t)==col(TraMa_t)+1] <- TraMa_t[row(TraMa_t)==col(TraMa_t)+1]*exp(-C_surv*b*abund) + } + } + } + else{ + if(SurvDensDep) { + if(SurvStageDep){ + # surv diagonals + diag(TraMa_t) <- diag(TraMa)*exp(-C_surv*b*SurvStageWts%*%N_t1) + # surv off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+1] <- TraMa[row(TraMa)==col(TraMa)+1]*exp(-C_surv*b*(SurvStageWts%*%N_t1)[-lines]) + } + else { + # surv diagonals + diag(TraMa_t) <- diag(TraMa)*exp(-C_surv*b*abund) + # surv off-diagonals + TraMa_t[row(TraMa)==col(TraMa)+1] <- TraMa[row(TraMa)==col(TraMa)+1]*exp(-C_surv*b*abund) + } + } + } + } + # turn RS transition matrix into actual Leslie matrix (i.e. remove zeroth stage) + if(rm.stage0){ + if(SexDep){ + TraMa_t[1:2,] <- TraMa_t[1:2,] * diag(TraMa_t[c(3,4),c(1,2)]) # put survival rate into fecundity + TraMa_t[3:4,] <- TraMa_t[3:4,] + TraMa_t[1:2,] + TraMa_t <- TraMa_t[3:lines,3:lines] # get rid of stage 0 + # compress state vector as well + N_t1[3] <- sum(N_t1[c(1,3)]) + N_t1[4] <- sum(N_t1[c(2,4)]) + N_t1 <- matrix(N_t1[3:lines], ncol = 1) + } + else{ # !SexDep + TraMa_t[1,] <- TraMa_t[1,] * TraMa_t[2,1] # -"- + TraMa_t[2,] <- TraMa_t[2,] + TraMa_t[1,] + TraMa_t <- TraMa_t[2:lines,2:lines] + # compress state vector as well + N_t1[2] <- sum(N_t1[1:2]) + N_t1 <- matrix(N_t1[2:lines], ncol = 1) + } + } + # take a time step + N_t2 <- TraMa_t %*% N_t1 + # evaluate convergence + del <- sqrt(sum((N_t2-N_t1)^2)) + N_rec[,1+(t%%t_rec)] <- N_t2 + if(del < delta || t >= t_max ){ + if(t >= t_max) warning("No convergence") + if(t < t_rec ) N_rec <- N_rec[,1:t] + if(diagnostics) return(list(N=N_rec, TraMa_t=TraMa_t, t=t, del=del)) + else return(N_rec) + break + } + # end time step + t <- t+1 + # expand state vector again + if(rm.stage0){ + if(SexDep){ + N_t2[1:2] <- N_t2[1:2]/2 + N_t2 <- matrix(c(N_t2[1:2],N_t2), ncol = 1) + } + else{ # !SexDep + N_t2[1] <- N_t2[1]/2 + N_t2 <- matrix(c(N_t2[1],N_t2), ncol = 1) + } + } + } +} + + +## ---- Frontend Plot function ----- + +#' Calculates the equilibrium density and stage distribution for a localised (i.e. non-spatial) closed population +#' +#' Uses the \emph{RangeShiftR} Demography module to create the corresponding matrix model and runs it until equilibrium is reached. +#' This corresponds to a localised population in a single cell without dispersal (i.e. no immigration or emigration). +#' Since the matrix model representation is used, some options (e.g. maximum age) of the \code{\link[RangeShiftR]{Demography}} module can not be taken into account. +#' @param demog DemogParams object with a \code{StageStructure} +#' @param DensDep_values values of \eqn{1/b} to run the matrix model for +#' @param plot plot the equilibrium densities? (default is \code{TRUE}) +#' @param stages_out which stages to plot? (defaults to all) +#' @param juv.stage use explicit juvenile (zeroth) stage? (default is \code{TRUE}) +#' @param t_rec number of time steps to record at the end (defaults to \eqn{1}); if \code{t_rec}\eqn{>1}, the mean over all recorded time steps is returned +#' @param N_0 initial condition, i.e. population density at time zero; must include stage zero regardless of the value of \code{juv.stage} +#' @param t_max allowed number of time steps to reach equilibrium (default is \eqn{1000}) +#' @param delta tolerance to check for equilibrium (default is \eqn{.1}); the utilised measure is euclidian distance of current to previous time steps +#' @param diagnostics in addition to recorded population vectors, returns the number of steps taken as well as the transition matrix and the value if delta at the last step (default is \code{FALSE}) +#' @details \emph{RangeShiftR} requires an additional juvenile stage to be added to the common transition matrix as stage \eqn{0} (in order +#' to allow for juvenile dispersal). For the simulation with \code{RunMatrixModel()}, this stage can be kept (\code{juv.stage=TRUE}) +#' or removed to yield the corresponding Lefkovitch matrix (\code{juv.stage=FALSE}).\cr +#' The default initial state \code{N_0} is a population at its respective density \eqn{1/b} with unpopulated juvenile stage and +#' all higher stages equally populated.\cr +#' @return a matrix of population densities with a named row for each stage and a column for each given value of \eqn{1/b} +#' @export +setGeneric("getLocalisedEquilPop", function(demog,...) standardGeneric("getLocalisedEquilPop") ) + +setMethod("getLocalisedEquilPop", "DemogParams", function(demog, DensDep_values, plot=TRUE, stages_out=NULL, juv.stage=TRUE, t_rec=1, + t_max = 1000, N_0 = NULL, delta=.1, diagnostics=FALSE){ + # make b from 1/b + b_vector <- 1/DensDep_values + # calculate equilibrium population + if(t_rec==1) res <- sapply(b_vector, get_eq_pop, demog=demog, t_rec = t_rec, rm.stage0 = !juv.stage) + if(t_rec>1) {res <- lapply(b_vector, get_eq_pop, demog=demog, t_rec = t_rec, rm.stage0 = !juv.stage) + res <- sapply(res, rowMeans)} + # name rows + if(demog@ReproductionType <2){row.names(res) <- seq((!juv.stage),demog@StageStruct@Stages-1)} + if(demog@ReproductionType==2){row.names(res) <- rep(seq((!juv.stage),demog@StageStruct@Stages-1), each = 2)} + # plot stages ? + if(plot) { + # x-axis labels + xlabs <- print(DensDep_values, digits = 2) + # which stages to plot? + if(is.null(stages_out)) stages_out = seq((!juv.stage),demog@StageStruct@Stages-1) + colors <- hcl.colors(length(stages_out), palette = "Harmonic") + if(demog@ReproductionType <2){ + barplot(res[as.character(stages_out),], names.arg = xlabs, beside = F, col = colors, + main = "Localised equilibrium densities", xlab = "1/b", ylab = "Population density") + } + if(demog@ReproductionType==2){ + if(length(stages_out)<2) warning("getLocalisedEquilPop(): Please specify more than one stage when plotting a sex-explicit model.", call. = TRUE) + else { + res_2 <- res[which(rownames(res) %in% stages_out),] + mal <- seq.int(1,length(stages_out)*2,2) + fem <- seq.int(2,length(stages_out)*2,2) + res_2 <- cbind(res_2[mal,1:length(DensDep_values)],res_2[fem,1:length(DensDep_values)]) + res_2 <- cbind(res_2[,c(sapply(1:length(DensDep_values), function(i){c(0,1)*length(DensDep_values)+i}))]) + barplot(res_2, space=c(0.3,0.1), names.arg = c(rbind(xlabs,NA)), beside = F, col = rep(colors, 2), + main = "Localised equilibrium densities", xlab = "1/b", ylab = "Population density") + text(seq(0.5,length(DensDep_values)*2,2)*1.2, colSums(res_2[,seq(1,length(DensDep_values)*2,2)])*1.1, "m", cex=1, col="black") + text(seq(1.5,length(DensDep_values)*2,2)*1.2, colSums(res_2[,seq(2,length(DensDep_values)*2,2)])*1.1, "f", cex=1, col="black") + } + } + legend("topleft", legend = rev(sapply(stages_out, function(s){paste("Stage",s)})), col = rev(colors), pch = 16) + } + # return equilibrium population densities + return(res) +}) + + +## ---- ODD documentation ----- + +#' Creating ODD template file for a specific RangeShiftR parameter master object +#' +#' This function creates an ODD template file for a specific RangeShiftR parameter master object \code{s}. +#' It only creates a new file, if the \code{filename} doesn't exist in the folder. +#' If the \code{filename} already exists, it only renders the document to the given type. +#' +#' @usage createODD(filename, s, type, title) +#' +#' @param filename Name of the R markdown file and document to be created, must have ending ".Rmd", e.g. 'ODD_protocol.Rmd' +#' @param s RangeShiftR parameter object +#' @param type file type of the rendering process output. Can currently only be "pdf_document" +#' @param title Title of the study if possible including authors, e.g. "'Study title ABC' by author ABC +#' @export +setGeneric("createODD", function(filename, s, type, title,...) standardGeneric("createODD") ) + +setMethod("createODD", c(filename = "character", s="RSparams", type="character", title="character"), function(filename="ODD_protocol_template.Rmd", s, type="pdf_document", title = "'Study ABC' by author ABC"){ + if(!file.exists(filename)) { + unlink(c("RSflowchart_big.pdf", "RSflowchart_detail.pdf", "RSflowchart_big.svg", "RSflowchart_detail.svg", "style-template.docx", "RS_ODD.json", "ecography.csl", "RS_ODD.bib")) + rmarkdown::draft(filename, template = "odd_protocol", package = "RangeShiftR", edit = FALSE) + } + if (type=="pdf_document") format <- "pdf" + if (type=="md_document") format <- "md" + if (type=="rtf_document") format <- "word" + if (type=="word_document") format <- "word" + + subtitle <- title + + rmarkdown::render(input = filename, output_format = type, params=list(format = format, subtitle = title)) +}) + + +## ---- Parameter table function ----- + +#' Creating parameter table file for a specific RangeShiftR parameter master object +#' +#' This function creates a file with tables of the parameter set for a specific RangeShiftR parameter master object \code{s}. +#' It only creates a new file, if the \code{filename} doesn't exist in the folder. +#' If the \code{filename} already exists, it only renders the document to either pdf, word or md. +#' +#' @usage createParameterTables(filename, s, type, title) +#' +#' @param filename Name of the R markdown file and document to be created, e.g. 'Parameter_table.rmd' +#' @param s RangeShiftR parameter object +#' @param type file type of the rendering process output. Can be either "pdf_document", "word_document" or "md_document" We recommend using "word_document" to refine the layout. +#' @param title Title of the study if possible including authors, e.g. "'Study title ABC' by author ABC +#' @export +setGeneric("createParameterTables", function(filename, s, type, title,...) standardGeneric("createParameterTables") ) + +setMethod("createParameterTables", c(filename = "character", s="RSparams", type="character", title = "character"), function(filename="ParameterTable_template.Rmd", s, type="word_document", title="'Study ABC' by author ABC"){ + if(!file.exists(filename)) { + rmarkdown::draft(filename, template = "parameter_table", package = "RangeShiftR", edit = FALSE) + } + if (type=="pdf_document") format <- "pdf" + if (type=="md_document") format <- "md" + if (type=="rtf_document") format <- "word" + if (type=="word_document") format <- "word" + + subtitle <- title + + rmarkdown::render(input = filename, output_format = type, params=list(format = format, subtitle=subtitle)) +}) + diff --git a/RangeShiftR/R/plotProbs.R b/RangeShiftR/R/plotProbs.R new file mode 100644 index 0000000..bcd6b00 --- /dev/null +++ b/RangeShiftR/R/plotProbs.R @@ -0,0 +1,70 @@ +#--------------------------------------------------------------------------- +# +# Copyright (C) 2020-2022 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell +# +# This file is part of RangeShiftR. +# +# RangeShiftR is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# RangeShiftR is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with RangeShiftR. If not, see . +# +#---------------------------------------------------------------------------- + + + +# ----- +# +# Plotting parameterised probabilities functions +# (the respective methods are defined together with their class) +# +# ----- + +#' Plot parameterised probabilities +#' +#' Visualise the dependencies or distributions of probabilities of the various processes that are defined by the different parameter modules, +#' like e.g. fecundity or mortality. +#' +#' @param x a RangeShiftR parameter object +#' @param xmax,ymax upper plotting limits (lower limits are fixed to \eqn{0}) +#' @param stage,sex stage(s) and sexe(s) to plot, default: all +#' @param ... various options, depend on the given parameter module type +#' @details +#' Available methods and their options: +#' \itemize{ +#' \item \code{\link[RangeShiftR]{Emigration}}: plot emigration probability +#' \item \code{\link[RangeShiftR]{DispersalKernel}}: +#' \itemize{ +#' \item \code{mortality=FALSE} - plot dispersal distance probability density (default) +#' \item \code{mortality= TRUE} - plot mortality probability +#' } +#' If a mixed kernel was defined (i.e. \code{DoubleKernel=TRUE}), plot the resulting dispersal probability by... +#' \itemize{ +#' \item \code{combinekernels=FALSE} - ...plotting both kernels separately (default) +#' \item \code{combinekernels= TRUE} - ...combining both kernels, i.e. \ifelse{html}{ \out{p(d; δ1,δ2) = pI p(d;δ1) + (1-pI) p(d;δ1) } }{\deqn{ p(d; δ_1,δ_2) = p_I p(d;δ_1) + (1-p_I) p(d;δ_2)} } +#' } +#' \item \code{\link[RangeShiftR]{StageStructure}}: plot fecundity as well as survival and development probabilities. +#' +#' Survival and development are calculated based on the transition matrix. Consider e.g. a 3 stage matrix with a transition matrix of +#' +#' \tabular{ccccc}{0 \tab | \tab 0 \tab | \tab \ifelse{html}{\out{φ2}}{\eqn{φ_2}} \cr +#' \eqn{1.0} \tab | \tab \ifelse{html}{\out{σ1 (1-γ1-2)}}{\eqn{σ_1 (1 − γ_(1-2))}} \tab | \tab \eqn{0} \cr +#' \eqn{0} \tab | \tab \ifelse{html}{\out{σ1 γ1-2}}{\eqn{σ_1 γ_(1-2)}} \tab | \tab \ifelse{html}{\out{σ2}}{\eqn{σ_2}} \cr} +#' +#' The survival probability is calculated as the sum of the probability to stay in the same stage and the probability to reach the next stage. +#' E.g. for stage 1: \ifelse{html}{\out{σ1 = sum( σ1 (1-γ1-2), σ1 γ1-2}}{\eqn{σ_1 = sum(σ_1 (1 − γ_(1-2)), σ_1 γ_(1-2))}} +#' +#' The development probability of stage 1 to stage 2 is the ratio of the probability to reach stage 2 and the previously calculated survival probability. +#' E.g. for stage 1: \ifelse{html}{\out{γ1-2 = σ1 γ1-2 / σ1}}{\eqn{γ_(1-2) = σ_1 / (σ_1 γ_(1-2) )}} +#' } +#' @export +setGeneric("plotProbs", function(x, ...) standardGeneric("plotProbs") ) + diff --git a/RangeShiftR/RangeShiftR.Rproj b/RangeShiftR/RangeShiftR.Rproj new file mode 100644 index 0000000..e5687b1 --- /dev/null +++ b/RangeShiftR/RangeShiftR.Rproj @@ -0,0 +1,24 @@ +Version: 1.0 + +RestoreWorkspace: No +SaveWorkspace: No +AlwaysSaveHistory: Yes + +EnableCodeIndexing: Yes +UseSpacesForTab: Yes +NumSpacesForTab: 4 +Encoding: UTF-8 + +RnwWeave: knitr +LaTeX: pdfLaTeX + +StripTrailingWhitespace: Yes +LineEndingConversion: Native + +BuildType: Package +PackageUseDevtools: Yes +PackageInstallArgs: --no-multiarch --with-keep.source +PackageBuildBinaryArgs: --no-multiarch --with-keep.source +PackageRoxygenize: rd,collate,namespace + +QuitChildProcessesOnExit: Yes diff --git a/RangeShiftR/inst/CITATION b/RangeShiftR/inst/CITATION new file mode 100644 index 0000000..728804d --- /dev/null +++ b/RangeShiftR/inst/CITATION @@ -0,0 +1,15 @@ +citHeader("To cite RangeShiftR in publications use:") + +citEntry(entry = "Article", + title = "{RangeShiftR}: an {R} package for individual-based simulation of spatial eco-evolutionary dynamics and species' responses to environmental change", + author = personList(as.person("Anne-Kathleen Malchow"), + as.person("Greta Bocedi"), + as.person("Stephen C. F. Palmer"), + as.person("Justin M.J. Travis"), + as.person("Damaris Zurell")), + journal = "Ecography", + year = "2021", + doi = "10.1111/ecog.05689", + textVersion = NULL +) + diff --git a/RangeShiftR/inst/REFERENCES.bib b/RangeShiftR/inst/REFERENCES.bib new file mode 100644 index 0000000..12b7b87 --- /dev/null +++ b/RangeShiftR/inst/REFERENCES.bib @@ -0,0 +1,595 @@ +@article{bocedi2020, + title = {{RangeShifter} 2.0: {An} extended and enhanced platform for modelling spatial eco-evolutionary dynamics and species' responses to environmental changes.}, + shorttitle = {{RangeShifter} 2.0}, + doi = {10.1111/ecog.05687}, + journal = {Ecography}, + language = {en}, + author = {Bocedi, Greta and Palmer, Stephen C. F. and Malchow, Anne-Kathleen and Zurell, Damaris and Watts, Kevin and Travis, Justin MJ}, + year = {2021} +} + +@article{bocedi2014, + title = {RangeShifter: a platform for modelling spatial eco-evolutionary dynamics and species' responses to environmental changes}, + volume = {5}, + url = {https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.12162}, + doi = {10.1111/2041-210X.12162}, + language = {en}, + number = {4}, + urldate = {2020-07-31}, + journal = {Methods in Ecology and Evolution}, + author = {Bocedi, Greta and Palmer, Stephen C. F. and Pe'er, Guy and Heikkinen, Risto K. and Matsinos, Yiannis G. and Watts, Kevin and Travis, Justin M. J.}, + year = {2014}, + keywords = {population dynamics, connectivity, dispersal, dynamic modelling, environmental change, individual-based modelling, population viability}, + pages = {388--396} +} + +@article{smith1973, + title={The stability of predator-prey systems}, + author={Maynard Smith, J and Slatkin, M}, + journal={Ecology}, + volume={54}, + number={2}, + pages={384--391}, + year={1973}, + publisher={Wiley Online Library} +} + +@article{caswell2001, + title={Matrix Population Models: Construction, Analysis, and Interpretation. 2nd edn Sinauer Associates}, + author={Caswell, Hal}, + journal={Inc., Sunderland, MA}, + year={2001} +} + +@article{lindstrom1998, + title={Sexual reproduction and population dynamics: the role of polygyny and demographic sex differences}, + author={Lindstr{\"o}m, Jan and Kokko, Hanna}, + journal={Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume={265}, + number={1395}, + pages={483--488}, + year={1998}, + publisher={The Royal Society} +} + +@article{legendre2004, + title={Age structure, mating system and population viability}, + author={Legendre, St{\'e}phane}, + journal={Evolutionary conservation biology. Cambridge University Press, Cambridge}, + pages={41--58}, + year={2004} +} + +@article{bessa2010, + title={Discrete two-sex models of population dynamics: on modelling the mating function}, + author={Bessa-Gomes, Carmen and Legendre, St{\'e}phane and Clobert, Jean}, + journal={Acta Oecologica}, + volume={36}, + number={5}, + pages={439--445}, + year={2010}, + publisher={Elsevier} +} + +@article{weeks1986, + title={Two-sex models: chaos, extinction, and other dynamic consequences of sex}, + author={Caswell, Hal and Weeks, Daniel E}, + journal={The American Naturalist}, + volume={128}, + number={5}, + pages={707--735}, + year={1986}, + publisher={University of Chicago Press} +} + +@article{neubert2000, + title={Density-dependent vital rates and their population dynamic consequences}, + author={Neubert, Michael G and Caswell, Hal}, + journal={Journal of Mathematical Biology}, + volume={41}, + number={2}, + pages={103--121}, + year={2000}, + publisher={Springer} +} + +@article{caswell2004, + title={Sensitivity analysis of equilibrium in density-dependent matrix population models}, + author={Caswell, Hal and Takada, Takenori and Hunter, Christine M}, + journal={Ecology Letters}, + volume={7}, + number={5}, + pages={380--387}, + year={2004}, + publisher={Wiley Online Library} +} + +@article{travis2004, + title={A method for simulating patterns of habitat availability at static and dynamic range margins}, + author={Travis, Justin Mark John and Dytham, C}, + journal={Oikos}, + pages={410--416}, + year={2004}, + publisher={JSTOR} +} + +@article{ruokolainen2009, + title={Ecological and evolutionary dynamics under coloured environmental variation}, + author={Ruokolainen, Lasse and Lind{\'e}n, Andreas and Kaitala, Veijo and Fowler, Mike S}, + journal={Trends in Ecology \& Evolution}, + volume={24}, + number={10}, + pages={555--563}, + year={2009}, + publisher={Elsevier} +} + +@book{stenseth1992, + title={Animal dispersal: small mammals as a model}, + author={Stenseth, Nils Chr and Lidicker Jr, William Z and Lidicker, WZ}, + year={1992}, + publisher={Springer Science \& Business Media} +} + +@book{clobert2001, + title={Dispersal}, + author={Clobert, J and Danchin, E and Dhondt, AA and Nichols, JD}, + year={2001}, + publisher={Oxford, Oxford University Press} +} + +@article{clobert2009, + title={Informed dispersal, heterogeneity in animal dispersal syndromes and the dynamics of spatially structured populations}, + author={Clobert, Jean and Le Galliard, Jean-Fran{\c{c}}ois and Cote, Julien and Meylan, Sandrine and Massot, Manuel}, + journal={Ecology letters}, + volume={12}, + number={3}, + pages={197--209}, + year={2009}, + publisher={Wiley Online Library} +} + +@book{clobert2012, + title={Dispersal ecology and evolution}, + author={Clobert, Jean and Baguette, Michel and Benton, Tim G and Bullock, James M}, + year={2012}, + publisher={Oxford University Press} +} + +@article{bowler2005, + title={Causes and consequences of animal dispersal strategies: relating individual behaviour to spatial dynamics}, + author={Bowler, Diana E and Benton, Tim G}, + journal={Biological Reviews}, + volume={80}, + number={2}, + pages={205--225}, + year={2005}, + publisher={Wiley Online Library} +} + +@article{ronce2007, + title={How does it feel to be like a rolling stone? Ten questions about dispersal evolution}, + author={Ronce, Oph{\'e}lie}, + journal={Annu. Rev. Ecol. Evol. Syst.}, + volume={38}, + pages={231--253}, + year={2007}, + publisher={Annual Reviews} +} + +@article{travis2011improving, + title={Improving prediction and management of range expansions by combining analytical and individual-based modelling approaches}, + author={Travis, Justin MJ and Harris, Catriona M and Park, Kirsty J and Bullock, James M}, + journal={Methods in Ecology and Evolution}, + volume={2}, + number={5}, + pages={477--488}, + year={2011}, + publisher={Wiley Online Library} +} + +@article{travis2012modelling, + title={Modelling dispersal: an eco-evolutionary framework incorporating emigration, movement, settlement behaviour and the multiple costs involved}, + author={Travis, Justin MJ and Mustin, Karen and Barto{\'n}, Kamil A and Benton, Tim G and Clobert, Jean and Delgado, Maria M and Dytham, Calvin and Hovestadt, Thomas and Palmer, Stephen CF and Van Dyck, Hans and others}, + journal={Methods in Ecology and Evolution}, + volume={3}, + number={4}, + pages={628--641}, + year={2012}, + publisher={Wiley Online Library} +} + +@article{travis2013dispersal, + title={Dispersal and species’ responses to climate change}, + author={Travis, Justin MJ and Delgado, Maria and Bocedi, Greta and Baguette, Michel and Barto{\'n}, Kamil and Bonte, Dries and Boulangeat, Isabelle and Hodgson, Jenny A and Kubisch, Alexander and Penteriani, Vincenzo and others}, + journal={Oikos}, + volume={122}, + number={11}, + pages={1532--1540}, + year={2013}, + publisher={Wiley Online Library} +} + +@article{bonte2012costs, + title={Costs of dispersal}, + author={Bonte, Dries and Van Dyck, Hans and Bullock, James M and Coulon, Aur{\'e}lie and Delgado, Maria and Gibbs, Melanie and Lehouck, Valerie and Matthysen, Erik and Mustin, Karin and Saastamoinen, Marjo and others}, + journal={Biological reviews}, + volume={87}, + number={2}, + pages={290--312}, + year={2012}, + publisher={Wiley Online Library} +} + +@article{kun2006evolution, + title={The evolution of density-dependent dispersal in a noisy spatial population model}, + author={Kun, {\'A}d{\'a}m and Scheuring, Istv{\'a}n}, + journal={Oikos}, + volume={115}, + number={2}, + pages={308--320}, + year={2006}, + publisher={Wiley Online Library} +} + +@article{poethke2011ability, + title={The ability of individuals to assess population density influences the evolution of emigration propensity and dispersal distance}, + author={Poethke, Hans Joachim and Gros, Andreas and Hovestadt, Thomas}, + journal={Journal of Theoretical Biology}, + volume={282}, + number={1}, + pages={93--99}, + year={2011}, + publisher={Elsevier} +} + +@article{hovestadt2010information, + title={Information processing in models for density-dependent emigration: a comparison}, + author={Hovestadt, Thomas and Kubisch, Alexander and Poethke, Hans-Joachim}, + journal={Ecological Modelling}, + volume={221}, + number={3}, + pages={405--410}, + year={2010}, + publisher={Elsevier} +} + +@article{hovestadt2011all, + title={Do all inter-patch movements represent dispersal? A mixed kernel study of butterfly mobility in fragmented landscapes}, + author={Hovestadt, Thomas and Binzenh{\"o}fer, Birgit and Nowicki, Piotr and Settele, Josef}, + journal={Journal of Animal Ecology}, + volume={80}, + number={5}, + pages={1070--1077}, + year={2011}, + publisher={Wiley Online Library} +} + +@article{hovestadt2012evolution, + title={Evolution and emergence of dispersal kernels--a brief theoretical evaluation}, + author={Hovestadt, Thomas and Bonte, Dries and Dytham, Calvin and Poethke, Hans Joachim}, + journal={Dispersal ecology and evolution}, + volume={211}, + pages={221}, + year={2012}, + publisher={Oxford University Press Oxford} +} + +@article{greenwood1980mating, + title={Mating systems, philopatry and dispersal in birds and mammals}, + author={Greenwood, Paul J}, + journal={Animal behaviour}, + volume={28}, + number={4}, + pages={1140--1162}, + year={1980}, + publisher={Elsevier} +} + +@article{bocedi2012projecting, + title={Projecting species’ range expansion dynamics: sources of systematic biases when scaling up patterns and processes}, + author={Bocedi, Greta and Pe’er, Guy and Heikkinen, Risto K and Matsinos, Yiannis and Travis, Justin MJ}, + journal={Methods in Ecology and Evolution}, + volume={3}, + number={6}, + pages={1008--1018}, + year={2012}, + publisher={Wiley Online Library} +} + + +@article{lawson2007advances, + title={Advances in our understanding of mammalian sex-biased dispersal}, + author={Lawson Handley, LJ and Perrin, N}, + journal={Molecular ecology}, + volume={16}, + number={8}, + pages={1559--1578}, + year={2007}, + publisher={Wiley Online Library} +} + +@misc{nathan2012dispersal, + title={Dispersal kernels: review In: Clobert J, Baguette M, Benton TG, Bullock JM, editors. Dispersal Ecology and Evolution}, + author={Nathan, R and Klein, E and Robledo-Arnuncio, JJ and Revilla, E}, + year={2012}, + publisher={Oxford: Oxford University Press} +} + +@article{palmer2011introducing, + title={Introducing a ‘stochastic movement simulator’for estimating habitat connectivity}, + author={Palmer, Stephen CF and Coulon, Aurelie and Travis, Justin MJ}, + journal={Methods in Ecology and Evolution}, + volume={2}, + number={3}, + pages={258--268}, + year={2011}, + publisher={Wiley Online Library} +} + +@article{anderson2009dynamics, + title={Dynamics of range margins for metapopulations under climate change}, + author={Anderson, BJ and Ak{\c{c}}akaya, HR and Ara{\'u}jo, MB and Fordham, DA and Martinez-Meyer, E and Thuiller, W and Brook, BW}, + journal={Proceedings of the Royal Society B: Biological Sciences}, + volume={276}, + number={1661}, + pages={1415--1420}, + year={2009}, + publisher={The Royal Society London} +} + +@article{adriaensen2003application, + title={The application of ‘least-cost’modelling as a functional landscape model}, + author={Adriaensen, Frank and Chardon, JP and De Blust, Geert and Swinnen, Else and Villalba, S and Gulinck, Hubert and Matthysen, Erik}, + journal={Landscape and urban planning}, + volume={64}, + number={4}, + pages={233--247}, + year={2003}, + publisher={Elsevier} +} + +@article{chardon2003incorporating, + title={Incorporating landscape elements into a connectivity measure: a case study for the Speckled wood butterfly (Pararge aegeria L.)}, + author={Chardon, J Paul and Adriaensen, Frank and Matthysen, Erik}, + journal={Landscape Ecology}, + volume={18}, + number={6}, + pages={561--573}, + year={2003}, + publisher={Springer} +} + +@article{stevens2006gene, + title={Gene flow and functional connectivity in the natterjack toad}, + author={Stevens, Virginie M and Verkenne, Catherine and Vandewoestijne, Sofie and Wesselingh, Renate A and Baguette, Michel}, + journal={Molecular Ecology}, + volume={15}, + number={9}, + pages={2333--2344}, + year={2006}, + publisher={Wiley Online Library} +} + +@article{driezen2007evaluating, + title={Evaluating least-cost model predictions with empirical dispersal data: a case-study using radiotracking data of hedgehogs (Erinaceus europaeus)}, + author={Driezen, Kassandra and Adriaensen, Frank and Rondinini, Carlo and Doncaster, C Patrick and Matthysen, Erik}, + journal={Ecological modelling}, + volume={209}, + number={2-4}, + pages={314--322}, + year={2007}, + publisher={Elsevier} +} + +@article{palmer2014inter, + title={Inter-individual variability in dispersal behaviours impacts connectivity estimates}, + author={Palmer, Stephen CF and Coulon, Aur{\'e}lie and Travis, Justin MJ}, + journal={Oikos}, + volume={123}, + number={8}, + pages={923--932}, + year={2014}, + publisher={Wiley Online Library} +} + +@article{aben2014simple, + title={Simple individual-based models effectively represent A frotropical forest bird movement in complex landscapes}, + author={Aben, Job and Strubbe, Diederik and Adriaensen, Frank and Palmer, Stephen CF and Travis, Justin MJ and Lens, Luc and Matthysen, Erik}, + journal={Journal of Applied Ecology}, + volume={51}, + number={3}, + pages={693--702}, + year={2014}, + publisher={Wiley Online Library} +} + +@article{zollner1999search, + title={Search strategies for landscape-level interpatch movements}, + author={Zollner, Patrick A and Lima, Steven L}, + journal={Ecology}, + volume={80}, + number={3}, + pages={1019--1030}, + year={1999}, + publisher={Wiley Online Library} +} + +@article{barton2009evolution, + title={The evolution of an ‘intelligent’dispersal strategy: biased, correlated random walks in patchy landscapes}, + author={Barton, Kamil A and Phillips, Ben L and Morales, Juan M and Travis, Justin MJ}, + journal={Oikos}, + volume={118}, + number={2}, + pages={309--319}, + year={2009}, + publisher={Wiley Online Library} +} + +@article{barton2012risky, + title={Risky movement increases the rate of range expansion}, + author={Barto{\'n}, KA and Hovestadt, T and Phillips, BL and Travis, JMJ}, + journal={Proceedings of the Royal Society B: Biological Sciences}, + volume={279}, + number={1731}, + pages={1194--1202}, + year={2012}, + publisher={The Royal Society} +} + +@article{jongejans2008dispersal, + title={Dispersal, demography and spatial population models for conservation and control management}, + author={Jongejans, Eelke and Skarpaas, Olav and Shea, Katriona}, + journal={Perspectives in Plant Ecology, Evolution and Systematics}, + volume={9}, + number={3-4}, + pages={153--170}, + year={2008}, + publisher={Elsevier} +} + +@book{grimm2005individual, + title={Individual-based modeling and ecology}, + author={Grimm, Volker and Railsback, Steven F}, + volume={8}, + year={2005}, + publisher={Princeton university press} +} + +@article{kendall2003unstructured, + title={Unstructured individual variation and demographic stochasticity}, + author={Kendall, Bruce E and Fox, Gordon A}, + journal={Conservation biology}, + volume={17}, + number={4}, + pages={1170--1172}, + year={2003}, + publisher={JSTOR} +} + +@article{robert2003variation, + title={Variation among individuals, demographic stochasticity, and extinction: response to Kendall and Fox}, + author={Robert, Alexandre and Sarrazin, Fran{\c{c}}ois and Couvet, Denis}, + journal={Conservation Biology}, + volume={17}, + number={4}, + pages={1166--1169}, + year={2003}, + publisher={JSTOR} +} + +@article{clark2001invasion, + title={Invasion by extremes: population spread with variation in dispersal and reproduction}, + author={Clark, James S and Lewis, Mark and Horvath, Lajos}, + journal={The American Naturalist}, + volume={157}, + number={5}, + pages={537--554}, + year={2001}, + publisher={The University of Chicago Press} +} + +@article{bian2003representation, + title={The representation of the environment in the context of individual-based modeling}, + author={Bian, Ling}, + journal={Ecological Modelling}, + volume={159}, + number={2-3}, + pages={279--296}, + year={2003}, + publisher={Elsevier} +} + +@incollection{saupe1988algorithms, + title={Algorithms for random fractals}, + author={Saupe, Dietmar}, + booktitle={The science of fractal images}, + pages={71--136}, + year={1988}, + publisher={Springer} +} + +@article{pe2013simple, + title={Simple process-based simulators for generating spatial patterns of habitat loss and fragmentation: a review and introduction to the G-RaFFe model}, + author={Pe'er, Guy and Zurita, Gustavo A and Schober, Lucia and Bellocq, Maria I and Strer, Maximilian and M{\"u}ller, Michael and P{\"u}tz, Sandro}, + journal={PLoS One}, + volume={8}, + number={5}, + pages={e64968}, + year={2013}, + publisher={Public Library of Science} +} + +@article{with1997application, + title={The Application of Neutral Landscape Models in Conservation Biology: Aplicaci{\'o}n de Modelos de Paisaje Neutros en la Biolog{\'\i}a de la Conservaci{\'o}n}, + author={With, Kimberly A}, + journal={Conservation Biology}, + volume={11}, + number={5}, + pages={1069--1080}, + year={1997}, + publisher={Wiley Online Library} +} + +@article{chipperfield2011updated, + title={An updated algorithm for the generation of neutral landscapes by spectral synthesis}, + author={Chipperfield, Joseph D and Dytham, Calvin and Hovestadt, Thomas}, + journal={PLoS One}, + volume={6}, + number={2}, + pages={e17040}, + year={2011}, + publisher={Public Library of Science} +} + +@article{peng2012, + title={Forward-Time Population Genetics Simulations: Methods, Implementation, and Applications.}, + author={Peng, Bo and Kimmel, Marek and Amos, Christopher}, + year={2012}, + journal={Wiley-Blackwell}, + publisher={Wiley-Blackwell} +} + +@article{weir1984, + title={Estimating F-Statistics for The Analysis of Population Structure}, + author={Weir, B.S. and Cockerham, C. C.}, + journal={Evolution}, + volume={38}, + number={6}, + pages={1358--1370}, + year={1984}, + doi = {10.1111/j.1558-5646.1984.tb05657.x} +} + +@article{weir2002, + title={Estimating F-Statistics}, + author={Weir, B.S. and Hill, W. G.}, + journal={Ann. Rev. Genet.}, + volume={36}, + pages={721--750}, + year={2002}, + doi = {10.1146/annurev.genet.36.050802.093940} +} + +@article{cockerham1969, +author = {Cockerham, C. Clark}, +title = {VARIANCE OF GENE FREQUENCIES}, +journal = {Evolution}, +volume = {23}, +number = {1}, +pages = {72-84}, +doi = {https://doi.org/10.1111/j.1558-5646.1969.tb03496.x}, +url = {https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1558-5646.1969.tb03496.x}, +eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1558-5646.1969.tb03496.x}, +year = {1969} +} + +@article{holsinger2009, + title={Genetics in geographically structured populations: defining, estimating and interpreting FST}, + author={Holsinger, Kent and Weir, Bruce S.}, + journal={Nature Reviews Genetics }, + volume={10}, + pages={639--650}, + year={2009}, + doi = {10.1038/nrg2611} +} \ No newline at end of file diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RS_ODD.bib b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RS_ODD.bib new file mode 100644 index 0000000..c95e86b --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RS_ODD.bib @@ -0,0 +1,5146 @@ + +@article{abenSimpleIndividualbasedModels2014, + title = {Simple Individual-Based Models Effectively Represent {{Afrotropical}} Forest Bird Movement in Complex Landscapes}, + author = {Aben, Job and Strubbe, Diederik and Adriaensen, Frank and Palmer, Stephen C. F. and Travis, Justin M. J. and Lens, Luc and Matthysen, Erik}, + year = {2014}, + journal = {Journal of Applied Ecology}, + volume = {51}, + number = {3}, + pages = {693--702}, + issn = {1365-2664}, + doi = {10.1111/1365-2664.12224}, + abstract = {Reliable estimates of dispersal rates between habitat patches (i.e. functional connectivity) are critical for predicting long-term effects of habitat fragmentation on population persistence. Connectivity measures are frequently derived from least cost path or graph-based approaches, despite the fact that these methods make biologically unrealistic assumptions. Individual-based models (IBMs) have been proposed as an alternative as they allow modelling movement behaviour in response to landscape resistance. However, IBMs typically require excessive data to be useful for management. Here, we test the extent to which an IBM requiring only an uncomplicated set of movement rules [the `stochastic movement simulator' (SMS)] can predict animal movement behaviour in real-world landscapes. Movement behaviour of two forest birds, the Cabanis's greenbul Phyllastrephus cabanisi (a forest specialist) and the white-starred robin Pogonocichla stellata (a habitat generalist), across an Afrotropical matrix was simulated using SMS. Predictions from SMS were evaluated against a set of detailed movement paths collected by radiotracking homing individuals. SMS was capable of generating credible predictions of bird movement, although simulations were sensitive to the cost values and the movement rules specified. Model performance was generally highest when movement was simulated across low-contrasting cost surfaces and when virtual individuals were assigned low directional persistence and limited perceptual range. SMS better predicted movements of the habitat specialist than the habitat generalist, which highlights its potential to model functional connectivity when species movements are affected by the matrix. Synthesis and applications. Modelling the dispersal process with greater biological realism is likely to be critical for improving our predictive capability regarding functional connectivity and population persistence. For more realistic models to be widely applied, it is vital that their application is not overly complicated or data demanding. Here, we show that given relatively basic understanding of a species' dispersal ecology, the stochastic movement simulator represents a promising tool for estimating connectivity, which can help improve the design of functional ecological networks aimed at successful species conservation.}, + langid = {english}, + keywords = {dispersal,functional connectivity,habitat fragmentation,homing experiment,perceptual range,true skill statistic}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/1365-2664.12224}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\BK8SA76N\\Aben et al. - 2014 - Simple individual-based models effectively represe.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\AMNGG6P5\\1365-2664.html} +} + +@article{adriaensenApplicationLeastcostModelling2003, + title = {The Application of `Least-Cost' Modelling as a Functional Landscape Model}, + author = {Adriaensen, F. and Chardon, J. P. and De Blust, G. and Swinnen, E. and Villalba, S. and Gulinck, H. and Matthysen, E.}, + year = {2003}, + month = aug, + journal = {Landscape and Urban Planning}, + volume = {64}, + number = {4}, + pages = {233--247}, + issn = {0169-2046}, + doi = {10.1016/S0169-2046(02)00242-6}, + abstract = {The growing awareness of the adverse effects of habitat fragmentation on natural systems has resulted in a rapidly increasing number of actions to reduce current fragmentation of natural systems as well as a growing demand for tools to predict and evaluate the effect of changes in the landscape on connectivity in the natural world. Recent studies used `least-cost' modelling (available as a toolbox in GIS-systems) to calculate `effective distance', a measure for distance modified with the cost to move between habitat patches based on detailed geographical information on the landscape as well as behavioural aspects of the organisms studied. We applied the method to a virtual landscape and a small scaled agricultural system subject to different scenarios in a land re-allotment project. We discuss the importance of technical aspects and ecological assumption underlying this modelling method. The model is shown to be a flexible tool to model functional connectivity in the study of the relation between landscape and mobility of organisms as well as in scenario building and evaluation in wild life protection projects and applied land management projects. Since `effective distance' has the same units as Euclidean distance (m), this effective distance may be a straightforward way to include landscape and behavioural aspects in other models which include distance as a measure for isolation. We show the importance of the `ecological' quality of the input maps and the choice of relevant landscape features and resistance values.}, + langid = {english}, + keywords = {Connectivity,Cost-distance,Effective distance,Environmental planning,Isolation,Landscape model}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\9X9J957L\\S0169204602002426.html} +} + +@article{altweggDensitydependentDispersalSpeed2013, + title = {Density-Dependent Dispersal and the Speed of Range Expansions}, + author = {Altwegg, Res and Collingham, Yvonne C. and Erni, Birgit and Huntley, Brian}, + year = {2013}, + journal = {Diversity and Distributions}, + volume = {19}, + number = {1}, + pages = {60--68}, + issn = {1472-4642}, + doi = {10.1111/j.1472-4642.2012.00943.x}, + abstract = {Aim The speed of range expansions, be it invasive species colonizing a new area or species tracking a moving climatic niche, critically depends on dispersal. Models for species' range expansions generally assume dispersal to be independent of local population densities. However, animals often disperse in response to high population size or alternatively may avoid or leave areas of very low population sizes. We explore whether such density dependence in dispersal can safely be ignored when predicting the speed of range expansions. Location Simulation study. Methods We use simulations to examine the effect of different forms of density dependence in emigration and immigration on the speed of range expansions. For emigration, we consider linear and nonlinear forms of positive density dependence, negative density dependence at low population densities and constant emigration rates. For immigration, we consider options where individuals avoid crowded patches, are attracted to the presence of conspecifics or settle independent of local density. Results The speed of range expansion was slowest when emigration was strongly positively related to density (higher emigration at higher densities) and when individuals avoided settling in low-density patches. It tended to be fastest under negatively density-dependent emigration (higher emigration at lower densities). These results were consistent across two different life histories and different levels of carrying capacity. Main conclusions Our results suggest that considering density-dependent dispersal and the mechanisms leading to it are important for correctly predicting species' rates of spread. Organisms with a tendency to aggregate, for example, by relying on conspecific attraction in settlement and emigrating mainly in response to high local densities, are predicted to be least likely to expand their ranges and most at risk from spatial shifts in their climatic niches.}, + langid = {english}, + keywords = {Allee effect,climate change,density-dependent emigration,density-dependent immigration,global change,invasion,range expansion,settlement,simulation model}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2012.00943.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6HS9GCCF\\Altwegg et al. - 2013 - Density-dependent dispersal and the speed of range.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\QXVH4PMB\\j.1472-4642.2012.00943.html} +} + +@article{andersonDynamicsRangeMargins2009, + title = {Dynamics of Range Margins for Metapopulations under Climate Change}, + author = {Anderson, B.j and Ak{\c c}akaya, H.r and Ara{\'u}jo, M.b and Fordham, D.a and {Martinez-Meyer}, E and Thuiller, W and Brook, B.w}, + year = {2009}, + month = apr, + journal = {Proceedings of the Royal Society B: Biological Sciences}, + volume = {276}, + number = {1661}, + pages = {1415--1420}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2008.1681}, + abstract = {We link spatially explicit climate change predictions to a dynamic metapopulation model. Predictions of species' responses to climate change, incorporating metapopulation dynamics and elements of dispersal, allow us to explore the range margin dynamics for two lagomorphs of conservation concern. Although the lagomorphs have very different distribution patterns, shifts at the edge of the range were more pronounced than shifts in the overall metapopulation. For Romerolagus diazi (volcano rabbit), the lower elevation range limit shifted upslope by approximately 700{$\mkern1mu$}m. This reduced the area occupied by the metapopulation, as the mountain peak currently lacks suitable vegetation. For Lepus timidus (European mountain hare), we modelled the British metapopulation. Increasing the dispersive estimate caused the metapopulation to shift faster on the northern range margin (leading edge). By contrast, it caused the metapopulation to respond to climate change slower, rather than faster, on the southern range margin (trailing edge). The differential responses of the leading and trailing range margins and the relative sensitivity of range limits to climate change compared with that of the metapopulation centroid have important implications for where conservation monitoring should be targeted. Our study demonstrates the importance and possibility of moving from simple bioclimatic envelope models to second-generation models that incorporate both dynamic climate change and metapopulation dynamics.}, + keywords = {elevation,extinction risk,global warming,latitude,population dynamics,range limits}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\SW9KLN7A\\Anderson et al. - 2009 - Dynamics of range margins for metapopulations unde.pdf} +} + +@article{araujoClimateChangeThreatens2011, + title = {Climate Change Threatens {{European}} Conservation Areas}, + author = {Ara{\'u}jo, Miguel B. and Alagador, Diogo and Cabeza, Mar and {Nogu{\'e}s-Bravo}, David and Thuiller, Wilfried}, + year = {2011}, + journal = {Ecology Letters}, + volume = {14}, + number = {5}, + pages = {484--492}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2011.01610.x}, + abstract = {Ecology Letters (2011) 14: 484\textendash 492 Abstract Europe has the world's most extensive network of conservation areas. Conservation areas are selected without taking into account the effects of climate change. How effectively would such areas conserve biodiversity under climate change? We assess the effectiveness of protected areas and the Natura 2000 network in conserving a large proportion of European plant and terrestrial vertebrate species under climate change. We found that by 2080, 58 {$\pm$} 2.6\% of the species would lose suitable climate in protected areas, whereas losses affected 63 {$\pm$} 2.1\% of the species of European concern occurring in Natura 2000 areas. Protected areas are expected to retain climatic suitability for species better than unprotected areas (P {$<$} 0.001), but Natura 2000 areas retain climate suitability for species no better and sometimes less effectively than unprotected areas. The risk is high that ongoing efforts to conserve Europe's biodiversity are jeopardized by climate change. New policies are required to avert this risk.}, + langid = {english}, + keywords = {Bioclimatic envelope models,climate change,conservation planning,gap analysis,Natura 2000 networks,protected areas}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2011.01610.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\U2354LV7\\Araújo et al. - 2011 - Climate change threatens European conservation are.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\C2EKNDRI\\j.1461-0248.2011.01610.html} +} + +@article{araujoReducingUncertaintyProjections2005, + title = {Reducing Uncertainty in Projections of Extinction Risk from Climate Change}, + author = {Ara{\'u}jo, Miguel B. and Whittaker, Robert J. and Ladle, Richard J. and Erhard, Markus}, + year = {2005}, + journal = {Global Ecology and Biogeography}, + volume = {14}, + number = {6}, + pages = {529--538}, + issn = {1466-8238}, + doi = {10.1111/j.1466-822X.2005.00182.x}, + abstract = {Aim Concern over the implications of climate change for biodiversity has led to the use of species\textendash climate `envelope' models to forecast risks of species extinctions under climate change scenarios. Recent studies have demonstrated significant variability in model projections and there remains a need to test the accuracy of models and to reduce uncertainties. Testing of models has been limited by a lack of data against which projections of future ranges can be tested. Here we provide a first test of the predictive accuracy of such models using observed species' range shifts and climate change in two periods of the recent past. Location Britain. Methods Observed range shifts for 116 breeding bird species in Britain between 1967 and 1972 (t1) and 1987\textendash 91 (t2) are used. We project range shifts between t1 and t2 for each species based on observed climate using 16 alternative models (4 methods \texttimes{} 2 data parameterizations \texttimes{} 2 rules to transform probabilities of occurrence into presence and absence records). Results Modelling results were extremely variable, with projected range shifts varying both in magnitude and in direction from observed changes and from each other. However, using approaches that explore the central tendency (consensus) of model projections, we were able to improve agreement between projected and observed shifts significantly. Conclusions Our results provide the first empirical evidence of the value of species\textendash climate `envelope' models under climate change and demonstrate reduction in uncertainty and improvement in accuracy through selection of the most consensual projections.}, + langid = {english}, + keywords = {Bioclimatic envelope modelling,British birds,climate change,consensus forecasting,model variability,probabilistic modelling,species distributions,uncertainty}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-822X.2005.00182.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QL2L633L\\Araújo et al. - 2005 - Reducing uncertainty in projections of extinction .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\PXZS6NGK\\j.1466-822X.2005.00182.html} +} + +@article{armsworthConditionalDispersalClines2008, + title = {Conditional Dispersal, Clines, and the Evolution of Dispersiveness}, + author = {Armsworth, Paul R.}, + year = {2008}, + journal = {Theoretical Ecology}, + volume = {2}, + number = {2}, + pages = {105--117}, + issn = {1874-1746}, + doi = {10.1007/s12080-008-0032-2}, + abstract = {Conditional dispersal, in which an individual's decision over whether to disperse is a response to environmental conditions, features prominently in studies of dispersal evolution. Using models of clines, I examine how one widely discussed cost of dispersal, namely, that dispersal impedes local adaptation, changes with conditional dispersal and what this implies for dispersal evolution. I examine the consequences for dispersal evolution of the responsiveness of dispersal to the environment, the accuracy of any proximal cues that individuals rely upon to assess habitat quality, and whether dispersal responds to fitness itself or only to some fitness components (juvenile survivorship). All of the conditional dispersal behaviors that I consider weaken the indirect cost of dispersal inhibiting local adaptation. However, if individuals rely on imprecise cues to assess habitat quality and base dispersal decisions on juvenile survivorship, then conditional dispersal can incur additional costs by exacerbating overcrowding. Conditional dispersal initially leads to steeper clines in traits under direct selection, but when dispersiveness can itself evolve, conditional dispersal allows sigmoidal clines to persist long after those obtained with unconditional movement would become stepped.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\4XFB9WFK\\Armsworth - 2009 - Conditional dispersal, clines, and the evolution o.pdf} +} + +@article{armsworthStructureClinesFitness2008, + title = {The {{Structure}} of {{Clines}} with {{Fitness}}-{{Dependent Dispersal}}.}, + author = {Armsworth, Paul R. and Roughgarden, Joan E.}, + year = {2008}, + month = nov, + journal = {The American Naturalist}, + volume = {172}, + number = {5}, + pages = {648--657}, + publisher = {{The University of Chicago Press}}, + issn = {0003-0147}, + doi = {10.1086/591685}, + abstract = {Spatial models commonly assume that dispersal does not depend on environmental conditions or phenotype. For example, these assumptions underpin explanations for clines on the basis of a trade-off between dispersal and local adaptation. We reexamine clines when an individual's decisions over whether and where to disperse depend on its fitness. We compare fitness-dependent dispersal with cases where dispersal responds to juvenile survivorship only. Clines are steeper the more responsive dispersal is to environmental conditions for all dispersal behaviors that we consider. Clines eventually become stepped as the responsiveness of dispersal to environmental conditions is increased for half of the dispersal behaviors we consider, but smooth clines are maintained for the remaining cases. Smooth clines are maintained by the biased movement of individuals out of the hybrid zone when individuals move directionally in response to gradients in juvenile survivorship, which is a different mechanism to that maintaining smooth clines in classic cline theory.}, + keywords = {cline,conditional dispersal,directed movement,fitness‐dependent dispersal,habitat selection,hybrid zone}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\CJSL35EC\\Armsworth und Roughgarden - 2008 - The Structure of Clines with Fitness‐Dependent Dis.pdf} +} + +@article{atkinsLocalAdaptationEvolution2010, + title = {Local Adaptation and the Evolution of Species' Ranges under Climate Change}, + author = {Atkins, K. E. and Travis, J. M. J.}, + year = {2010}, + month = oct, + journal = {Journal of Theoretical Biology}, + volume = {266}, + number = {3}, + pages = {449--457}, + issn = {0022-5193}, + doi = {10.1016/j.jtbi.2010.07.014}, + abstract = {The potential impact of climate change on biodiversity is well documented. A well developed range of statistical methods currently exists that projects the possible future habitat of a species directly from the current climate and a species distribution. However, studies incorporating ecological and evolutionary processes remain limited. Here, we focus on the potential role that local adaptation to climate may play in driving the range dynamics of sessile organisms. Incorporating environmental adaptation into a stochastic simulation yields several new insights. Counter-intuitively, our simulation results suggest that species with broader ranges are not necessarily more robust to climate change. Instead, species with broader ranges can be more susceptible to extinction as locally adapted genotypes are often blocked from range shifting by the presence of cooler adapted genotypes that persist even when their optimum climate has left them behind. Interestingly, our results also suggest that it will not always be the cold-adapted phenotypes that drive polewards range expansion. Instead, range shifts may be driven by phenotypes conferring adaptation to conditions prevalent towards the centre of a species' equilibrium distribution. This may have important consequences for the conservation method termed predictive provenancing. These initial results highlight the potential importance of local adaptation in determining how species will respond to climate change and we argue that this is an area requiring urgent theoretical and empirical attention.}, + langid = {english}, + keywords = {Environmental gradient,Environmental niche,Extinction,Local density dependence,Species’ range}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Y5SR9B3N\\Atkins und Travis - 2010 - Local adaptation and the evolution of species’ ran.pdf} +} + +@article{bachEvolutionConditionalDispersal2007, + title = {On the Evolution of Conditional Dispersal under Environmental and Demographic Stochasticity}, + author = {Bach, Lars and Ripa, J{\"o}rgen and Lundberg, Per}, + year = {2007}, + journal = {Evolutionary Ecology}, + volume = {9}, + number = {4}, + pages = {663--673}, + publisher = {{Springer}}, + issn = {1573-8477}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\22L7H7FA\\on-the-evolution-of-conditional-dispersal-under-environmental-and-demographic-stochasticity(f23.html} +} + +@article{baguetteIndividualDispersalLandscape2013, + title = {Individual Dispersal, Landscape Connectivity and Ecological Networks}, + author = {Baguette, Michel and Blanchet, Simon and Legrand, Delphine and Stevens, Virginie M. and Turlure, Camille}, + year = {2013}, + journal = {Biological Reviews}, + volume = {88}, + number = {2}, + pages = {310--326}, + issn = {1469-185X}, + doi = {10.1111/brv.12000}, + abstract = {Connectivity is classically considered an emergent property of landscapes encapsulating individuals' flows across space. However, its operational use requires a precise understanding of why and how organisms disperse. Such movements, and hence landscape connectivity, will obviously vary according to both organism properties and landscape features. We review whether landscape connectivity estimates could gain in both precision and generality by incorporating three fundamental outcomes of dispersal theory. Firstly, dispersal is a multi-causal process; its restriction to an `escape reaction' to environmental unsuitability is an oversimplification, as dispersing individuals can leave excellent quality habitat patches or stay in poor-quality habitats according to the relative costs and benefits of dispersal and philopatry. Secondly, species, populations and individuals do not always react similarly to those cues that trigger dispersal, which sometimes results in contrasting dispersal strategies. Finally, dispersal is a major component of fitness and is thus under strong selective pressures, which could generate rapid adaptations of dispersal strategies. Such evolutionary responses will entail spatiotemporal variation in landscape connectivity. We thus strongly recommend the use of genetic tools to: (i) assess gene flow intensity and direction among populations in a given landscape; and (ii) accurately estimate landscape features impacting gene flow, and hence landscape connectivity. Such approaches will provide the basic data for planning corridors or stepping stones aiming at (re)connecting local populations of a given species in a given landscape. This strategy is clearly species- and landscape-specific. But we suggest that the ecological network in a given landscape could be designed by stacking up such linkages designed for several species living in different ecosystems. This procedure relies on the use of umbrella species that are representative of other species living in the same ecosystem.}, + langid = {english}, + keywords = {biodiversity,biological conservation,extinction,functional connectivity,gene flow,habitat selection,ideal free distribution,individual fitness,landscape,landscape fragmentation,landscape genetics,linkage strategy,population isolation,seascape,structural connectivity,umbrella species,water basin}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/brv.12000}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\BITCE59D\\Baguette et al. - 2013 - Individual dispersal, landscape connectivity and e.pdf} +} + +@article{baguetteLandscapeConnectivityAnimal2007, + title = {Landscape Connectivity and Animal Behavior: Functional Grain as a Key Determinant for Dispersal}, + shorttitle = {Landscape Connectivity and Animal Behavior}, + author = {Baguette, Michel and Van Dyck, Hans}, + year = {2007}, + month = oct, + journal = {Landscape Ecology}, + volume = {22}, + number = {8}, + pages = {1117--1129}, + issn = {1572-9761}, + doi = {10.1007/s10980-007-9108-4}, + abstract = {Landscape connectivity can be viewed from two perspectives that could be considered as extremes of a gradient: functional connectivity (refers to how the behavior of a dispersing organism is affected by landscape structure and elements) and structural connectivity (depends on the spatial configuration of habitat patches in the landscape like vicinity or presence of barriers). Here we argue that dispersal behavior changes with landscape configuration stressing the evolutionary dimension that has often been ignored in landscape ecology. Our working hypothesis is that the functional grain of resource patches in the landscape is a crucial factor shaping individual movements, and therefore influencing landscape connectivity. Such changes are likely to occur on the short-term (some generations). We review empirical studies comparing dispersal behavior in landscapes differing in their fragmentation level, i.e., with variable resource grain. We show that behavioral variation affecting each of the three stages of the dispersal process (emigration, displacement or transfer in the matrix, and immigration) is indeed likely to occur according to selective pressures resulting from changes in the grain of the landscape (mortality or deferred costs). Accordingly, landscape connectivity results from the interaction between the dispersal behavior of individuals and the grain of each particular landscape. The existence of this interaction requires that connectivity estimates (being based on individual-based models, least cost distance algorithms, and structural connectivity metrics or even Euclidian distance) should be carefully evaluated for their applicability with respect to the required level of precision in species-specific and landscape information.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\MDCFMANN\\Baguette und Van Dyck - 2007 - Landscape connectivity and animal behavior functi.pdf} +} + +@article{baguetteLongDistanceDispersal2003, + title = {Long {{Distance Dispersal}} and {{Landscape Occupancy}} in a {{Metapopulation}} of the {{Cranberry Fritillary Butterfly}}}, + author = {Baguette, Michel}, + year = {2003}, + journal = {Ecography}, + volume = {26}, + number = {2}, + pages = {153--160}, + publisher = {{[Nordic Society Oikos, Wiley]}}, + issn = {0906-7590}, + abstract = {Movements between habitat patches in a patchy population of the butterfly Boloria aquilonaris were monitored using capture-mark-recapture methods during three successive generations. For each data set, the inverse cumulative proportion of individuals moving 100 m distance classes was fitted to the negative exponential function and the inverse power function. In each case, the negative exponential function provided a better fit than the inverse power function. Two dispersal kernels were generated using both negative exponential and inverse power functions. These dispersal kernels were used to predict movements between 14 suitable sites in a landscape of \$220\textbackslash{} \{\textbackslash rm km\}\^\{2\}\$. The negative exponential function generated a dispersal kernel predicting extremely low probabilities for movements exceeding 1 km. The inverse power function generated probabilities predicting that between site movements were possible, according to metapopulation size. CMR studies in the landscape revealed that long distance movements occurred at each generation, corresponding to predictions of the inverse power function dispersal kernel. A total of 26 movements between sites (up to 13 km) were detected, together with recolonisation of empty sites. The spatial scale of the metapopulation dynamics is larger than ever reported on butterflies and long distance movements clearly matter to the persistence of this species in a highly fragmented landscape.} +} + +@article{bakerIncrementalCostsBenefits2004, + title = {Incremental {{Costs}} and {{Benefits Shape Natal Dispersal}}: {{Theory}} and {{Example}} with {{Hemilepistus}} Reaumuri}, + shorttitle = {Incremental {{Costs}} and {{Benefits Shape Natal Dispersal}}}, + author = {Baker, Mitchell B. and Rao, Steven}, + year = {2004}, + journal = {Ecology}, + volume = {85}, + number = {4}, + pages = {1039--1051}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + abstract = {Incremental (distance-dependent) costs and benefits of dispersal have received less attention than those that are qualitative. We present a dynamic programming model of settling behavior using parameters estimated from a field study of dispersal in desert isopods, Hemilepistus reaumuri, which walk up to thousands of meters before settling in new or already-established burrows each spring. The model shows that incremental costs of dispersal lead to right-skewed population dispersal patterns, in contrast to cost-free systems or those with unitary costs (i.e., a one time cost of leaving a group or patch). In the model, continuous variation in habitat quality, as opposed to discrete suitable vs. unsuitable sites, allows for trade-offs with dispersal costs that lead to shifts in the likelihood of settling in a patch of a given quality. Thus, measurement of quantitative costs and benefits of movement are needed to understand population dispersal distributions. These costs or benefits may be observable during or after movement, and we examined both pre- and postsettling incremental consequences of dispersal. The daily mortality rate of traveling isopods was 4.2\% during the dispersal season, higher than that of settled individuals. Successful settlers traveled more slowly, but burrows started in midseason were most likely to succeed. More distant burrows failed more often, suggesting either an additional cost of movement or a difference in the quality of individuals traveling different distances. The predicted mean dispersal duration from the simulations matched observed values closely, but was based on an unrealistic assumption of perfect knowledge of habitat quality, suggesting some other factor favors longer times before settling. Reproductive success was much higher in re-used burrows than in new burrows, making them a possible incentive for long-distance movements.} +} + +@article{balciauskasEstimationCarryingCapacity2009, + title = {Estimation of {{Carrying Capacity}} and {{Growth Rate}} of {{Wolf}} in {{Lithuania}}}, + author = {Bal{\v c}iauskas, Linas and Kawata, Yukichika}, + year = {2009}, + month = jan, + journal = {Acta Zoologica Lituanica}, + volume = {19}, + number = {2}, + pages = {79--84}, + publisher = {{Taylor \& Francis}}, + issn = {1392-1657}, + doi = {10.2478/v10043-009-0018-3}, + abstract = {The purpose of this paper is to estimate ecological carrying capacity (K) and growth rate (r) of Lithuanian wolf based on the estimated population sizes and number of harvests from 1966 to 2007. We used the modified Schaefer model where population dynamics is described by the logistic-equation-type growth function with time lag operator ({$\tau$}) and harvest. We statistically selected the best model whose {$\tau$} value was 4 and estimated value of K and r were 626 heads for the total Lithuanian territory and 0.776/ year, respectively. Then we examined the appropriateness of the values from the ecological point of view and concluded that ecological carrying capacity is supported by the prey base of wild animals, mainly cervids, and also by depredation on domestic animals. In 1994\textendash 1998, the population was near ecological carrying capacity or exceeding it, what we explain by high ecological plasticity of the species and increased use of domestic animals.}, + keywords = {Canis lupus,ecological carrying capacity,growth rate,Schaefer model}, + annotation = {\_eprint: https://doi.org/10.2478/v10043-009-0018-3}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HUEETBTZ\\Balčiauskas und Kawata - 2009 - Estimation of Carrying Capacity and Growth Rate of.pdf} +} + +@article{bartonEvolutionIntelligentDispersal2009, + title = {The Evolution of an `Intelligent' Dispersal Strategy: Biased, Correlated Random Walks in Patchy Landscapes}, + shorttitle = {The Evolution of an `Intelligent' Dispersal Strategy}, + author = {Barto{\'n}, Kamil A. and Phillips, Ben L. and Morales, Juan M. and Travis, Justin M. J.}, + year = {2009}, + journal = {Oikos}, + volume = {118}, + number = {2}, + pages = {309--319}, + issn = {1600-0706}, + doi = {10.1111/j.1600-0706.2008.16936.x}, + abstract = {Theoretical work exploring dispersal evolution focuses on the emigration rate of individuals and typically assumes that movement occurs either at random to any other patch or to one of the nearest-neighbour patches. There is a lack of work exploring the process by which individuals move between patches, and how this process evolves. This is of concern because any organism that can exert control over dispersal direction can potentially evolve efficiencies in locating patches, and the process by which individuals find new patches will potentially have major effects on metapopulation dynamics and gene flow. Here, we take an initial step towards filling this knowledge gap. To do this we constructed a continuous space population model, in which individuals each carry heritable trait values that specify the characteristics of the biased correlated random walk they use to disperse from their natal patch. We explore how the evolution of the random walk depends upon the cost of dispersal, the density of patches in the landscape, and the emigration rate. The clearest result is that highly correlated walks always evolved (individuals tended to disperse in relatively straight lines from their natal patch), reflecting the efficiency of straight-line movement. In our models, more costly dispersal resulted in walks with higher correlation between successive steps. However, the exact walk that evolved also depended upon the density of suitable habitat patches, with low density habitat evolving more biased walks (individuals which orient towards suitable habitat at quite large distances from that habitat). Thus, low density habitat will tend to develop individuals which disperse efficiently between adjacent habitat patches but which only rarely disperse to more distant patches; a result that has clear implications for metapopulation theory. Hence, an understanding of the movement behaviour of dispersing individuals is critical for robust long-term predictions of population dynamics in fragmented landscapes.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2008.16936.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\JNCMDJPJ\\Barton et al. - 2009 - The evolution of an ‘intelligent’ dispersal strate.pdf} +} + +@article{bartonRiskyMovementIncreases2012, + title = {Risky Movement Increases the Rate of Range Expansion}, + author = {Barto{\'n}, K. A. and Hovestadt, T. and Phillips, B. L. and Travis, J. M. J.}, + year = {2012}, + month = mar, + journal = {Proceedings of the Royal Society B: Biological Sciences}, + volume = {279}, + number = {1731}, + pages = {1194--1202}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2011.1254}, + abstract = {The movement rules used by an individual determine both its survival and dispersal success. Here, we develop a simple model that links inter-patch movement behaviour with population dynamics in order to explore how individual dispersal behaviour influences not only its dispersal and survival, but also the population's rate of range expansion. Whereas dispersers are most likely to survive when they follow nearly straight lines and rapidly orient movement towards a non-natal patch, the most rapid rates of range expansion are obtained for trajectories in which individuals delay biasing their movement towards a non-natal patch. This result is robust to the spatial structure of the landscape. Importantly, in a set of evolutionary simulations, we also demonstrate that the movement strategy that evolves at an expanding front is much closer to that maximizing the rate of range expansion than that which maximizes the survival of dispersers. Our results suggest that if one of our conservation goals is the facilitation of range-shifting, then current indices of connectivity need to be complemented by the development and utilization of new indices providing a measure of the ease with which a species spreads across a landscape.}, + keywords = {biased correlated random walk,evolution,individual-based model,movement,range margin}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\M8C2KNS4\\Bartoń et al. - 2012 - Risky movement increases the rate of range expansi.pdf} +} + +@article{beaumontApproximateBayesianComputation2010, + title = {Approximate {{Bayesian Computation}} in {{Evolution}} and {{Ecology}}}, + author = {Beaumont, Mark A.}, + year = {2010}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + volume = {41}, + number = {1}, + pages = {379--406}, + doi = {10.1146/annurev-ecolsys-102209-144621}, + abstract = {In the past 10years a statistical technique, approximate Bayesian computation (ABC), has been developed that can be used to infer parameters and choose between models in the complicated scenarios that are often considered in the environmental sciences. For example, based on gene sequence and microsatellite data, the method has been used to choose between competing models of human demographic history as well as to infer growth rates, times of divergence, and other parameters. The method fits naturally in the Bayesian inferential framework, and a brief overview is given of the key concepts. Three main approaches to ABC have been developed, and these are described and compared. Although the method arose in population genetics, ABC is increasingly used in other fields, including epidemiology, systems biology, ecology, and agent-based modeling, and many of these applications are briefly described.}, + annotation = {\_eprint: https://doi.org/10.1146/annurev-ecolsys-102209-144621}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GYAR69T9\\Beaumont - 2010 - Approximate Bayesian Computation in Evolution and .pdf} +} + +@article{bellardImpactsClimateChange2012, + title = {Impacts of Climate Change on the Future of Biodiversity}, + author = {Bellard, C{\'e}line and Bertelsmeier, Cleo and Leadley, Paul and Thuiller, Wilfried and Courchamp, Franck}, + year = {2012}, + month = apr, + journal = {Ecology Letters}, + volume = {15}, + number = {4}, + pages = {365--377}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2011.01736.x}, + abstract = {Many studies in recent years have investigated the effects of climate change on the future of biodiversity. In this review, we first examine the different possible effects of climate change that can operate at individual, population, species, community, ecosystem and biome scales, notably showing that species can respond to climate change challenges by shifting their climatic niche along three non-exclusive axes: time (e.g. phenology), space (e.g. range) and self (e.g. physiology). Then, we present the principal specificities and caveats of the most common approaches used to estimate future biodiversity at global and sub-continental scales and we synthesise their results. Finally, we highlight several challenges for future research both in theoretical and applied realms. Overall, our review shows that current estimates are very variable, depending on the method, taxonomic group, biodiversity loss metrics, spatial scales and time periods considered. Yet, the majority of models indicate alarming consequences for biodiversity, with the worst-case scenarios leading to extinction rates that would qualify as the sixth mass extinction in the history of the earth.}, + langid = {english}, + pmcid = {PMC3880584}, + pmid = {22257223}, + keywords = {Biodiversity,climate change,Climate Change,Conservation of Natural Resources,Ecosystem,Models; Theoretical,Population Dynamics,species extinctions}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HLSEUUDE\\Bellard et al. - 2012 - Impacts of climate change on the future of biodive.pdf} +} + +@incollection{bentonDispersalInvertebratesInfluences2012, + title = {Dispersal in Invertebrates: Influences on Individual Decisions}, + shorttitle = {Dispersal in Invertebrates}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Benton, Tim G. and Bowler, Diana E.}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0004}, + abstract = {This chapter briefly lists some of the generic factors that differentiate dispersal in invertebrates from vertebrates. Invertebrates can have considerable flexibility in their life histories and can often develop specific machinery or life-history stages for movement or a combination of life-history stage and behaviour. This makes the overall context of the life history crucial in determining the scope for dispersal, which is often constrained developmentally into a short period. There has been an increasing recognition that variability between individuals is both ubiquitous and important in ecology. The purpose of this chapter is to focus on the proximal factors that influence an individual's decisions, using examples from invertebrates. Environmental factors are first addressed, followed by the role of an individual's age, stage, sex, and condition on dispersal decisions.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {ecology,invertebrates,life histories,life-history stages,variability,vertebrates} +} + +@article{bentonMicrocosmExperimentsCan2007, + title = {Microcosm Experiments Can Inform Global Ecological Problems}, + author = {Benton, Tim G. and Solan, Martin and Travis, Justin M. J. and Sait, Steven M.}, + year = {2007}, + month = oct, + journal = {Trends in Ecology \& Evolution}, + volume = {22}, + number = {10}, + pages = {516--521}, + issn = {0169-5347}, + doi = {10.1016/j.tree.2007.08.003}, + abstract = {Global-scale environmental problems are rarely regarded as amenable to traditional scientific experiment. We argue here that small-scale experiments using `model organisms' in microcosms or mesocosms can be a useful approach for apparently intractable global problems, such as ecosystem responses to climate change or managing biodiversity through the design of nature reserves. An experimental, small-scale research programme can easily be coupled with the development of theory and act as a stimulus to further research, thereby hastening both understanding of the issues and development of practical solutions. This process \textendash{} from microcosm experiment to the development of practical application \textendash{} has previously been influential but also has a long time lag. We suggest short-cuts in an attempt to stimulate the use of small-scale experiments to address globally urgent issues with meaningful policy implications.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\L32VQKBL\\S0169534707002315.html} +} + +@article{bessa-gomesDiscreteTwosexModels2010, + title = {Discrete Two-Sex Models of Population Dynamics: {{On}} Modelling the Mating Function}, + shorttitle = {Discrete Two-Sex Models of Population Dynamics}, + author = {{Bessa-Gomes}, Carmen and Legendre, St{\'e}phane and Clobert, Jean}, + year = {2010}, + month = sep, + journal = {Acta Oecologica}, + volume = {36}, + pages = {439--445}, + issn = {1146-609X}, + doi = {10.1016/j.actao.2010.02.010}, + abstract = {Although sexual reproduction has long been a central subject of theoretical ecology, until recently its consequences for population dynamics were largely overlooked. This is now changing, and many studies have addressed this issue, showing that when the mating system is taken into account, the population dynamics depends on the relative abundance of males and females, and is non-linear. Moreover, sexual reproduction increases the extinction risk, namely due to the Allee effect. Nevertheless, different studies have identified diverse potential consequences, depending on the choice of mating function. In this study, we investigate the consequences of three alternative mating functions that are frequently used in discrete population models: the minimum; the harmonic mean; and the modified harmonic mean. We consider their consequences at three levels: on the probability that females will breed; on the presence and intensity of the Allee effect; and on the extinction risk. When we consider the harmonic mean, the number of times the individuals of the least abundant sex mate exceeds their mating potential, which implies that with variable sex-ratios the potential reproductive rate is no longer under the modeller's control. Consequently, the female breeding probability exceeds 1 whenever the sex-ratio is male-biased, which constitutes an obvious problem. The use of the harmonic mean is thus only justified if we think that this parameter should be re-defined in order to represent the females' breeding rate and the fact that females may reproduce more than once per breeding season. This phenomenon buffers the Allee effect, and reduces the extinction risk. However, when we consider birth-pulse populations, such a phenomenon is implausible because the number of times females can reproduce per birth season is limited. In general, the minimum or modified harmonic mean mating functions seem to be more suitable for assessing the impact of mating systems on population dynamics.} +} + +@article{bestWhichSpeciesWill2007, + title = {Which Species Will Succesfully Track Climate Change? {{The}} Influence of Intraspecific Competition and Density Dependent Dispersal on Range Shifting Dynamics}, + shorttitle = {Which Species Will Succesfully Track Climate Change?}, + author = {Best, A. S. and Johst, K. and M{\"u}nkem{\"u}ller, T. and Travis, J. M. J.}, + year = {2007}, + journal = {Oikos}, + volume = {116}, + number = {9}, + pages = {1531--1539}, + issn = {1600-0706}, + doi = {10.1111/j.0030-1299.2007.16047.x}, + abstract = {Understanding the ability of species to shift their geographic range is of considerable importance given the current period of rapid climate change. Furthermore, a greater understanding of the spatial population dynamics underlying range shifting is required to complement the advances made in climate niche modelling. A simulation model is developed which incorporates three key features that have been largely overlooked in studies of range shifting dynamics: the form of intraspecific competition, density dependent dispersal and the transient dynamics of habitat patches. The results show that the exact shape of the response depends critically on both local and patch dynamics. Species whose intraspecific competition is contest based are more vulnerable than those whose competition is scramble based. Contesters are especially sensitive when combined with density dependent dispersal. Species living in patches whose carrying capacity grows slowly are also susceptible to rapid shifts of environmental conditions. A complementary analytic approach further highlights the importance of intraspecific competition.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.0030-1299.2007.16047.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\IJZ8ET6D\\Best et al. - 2007 - Which species will succesfully track climate chang.pdf} +} + +@article{bianRepresentationEnvironmentContext2003, + title = {The Representation of the Environment in the Context of Individual-Based Modeling}, + author = {Bian, Ling}, + year = {2003}, + month = jan, + journal = {Ecological Modelling}, + volume = {159}, + number = {2}, + pages = {279--296}, + issn = {0304-3800}, + doi = {10.1016/S0304-3800(02)00298-3}, + abstract = {Individual-based modeling includes the explicit representation of the environment, to which individual organisms interact. From the perspective of spatial representation, spatially extended environment is different from discrete individual organisms, thus the success of object-orientation in the representation of individual organisms may not be applicable to the representation of the environment. Over the past few years, the attempt to adopt object-orientation in the representation of the environment has stimulated interesting discussions over what space is and how it may be represented in ecological modeling. The objective of this paper is to evaluate the merit of two traditional approaches used to represent the environment, i.e., the grid model and the patch model, and, in particular, the object-oriented versions of the two approaches in the representation of the environment. Two case studies are provided in support of the discussions of how the environment may be represented. One case study concerns individual fish growth and movement in an aquatic environment and the other concerns the movement of calving elk in a short-grass prairie. The discussion stresses the importance of two issues in the context of individual-based modeling: (1) the distinction between object-orientation used as a programming technique and as a representation means, and (2) the conceptual compatibility between a perceived phenomenon and the approach used to represent the phenomenon. It is suggested that caution be exercised in the practice of treating cells as objects. The paper concludes that two approaches may be appropriate for individual-based modeling. One is a hybrid approach that incorporates the traditional grid model of the environment and an object-oriented model of individual organisms. The other is the all-object approach that combines the object-oriented patches of the environment and the object-oriented individual organisms.}, + langid = {english}, + keywords = {Individual-based modeling,Object-orientation,Spatial representation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RLNSJF35\\S0304380002002983.html} +} + +@article{bitumeDensityGeneticRelatedness2013, + title = {Density and Genetic Relatedness Increase Dispersal Distance in a Subsocial Organism}, + author = {Bitume, E. V. and Bonte, D. and Ronce, O. and Bach, F. and Flaven, E. and Olivieri, I. and Nieberding, C. M.}, + year = {2013}, + journal = {Ecology Letters}, + volume = {16}, + number = {4}, + pages = {430--437}, + issn = {1461-0248}, + doi = {10.1111/ele.12057}, + abstract = {Although dispersal distance plays a major role in determining whether organisms will reach new habitats, empirical data on the environmental factors that affect dispersal distance are lacking. Population density and kin competition are two factors theorised to increase dispersal distance. Using the two-spotted spider mite as a model species, we altered these two environmental conditions and measured the mean dispersal distance of individuals, as well as other attributes of the dispersal kernel. We find that both density and relatedness in the release patch increase dispersal distance. Relatedness, but not density, changes the shape of the dispersal kernel towards a more skewed and leptokurtic shape including a longer `fat-tail'. This is the first experimental demonstration that kin competition can shape the whole distribution of dispersal distances in a population, and thus affect the geographical spread of dispersal phenotypes.}, + langid = {english}, + keywords = {Conditional dispersal,density,distance,invasion,kernel,plasticity,relatedness}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ele.12057}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8XQNKD3E\\Bitume et al. - 2013 - Density and genetic relatedness increase dispersal.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\7RE73I53\\ele.html} +} + +@article{bocediEffectsLocalAdaptation2013, + title = {Effects of Local Adaptation and Interspecific Competition on Species' Responses to Climate Change}, + author = {Bocedi, Greta and Atkins, Katherine E. and Liao, Jishan and Henry, Roslyn C. and Travis, Justin M. J. and Hellmann, Jessica J.}, + year = {2013}, + month = sep, + journal = {Annals of the New York Academy of Sciences}, + volume = {1297}, + pages = {83--97}, + issn = {1749-6632}, + doi = {10.1111/nyas.12211}, + abstract = {Local adaptation and species interactions have been shown to affect geographic ranges; therefore, we need models of climate impact that include both factors. To identify possible dynamics of species when including these factors, we ran simulations of two competing species using an individual-based, coupled map-lattice model using a linear climatic gradient that varies across latitude and is warmed over time. Reproductive success is governed by an individual's adaptation to local climate as well as its location relative to global constraints. In exploratory experiments varying the strength of adaptation and competition, competition reduces genetic diversity and slows range change, although the two species can coexist in the absence of climate change and shift in the absence of competitors. We also found that one species can drive the other to extinction, sometimes long after climate change ends. Weak selection on local adaptation and poor dispersal ability also caused surfing of cooler-adapted phenotypes from the expanding margin backwards, causing loss of warmer-adapted phenotypes. Finally, geographic ranges can become disjointed, losing centrally-adapted genotypes. These initial results suggest that the interplay between local adaptation and interspecific competition can significantly influence species' responses to climate change, in a way that demands future research.}, + langid = {english}, + pmid = {23905876}, + keywords = {Adaptation; Physiological,Animals,Biodiversity,Climate,climate change,Climate Change,competition,Computer Simulation,Ecology,Genetic Variation,geographic range shift,Geography,lattice map model,local adaptation,Phenotype,Plants,species interactions,Species Specificity,Temperature} +} + +@article{bocediProjectingSpeciesRange2012a, + title = {Projecting Species' Range Expansion Dynamics: {{Sources}} of Systematic Biases When Scaling up Patterns and Processes}, + shorttitle = {Projecting Species' Range Expansion Dynamics}, + author = {Bocedi, Greta and Pe'er, Guy and Heikkinen, Risto and Matsinos, Yiannis and Travis, Justin}, + year = {2012}, + month = dec, + journal = {Methods in Ecology and Evolution}, + volume = {3}, + pages = {1008--1018}, + doi = {10.1111/j.2041-210X.2012.00235.x}, + abstract = {1. Dynamic simulation models are a promising tool for assessing how species respond to habitat fragmentation and climate change. However, sensitivity of their outputs to impacts of spatial resolution is insufficiently known. 2. Using an individual-based dynamic model for species' range expansion, we demonstrate an inherent risk of substantial biases resulting from choices relating to the resolution at which key patterns and processes are modelled. 3. Increasing cell size leads to overestimating dispersal distances, the extent of the range shift and population size. Overestimation accelerates with cell size for species with short dispersal capacity and is particularly severe in highly fragmented landscapes. 4. The overestimation results from three main interacting sources: homogenisation of spatial information, alteration of dispersal kernels and stabilisation/aggregation of population dynamics. 5. We urge for caution in selecting the spatial resolution used in dynamic simulations and other predictive models and highlight the urgent need to develop upscaling methods that maintain important patterns and processes at fine scales.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RUMGZ673\\Bocedi et al. - 2012 - Projecting species' range expansion dynamics Sour.pdf} +} + +@article{bocediRangeShifterPlatformModelling2014, + title = {{{RangeShifter}}: A Platform for Modelling Spatial Eco-Evolutionary Dynamics and Species' Responses to Environmental Changes}, + shorttitle = {{{RangeShifter}}}, + author = {Bocedi, Greta and Palmer, Stephen C. F. and Pe'er, Guy and Heikkinen, Risto K. and Matsinos, Yiannis G. and Watts, Kevin and Travis, Justin M. J.}, + year = {2014}, + journal = {Methods in Ecology and Evolution}, + volume = {5}, + number = {4}, + pages = {388--396}, + issn = {2041-210X}, + doi = {10.1111/2041-210X.12162}, + abstract = {Rapid environmental changes are threatening biodiversity and exposing species to novel ecological and evolutionary pressures. The scientific community increasingly recognizes the need for dynamic models integrating sufficient complexity both to improve our understanding of species' responses to environmental changes and to inform effective management strategies. Using three illustrative examples, we introduce a novel modelling platform, RangeShifter, which integrates complex population dynamics and dispersal behaviour, includes plastic and evolutionary processes and simulates scenarios on spatially explicit landscapes. The software provides functionality for a wide variety of modelling applications ranging from applied questions, where it can be parameterized for real landscapes and species to compare alternative potential management interventions, to purely theoretical studies of species' eco-evolutionary dynamics and responses to different environmental pressures. RangeShifter provides an important tool for facilitating the advancement of ecological theory on species' spatial dynamics in response to environmental changes, and linking it directly to application in biodiversity conservation.}, + langid = {english}, + keywords = {connectivity,dispersal,dynamic modelling,environmental change,individual-based modelling,population dynamics,population viability}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/2041-210X.12162}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QHNGAGMT\\Bocedi et al. - 2014 - RangeShifter a platform for modelling spatial eco.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\7ZLZZ8X7\\2041-210X.html} +} + +@article{bocediUncertaintyRoleInformation2012, + title = {Uncertainty and the {{Role}} of {{Information Acquisition}} in the {{Evolution}} of {{Context-Dependent Emigration}}.}, + author = {Bocedi, Greta and Heinonen, Johannes and Travis, Justin M. J.}, + year = {2012}, + month = may, + journal = {The American Naturalist}, + volume = {179}, + number = {5}, + pages = {606--620}, + publisher = {{The University of Chicago Press}}, + issn = {0003-0147}, + doi = {10.1086/665004}, + abstract = {There is increasing empirical evidence that individuals utilize social and environmental cues in making decisions as to whether or not to disperse. However, we lack theory exploring the influence of information acquisition and use on the evolution of dispersal strategies and metapopulation dynamics. We used an individual-based, spatially explicit simulation model to explore the evolution of emigration strategies under varying precision of information about the natal patch, cost of information acquisition, and environmental predictability. Our findings show an interesting interplay between information use and the evolved emigration propensity. Lack of information led to higher emigration probabilities in more unpredictable environments but to lower emigration probabilities in constant or highly predictable scenarios. Somewhat-informed dispersal strategies were selected for in most cases, even when the acquisition of information was associated with a moderate reproductive cost. Notably, selection rarely favored investment in acquisition of high-precision information, and the tendency to invest in information acquisition was greatest in predictable environments when the associated cost was low. Our results highlight that information use can affect dispersal in a complex manner and also emphasize that information-acquisition behaviors can themselves come under strong selection, resulting in evolutionary dynamics that are tightly coupled to those of context-dependent behaviors.}, + keywords = {context-dependent dispersal,cost of information,emigration,environmental stochasticity,information,uncertainty}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VIVSA5K9\\Bocedi et al. - 2012 - Uncertainty and the Role of Information Acquisitio.pdf} +} + +@article{boeyeMoreRapidClimate2013, + title = {More Rapid Climate Change Promotes Evolutionary Rescue through Selection for Increased Dispersal Distance}, + author = {Boeye, Jeroen and Travis, Justin M J and Stoks, Robby and Bonte, Dries}, + year = {2013}, + month = feb, + journal = {Evolutionary Applications}, + volume = {6}, + number = {2}, + pages = {353--364}, + issn = {1752-4571}, + doi = {10.1111/eva.12004}, + abstract = {Species can either adapt to new conditions induced by climate change or shift their range in an attempt to track optimal environmental conditions. During current range shifts, species are simultaneously confronted with a second major anthropogenic disturbance, landscape fragmentation. Using individual-based models with a shifting climate window, we examine the effect of different rates of climate change on the evolution of dispersal distances through changes in the genetically determined dispersal kernel. Our results demonstrate that the rate of climate change is positively correlated to the evolved dispersal distances although too fast climate change causes the population to crash. When faced with realistic rates of climate change, greater dispersal distances evolve than those required for the population to keep track of the climate, thereby maximizing population size. Importantly, the greater dispersal distances that evolve when climate change is more rapid, induce evolutionary rescue by facilitating the population in crossing large gaps in the landscape. This could ensure population persistence in case of range shifting in fragmented landscapes. Furthermore, we highlight problems in using invasion speed as a proxy for potential range shifting abilities under climate change.}, + pmcid = {PMC3586623}, + pmid = {23467649}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\YF5C6PZH\\Boeye et al. - 2013 - More rapid climate change promotes evolutionary re.pdf} +} + +@incollection{bonenfantChapterEmpiricalEvidence2009, + title = {Chapter 5 {{Empirical Evidence}} of {{Density}}-{{Dependence}} in {{Populations}} of {{Large Herbivores}}}, + booktitle = {Advances in {{Ecological Research}}}, + author = {Bonenfant, Christophe and Gaillard, Jean-Michel and Coulson, Tim and Festa-Bianchet, Marco and Loison, Anne and Garel, Mathieu and Loe, Leif Egil and Blanchard, Pierrick and Pettorelli, Nathalie and Owen-Smith, Norman and Du Toit, Johan and Duncan, Patrick}, + year = {2009}, + month = jan, + volume = {41}, + pages = {313--357}, + publisher = {{Academic Press}}, + doi = {10.1016/S0065-2504(09)00405-X}, + abstract = {Density-dependence is a key concept in population dynamics. Here, we review how body mass and demographic parameters vary with population density in large herbivores. The demographic parameters we consider are age- and sex-specific reproduction, survival and dispersal. As population density increases, the body mass of large herbivores typically declines, affecting individual performance traits such as age of first reproduction and juvenile survival. We documented density-dependent variations in reproductive rates for many species from the Arctic to subtropical zones, both with and without predation. At high density, a trade-off between growth and reproduction delays the age of primiparity and often increases the costs of reproduction, decreasing both survival and future reproductive success of adult females. Density-dependent preweaning juvenile survival occurs more often in polytocous than monotocous species, while the effects of density on post-weaning juvenile survival are independent of litter size. Responses of adult survival to density are much less marked than for juvenile survival, and may be exaggerated by density-dependent changes in age structure. The role of density-dependent dispersal in population dynamics remains uncertain, because very few studies have examined it. For sexually dimorphic species, we found little support for higher sensitivity to increasing density in the life history traits of males compared to females, except for young age classes. It remains unclear whether males of dimorphic species are sensitive to male density, female density or a combination of both. Eberhardt's model predicting a sequential effect of density on demographic parameters (from juvenile survival to adult survival) was supported by 9 of 10 case studies. In addition, population density at birth can also lead to cohort effects, including a direct effect on juvenile survival and long-term effects on average cohort performance as adults. Density effects typically interact with weather, increasing in strength in years of harsh weather. For some species, the synchronization between plant phenology and reproductive cycle is a key process in population dynamics. The timing of late gestation as a function of plant phenology determines whether density-dependence influences juvenile survival or adult female reproduction. The detection of density-dependence can be made difficult by nonlinear relationships with density, high sampling variability, lagged responses to density changes, changes in population age structure, and temporal variation in the main factors limiting population growth. The negative feedbacks of population size on individual performance, and hence on life history traits, are thus only expected in particular ecological contexts and are most often restricted to certain age-specific demographic traits.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GW6JUAKL\\S006525040900405X.html} +} + +@article{bonteCostsDispersal2012a, + title = {Costs of Dispersal}, + author = {Bonte, D. and Bullock, James M. and Coulon, Aur{\'e}lie and Delgado, Maria and Gibbs, Melanie and Lehouck, Valerie and Matthysen, Erik and Mustin, Karin and Saastamoinen, Marjo and Schtickzelle, Nicolas and Stevens, Virginie M. and Vandewoestijne, Sofie and Baguette, Michel and Barton, Kamil and Benton, Tim G. and {Chaput-Bardy}, Audrey and Clobert, Jean and Dytham, Calvin and Hovestadt, Thomas and Meier, Christoph M. and Palmer, Steve C. F. and Turlure, Camille and Travis, Justin M. J.}, + year = {2012}, + month = may, + journal = {Biological Reviews of the Cambridge Philosophical Society}, + volume = {87}, + number = {2}, + pages = {290--312}, + issn = {1469-185X}, + doi = {10.1111/j.1469-185X.2011.00201.x}, + abstract = {Dispersal costs can be classified into energetic, time, risk and opportunity costs and may be levied directly or deferred during departure, transfer and settlement. They may equally be incurred during life stages before the actual dispersal event through investments in special morphologies. Because costs will eventually determine the performance of dispersing individuals and the evolution of dispersal, we here provide an extensive review on the different cost types that occur during dispersal in a wide array of organisms, ranging from micro-organisms to plants, invertebrates and vertebrates. In general, costs of transfer have been more widely documented in actively dispersing organisms, in contrast to a greater focus on costs during departure and settlement in plants and animals with a passive transfer phase. Costs related to the development of specific dispersal attributes appear to be much more prominent than previously accepted. Because costs induce trade-offs, they give rise to covariation between dispersal and other life-history traits at different scales of organismal organisation. The consequences of (i) the presence and magnitude of different costs during different phases of the dispersal process, and (ii) their internal organisation through covariation with other life-history traits, are synthesised with respect to potential consequences for species conservation and the need for development of a new generation of spatial simulation models.}, + langid = {english}, + pmid = {21929715}, + keywords = {Animals,Biological Evolution,Demography,Ecosystem,Models; Biological,Plants} +} + +@article{bonteEvolutionDispersalPolymorphism2010, + title = {Evolution of Dispersal Polymorphism and Local Adaptation of Dispersal Distance in Spatially Structured Landscapes}, + author = {Bonte, Dries and Hovestadt, Thomas and Poethke, Hans-Joachim}, + year = {2010}, + journal = {Oikos}, + volume = {119}, + number = {3}, + pages = {560--566}, + issn = {1600-0706}, + doi = {10.1111/j.1600-0706.2009.17943.x}, + abstract = {Many organisms show polymorphism in dispersal distance strategies. This variation is particularly ecological relevant if it encompasses a functional separation of short- (SDD) and long-distance dispersal (LDD). It remains, however, an open question whether both parts of the dispersal kernel are similarly affected by landscape related selection pressures. We implemented an individual-based model to analyze the evolution of dispersal traits in fractal landscapes that vary in the proportion of habitat and its spatial configuration. Individuals are parthenogenetic with dispersal distance determined by two alleles on each individual's genome: one allele coding for the probability of global dispersal and one allele coding for the variance {$\sigma$} of a Gaussian local dispersal with mean value zero. Simulations show that mean distances of local dispersal and the probability of global dispersal, increase with increasing habitat availability, but that changes in the habitat's spatial autocorrelation impose opposing selective pressure: local dispersal distances decrease and global dispersal probabilities increase with decreasing spatial autocorrelation of the available habitat. Local adaptation of local dispersal distance emerges in landscapes with less than 70\% of clumped habitat. These results demonstrate that long and short distance dispersal evolve separately according to different properties of the landscape. The landscape structure may consequently largely affect the evolution of dispersal distance strategies and the level of dispersal polymorphism.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2009.17943.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\26JI7GPW\\Bonte et al. - 2010 - Evolution of dispersal polymorphism and local adap.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\TWEVRDE9\\j.1600-0706.2009.17943.html} +} + +@article{bonteGeographicalVariationWolf2006, + title = {Geographical Variation in Wolf Spider Dispersal Behaviour Is Related to Landscape Structure}, + author = {Bonte, D. and Borre, J. V. and Lens, L. and Maelfait, J.}, + year = {2006}, + journal = {Animal Behaviour}, + doi = {10.1016/j.anbehav.2005.11.026}, + abstract = {Theoretical studies suggest that mechanisms underlying habitat and population structure are important for shaping inter- and intraspecific variation in dispersal behaviour. Empirical evidence, especially in organisms living in spatially structured populations, however, is scarce. We investigated the relation between habitat configuration (patch size, connectivity) and dispersal by studying variation in tiptoe behaviour in the dune wolf spider, Pardosa monticola, under standardized laboratory conditions. Tiptoe behaviour prepares spiderlings for ballooning and can hence be considered as a precursor of aerial dispersal. The proportion of individuals that displayed tiptoe behaviour was highest in offspring from grasslands in a large dune landscape where habitat was continuously available, intermediate in offspring originating from a fragmented landscape, and lowest in offspring originating from a small and extremely isolated grassland patch. At the level of the fragmented landscape, variation was related to size and connectivity of four subpopulations. Both between and within landscapes, maternal condition had no effect on offspring dispersal. These results indicate that changes in habitat configuration from a large, connected landscape towards a small, fragmented one may lead to a decrease in dispersal rates, even at small spatial scales. Hence, behavioural traits narrowly linked to dispersal evolve towards less mobile phenotypes in small, isolated habitats, indicating high dispersal costs and low efficacy for gene flow in a spider species restricted to fragmented habitats.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VZYMCIZB\\Bonte et al. - 2006 - Geographical variation in wolf spider dispersal be.pdf} +} + +@article{bonteSexspecificDispersalEvolutionary2009, + title = {Sex-Specific Dispersal and Evolutionary Rescue in Metapopulations Infected by Male Killing Endosymbionts}, + author = {Bonte, Dries and Hovestadt, Thomas and Poethke, Hans Joachim}, + year = {2009}, + abstract = {Background: Male killing endosymbionts manipulate their arthropod host reproduction by only allowing female embryos to develop into infected females and killing all male offspring. Because the resulting change in sex ratio is expected to affect the evolution of sex-specific dispersal, we investigated under which environmental conditions strong sex-biased dispersal would emerge, and how this would affect host and endosymbiont metapopulation persistence. Results: We simulated host-endosymbiont metapopulation dynamics in an individual-based model, in which dispersal rates are allowed to evolve independently for the two sexes. Prominent male-biased dispersal emerges under conditions of low environmental stochasticity and high dispersal mortality. By applying a reshuffling algorithm, we show that kin-competition is a major driver of this evolutionary pattern because of the high within-population relatedness of males compared to those of females. Moreover, the evolution of sex-specific dispersal rescues metapopulations from extinction by (i) reducing endosymbiont fixation rates and (ii) by enhancing the extinction of endosymbionts within metapopulations that are characterized by low environmental stochasticity. Conclusion: Male killing endosymbionts induce the evolution of sex-specific dispersal, with prominent male-biased dispersal under conditions of low environmental stochasticity and high dispersal mortality. This male-biased dispersal emerges from stronger kin-competition in males compared to females and induces an evolutionary rescue mechanism.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\247LIPEI\\Bonte et al. - 2009 - Sex-specific dispersal and evolutionary rescue in .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\HUQ9MEX5\\3999.html} +} + +@article{boulangeatAccountingDispersalBiotic2012, + title = {Accounting for Dispersal and Biotic Interactions to Disentangle the Drivers of Species Distributions and Their Abundances}, + author = {Boulangeat, Isabelle and Gravel, Dominique and Thuiller, Wilfried}, + year = {2012}, + journal = {Ecology Letters}, + volume = {15}, + number = {6}, + pages = {584--593}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2012.01772.x}, + abstract = {Ecology Letters (2012) Abstract Although abiotic factors, together with dispersal and biotic interactions, are often suggested to explain the distribution of species and their abundances, species distribution models usually focus on abiotic factors only. We propose an integrative framework linking ecological theory, empirical data and statistical models to understand the distribution of species and their abundances together with the underlying community assembly dynamics. We illustrate our approach with 21 plant species in the French Alps. We show that a spatially nested modelling framework significantly improves the model's performance and that the spatial variations of species presence\textendash absence and abundances are predominantly explained by different factors. We also show that incorporating abiotic, dispersal and biotic factors into the same model bring new insights to our understanding of community assembly. This approach, at the crossroads between community ecology and biogeography, is a promising avenue for a better understanding of species co-existence and biodiversity distribution.}, + langid = {english}, + keywords = {Abiotic niche,co-occurrence index,community assembly rules,dispersal mechanisms,fundamental niche,niche overlap,species distribution model,species pool}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2012.01772.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Z73IB6IG\\Boulangeat et al. - 2012 - Accounting for dispersal and biotic interactions t.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\3EFKHHTR\\j.1461-0248.2012.01772.html} +} + +@article{bowlerCausesConsequencesAnimal2005a, + title = {Causes and Consequences of Animal Dispersal Strategies: Relating Individual Behaviour to Spatial Dynamics}, + shorttitle = {Causes and Consequences of Animal Dispersal Strategies}, + author = {Bowler, Diana E. and Benton, Tim G.}, + year = {2005}, + month = may, + journal = {Biological Reviews of the Cambridge Philosophical Society}, + volume = {80}, + number = {2}, + pages = {205--225}, + issn = {1464-7931}, + doi = {10.1017/s1464793104006645}, + abstract = {Knowledge of the ecological and evolutionary causes of dispersal can be crucial in understanding the behaviour of spatially structured populations, and predicting how species respond to environmental change. Despite the focus of much theoretical research, simplistic assumptions regarding the dispersal process are still made. Dispersal is usually regarded as an unconditional process although in many cases fitness gains of dispersal are dependent on environmental factors and individual state. Condition-dependent dispersal strategies will often be superior to unconditional, fixed strategies. In addition, dispersal is often collapsed into a single parameter, despite it being a process composed of three interdependent stages: emigration, inter-patch movement and immigration, each of which may display different condition dependencies. Empirical studies have investigated correlates of these stages, emigration in particular, providing evidence for the prevalence of conditional dispersal strategies. Ill-defined use of the term 'dispersal', for movement across many different spatial scales, further hinders making general conclusions and relating movement correlates to consequences at the population level. Logistical difficulties preclude a detailed study of dispersal for many species, however incorporating unrealistic dispersal assumptions in spatial population models may yield inaccurate and costly predictions. Further studies are necessary to explore the importance of incorporating specific condition-dependent dispersal strategies for evolutionary and population dynamic predictions.}, + langid = {english}, + pmid = {15921049}, + keywords = {Animals,Animals; Wild,Behavior; Animal,Breeding,Ecosystem,Female,Food Chain,Inbreeding,Male,Population Density,Population Dynamics,Sex Ratio} +} + +@article{bridleLimitsEvolutionRange2007, + title = {Limits to Evolution at Range Margins: When and Why Does Adaptation Fail?}, + shorttitle = {Limits to Evolution at Range Margins}, + author = {Bridle, Jon R and Vines, Timothy H}, + year = {2007}, + month = mar, + journal = {Trends in Ecology \& Evolution}, + volume = {22}, + number = {3}, + pages = {140--147}, + issn = {0169-5347}, + doi = {10.1016/j.tree.2006.11.002}, + abstract = {What stops populations expanding into new territory beyond the edge of a range margin? Recent models addressing this problem have brought together population genetics and population ecology, and some have included interactions among species at range edges. Here, we review these models of adaptation at environmental or parapatric margins, and discuss the contrasting effects of migration in either swamping local adaptation, or supplying the genetic variation that is necessary for adaptation to continue. We illustrate how studying adaptation at range margins (both with and without hybridization) can provide insight into the genetic and ecological factors that limit evolution more generally, especially in response to current rates of environmental change.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\G3XSAUPQ\\S0169534706003636.html} +} + +@article{brookerModellingSpeciesRange2007, + title = {Modelling Species' Range Shifts in a Changing Climate: The Impacts of Biotic Interactions, Dispersal Distance and the Rate of Climate Change}, + shorttitle = {Modelling Species' Range Shifts in a Changing Climate}, + author = {Brooker, Rob W. and Travis, Justin M. J. and Clark, Ewen J. and Dytham, Calvin}, + year = {2007}, + month = mar, + journal = {Journal of Theoretical Biology}, + volume = {245}, + number = {1}, + pages = {59--65}, + issn = {0022-5193}, + doi = {10.1016/j.jtbi.2006.09.033}, + abstract = {There is an urgent need for accurate prediction of climate change impacts on species ranges. Current reliance on bioclimatic envelope approaches ignores important biological processes such as interactions and dispersal. Although much debated, it is unclear how such processes might influence range shifting. Using individual-based modelling we show that interspecific interactions and dispersal ability interact with the rate of climate change to determine range-shifting dynamics in a simulated community with two growth forms--mutualists and competitors. Interactions determine spatial arrangements of species prior to the onset of rapid climate change. These lead to space-occupancy effects that limit the rate of expansion of the fast-growing competitors but which can be overcome by increased long-distance dispersal. As the rate of climate change increases, lower levels of long-distance dispersal can drive the mutualists to extinction, demonstrating the potential for subtle process balances, non-linear dynamics and abrupt changes from species coexistence to species loss during climate change.}, + langid = {english}, + pmid = {17087974}, + keywords = {Animals,Behavior; Animal,Biodiversity,Climate,Competitive Behavior,Ecosystem,Environment,Models; Biological,Population Dynamics} +} + +@article{broquetMolecularEstimationDispersal2009, + title = {Molecular {{Estimation}} of {{Dispersal}} for {{Ecology}} and {{Population Genetics}}}, + author = {Broquet, Thomas and Petit, Eric J.}, + year = {2009}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + volume = {40}, + number = {1}, + pages = {193--216}, + doi = {10.1146/annurev.ecolsys.110308.120324}, + abstract = {The dispersal process, by which individuals or other dispersing agents such as gametes or seeds move from birthplace to a new settlement locality, has important consequences for the dynamics of genes, individuals, and species. Many of the questions addressed by ecology and evolutionary biology require a good understanding of species' dispersal patterns. Much effort has thus been devoted to overcoming the difficulties associated with dispersal measurement. In this context, genetic tools have long been the focus of intensive research, providing a great variety of potential solutions to measuring dispersal. This methodological diversity is reviewed here to help (molecular) ecologists find their way toward dispersal inference and interpretation and to stimulate further developments.}, + annotation = {\_eprint: https://doi.org/10.1146/annurev.ecolsys.110308.120324}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\FEHEGY8P\\Broquet und Petit - 2009 - Molecular Estimation of Dispersal for Ecology and .pdf} +} + +@article{bullockLongDistanceSeed2000, + title = {Long Distance Seed Dispersal by Wind: Measuring and Modelling the Tail of the Curve}, + shorttitle = {Long Distance Seed Dispersal by Wind}, + author = {Bullock, J. M. and Clarke, R. T.}, + year = {2000}, + month = sep, + journal = {Oecologia}, + volume = {124}, + number = {4}, + pages = {506--521}, + issn = {1432-1939}, + doi = {10.1007/PL00008876}, + abstract = {The size and shape of the tail of the seed dispersal curve is important in determining the spatial dynamics of plants, but is difficult to quantify. We devised an experimental protocol to measure long-distance dispersal which involved measuring dispersal by wind from isolated individuals at a range of distances from the source, but maintaining a large and constant sampling intensity at each distance. Seeds were trapped up to 80 m from the plants, the furthest a dispersal curve for an individual plant has been measured for a non-tree species. Standard empirical negative exponential and inverse power models were fitted using likelihood methods. The latter always had a better fit than the former, but in most cases neither described the data well, and strongly under-estimated the tail of the dispersal curve. An alternative model formulation with two kernel components had a much better fit in most cases and described the tail data more accurately. Mechanistic models provide an alternative to direct measurement of dispersal. However, while a previous mechanistic model accurately predicted the modal dispersal distance, it always under-predicted the measured tail. Long-distance dispersal may be caused by rare extremes in horizontal wind speed or turbulence. Therefore, under-estimation of the tail by standard empirical models and mechanistic models may indicate a lack of flexibility to take account of such extremes. Future studies should examine carefully whether the widely used exponential and power models are, in fact, valid, and investigate alternative models.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RYBFU2QH\\Bullock und Clarke - 2000 - Long distance seed dispersal by wind measuring an.pdf} +} + +@article{cagnacciAnimalEcologyMeets2010, + title = {Animal Ecology Meets {{GPS-based}} Radiotelemetry: A Perfect Storm of Opportunities and Challenges}, + shorttitle = {Animal Ecology Meets {{GPS-based}} Radiotelemetry}, + author = {Cagnacci, Francesca and Boitani, Luigi and Powell, Roger A. and Boyce, Mark S.}, + year = {2010}, + month = jul, + journal = {Philosophical Transactions of the Royal Society B: Biological Sciences}, + volume = {365}, + number = {1550}, + pages = {2157--2162}, + publisher = {{Royal Society}}, + doi = {10.1098/rstb.2010.0107}, + abstract = {Global positioning system (GPS) telemetry technology allows us to monitor and to map the details of animal movement, securing vast quantities of such data even for highly cryptic organisms. We envision an exciting synergy between animal ecology and GPS-based radiotelemetry, as for other examples of new technologies stimulating rapid conceptual advances, where research opportunities have been paralleled by technical and analytical challenges. Animal positions provide the elemental unit of movement paths and show where individuals interact with the ecosystems around them. We discuss how knowing where animals go can help scientists in their search for a mechanistic understanding of key concepts of animal ecology, including resource use, home range and dispersal, and population dynamics. It is probable that in the not-so-distant future, intense sampling of movements coupled with detailed information on habitat features at a variety of scales will allow us to represent an animal's cognitive map of its environment, and the intimate relationship between behaviour and fitness. An extended use of these data over long periods of time and over large spatial scales can provide robust inferences for complex, multi-factorial phenomena, such as meta-analyses of the effects of climate change on animal behaviour and distribution.}, + keywords = {animal movement,autocorrelation,biotelemetry,fitness,global positioning system technology,mechanistic models}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\373TI4KL\\Cagnacci et al. - 2010 - Animal ecology meets GPS-based radiotelemetry a p.pdf} +} + +@book{caswellMatrixPopulationModels2001a, + title = {Matrix {{Population Models}}: {{Construction}}, {{Analysis}}, and {{Interpretation}}}, + shorttitle = {Matrix {{Population Models}}}, + author = {Caswell, Hal}, + year = {2001}, + edition = {Second Edition, Matrix Population Models, Second Edition, is a comprehensive treatment of matrix population models and their applications in ecology and ...}, + publisher = {{Oxford University Press}}, + address = {{Oxford, New York}}, + abstract = {Published by Sinauer Associates, an imprint of Oxford University Press. Matrix Population Models, Second Edition, is a comprehensive treatment of matrix population models and their applications in ecology and demography. It begins with simple cases, presented in detail so that beginning students can learn how to use these powerful models. It goes on to cover advanced topics in stochastic and nonlinear models. Analytical methods and theoretical issues are illustrated with empirical examples throughout. The decade since the publication of the First Edition of this book has seen enormous progress in the theory and application of matrix population models. The new edition includes greatly expanded treatment of stochastic and density-dependent models, sensitivity analysis, and statistical inference, and new chapters on parameter estimation, structured population models, demographic stochasticity, and applications of matrix models in conservation biology. Matrix Population Models, Second Edition, is an indispensable reference for graduate students and researchers in ecology, population biology, conservation biology, and human demography}, + isbn = {978-0-87893-121-7}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\WGS8CE2Q\\matrix-population-models-9780878931217.html} +} + +@article{caswellSensitivityAnalysisEquilibrium2004, + title = {Sensitivity Analysis of Equilibrium in Density-Dependent Matrix Population Models}, + author = {Caswell, Hal and Takada, Takenori and Hunter, Christine M.}, + year = {2004}, + journal = {Ecology Letters}, + volume = {7}, + number = {5}, + pages = {380--387}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2004.00595.x}, + abstract = {We consider the effects of parameter perturbations on a density-dependent population at equilibrium. Such perturbations change the dominant eigenvalue {$\lambda$} of the projection matrix evaluated at the equilibrium as well as the equilibrium itself. We show that, regardless of the functional form of density dependence, the sensitivity of {$\lambda$} is equal to the sensitivity of an effective equilibrium density , which is a weighted combination of the equilibrium stage densities. The weights measure the contributions of each stage to density dependence and their effects on demography. Thus, is in general more relevant than total density, which simply adds all stages regardless of their ecological properties. As log {$\lambda$} is the invasion exponent, our results show that successful invasion will increase , and that an evolutionary stable strategy will maximize . Our results imply that eigenvalue sensitivity analysis of a population projection matrix that is evaluated near equilibrium can give useful information about the sensitivity of the equilibrium population, even if no data on density dependence are available.}, + langid = {english}, + keywords = {Density dependence,elasticity analysis,equilibrium,evolutionary stable strategy,invasion exponent,matrix population models,nonlinear,sensitivity analysis,territory limitation,Tribolium}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2004.00595.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\3CZR3IWE\\Caswell et al. - 2004 - Sensitivity analysis of equilibrium in density-dep.pdf} +} + +@article{caswellTwoSexModelsChaos1986, + title = {Two-{{Sex Models}}: {{Chaos}}, {{Extinction}}, and {{Other Dynamic Consequences}} of {{Sex}}}, + shorttitle = {Two-{{Sex Models}}}, + author = {Caswell, Hal and Weeks, Daniel E.}, + year = {1986}, + journal = {The American Naturalist}, + volume = {128}, + number = {5}, + pages = {707--735}, + publisher = {{[University of Chicago Press, American Society of Naturalists]}}, + issn = {0003-0147}, + abstract = {Most demographic models consider only one sex, usually the female. The widespread occurrence of sexual dimorphism in life history traits and the occurrence of skewed and fluctuating sex ratios suggest that one-sex models or those dominated by one sex may often be less appropriate than two-sex models. Reproduction in two-sex models is a frequency-dependent nonlinear function (the birth or marriage function) of the relative abundance of males and females. In this paper, we examine the population dynamics resulting from three different two-sex, discrete-time, population-projection models. For a large class of birth functions, models without inter-stage mate competition are shown to converge to a locally stable adult sex ratio. Formulas for the stable population structure, stable sex ratio, and reproductive value at equilibrium are derived. When individuals of different stages compete for mates, the equilibrium population structure may become unstable. A sequence of bifurcations then occurs, leading to periodic oscillations, quasi-periodic fluctuations, and chaos as the intensity of competition increases. Finally, when per capita fecundity is a sigmoid function of the relative abundance of the other sex, perturbations of the sex ratio may lead to extinction.} +} + +@article{chaineCoevolutionMultiplyinformedDispersal2013, + title = {The Co-Evolution of Multiply-Informed Dispersal: Information Transfer across Landscapes from Neighbors and Immigrants}, + shorttitle = {The Co-Evolution of Multiply-Informed Dispersal}, + author = {Chaine, Alexis S. and Legendre, St{\'e}phane and Clobert, Jean}, + year = {2013}, + month = feb, + journal = {PeerJ}, + volume = {1}, + pages = {e44}, + publisher = {{PeerJ Inc.}}, + issn = {2167-8359}, + doi = {10.7717/peerj.44}, + abstract = {Dispersal plays a key role in natural systems by shaping spatial population and evolutionary dynamics. Dispersal has been largely treated as a population process with little attention to individual decisions and the influence of information use on the fitness benefits of dispersal despite clear empirical evidence that dispersal behavior varies among individuals. While information on local density is common, more controversial is the notion that indirect information use can easily evolve. We used an individual-based model to ask under what conditions indirect information use in dispersal will evolve. We modeled indirect information provided by immigrant arrival into a population which should be linked to overall metapopulation density. We also modeled direct information use of density which directly impacts fitness. We show that immigrant-dependent dispersal evolves and does so even when density dependent information is available. Use of two sources of information also provides benefits at the metapopulation level by reducing extinction risk and prolonging the persistence of populations. Our results suggest that use of indirect information in dispersal can evolve under conservative conditions and thus could be widespread.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RW45GZGV\\Chaine et al. - 2013 - The co-evolution of multiply-informed dispersal i.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\MMN68IIM\\44.html} +} + +@article{chaput-bardyConditionPhenotypeDependentDispersal2010, + title = {Condition and {{Phenotype-Dependent Dispersal}} in a {{Damselfly}}, {{Calopteryx}} Splendens}, + author = {{Chaput-Bardy}, Audrey and Gr{\'e}goire, Arnaud and Baguette, Michel and Pagano, Alain and Secondi, Jean}, + year = {2010}, + month = may, + journal = {PLOS ONE}, + volume = {5}, + number = {5}, + pages = {e10694}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0010694}, + abstract = {Individual dispersal decisions may be affected by the internal state of the individual and the external information of its current environment. Here we estimated the influence of dispersal on survival and investigated if individual phenotype (sex and wing length) and environmental condition (conspecific density and sex-ratio) affected dispersal decisions in the banded damselfly, Calopteryx splendens. As suspected from the literature, we showed that the proportion of dispersing individuals was higher in females than in males. We also found negative-density dependent dispersal in both sexes and influence of sex-ratio on dispersal. Individuals moved less when sex-ratio was male biased. These results are consistent with a lek mating system where males aggregate in a place and hold mating territories. Contrary to our expectations, neither dispersal nor survival was affected by wing length. Nevertheless, mean adult survival was about 8\% lower in dispersing individuals than in residents. This might reflect a mortality cost due to dispersal.}, + langid = {english}, + keywords = {Animal flight,Animal wings,Habitats,Insect flight,Insects,Mating behavior,Physiological parameters,Thorax}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\X6NDS2LP\\Chaput-Bardy et al. - 2010 - Condition and Phenotype-Dependent Dispersal in a D.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\ENLD9MSR\\article.html} +} + +@article{chardonIncorporatingLandscapeElements2003, + title = {Incorporating Landscape Elements into a Connectivity Measure: A Case Study for the {{Speckled}} Wood Butterfly ({{Pararge}} Aegeria {{L}}.)}, + shorttitle = {Incorporating Landscape Elements into a Connectivity Measure}, + author = {Chardon, J. Paul and Adriaensen, Frank and Matthysen, Erik}, + year = {2003}, + month = sep, + journal = {Landscape Ecology}, + volume = {18}, + number = {6}, + pages = {561--573}, + issn = {1572-9761}, + doi = {10.1023/A:1026062530600}, + abstract = {In spatial studies of populations, Euclidean distance is commonly used to measure the structural connectivity between habitat patches. The role of the matrix on patch connectivity is thereby ignored. However, the importance of the matrix for (dispersal) movement is increasingly being acknowledged. Our study compared the cost-distance measure with the Euclidean distance. The cost-distance is a simple GIS-calculated connectivity measure that incorporates the resistance of the landscape matrix to movement behaviour. We used presence-absence data from a field study on the Speckled wood butterfly in two Belgian landscapes. Logistic regression revealed that the cost-distance measure had a significantly better predictive power than the Euclidean distance. This result was consistent for all the six sets of different matrix resistance values. In our study the cost-distance proves to be a better connectivity measure than the Euclidean distance.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\5MAK4WU6\\Chardon et al. - 2003 - Incorporating landscape elements into a connectivi.pdf} +} + +@article{chenRapidRangeShifts2011, + title = {Rapid {{Range Shifts}} of {{Species Associated}} with {{High Levels}} of {{Climate Warming}}}, + author = {Chen, I.-Ching and Hill, Jane K. and Ohlem{\"u}ller, Ralf and Roy, David B. and Thomas, Chris D.}, + year = {2011}, + month = aug, + journal = {Science}, + volume = {333}, + number = {6045}, + pages = {1024--1026}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.1206432}, + abstract = {The distributions of many terrestrial organisms are currently shifting in latitude or elevation in response to changing climate. Using a meta-analysis, we estimated that the distributions of species have recently shifted to higher elevations at a median rate of 11.0 meters per decade, and to higher latitudes at a median rate of 16.9 kilometers per decade. These rates are approximately two and three times faster than previously reported. The distances moved by species are greatest in studies showing the highest levels of warming, with average latitudinal shifts being generally sufficient to track temperature changes. However, individual species vary greatly in their rates of change, suggesting that the range shift of each species depends on multiple internal species traits and external drivers of change. Rapid average shifts derive from a wide diversity of responses by individual species. A meta-analysis shows that species are shifting their distributions in response to climate change at an accelerating rate. A meta-analysis shows that species are shifting their distributions in response to climate change at an accelerating rate.}, + chapter = {Report}, + copyright = {Copyright \textcopyright{} 2011, American Association for the Advancement of Science}, + langid = {english}, + pmid = {21852500}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\5EB2EIIC\\Chen et al. - 2011 - Rapid Range Shifts of Species Associated with High.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\X6WJLETL\\1024.html} +} + +@article{chipperfieldUpdatedAlgorithmGeneration2011, + title = {An {{Updated Algorithm}} for the {{Generation}} of {{Neutral Landscapes}} by {{Spectral Synthesis}}}, + author = {Chipperfield, Joseph D. and Dytham, Calvin and Hovestadt, Thomas}, + year = {2011}, + month = feb, + journal = {PLOS ONE}, + volume = {6}, + number = {2}, + pages = {e17040}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0017040}, + abstract = {Background Patterns that arise from an ecological process can be driven as much from the landscape over which the process is run as it is by some intrinsic properties of the process itself. The disentanglement of these effects is aided if it possible to run models of the process over artificial landscapes with controllable spatial properties. A number of different methods for the generation of so-called `neutral landscapes' have been developed to provide just such a tool. Of these methods, a particular class that simulate fractional Brownian motion have shown particular promise. The existing methods of simulating fractional Brownian motion suffer from a number of problems however: they are often not easily generalisable to an arbitrary number of dimensions and produce outputs that can exhibit some undesirable artefacts. Methodology We describe here an updated algorithm for the generation of neutral landscapes by fractional Brownian motion that do not display such undesirable properties. Using Monte Carlo simulation we assess the anisotropic properties of landscapes generated using the new algorithm described in this paper and compare it against a popular benchmark algorithm. Conclusion/Significance The results show that the existing algorithm creates landscapes with values strongly correlated in the diagonal direction and that the new algorithm presented here corrects this artefact. A number of extensions of the algorithm described here are also highlighted: we describe how the algorithm can be employed to generate landscapes that display different properties in different dimensions and how they can be combined with an environmental gradient to produce landscapes that combine environmental variation at the local and macro scales.}, + langid = {english}, + keywords = {Algorithms,Anisotropy,Autocorrelation,Brownian motion,Fourier analysis,Fractals,Habitats,Monte Carlo method}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2XFWN3MP\\Chipperfield et al. - 2011 - An Updated Algorithm for the Generation of Neutral.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\QMA3HRR3\\article.html} +} + +@article{clarkInvasionExtremesPopulation2001, + title = {Invasion by Extremes: Population Spread with Variation in Dispersal and Reproduction}, + shorttitle = {Invasion by Extremes}, + author = {Clark, J. S. and Lewis, M. and Horvath, L.}, + year = {2001}, + month = may, + journal = {The American Naturalist}, + volume = {157}, + number = {5}, + pages = {537--554}, + issn = {1537-5323}, + doi = {10.1086/319934}, + abstract = {For populations having dispersal described by fat-tailed kernels (kernels with tails that are not exponentially bounded), asymptotic population spread rates cannot be estimated by traditional models because these models predict continually accelerating (asymptotically infinite) invasion. The impossible predictions come from the fact that the fat-tailed kernels fitted to dispersal data have a quality (nondiscrete individuals and, thus, no moment-generating function) that never applies to data. Real organisms produce finite (and random) numbers of offspring; thus, an empirical moment-generating function can always be determined. Using an alternative method to estimate spread rates in terms of extreme dispersal events, we show that finite estimates can be derived for fat-tailed kernels, and we demonstrate how variable reproduction modifies these rates. Whereas the traditional models define spread rate as the speed of an advancing front describing the expected density of individuals, our alternative definition for spread rate is the expected velocity for the location of the furthest-forward individual in the population. The asymptotic wave speed for a constant net reproductive rate R0 is approximated as (1/T)(piuR)/2)(1/2) m yr(-1), where T is generation time, and u is a distance parameter (m2) of Clark et al.'s 2Dt model having shape parameter p = 1. From fitted dispersal kernels with fat tails and infinite variance, we derive finite rates of spread and a simple method for numerical estimation. Fitted kernels, with infinite variance, yield distributions of rates of spread that are asymptotically normal and, thus, have finite moments. Variable reproduction can profoundly affect rates of spread. By incorporating the variance in reproduction that results from variable life span, we estimate much lower rates than predicted by the standard approach, which assumes a constant net reproductive rate. Using basic life-history data for trees, we show these estimated rates to be lower than expected from previous analytical models and as interpreted from paleorecords of forest spread at the end of the Pleistocene. Our results suggest reexamination of past rates of spread and the potential for future response to climate change.}, + langid = {english}, + pmid = {18707261} +} + +@article{clarkReidParadoxRapid1998, + title = {Reid's {{Paradox}} of {{Rapid Plant Migration}}: {{Dispersal}} Theory and Interpretation of Paleoecological Records}, + shorttitle = {Reid's {{Paradox}} of {{Rapid Plant Migration}}}, + author = {Clark, James S. and Fastie, Chris and Hurtt, George and Jackson, Stephen T. and Johnson, Carter and King, George A. and Lewis, Mark and Lynch, Jason and Pacala, Stephen and Prentice, Colin and Schupp, Eugene W. and Webb, III, Thompson and Wyckoff, Peter}, + year = {1998}, + month = jan, + journal = {BioScience}, + volume = {48}, + number = {1}, + pages = {13--24}, + issn = {0006-3568}, + doi = {10.2307/1313224}, + abstract = {The oak, to gain its present most northerly position in North Britain after being driven out by the cold probably had to travel fully six hundred miles, and this without external aid would take something like a million years. (Reid 1899)}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\WD97WG6G\\Clark et al. - 1998 - Reid's Paradox of Rapid Plant Migration Dispersal.pdf} +} + +@book{clobertDispersal2001, + title = {Dispersal}, + editor = {Clobert, Jean and Danchin, Etienne and Dhondt, Andre A. and Nichols, James D.}, + year = {2001}, + month = feb, + publisher = {{Oxford University Press}}, + address = {{Oxford, New York}}, + abstract = {The ability of species to migrate that has interested ecologists for many years. Now that so many species and ecosystems face major environmental change, the ability of species to adapt to these changes by dispersing, migrating, or moving between different patches of habitat can be crucial to ensuring their survivial. This book provides a timely and wide-ranging overview of the study of dispersal and incorporates much of the latest research. The causes, mechanisms, and consequences of dispersal at the individual, population, species and community levels are considered. The potential of new techniques and models for studying dispersal, drawn from molecular biology and demography, is also explored. Perspectives and insights are offered from the fields of evolution, conservation biology and genetics. Throughout the book, theoretical approaches are combined with empirical data, and care has been taken to include examples from as wide a range of species as possible.}, + isbn = {978-0-19-850659-1}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\F9QZQAE9\\dispersal-9780198506591.html} +} + +@book{clobertDispersalEcologyEvolution2012a, + title = {Dispersal {{Ecology}} and {{Evolution}}}, + editor = {Clobert, Jean and Baguette, Michel and Benton, Tim G. and Bullock, James M.}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.001.0001}, + abstract = {Now that so many ecosystems face rapid and major environmental change, the ability of species to respond to these changes by dispersing or moving between different patches of habitat can be crucial to ensuring their survival. Understanding dispersal has become key to understanding how populations may persist. This book provides an overview of the fast expanding field of dispersal ecology, incorporating the very latest research. The causes, mechanisms, and consequences of dispersal at the individual, population, species, and community levels are considered. Perspectives and insights are offered from the fields of evolution, behavioural ecology, conservation biology, and genetics. Throughout the book theoretical approaches are combined with empirical data, and care has been taken to include examples from as wide a range of species as possible \textemdash{} both plant and animal.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {behavioural ecology,conservation biology,dispersal ecology,ecosystems,environmental change,evolution,genetics,habitat,species,survival} +} + +@article{clobertInformedDispersalHeterogeneity2009, + title = {Informed Dispersal, Heterogeneity in Animal Dispersal Syndromes and the Dynamics of Spatially Structured Populations}, + author = {Clobert, Jean and Le Galliard, Jean-Fran{\c c}ois and Cote, Julien and Meylan, Sandrine and Massot, Manuel}, + year = {2009}, + month = mar, + journal = {Ecology Letters}, + volume = {12}, + number = {3}, + pages = {197--209}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2008.01267.x}, + abstract = {There is accumulating evidence that individuals leave their natal area and select a breeding habitat non-randomly by relying upon information about their natal and future breeding environments. This variation in dispersal is not only based on external information (condition dependence) but also depends upon the internal state of individuals (phenotype dependence). As a consequence, not all dispersers are of the same quality or search for the same habitats. In addition, the individual's state is characterized by morphological, physiological or behavioural attributes that might themselves serve as a cue altering the habitat choice of conspecifics. These combined effects of internal and external information have the potential to generate complex movement patterns and could influence population dynamics and colonization processes. Here, we highlight three particular processes that link condition-dependent dispersal, phenotype-dependent dispersal and habitat choice strategies: (1) the relationship between the cause of departure and the dispersers' phenotype; (2) the relationship between the cause of departure and the settlement behaviour and (3) the concept of informed dispersal, where individuals gather and transfer information before and during their movements through the landscape. We review the empirical evidence for these processes with a special emphasis on vertebrate and arthropod model systems, and present case studies that have quantified the impacts of these processes on spatially structured population dynamics. We also discuss recent literature providing strong evidence that individual variation in dispersal has an important impact on both reinforcement and colonization success and therefore must be taken into account when predicting ecological responses to global warming and habitat fragmentation.}, + langid = {english}, + pmid = {19170731}, + keywords = {Animal Migration,Animals,Competitive Behavior,Ecosystem,Female,Male,Population Dynamics} +} + +@article{clotucheSettlementDecisionsTwospotted2013, + title = {Settlement Decisions by the Two-Spotted Spider Mite {{Tetranychus}} Urticae}, + author = {Clotuche, Gwendoline and Mailleux, Anne-Catherine and Yano, Shuichi and Detrain, Claire and Deneubourg, Jean-Louis and Hance, Thierry}, + year = {2013}, + month = feb, + journal = {Comptes Rendus Biologies}, + volume = {336}, + number = {2}, + pages = {93--101}, + issn = {1631-0691}, + doi = {10.1016/j.crvi.2013.02.006}, + abstract = {In silk-spinning arthropods, silk can be used for web building, protection, and communication. Silk is an informative material about the presence of conspecifics. It can therefore inform on habitat suitability and hence assist in habitat choice. In this context, we investigated the influence of silk on microhabitat choice by the two-spotted spider mite, Tetranychus urticae. Three factors that could potentially influence habitat choice were manipulated: the strain, number, and the stage of mites. Our study showed that these factors all influence the choice of microhabitat. The tendency of whether to settle on a silk-covered area was influenced by the origin of mites (strain effect). Adult females showed a higher tendency to settle on an area covered with the silk laid by numerous congeners (number effect). Moreover, larvae seemed to be more responsive to the presence of silk than adults (stage effect). This suggests that individuals use silk as a social cue in selecting their microhabitat and that the spatial organization and group behaviour seem to be shaped by the individuals' response to social cues, such as the amount of silk already present. R\'esum\'e Chez les arthropodes tisseurs, la soie peut \^etre utilis\'ee pour la construction, la protection et la communication. La soie peut \'egalement informer de la pr\'esence de cong\'en\`eres. Elle peut renseigner sur la qualit\'e d'un habitat et donc aider les individus lors du choix d'\'etablissement. Dans ce contexte, nous avons \'etudi\'e l'influence de la soie lors de la s\'election d'un micro-habitat chez l'acarien tisserand, Tetranychus urticae. Trois facteurs ont \'et\'e manipul\'es~: la souche, le nombre et le stade des acariens. Notre \'etude montre que ces facteurs influencent le choix du micro-habitat. La tendance \`a s'installer sur une zone couverte de soie diff\`ere en fonction de l'origine des acariens. Les femelles adultes montrent une plus forte tendance \`a s'installer sur une zone couverte de soie tiss\'ee par de nombreux cong\'en\`eres. Les larves semblent plus sensibles que les adultes \`a la pr\'esence de soie. La soie est utilis\'ee comme indice social pour choisir le micro-habitat et, d\`es lors, l'organisation spatiale et l'agr\'egation de cet acarien semblent \^etre fa\c{c}onn\'ees par la r\'eponse des individus \`a des signaux sociaux tels que la quantit\'e de soie.}, + langid = {english}, + keywords = {Comportement de groupe,Group behaviour,Habitat settlement,Indice social,Localisation spatiale,Sélection d’un micro-habitat,Silk,Social cue,Soie,Souche,Spatial location,Strain}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\I5KZK44U\\Clotuche et al. - 2013 - Settlement decisions by the two-spotted spider mit.pdf} +} + +@article{codlingRandomWalkModels2008, + title = {Random Walk Models in Biology}, + author = {Codling, Edward A. and Plank, Michael J. and Benhamou, Simon}, + year = {2008}, + month = aug, + journal = {Journal of the Royal Society, Interface}, + volume = {5}, + number = {25}, + pages = {813--834}, + issn = {1742-5689}, + doi = {10.1098/rsif.2008.0014}, + abstract = {Mathematical modelling of the movement of animals, micro-organisms and cells is of great relevance in the fields of biology, ecology and medicine. Movement models can take many different forms, but the most widely used are based on the extensions of simple random walk processes. In this review paper, our aim is twofold: to introduce the mathematics behind random walks in a straightforward manner and to explain how such models can be used to aid our understanding of biological processes. We introduce the mathematical theory behind the simple random walk and explain how this relates to Brownian motion and diffusive processes in general. We demonstrate how these simple models can be extended to include drift and waiting times or be used to calculate first passage times. We discuss biased random walks and show how hyperbolic models can be used to generate correlated random walks. We cover two main applications of the random walk model. Firstly, we review models and results relating to the movement, dispersal and population redistribution of animals and micro-organisms. This includes direct calculation of mean squared displacement, mean dispersal distance, tortuosity measures, as well as possible limitations of these model approaches. Secondly, oriented movement and chemotaxis models are reviewed. General hyperbolic models based on the linear transport equation are introduced and we show how a reinforced random walk can be used to model movement where the individual changes its environment. We discuss the applications of these models in the context of cell migration leading to blood vessel growth (angiogenesis). Finally, we discuss how the various random walk models and approaches are related and the connections that underpin many of the key processes involved.}, + langid = {english}, + pmcid = {PMC2504494}, + pmid = {18426776}, + keywords = {Cell Movement,Diffusion,Models; Biological,Movement,Stochastic Processes}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\KHCXT9UB\\Codling et al. - 2008 - Random walk models in biology.pdf} +} + +@article{cominsEvolutionarilyStableDispersal1980, + title = {Evolutionarily Stable Dispersal Strategies}, + author = {Comins, Hugh N. and Hamilton, William D. and May, Robert M.}, + year = {1980}, + month = jan, + journal = {Journal of Theoretical Biology}, + volume = {82}, + number = {2}, + pages = {205--230}, + issn = {0022-5193}, + doi = {10.1016/0022-5193(80)90099-5}, + abstract = {Using the idea that life-history parameters are subject to natural selection and should approach values that are stable optima, with the population immune to invasion by mutant individuals, we derive an analytic expression for the evolutionarily stable dispersal rate in a stochastic island model with random site extinction. The results provide interesting contrasts between three different optimization criteria: species survival, individual fitness and gene fitness. We also consider the effects of sexual reproduction, and of localized migration (stepping-stone structure).}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RZJSV49C\\Comins et al. - 1980 - Evolutionarily stable dispersal strategies.pdf} +} + +@article{conliskUncertaintyAssessingImpacts2013, + title = {Uncertainty in Assessing the Impacts of Global Change with Coupled Dynamic Species Distribution and Population Models}, + author = {Conlisk, Erin and Syphard, Alexandra D. and Franklin, Janet and Flint, Lorraine and Flint, Alan and Regan, Helen}, + year = {2013}, + month = mar, + journal = {Global Change Biology}, + volume = {19}, + number = {3}, + pages = {858--869}, + issn = {1354-1013}, + doi = {10.1111/gcb.12090}, + abstract = {Concern over rapid global changes and the potential for interactions among multiple threats are prompting scientists to combine multiple modelling approaches to understand impacts on biodiversity. A relatively recent development is the combination of species distribution models, land-use change predictions, and dynamic population models to predict the relative and combined impacts of climate change, land-use change, and altered disturbance regimes on species' extinction risk. Each modelling component introduces its own source of uncertainty through different parameters and assumptions, which, when combined, can result in compounded uncertainty that can have major implications for management. Although some uncertainty analyses have been conducted separately on various model components - such as climate predictions, species distribution models, land-use change predictions, and population models - a unified sensitivity analysis comparing various sources of uncertainty in combined modelling approaches is needed to identify the most influential and problematic assumptions. We estimated the sensitivities of long-run population predictions to different ecological assumptions and parameter settings for a rare and endangered annual plant species (Acanthomintha ilicifolia, or San Diego thornmint). Uncertainty about habitat suitability predictions, due to the choice of species distribution model, contributed most to variation in predictions about long-run populations.}, + langid = {english}, + pmid = {23504842}, + keywords = {Biodiversity,Climate Change,Models; Theoretical,Population Dynamics,Uncertainty} +} + +@article{coteSocialInformationEmigration2007, + title = {Social Information and Emigration: Lessons from Immigrants}, + shorttitle = {Social Information and Emigration}, + author = {Cote, J. and Clobert, J.}, + year = {2007}, + month = may, + journal = {Ecology Letters}, + volume = {10}, + number = {5}, + pages = {411--417}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2007.01032.x}, + abstract = {'Should I stay or should I go?' is a fundamental question facing any candidate for emigration, as emigrating without outside information has major costs. Most studies on this topic have concentrated on risk-reducing strategies (e.g. exploration) developed after leaving the natal habitat. The idea that information might be acquired before leaving has not been investigated. Immigrants carrying information about their origins could provide such information to potential emigrants in their initial habitat. We manipulated the density of common lizard (Lacerta vivipara) populations, to investigate whether immigrants originating from these populations transmitted such information to the population they joined. Emigration of the residents of this new population clearly depended on the origin of the immigrant. Immigrants are therefore a source of information, in this case about surrounding population densities, and may have a major effect on dispersal and species persistence in a fragmented habitat.}, + langid = {english}, + pmid = {17498140}, + keywords = {Animals,Behavior; Animal,Lizards,Population Dynamics} +} + +@article{cottoNemoageSpatiallyExplicit2020, + title = {Nemo-Age: {{Spatially}} Explicit Simulations of Eco-Evolutionary Dynamics in Stage-Structured Populations under Changing Environments}, + shorttitle = {Nemo-Age}, + author = {Cotto, Olivier and Schmid, Max and Guillaume, Fr{\'e}d{\'e}ric}, + year = {2020}, + journal = {Methods in Ecology and Evolution}, + volume = {11}, + number = {10}, + pages = {1227--1236}, + issn = {2041-210X}, + doi = {10.1111/2041-210X.13460}, + abstract = {Anticipating and preparing for the effect of environmental changes on biodiversity requires to understand and predict both the ecological and evolutionary responses of populations. Tools and methods to efficiently integrate these complex processes are lacking. We present the genetically and spatially explicit individual-based simulation software Nemo-age combining ecological and evolutionary processes. Nemo-age has a strong emphasis on modelling complex life histories. We here provide a methodology to predict changes in species distribution for given climate projections using Nemo-age. Modelling complex life histories, spatial distribution and evolutionary processes unravel possible eco-evolutionary mechanisms that have been previously overlooked when populations endure rapid environmental changes. The interface of Nemo-age is designed to integrate species' data from different fields, from demography to genetic architecture and spatial distributions, thus representing a versatile tool to model a variety of applied and theoretical scenarios.}, + langid = {english}, + keywords = {adaptation,forward-time simulations,life history,population dynamics,spatially explicit}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/2041-210X.13460}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\62TTZ4SR\\Cotto et al. - 2020 - Nemo-age Spatially explicit simulations of eco-ev.pdf} +} + +@article{coulsonEstimatingFunctionalForm2008, + title = {Estimating the {{Functional Form}} for the {{Density Dependence}} from {{Life History Data}}}, + author = {Coulson, T. and Ezard, T. H. G. and Pelletier, F. and Tavecchia, G. and Stenseth, N. C. and Childs, D. Z. and Pilkington, J. G. and Pemberton, J. M. and Kruuk, L. E. B. and {Clutton-Brock}, T. H. and Crawley, M. J.}, + year = {2008}, + journal = {Ecology}, + volume = {89}, + number = {6}, + pages = {1661--1674}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + abstract = {Two contrasting approaches to the analysis of population dynamics are currently popular: demographic approaches where the associations between demographic rates and statistics summarizing the population dynamics are identified; and time series approaches where the associations between population dynamics, population density, and environmental covariates are investigated. In this paper, we develop an approach to combine these methods and apply it to detailed data from Soay sheep (Ovis aries). We examine how density dependence and climate contribute to fluctuations in population size via age- and sex-specific demographic rates, and how fluctuations in demographic structure influence population dynamics. Density dependence contributes most, followed by climatic variation, age structure fluctuations and interactions between density and climate. We then simplify the density-dependent, stochastic, age-structured demographic model and derive a new phenomenological time series which captures the dynamics better than previously selected functions. The simple method we develop has potential to provide substantial insight into the relative contributions of population and individual-level processes to the dynamics of populations in stochastic environments.} +} + +@article{coumouDecadeWeatherExtremes2012, + title = {A Decade of Weather Extremes}, + author = {Coumou, Dim and Rahmstorf, Stefan}, + year = {2012}, + month = jul, + journal = {Nature Climate Change}, + volume = {2}, + number = {7}, + pages = {491--496}, + publisher = {{Nature Publishing Group}}, + issn = {1758-6798}, + doi = {10.1038/nclimate1452}, + abstract = {The ostensibly large number of recent extreme weather events has triggered intensive discussions, both in- and outside the scientific community, on whether they are related to global warming. Here, we review the evidence and argue that for some types of extreme \textemdash{} notably heatwaves, but also precipitation extremes \textemdash{} there is now strong evidence linking specific events or an increase in their numbers to the human influence on climate. For other types of extreme, such as storms, the available evidence is less conclusive, but based on observed trends and basic physical concepts it is nevertheless plausible to expect an increase.}, + copyright = {2012 Nature Publishing Group, a division of Macmillan Publishers Limited. All Rights Reserved.}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Reviews Subject\_term: Climate change;Climate-change impacts Subject\_term\_id: climate-change;climate-change-impacts}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2MBSWQEE\\nclimate1452.html} +} + +@article{davisRangeShiftsAdaptive2001, + title = {Range {{Shifts}} and {{Adaptive Responses}} to {{Quaternary Climate Change}}}, + author = {Davis, Margaret B. and Shaw, Ruth G.}, + year = {2001}, + month = apr, + journal = {Science}, + volume = {292}, + number = {5517}, + pages = {673--679}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.292.5517.673}, + abstract = {Tree taxa shifted latitude or elevation range in response to changes in Quaternary climate. Because many modern trees display adaptive differentiation in relation to latitude or elevation, it is likely that ancient trees were also so differentiated, with environmental sensitivities of populations throughout the range evolving in conjunction with migrations. Rapid climate changes challenge this process by imposing stronger selection and by distancing populations from environments to which they are adapted. The unprecedented rates of climate changes anticipated to occur in the future, coupled with land use changes that impede gene flow, can be expected to disrupt the interplay of adaptation and migration, likely affecting productivity and threatening the persistence of many species.}, + chapter = {Special Reviews}, + langid = {english}, + pmid = {11326089}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\WE6DSYX8\\Davis und Shaw - 2001 - Range Shifts and Adaptive Responses to Quaternary .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\5Z9K4ENH\\673.html} +} + +@article{dawsonPredictionsBiodiversityConservation2011, + title = {Beyond {{Predictions}}: {{Biodiversity Conservation}} in a {{Changing Climate}}}, + shorttitle = {Beyond {{Predictions}}}, + author = {Dawson, Terence P. and Jackson, Stephen T. and House, Joanna I. and Prentice, Iain Colin and Mace, Georgina M.}, + year = {2011}, + month = apr, + journal = {Science}, + volume = {332}, + number = {6025}, + pages = {53--58}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.1200303}, + abstract = {Climate change is predicted to become a major threat to biodiversity in the 21st century, but accurate predictions and effective solutions have proved difficult to formulate. Alarming predictions have come from a rather narrow methodological base, but a new, integrated science of climate-change biodiversity assessment is emerging, based on multiple sources and approaches. Drawing on evidence from paleoecological observations, recent phenological and microevolutionary responses, experiments, and computational models, we review the insights that different approaches bring to anticipating and managing the biodiversity consequences of climate change, including the extent of species' natural resilience. We introduce a framework that uses information from different sources to identify vulnerability and to support the design of conservation responses. Although much of the information reviewed is on species, our framework and conclusions are also applicable to ecosystems, habitats, ecological communities, and genetic diversity, whether terrestrial, marine, or fresh water.}, + chapter = {Review}, + copyright = {Copyright \textcopyright{} 2011, American Association for the Advancement of Science}, + langid = {english}, + pmid = {21454781}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\EWLKGXFQ\\Dawson et al. - 2011 - Beyond Predictions Biodiversity Conservation in a.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\CEML54NW\\53.html} +} + +@article{deblockLocalGeneticAdaptation2013, + title = {Local Genetic Adaptation Generates Latitude-Specific Effects of Warming on Predator-Prey Interactions}, + author = {De Block, Marjan and Pauwels, Kevin and Van Den Broeck, Maarten and De Meester, Luc and Stoks, Robby}, + year = {2013}, + month = mar, + journal = {Global Change Biology}, + volume = {19}, + number = {3}, + pages = {689--696}, + issn = {1354-1013}, + doi = {10.1111/gcb.12089}, + abstract = {Temperature effects on predator-prey interactions are fundamental to better understand the effects of global warming. Previous studies never considered local adaptation of both predators and prey at different latitudes, and ignored the novel population combinations of the same predator-prey species system that may arise because of northward dispersal. We set up a common garden warming experiment to study predator-prey interactions between Ischnura elegans damselfly predators and Daphnia magna zooplankton prey from three source latitudes spanning {$>$}1500~km. Damselfly foraging rates showed thermal plasticity and strong latitudinal differences consistent with adaptation to local time constraints. Relative survival was higher at 24~\textdegree C than at 20~\textdegree C in southern Daphnia and higher at 20~\textdegree C than at 24~\textdegree C, in northern Daphnia indicating local thermal adaptation of the Daphnia prey. Yet, this thermal advantage disappeared when they were confronted with the damselfly predators of the same latitude, reflecting also a signal of local thermal adaptation in the damselfly predators. Our results further suggest the invasion success of northward moving predators as well as prey to be latitude-specific. We advocate the novel common garden experimental approach using predators and prey obtained from natural temperature gradients spanning the predicted temperature increase in the northern populations as a powerful approach to gain mechanistic insights into how community modules will be affected by global warming. It can be used as a space-for-time substitution to inform how predator-prey interaction may gradually evolve to long-term warming.}, + langid = {english}, + pmid = {23504827}, + keywords = {Adaptation; Physiological,Animals,Daphnia,Global Warming,Odonata,Predatory Behavior} +} + +@article{delattreDispersalMoodRevealed2010, + title = {Dispersal Mood Revealed by Shifts from Routine to Direct Flights in the Meadow Brown Butterfly {{Maniola}} Jurtina.}, + author = {Delattre, Thomas and Burel, Francoise and Humeau, Antoine and Stevens, Virginie Marie and Vernon, Philippe and Baguette, Michel}, + year = {2010}, + journal = {Oikos}, + volume = {119}, + number = {12}, + pages = {1900--1908}, + publisher = {{Nordic Ecological Society}}, + doi = {10.1111/j.1600-0706.2010.18615.x}, + abstract = {A comprehensive mechanistic approach to dispersal requires the translation of the whole mobility register of the target organism into movement rules that could subsequently be used to model its displacements. According to the optimality paradigm, this procedure implies a cost \textendash{} benefi t analysis of mobility patterns taking into account not only movements, but also their external context and the internal state of the moving individuals. Using this framework, we detected a `dispersal mood' in some individuals of the meadow brown butterfly Maniola jurtina. These adopted a direct flight strategy, which was topologically different from the previously documented foray search strategy. Those individuals that used the direct flight strategy moved straighter as soon as they left the habitat and avoided heading back to their patch of origin, which is the best inter-patch search strategy when dispersal risks and costs are high. The direct flight strategy was conditional to sex: females used it twice as much as males. We suggest that this sex bias was due to female investment in off spring, which is maximized by male avoidance and spatial bet hedging. Inter-patch dispersal of gravid females is crucial for the persistence of M. jurtina populations in spatially and temporally unpredictable environments.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8ECDD6JJ\\hal-00557623.html} +} + +@article{delgadoEffectPhenotypicTraits2010, + title = {The Effect of Phenotypic Traits and External Cues on Natal Dispersal Movements}, + author = {Delgado, Mar{\'i}a del Mar and Penteriani, Vincenzo and Revilla, Eloy and Nams, Vilis O.}, + year = {2010}, + journal = {Journal of Animal Ecology}, + volume = {79}, + number = {3}, + pages = {620--632}, + issn = {1365-2656}, + doi = {10.1111/j.1365-2656.2009.01655.x}, + abstract = {1. Natal dispersal has the potential to affect most ecological and evolutionary processes. However, despite its importance, this complex ecological process still represents a significant gap in our understanding of animal ecology due to both the lack of empirical data and the intrinsic complexity of dispersal dynamics. 2. By studying natal dispersal of 74 radiotagged juvenile eagle owls Bubo bubo (Linnaeus), in both the wandering and the settlement phases, we empirically addressed the complex interactions by which individual phenotypic traits and external cues jointly shape individual heterogeneity through the different phases of dispersal, both at nightly and weekly temporal scales. 3. Owls in poorer physical conditions travelled shorter total distances during the wandering phase, describing straighter paths and moving slower, especially when crossing heterogeneous habitats. In general, the owls in worse condition started dispersal later and took longer times to find further settlement areas. Net distances were also sex biased, with females settling at further distances. Dispersing individuals did not seem to explore wandering and settlement areas by using a search image of their natal surroundings. Eagle owls showed a heterogeneous pattern of patch occupancy, where few patches were highly visited by different owls whereas the majority were visited by just one individual. During dispersal, the routes followed by owls were an intermediate solution between optimized and randomized ones. Finally, dispersal direction had a marked directionality, largely influenced by dominant winds. These results suggest an asymmetric and anisotropic dispersal pattern, where not only the number of patches but also their functions can affect population viability. 4. The combination of the information coming from the relationships among a large set of factors acting and integrating at different spatial and temporal scales, under the perspective of heterogeneous life histories, are a fruitful ground for future understanding of natal dispersal.}, + langid = {english}, + keywords = {animal movements,dispersal behaviour,dispersal condition dependent,eagle owl,spatial networks}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2656.2009.01655.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\EUQHADWP\\Delgado et al. - 2010 - The effect of phenotypic traits and external cues .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\KJMLTTZT\\j.1365-2656.2009.01655.html} +} + +@article{demeesterInformationUseDensitydependent2010, + title = {Information Use and Density-Dependent Emigration in an Agrobiont Spider}, + author = {De Meester, Nele and Bonte, Dries}, + year = {2010}, + month = sep, + journal = {Behavioral Ecology}, + volume = {21}, + number = {5}, + pages = {992--998}, + issn = {1045-2249}, + doi = {10.1093/beheco/arq088}, + abstract = {Density of conspecifics is considered as one of the main conditions affecting dispersal behavior and leading to a stabilization of population dynamics. Density-dependent dispersal can be induced by local competition at different phases during development and/or by density-related sources of social information. Here, we assessed the importance of population density on emigration rates and the degree to which the presence of silk threads at dispersal takeoff locations affects immediate dispersal decision making in the spider Erigone atra. By quantifying behaviors in wind tunnels under standardized laboratory conditions, silk-assisted long- and short-distance dispersal is quantified before the actual onset of the dispersal event.Increased densities during juvenile development only affected short-distance dispersal behavior. In females, short-distance dispersal increased with the female density experienced during development, whereas responses in males increased under combined high male/low female-experienced densities. Elevated densities at the onset of dispersal led to a general increase of predispersal behaviors. The presence of silk threads at takeoff platforms similarly induced an increase of dispersal displays, with specifically an increase in long-distance dispersal in both sexes.Our results demonstrate that the spider E. atra uses information related to density during development, most probably to avoid competition by performing short-distance dispersal. In contrast, density-related cues at the time of dispersal (i.e., increased densities and the presence of silk threads) increase general dispersal activities and long-distance ballooning events. Short- and long-distance dispersal strategies are consequently guided by differential density-related information use.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\9WEVP9KQ\\De Meester und Bonte - 2010 - Information use and density-dependent emigration i.pdf} +} + +@article{dennoHabitatPersistenceUnderlies1996, + title = {Habitat {{Persistence Underlies Intraspecific Variation}} in the {{Dispersal Strategies}} of {{Planthoppers}}}, + author = {Denno, Robert F. and Roderick, George K. and Peterson, Merrill A. and Huberty, Andrea F. and Dobel, Hartmut G. and Eubanks, Micky D. and Losey, John E. and Langellotto, Gail A.}, + year = {1996}, + journal = {Ecological Monographs}, + volume = {66}, + number = {4}, + pages = {389--408}, + publisher = {{Ecological Society of America}}, + issn = {0012-9615}, + doi = {10.2307/2963487}, + abstract = {Dispersal is considered a vital life history characteristic for insects exploiting temporary habitats, and life history theorists have often hypothesized an inverse relationship between dispersal capability and habitat persistence. Most often, this hypothesis has been tested using interspecific comparisons of dispersal capability and qualitative estimates of habitat persistence. Consequently, most assessments have failed to control for possible phylogenetic nonindependence and they also lack quantitative rigor. We capitalized on existing intraspecific variation in the dispersal capability of Prokelisia planthoppers to examine the relationship between habitat persistence and dispersal, thereby minimizing possible phylogenetic effects. Two congeneric species (Prokelisia marginata and P. dolus) occur in the intertidal marshes of North America, where they feed exclusively on cordgrasses (Spartina). Because these planthoppers exhibit wing dimorphism, flight-capable adults (macropters with fully developed wings) are easily differentiated from flightless adults (brachypters with reduced wings). Thus, dispersal capability can be readily estimated by the percentage of macropters in a population. At a regional spatial scale, we found a highly significant negative relationship between dispersal capability (percent macroptery) and habitat persistence. In this system, habitat persistence is influenced by a combination of marsh elevation, winter severity, and tidal range, which interact to determine the ability of planthoppers to endure through winter in their primary habitat for development. P. marginata develops primarily in low-marsh habitats during summer, habitats that can be subjected to pronounced winter disturbance due to ice scouring and/or extensive tidal inundation. Levels of winter disturbance of the low marsh are extreme along the Atlantic coast, intermediate along the Pacific, and low along the Gulf. Both the failure of P. marginata populations to remain through winter in this habitat, and the dispersal ability of these populations (92\%, 29\%, and 17\% macroptery, respectively), are correlated with levels of disturbance. Thus, in regions where winter disturbance is high, levels of dispersal are correspondingly high to allow for recolonization of extirpated habitats from overwintering sites on the high marsh. Unlike P. marginata, P. dolus develops primarily in high-marsh habitats, which are much less disturbed on all coasts during winter. Consequently, this species remains year-round in its primary habitat for development, and most populations exhibit relatively low levels of macroptery ({$<$}10\%). When raised under common garden conditions, many more macropters of both species were produced from Atlantic compared to Gulf populations. Thus the proportion of macropters produced from the populations used in this experiment paralleled the incidence of macroptery measured in the field, providing evidence that the geographic variation in dispersal capability in both species has in part a genetic basis. The results of this study provide strong intraspecific evidence for an inverse relationship between the dispersal capability of insects and the persistence of their habitats.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ZHTGPG3S\\Denno et al. - 1996 - Habitat Persistence Underlies Intraspecific Variat.pdf} +} + +@article{doerrConnectivityDispersalBehaviour2011a, + title = {Connectivity, Dispersal Behaviour and Conservation under Climate Change: A Response to {{Hodgson}} et Al.}, + shorttitle = {Connectivity, Dispersal Behaviour and Conservation under Climate Change}, + author = {Doerr, Veronica A. J. and Barrett, Tom and Doerr, Erik D.}, + year = {2011}, + journal = {Journal of Applied Ecology}, + volume = {48}, + number = {1}, + pages = {143--147}, + issn = {1365-2664}, + doi = {10.1111/j.1365-2664.2010.01899.x}, + abstract = {1. Hodgson et al. [Journal of Applied Ecology46 (2009) 964] argue that connectivity is complex and uncertain, that it can be improved incidentally by increasing habitat extent, and that connectivity conservation is unlikely to be effective under climate change. 2. We believe that they have overlooked recent research on dispersal behaviour and structural connectivity, which has improved our understanding of functional connectivity and revealed that it will not necessarily increase with habitat extent. 3. New modelling techniques including least-cost path models incorporate this more detailed understanding of connectivity into conservation planning, facilitating the true aim of connectivity conservation \textendash{} to ensure appropriate interactions between habitat extent, quality and connectivity. 4. Synthesis and applications. Advances in behavioural research and modelling techniques allow us to manage structural connectivity with as much certainty as we manage extent and quality of habitat. Successful landscape conservation to address both current threats and future climate change must manage these three elements in concert.}, + langid = {english}, + keywords = {aggregation,behavioural ecology,connectivity conservation,corridor,fragmentation,gap-crossing,metapopulation,population viability,range shift,stepping stone}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2664.2010.01899.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\EZMNQQG4\\Doerr et al. - 2011 - Connectivity, dispersal behaviour and conservation.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\KRMKE8WD\\j.1365-2664.2010.01899.html} +} + +@article{doligezAvailabilityUsePublic2004, + title = {Availability and {{Use}} of {{Public Information}} and {{Conspecific Density}} for {{Settlement Decisions}} in the {{Collared Flycatcher}}}, + author = {Doligez, Blandine and P{\"a}rt, Tomas and Danchin, Etienne and Clobert, Jean and Gustafsson, Lars}, + year = {2004}, + journal = {Journal of Animal Ecology}, + volume = {73}, + number = {1}, + pages = {75--87}, + publisher = {{[Wiley, British Ecological Society]}}, + issn = {0021-8790}, + abstract = {1. Public information, i.e. local reproductive performance of conspecifics, is expected to be a highly valuable cue for breeding habitat selection. However, the access to this cue may be spatially and temporally constrained. When public information is unavailable, individuals may use other integrative cues, such as the local density of breeders. 2. Departure decisions of collared flycatchers (Ficedula albicollis) were shown previously to be related to both public information and breeding density, in a long-term correlative study of a fragmented population. Here, we tested whether flycatchers also use public information (number and condition of fledglings produced locally) and breeding density to make individual settlement decisions in the following year. 3. Immigration rates were computed to measure the degree of attractiveness of patches to new breeders. We investigated the relative influence of public information and breeding density on immigration rates of yearlings and older adults separately. The access to public information for settlement decisions may indeed be more limited for yearlings. 4. Immigration rate in a patch increased with mean fledgling number in the previous year for older adults but not for yearlings. Yearling immigration rate was correlated positively to mean fledgling condition when patch breeding density in the previous year was low, but negatively when density was high. 5. Immigration rates of both yearlings and older adults increased with breeding density in the previous year. Breeding density explained a larger part of the variance in immigration rate than patch reproductive success. 6. The proportion of yearlings among breeders decreased with increasing patch reproductive success and breeding density in the previous year, suggesting that local competition was high in attractive patches. 7. Our results thus suggest that public information is also used for immigration decisions. However, decisions of yearlings are more complex than those of older adults, due to their more limited access to public information and the higher impact of intraspecific competition. Conversely, all individuals seemed to cue on breeding density in a similar way. Density is correlated to patch reproductive success, and may be a more easily accessible cue. We discuss the potential advantages of using conspecific density over conspecific reproductive performance for future immigration decisions.} +} + +@article{dormannCorrelationProcessSpecies2012, + title = {Correlation and Process in Species Distribution Models: Bridging a Dichotomy}, + shorttitle = {Correlation and Process in Species Distribution Models}, + author = {Dormann, Carsten F. and Schymanski, Stanislaus J. and Cabral, Juliano and Chuine, Isabelle and Graham, Catherine and Hartig, Florian and Kearney, Michael and Morin, Xavier and R{\"o}mermann, Christine and Schr{\"o}der, Boris and Singer, Alexander}, + year = {2012}, + journal = {Journal of Biogeography}, + volume = {39}, + number = {12}, + pages = {2119--2131}, + issn = {1365-2699}, + doi = {10.1111/j.1365-2699.2011.02659.x}, + abstract = {Within the field of species distribution modelling an apparent dichotomy exists between process-based and correlative approaches, where the processes are explicit in the former and implicit in the latter. However, these intuitive distinctions can become blurred when comparing species distribution modelling approaches in more detail. In this review article, we contrast the extremes of the correlative\textendash process spectrum of species distribution models with respect to core assumptions, model building and selection strategies, validation, uncertainties, common errors and the questions they are most suited to answer. The extremes of such approaches differ clearly in many aspects, such as model building approaches, parameter estimation strategies and transferability. However, they also share strengths and weaknesses. We show that claims of one approach being intrinsically superior to the other are misguided and that they ignore the process\textendash correlation continuum as well as the domains of questions that each approach is addressing. Nonetheless, the application of process-based approaches to species distribution modelling lags far behind more correlative (process-implicit) methods and more research is required to explore their potential benefits. Critical issues for the employment of species distribution modelling approaches are given, together with a guideline for appropriate usage. We close with challenges for future development of process-explicit species distribution models and how they may complement current approaches to study species distributions.}, + langid = {english}, + keywords = {Hypothesis generation,mechanistic model,parameterization,process-based model,SDM,species distribution model,uncertainty,validation}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2011.02659.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GPTLTKUH\\Dormann et al. - 2012 - Correlation and process in species distribution mo.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\SEGWRBYA\\j.1365-2699.2011.02659.html} +} + +@article{dormannEffectsIncorporatingSpatial2007, + title = {Effects of Incorporating Spatial Autocorrelation into the Analysis of Species Distribution Data}, + author = {Dormann, Carsten F.}, + year = {2007}, + journal = {Global Ecology and Biogeography}, + volume = {16}, + number = {2}, + pages = {129--138}, + issn = {1466-8238}, + doi = {10.1111/j.1466-8238.2006.00279.x}, + abstract = {Aim Spatial autocorrelation (SAC) in data, i.e. the higher similarity of closer samples, is a common phenomenon in ecology. SAC is starting to be considered in the analysis of species distribution data, and over the last 10 years several studies have incorporated SAC into statistical models (here termed `spatial models'). Here, I address the question of whether incorporating SAC affects estimates of model coefficients and inference from statistical models. Methods I review ecological studies that compare spatial and non-spatial models. Results In all cases coefficient estimates for environmental correlates of species distributions were affected by SAC, leading to a mis-estimation of on average c. 25\%. Model fit was also improved by incorporating SAC. Main conclusions These biased estimates and incorrect model specifications have implications for predicting species occurrences under changing environmental conditions. Spatial models are therefore required to estimate correctly the effects of environmental drivers on species present distributions, for a statistically unbiased identification of the drivers of distribution, and hence for more accurate forecasts of future distributions.}, + langid = {english}, + keywords = {Autologistic regression,autoregressive model,spatial autocorrelation,spatial statistics,species distribution analysis,statistical biogeography}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-8238.2006.00279.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\TLWDUIYD\\Dormann - 2007 - Effects of incorporating spatial autocorrelation i.pdf} +} + +@article{doverInfluencesLandscapeStructure2009, + title = {The Influences of Landscape Structure on Butterfly Distribution and Movement: A Review}, + shorttitle = {The Influences of Landscape Structure on Butterfly Distribution and Movement}, + author = {Dover, John and Settele, Josef}, + year = {2009}, + month = feb, + journal = {Journal of Insect Conservation}, + volume = {13}, + number = {1}, + pages = {3--27}, + issn = {1572-9753}, + doi = {10.1007/s10841-008-9135-8}, + abstract = {We review the literature on the influence of landscape structure on butterfly distribution and movement. We start by examining the definition of landscape commonly used in spatial ecology. Landscape-level processes are reviewed before focusing on the impact of the geometry and spatial arrangement of habitat patches on butterflies e.g. the nature of the matrix, patch size and shape, minimum area requirements, immigration and emigration, and temporal habitat dynamics. The role of landscape elements is reviewed in terms of corridors (and stepping-stones), barriers, nodes, environmental buffers, and prominent landmark features.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\LJVY2JZQ\\Dover und Settele - 2009 - The influences of landscape structure on butterfly.pdf} +} + +@article{driezenEvaluatingLeastcostModel2007, + title = {Evaluating Least-Cost Model Predictions with Empirical Dispersal Data: {{A}} Case-Study Using Radiotracking Data of Hedgehogs ({{Erinaceus}} Europaeus)}, + shorttitle = {Evaluating Least-Cost Model Predictions with Empirical Dispersal Data}, + author = {Driezen, Kassandra and Adriaensen, Frank and Rondinini, Carlo and Doncaster, C. Patrick and Matthysen, Erik}, + year = {2007}, + journal = {Ecological Modelling}, + volume = {209}, + number = {2}, + pages = {314--322}, + publisher = {{Elsevier}}, + abstract = {Habitat fragmentation and habitat loss are widely recognized as major threats to biodiversity on a regional as well as on a global scale. To restrict its effects, ecological networks such as the trans-European network NATURA2000 are being developed based on the assumption that structural connections between habitat fragments lead to increased exchange through dispersal and a higher viability of (meta)populations. However, there is a great need for techniques that translate these networks and/or structural characteristics of landscapes into functional connectivity for specific organisms. Least-cost analysis has the capacities to fulfill these needs, but has never been validated against actual observations of dispersal paths. Here we present a method to validate the results of a least-cost analysis by comparing realized movement paths of hedgehogs in unfamiliar areas, obtained by radiotracking, with statistics on landscape-wide distribution of cost values. The degree of correspondence between empirical dispersal paths and the output of a least-cost analysis can be visualized and quantified, and least-cost scenarios can be statistically compared. We show that hedgehogs moved along paths with significantly lower cost values than the average landscape, implying that they took better than random routes, but performance was relatively poor. We attribute this to the relatively generalistic habitat use of the model species and the rather homogeneous landscapes. We conclude that this approach can be useful for further validation of the least-cost model and allows a direct comparison of model performance among different taxa and/or landscapes.}, + langid = {english}, + keywords = {Connectivity,Cost-distance,Dispersal path,Erinaceus europaeus,Least-cost model}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8A74C4QW\\v209y2007i2p314-322.html} +} + +@article{duckworthAdaptiveDispersalStrategies2008, + title = {Adaptive Dispersal Strategies and the Dynamics of a Range Expansion}, + author = {Duckworth, Ren{\'e}e A.}, + year = {2008}, + month = jul, + journal = {The American Naturalist}, + volume = {172 Suppl 1}, + pages = {S4-17}, + issn = {1537-5323}, + doi = {10.1086/588289}, + abstract = {In species undergoing range expansion, newly established populations are often more dispersive than older populations. Because dispersal phenotypes are complex and often costly, it is unclear how highly dispersive phenotypes are maintained in a species to enable their rapid expression during periods of range expansion. Here I test the idea that metapopulation dynamics of local extinction and recolonization maintain distinct dispersal strategies outside the context of range expansion. Western bluebirds display distinct dispersal phenotypes where aggressive males are more dispersive than nonaggressive males, resulting in highly aggressive populations at the edge of their expanding range. I experimentally created new habitat interior to the range edge to show that, as on the range front, it was colonized solely by aggressive males. Moreover, fitness consequences of aggression depended on population age: aggressive males had high fitness when colonizing new populations, while nonaggressive males performed best in an older population. These results suggest that distinct dispersal strategies were maintained before range expansion as an adaptation for the continual recolonization of new habitat. These results emphasize similarities between range expansion and metapopulation dynamics and suggest that preexisting adaptive dispersal strategies may explain rapid changes in dispersal phenotypes during range expansion.}, + langid = {english}, + pmid = {18554143}, + keywords = {Adaptation; Biological,Aggression,Animals,Ecosystem,Female,Geography,Male,Montana,Population Dynamics,Selection; Genetic,Songbirds} +} + +@article{dyckHabitatFragmentationInsect1999, + title = {Habitat Fragmentation and Insect Flight: A Changing `Design' in a Changing Landscape?}, + shorttitle = {Habitat Fragmentation and Insect Flight}, + author = {Dyck, Hans Van and Matthysen, Erik}, + year = {1999}, + month = may, + journal = {Trends in Ecology \& Evolution}, + volume = {14}, + number = {5}, + pages = {172--174}, + publisher = {{Elsevier}}, + issn = {0169-5347}, + doi = {10.1016/S0169-5347(99)01610-9}, + langid = {english}, + pmid = {10322528}, + keywords = {butterflies,dispersal,Ecology,evolution,Evolution,habitat fragmentation,insect flight,morphological design}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\3A89AYW2\\Dyck et al. - 1999 - Habitat fragmentation and insect flight a changin.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\LL532EVX\\S0169-5347(99)01610-9.html} +} + +@article{dythamEvolvedDispersalStrategies2009, + title = {Evolved Dispersal Strategies at Range Margins}, + author = {Dytham, Calvin}, + year = {2009}, + month = apr, + journal = {Proceedings of the Royal Society B: Biological Sciences}, + volume = {276}, + number = {1661}, + pages = {1407--1413}, + issn = {0962-8452}, + doi = {10.1098/rspb.2008.1535}, + abstract = {Dispersal is a key component of a species's ecology and will be under different selection pressures in different parts of the range. For example, a long-distance dispersal strategy suitable for continuous habitat at the range core might not be favoured at the margin, where the habitat is sparse. Using a spatially explicit, individual-based, evolutionary simulation model, the dispersal strategies of an organism that has only one dispersal event in its lifetime, such as a plant or sessile animal, are considered. Within the model, removing habitat, increasing habitat turnover, increasing the cost of dispersal, reducing habitat quality or altering vital rates imposes range limits. In most cases, there is a clear change in the dispersal strategies across the range, although increasing death rate towards the margin has little impact on evolved dispersal strategy across the range. Habitat turnover, reduced birth rate and reduced habitat quality all increase evolved dispersal distances at the margin, while increased cost of dispersal and reduced habitat density lead to lower evolved dispersal distances at the margins. As climate change shifts suitable habitat poleward, species ranges will also start to shift, and it will be the dispersal capabilities of marginal populations, rather than core populations, that will influence the rate of range shifting.}, + pmcid = {PMC2677228}, + pmid = {19324810}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\625B7SCP\\Dytham - 2009 - Evolved dispersal strategies at range margins.pdf} +} + +@article{dythamEvolvingDispersalAge2006, + title = {Evolving {{Dispersal}} and {{Age}} at {{Death}}}, + author = {Dytham, Calvin and Travis, Justin M. J.}, + year = {2006}, + journal = {Oikos}, + volume = {113}, + number = {3}, + pages = {530--538}, + publisher = {{[Nordic Society Oikos, Wiley]}}, + issn = {0030-1299}, + abstract = {Traditional, and often competing, theories on ageing agree that a programmed age at death must have arisen as a side effect of natural selection, and that it can have no adaptive value of its own. However, theoretical models suggest that ageing and programmed death can be adaptive. Travis J. M. J. suggested that if fecundity declines with age, a programmed age of death evolves through kin selection and that the nature of dispersal is crucial as it determines the degree of spatial structure and hence the strength of kin selection. Here, using a similar model, we consider the interplay between dispersal and age of death. We incorporate more realistic dispersal kernels and allow both dispersal and age of death to evolve. Our results show each trait can evolve in response to the other: earlier age of death evolves when individuals disperse less and greater dispersal distances evolve when individuals are programmed to die later. When we allow dispersal and age of death to evolve at the same time we typically find that dispersal evolves more rapidly, and that ageing then evolves in response to the new dispersal regime. The cost of dispersal is crucial in determining the evolution of both traits. We argue both that ageing is an overlooked ecological process, and that the field of gerontology could learn a lot from evolutionary ecology. We suggest that it is time to develop the field of ecological gerontology and we highlight a few areas where future work might be particularly rewarding.} +} + +@article{easterlingClimateExtremesObservations2000, + title = {Climate {{Extremes}}: {{Observations}}, {{Modeling}}, and {{Impacts}}}, + shorttitle = {Climate {{Extremes}}}, + author = {Easterling, David R. and Meehl, Gerald A. and Parmesan, Camille and Changnon, Stanley A. and Karl, Thomas R. and Mearns, Linda O.}, + year = {2000}, + month = sep, + journal = {Science}, + volume = {289}, + number = {5487}, + pages = {2068--2074}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.289.5487.2068}, + abstract = {One of the major concerns with a potential change in climate is that an increase in extreme events will occur. Results of observational studies suggest that in many areas that have been analyzed, changes in total precipitation are amplified at the tails, and changes in some temperature extremes have been observed. Model output has been analyzed that shows changes in extreme events for future climates, such as increases in extreme high temperatures, decreases in extreme low temperatures, and increases in intense precipitation events. In addition, the societal infrastructure is becoming more sensitive to weather and climate extremes, which would be exacerbated by climate change. In wild plants and animals, climate-induced extinctions, distributional and phenological changes, and species' range shifts are being documented at an increasing rate. Several apparently gradual biological changes are linked to responses to extreme weather and climate events.}, + chapter = {Review}, + langid = {english}, + pmid = {11000103}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\F5G4BRUV\\Easterling et al. - 2000 - Climate Extremes Observations, Modeling, and Impa.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\4GK3BV9N\\2068.html} +} + +@article{edelaarMatchingHabitatChoice2008, + title = {Matching {{Habitat Choice Causes Directed Gene Flow}}: {{A Neglected Dimension}} in {{Evolution}} and {{Ecology}}}, + shorttitle = {Matching {{Habitat Choice Causes Directed Gene Flow}}}, + author = {Edelaar, Pim and Siepielski, Adam M. and Clobert, Jean}, + year = {2008}, + journal = {Evolution}, + volume = {62}, + number = {10}, + pages = {2462--2472}, + issn = {1558-5646}, + doi = {10.1111/j.1558-5646.2008.00459.x}, + abstract = {Gene flow among populations is typically thought to be antagonistic to population differentiation and local adaptation. However, this assumes that dispersing individuals disperse randomly with respect to their ability to use the environment. Yet dispersing individuals often sample and compare environments and settle in those environments that best match their phenotype, causing directed gene flow, which can in fact promote population differentiation and adaptation. We refer to this process as ``matching habitat choice.'' Although this process has been acknowledged by several researchers, no synthesis or perspective on its potentially widespread importance exists. Here we synthesize empirical and theoretical studies, and offer a new perspective that matching habitat choice can have significant effects on important and controversial topics. We discuss the potential implications of matching habitat choice for the degree and rate of local adaptation, the evolution of niche width, adaptive peak shifts, speciation in the presence of gene flow, and on our view and interpretation of measures of natural selection. Because of its potential importance for such a wide range of topics, we call for heightened empirical and theoretical attention for this neglected dimension in evolutionary and ecological studies.}, + langid = {english}, + keywords = {Dispersal,gene flow,habitat choice,local adaptation,migration–selection balance,natural selection,population differentiation}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1558-5646.2008.00459.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\DBFI93ZP\\Edelaar et al. - 2008 - Matching Habitat Choice Causes Directed Gene Flow.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\756WY33F\\j.1558-5646.2008.00459.html} +} + +@article{elithSpeciesDistributionModels, + title = {Species {{Distribution Models}}: {{Ecological Explanation}} and {{Prediction Across Space}} and {{Time}}}, + author = {Elith, J and Leathwick, J. R.}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + number = {40}, + pages = {677--697} +} + +@article{enfjallEvolutionDispersalImportance2009, + title = {The Evolution of Dispersal \textendash{} the Importance of Information about Population Density and Habitat Characteristics}, + author = {Enfj{\"a}ll, Karin and Leimar, Olof}, + year = {2009}, + journal = {Oikos}, + volume = {118}, + number = {2}, + pages = {291--299}, + issn = {1600-0706}, + doi = {10.1111/j.1600-0706.2008.16863.x}, + abstract = {The evolution of mobility patterns and dispersal strategies depend on different population, habitat and life history characteristics. The ability to perceive and make use of information about the surrounding environment for dispersal decisions will also differ between organisms. To investigate the evolutionary consequences of such differences, we have used a simulation model with nearest-neighbour dispersal in a metapopulation to study how variation in the ability to obtain and make use of information about habitat quality and conspecific density affects the evolution of dispersal strategies. We found a rather strong influence of variation in information on the overall rate of dispersal in a metapopulation. The highest emigration rate evolved in organisms with no information about either density or habitat quality and the lowest rate was found in organisms with information about both the natal and the neighbouring patches. For organisms that can make use of information about conspecific density, positively density-dependent dispersal evolved in the majority of cases, with the strongest density dependence occurring when an individual only has information about density in the natal patch. However, we also identified situations, involving strong local population fluctuations and frequent local extinctions, where negatively density-dependent dispersal evolved.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2008.16863.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\LT3FZ62H\\Enfjäll und Leimar - 2009 - The evolution of dispersal – the importance of inf.pdf} +} + +@article{englerMigClimPredictingPlant2009, + title = {{{MigClim}}: {{Predicting}} Plant Distribution and Dispersal in a Changing Climate}, + shorttitle = {{{MigClim}}}, + author = {Engler, Robin and Guisan, Antoine}, + year = {2009}, + journal = {Diversity and Distributions}, + volume = {15}, + number = {4}, + pages = {590--601}, + issn = {1472-4642}, + doi = {10.1111/j.1472-4642.2009.00566.x}, + abstract = {Aim Many studies have forecasted the possible impact of climate change on plant distributions using models based on ecological niche theory, but most of them have ignored dispersal-limitations, assuming dispersal to be either unlimited or null. Depending on the rate of climatic change, the landscape fragmentation and the dispersal capabilities of individual species, these assumptions are likely to prove inaccurate, leading to under- or overestimation of future species distributions and yielding large uncertainty between these two extremes. As a result, the concepts of `potentially suitable' and `potentially colonizable' habitat are expected to differ significantly. To quantify to what extent these two concepts can differ, we developed MigClim, a model simulating plant dispersal under climate change and landscape fragmentation scenarios. MigClim implements various parameters, such as dispersal distance, increase in reproductive potential over time, landscape fragmentation or long-distance dispersal. Location Western Swiss Alps. Methods Using our MigClim model, several simulations were run for two virtual species by varying dispersal distance and other parameters. Each simulation covered the 100-year period 2001\textendash 2100 and three different IPCC-based temperature warming scenarios were considered. Results of dispersal-limited projections were compared with unlimited and no-dispersal projections. Results Our simulations indicate that: (1) using realistic parameter values, the future potential distributions generated using MigClim can differ significantly (up to more than 95\% difference in colonized surface) from those that ignore dispersal; (2) this divergence increases under more extreme climate warming scenarios and over longer time periods; and (3) the uncertainty associated with the warming scenario can be as large as the one related to dispersal parameters. Main conclusions Accounting for dispersal, even roughly, can importantly reduce uncertainty in projections of species distribution under climate change scenarios.}, + langid = {english}, + keywords = {Cellular automaton,climate change,dispersal modelling,dynamic niche-based models,GLM,plant species distribution}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2009.00566.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\23WHR4RV\\Engler und Guisan - 2009 - MigClim Predicting plant distribution and dispers.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\SCAJT7CB\\j.1472-4642.2009.00566.html} +} + +@article{eppersonUtilityComputerSimulations2010, + title = {Utility of Computer Simulations in Landscape Genetics}, + author = {Epperson, Bryan K. and Mcrae, Brad H. and Scribner, Kim and Cushman, Samuel A. and Rosenberg, Michael S. and Fortin, Marie-Jos{\'e}e and James, Patrick M. A. and Murphy, Melanie and Manel, St{\'e}phanie and Legendre, Pierre and Dale, Mark R. T.}, + year = {2010}, + journal = {Molecular Ecology}, + volume = {19}, + number = {17}, + pages = {3549--3564}, + issn = {1365-294X}, + doi = {10.1111/j.1365-294X.2010.04678.x}, + abstract = {Population genetics theory is primarily based on mathematical models in which spatial complexity and temporal variability are largely ignored. In contrast, the field of landscape genetics expressly focuses on how population genetic processes are affected by complex spatial and temporal environmental heterogeneity. It is spatially explicit and relates patterns to processes by combining complex and realistic life histories, behaviours, landscape features and genetic data. Central to landscape genetics is the connection of spatial patterns of genetic variation to the usually highly stochastic space\textendash time processes that create them over both historical and contemporary time periods. The field should benefit from a shift to computer simulation approaches, which enable incorporation of demographic and environmental stochasticity. A key role of simulations is to show how demographic processes such as dispersal or reproduction interact with landscape features to affect probability of site occupancy, population size, and gene flow, which in turn determine spatial genetic structure. Simulations could also be used to compare various statistical methods and determine which have correct type I error or the highest statistical power to correctly identify spatio-temporal and environmental effects. Simulations may also help in evaluating how specific spatial metrics may be used to project future genetic trends. This article summarizes some of the fundamental aspects of spatial\textendash temporal population genetic processes. It discusses the potential use of simulations to determine how various spatial metrics can be rigorously employed to identify features of interest, including contrasting locus-specific spatial patterns due to micro-scale environmental selection.}, + langid = {english}, + keywords = {individual-based models,landscape ecology,population genetics,simulations,spatial statistics}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-294X.2010.04678.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\V96KB67J\\Epperson et al. - 2010 - Utility of computer simulations in landscape genet.pdf} +} + +@article{excoffierGeneticConsequencesRange2009, + title = {Genetic {{Consequences}} of {{Range Expansions}}}, + author = {Excoffier, Laurent and Foll, Matthieu and Petit, R{\'e}my J.}, + year = {2009}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + volume = {40}, + number = {1}, + pages = {481--501}, + doi = {10.1146/annurev.ecolsys.39.110707.173414}, + abstract = {Although range expansions have occurred recurrently in the history of most species, their genetic consequences have been little investigated. Theoretical studies show that range expansions are quite different from pure demographic expansions and that the extent of recent gene flow conditions expected patterns of molecular diversity within and between populations. Spatially explicit simulation studies have led to unexpected and fascinating results about genetic patterns emerging after a range expansion. For instance, spatial expansions can generate allele frequency gradients, promote the surfing of rare variants into newly occupied territories, induce the structuring of newly colonized areas into distinct sectors of low genetic diversity, or lead to massive introgression of local genes into the genome of an invading species. Interestingly, most of these patterns had been previously attributed to distinct selective processes, showing that taking into account the dynamic nature of a species range can lead to a paradigm shift in our perception of evolutionary processes.}, + annotation = {\_eprint: https://doi.org/10.1146/annurev.ecolsys.39.110707.173414}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ME9I5RQA\\Excoffier et al. - 2009 - Genetic Consequences of Range Expansions.pdf} +} + +@article{fahrigEffectsHabitatFragmentation2003a, + title = {Effects of {{Habitat Fragmentation}} on {{Biodiversity}}}, + author = {Fahrig, Lenore}, + year = {2003}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + volume = {34}, + number = {1}, + pages = {487--515}, + doi = {10.1146/annurev.ecolsys.34.011802.132419}, + abstract = {The literature on effects of habitat fragmentation on biodiversity is huge. It is also very diverse, with different authors measuring fragmentation in different ways and, as a consequence, drawing different conclusions regarding both the magnitude and direction of its effects. Habitat fragmentation is usually defined as a landscape-scale process involving both habitat loss and the breaking apart of habitat. Results of empirical studies of habitat fragmentation are often difficult to interpret because (a) many researchers measure fragmentation at the patch scale, not the landscape scale and (b) most researchers measure fragmentation in ways that do not distinguish between habitat loss and habitat fragmentation per se, i.e., the breaking apart of habitat after controlling for habitat loss. Empirical studies to date suggest that habitat loss has large, consistently negative effects on biodiversity. Habitat fragmentation per se has much weaker effects on biodiversity that are at least as likely to be positive as negative. Therefore, to correctly interpret the influence of habitat fragmentation on biodiversity, the effects of these two components of fragmentation must be measured independently. More studies of the independent effects of habitat loss and fragmentation per se are needed to determine the factors that lead to positive versus negative effects of fragmentation per se. I suggest that the term ``fragmentation'' should be reserved for the breaking apart of habitat, independent of habitat loss.}, + annotation = {\_eprint: https://doi.org/10.1146/annurev.ecolsys.34.011802.132419}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\JW2M3HGH\\Fahrig - 2003 - Effects of Habitat Fragmentation on Biodiversity.pdf} +} + +@article{fahrigNonoptimalAnimalMovement2007a, + title = {Non-Optimal Animal Movement in Human-Altered Landscapes}, + author = {Fahrig, Lenore}, + year = {2007}, + journal = {Functional Ecology}, + volume = {21}, + number = {6}, + pages = {1003--1015}, + issn = {1365-2435}, + doi = {10.1111/j.1365-2435.2007.01326.x}, + abstract = {1 I synthesize the understanding of the relationship between landscape structure and animal movement in human-modified landscapes. 2 The variety of landscape structures is first classified into four categories: continuous habitat, patchy habitat with high-quality matrix, patchy habitat with low-quality matrix, and patchy, ephemeral habitat. Using this simplification I group the range of evolved movement parameters into four categories or movement types. I then discuss how these movement types interact with current human-caused landscape changes, and how this often results in non-optimal movement. 3 From this synthesis I develop a hypothesis that predicts the relative importance of the different population-level consequences of these non-optimal movements, for the four movement types. 4 Populations of species that have inhabited landscapes with high habitat cover or patchy landscapes with low-risk matrix should have evolved low boundary responses and moderate to high movement probabilities. These species are predicted to be highly susceptible to increased movement mortality resulting from habitat loss and reduced matrix quality. 5 In contrast, populations of species that evolved in patchy landscapes with high-risk matrix or dynamic patchy landscapes are predicted to be highly susceptible to decreased immigration and colonization success, due to the increasing patch isolation that results from habitat loss. 6 Finally, I discuss three implications of this synthesis: (i) `least cost path' analysis should not be used for land management decisions without data on actual movement paths and movement risks in the landscape; (ii) `dispersal ability' is not simply an attribute of a species, but varies strongly with landscape structure such that the relative rankings of species' dispersal abilities can change following landscape alteration; and (iii) the assumption that more mobile species are more resilient to human-caused landscape change is not generally true, but depends on the structure of the landscape where the species evolved.}, + langid = {english}, + keywords = {colonization,dispersal ability,dispersal mortality,landscape structure,least cost path}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2435.2007.01326.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\SAETXSAN\\Fahrig - 2007 - Non-optimal animal movement in human-altered lands.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\9NAZ9VUH\\j.1365-2435.2007.01326.html} +} + +@article{fellousQuorumSensingDensityDependent2012, + title = {Quorum {{Sensing}} and {{Density-Dependent Dispersal}} in an {{Aquatic Model System}}}, + author = {Fellous, Simon and Duncan, Alison and Coulon, Aur{\'e}lie and Kaltz, Oliver}, + year = {2012}, + month = nov, + journal = {PLOS ONE}, + volume = {7}, + number = {11}, + pages = {e48436}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0048436}, + abstract = {Many organisms use cues to decide whether to disperse or not, especially those related to the composition of their environment. Dispersal hence sometimes depends on population density, which can be important for the dynamics and evolution of sub-divided populations. But very little is known about the factors that organisms use to inform their dispersal decision. We investigated the cues underlying density-dependent dispersal in inter-connected microcosms of the freshwater protozoan Paramecium caudatum. In two experiments, we manipulated (i) the number of cells per microcosm and (ii) the origin of their culture medium (supernatant from high- or low-density populations). We found a negative relationship between population density and rates of dispersal, suggesting the use of physical cues. There was no significant effect of culture medium origin on dispersal and thus no support for chemical cues usage. These results suggest that the perception of density \textendash{} and as a result, the decision to disperse \textendash{} in this organism can be based on physical factors. This type of quorum sensing may be an adaptation optimizing small scale monitoring of the environment and swarm formation in open water.}, + langid = {english}, + keywords = {Allee effect,Behavior,Cloning,Paramecium,Population density,Quorum sensing,Statistical dispersion,Swimming}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\KNTDRHDG\\Fellous et al. - 2012 - Quorum Sensing and Density-Dependent Dispersal in .pdf} +} + +@article{fischerLandscapeModificationHabitat2007, + title = {Landscape Modification and Habitat Fragmentation: A Synthesis}, + shorttitle = {Landscape Modification and Habitat Fragmentation}, + author = {Fischer, Joern and Lindenmayer, David B.}, + year = {2007}, + journal = {Global Ecology and Biogeography}, + volume = {16}, + number = {3}, + pages = {265--280}, + issn = {1466-8238}, + doi = {10.1111/j.1466-8238.2007.00287.x}, + abstract = {Landscape modification and habitat fragmentation are key drivers of global species loss. Their effects may be understood by focusing on: (1) individual species and the processes threatening them, and (2) human-perceived landscape patterns and their correlation with species and assemblages. Individual species may decline as a result of interacting exogenous and endogenous threats, including habitat loss, habitat degradation, habitat isolation, changes in the biology, behaviour, and interactions of species, as well as additional, stochastic threats. Human-perceived landscape patterns that are frequently correlated with species assemblages include the amount and structure of native vegetation, the prevalence of anthropogenic edges, the degree of landscape connectivity, and the structure and heterogeneity of modified areas. Extinction cascades are particularly likely to occur in landscapes with low native vegetation cover, low landscape connectivity, degraded native vegetation and intensive land use in modified areas, especially if keystone species or entire functional groups of species are lost. This review (1) demonstrates that species-oriented and pattern-oriented approaches to understanding the ecology of modified landscapes are highly complementary, (2) clarifies the links between a wide range of interconnected themes, and (3) provides clear and consistent terminology. Tangible research and management priorities are outlined that are likely to benefit the conservation of native species in modified landscapes around the world.}, + langid = {english}, + keywords = {Connectivity,countryside biogeography,edge effects,extinction proneness,habitat fragmentat,habitat loss,keystone,landscape heterogeneity,matrix,species,threatening processes}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-8238.2007.00287.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\FH4QSVBH\\Fischer und Lindenmayer - 2007 - Landscape modification and habitat fragmentation .pdf} +} + +@article{fletcherjr.EmergentPropertiesConspecific2006, + title = {Emergent {{Properties}} of {{Conspecific Attraction}} in {{Fragmented Landscapes}}}, + author = {Fletcher Jr., Robert J. and Grimm, Associate Editor: Volker and DeAngelis, Editor: Donald L.}, + year = {2006}, + journal = {The American Naturalist}, + volume = {168}, + number = {2}, + pages = {207--219}, + publisher = {{[The University of Chicago Press, The American Society of Naturalists]}}, + issn = {0003-0147}, + doi = {10.1086/505764}, + abstract = {Abstract: Attraction to conspecifics may have wide-ranging implications for habitat selection and metapopulation theory, yet little is known about the process of attraction and its effects relative to other habitat selection strategies. Using individual-based simulations, I investigated the emergent properties of conspecific attraction during habitat selection on survival, fecundity, short-term fitness (sur \textbackslash documentclass\{aastex\} \textbackslash usepackage\{amsbsy\} \textbackslash usepackage\{amsfonts\} \textbackslash usepackage\{amssymb\} \textbackslash usepackage\{bm\} \textbackslash usepackage\{mathrsfs\} \textbackslash usepackage\{pifont\} \textbackslash usepackage\{stmaryrd\} \textbackslash usepackage\{textcomp\} \textbackslash usepackage\{portland,xspace\} \textbackslash usepackage\{amsmath,amsxtra\} \textbackslash usepackage[OT2,OT1]\{fontenc\} \textbackslash newcommand\textbackslash cyr\{ \textbackslash renewcommand\textbackslash rmdefault\{wncyr\} \textbackslash renewcommand\textbackslash sfdefault\{wncyss\} \textbackslash renewcommand\textbackslash encodingdefault\{OT2\} \textbackslash normalfont \textbackslash selectfont\} \textbackslash DeclareTextFontCommand\{\textbackslash textcyr\}\{\textbackslash cyr\} \textbackslash pagestyle\{empty\} \textbackslash DeclareMathSizes\{10\}\{9\}\{7\}\{6\} \textbackslash begin\{document\} \textbackslash landscape \$\textbackslash mathrm\{vival\}\textbackslash,\textbackslash times \textbackslash mathrm\{fecundity\}\textbackslash,\$ \textbackslash end\{document\} ), and distributions in fragmented landscapes. I simulated conspecific attraction during searching and settlement decisions and compared attraction with random, habitat-based (searching for the presence of habitat), and habitat quality sampling strategies (searching for and settling in high-quality habitat). Conspecific attraction during searching or settlement decisions had different consequences for animals: attraction while searching increased survival by decreasing time spent in nonsuitable habitat, whereas attraction during settlement increased fecundity by aggregating animals in high-quality habitats. Habitat-based sampling did not improve fitness over attraction, but directly sampling habitat quality resulted in the highest short-term fitness among strategies. These results suggest that attraction can improve fitness when animals cannot directly assess habitat quality. Interestingly, conspecific attraction influenced distributions by generating patch size effects and weak edge effects, highlighting that attraction is one potential, yet previously unappreciated, mechanism to explain the widespread patterns of animal sensitivity to habitat fragmentation.} +} + +@article{fletcherSpeciesInteractionsPopulation2007, + title = {Species Interactions and Population Density Mediate the Use of Social Cues for Habitat Selection}, + author = {Fletcher, Robert J.}, + year = {2007}, + month = may, + journal = {The Journal of Animal Ecology}, + volume = {76}, + number = {3}, + pages = {598--606}, + issn = {0021-8790}, + doi = {10.1111/j.1365-2656.2007.01230.x}, + abstract = {1. The perspective that populations and communities are structured by antagonistic interactions among individuals has dominated much of ecology. Yet how animals use social information to guide decisions, such as habitat selection, may be influenced by both positive and negative interactions among individuals. Recent theory also suggests that the way animals use social information may be substantially influenced by population density, which alters the potential costs and benefits of such behaviours. 2. I manipulated cues of two competitors, the dominant least flycatcher Empidonax minimus (Baird \& Baird) and the subordinate American redstart Setophaga ruticilla (Linnaeus), to assess the use of conspecific and heterospecific cues during habitat selection, and if population density influences these strategies. The experiment consisted of surveying birds during a pre-treatment year, which allows for the control and testing the effect of baseline densities, and a treatment year, in which treatments were applied just prior to settlement. Treatments included broadcasting songs of flycatchers and redstarts, and were compared with controls. 3. When controlling for pre-treatment densities, bird densities, and to a lesser extent arrival dates, during the treatment year suggested that flycatchers were attracted to both conspecific and heterospecific cues during settlement. Furthermore, attraction was strongest for flycatchers in plots with moderate pre-treatment densities. American redstarts were rare in the study area but showed apparent attraction to conspecifics and avoidance of heterospecifics. 4. These results provide experimental evidence for the use of multiple social cues in habitat selection and suggest that heterospecific attraction may operate under broader contexts than originally envisioned. In such instances, nontarget effects can potentially occur when manipulating social cues to elicit settlement in conservation strategies. The impact of population density on the use of social cues shown here can also influence our understanding of metapopulation dynamics by causing complex threshold effects on the likelihood of rescue, which may influence metapopulation stability and the likelihood of local extinction.}, + langid = {english}, + pmid = {17439476}, + keywords = {Animals,Behavior; Animal,Competitive Behavior,Conservation of Natural Resources,Ecosystem,Female,Male,Population Density,Population Dynamics,Social Behavior,Songbirds,Species Specificity}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\AMEKHZ9S\\Fletcher - 2007 - Species interactions and population density mediat.pdf} +} + +@article{fowlerConfoundingEnvironmentalColour2013, + title = {Confounding {{Environmental Colour}} and {{Distribution Shape Leads}} to {{Underestimation}} of {{Population Extinction Risk}}}, + author = {Fowler, Mike S. and Ruokolainen, Lasse}, + year = {2013}, + month = feb, + journal = {PLOS ONE}, + volume = {8}, + number = {2}, + pages = {e55855}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0055855}, + abstract = {The colour of environmental variability influences the size of population fluctuations when filtered through density dependent dynamics, driving extinction risk through dynamical resonance. Slow fluctuations (low frequencies) dominate in red environments, rapid fluctuations (high frequencies) in blue environments and white environments are purely random (no frequencies dominate). Two methods are commonly employed to generate the coloured spatial and/or temporal stochastic (environmental) series used in combination with population (dynamical feedback) models: autoregressive [AR(1)] and sinusoidal (1/f) models. We show that changing environmental colour from white to red with 1/f models, and from white to red or blue with AR(1) models, generates coloured environmental series that are not normally distributed at finite time-scales, potentially confounding comparison with normally distributed white noise models. Increasing variability of sample Skewness and Kurtosis and decreasing mean Kurtosis of these series alter the frequency distribution shape of the realised values of the coloured stochastic processes. These changes in distribution shape alter patterns in the probability of single and series of extreme conditions. We show that the reduced extinction risk for undercompensating (slow growing) populations in red environments previously predicted with traditional 1/f methods is an artefact of changes in the distribution shapes of the environmental series. This is demonstrated by comparison with coloured series controlled to be normally distributed using spectral mimicry. Changes in the distribution shape that arise using traditional methods lead to underestimation of extinction risk in normally distributed, red 1/f environments. AR(1) methods also underestimate extinction risks in traditionally generated red environments. This work synthesises previous results and provides further insight into the processes driving extinction risk in model populations. We must let the characteristics of known natural environmental covariates (e.g., colour and distribution shape) guide us in our choice of how to best model the impact of coloured environmental variation on population dynamics.}, + langid = {english}, + keywords = {Autocorrelation,Extinction risk,Normal distribution,Population density,Population dynamics,Probability distribution,Skewness,Stochastic processes}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\4YG8CQTQ\\Fowler und Ruokolainen - 2013 - Confounding Environmental Colour and Distribution .pdf} +} + +@article{frankhamWhereAreWe2010, + title = {Where Are We in Conservation Genetics and Where Do We Need to Go?}, + author = {Frankham, Richard}, + year = {2010}, + month = apr, + journal = {Conservation Genetics}, + volume = {11}, + number = {2}, + pages = {661--663}, + issn = {1572-9737}, + doi = {10.1007/s10592-009-0010-2}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\R8F8LQK2\\Frankham - 2010 - Where are we in conservation genetics and where do.pdf} +} + +@article{franklinMovingStaticSpecies2010, + title = {Moving beyond Static Species Distribution Models in Support of Conservation Biogeography}, + author = {Franklin, Janet}, + year = {2010}, + journal = {Diversity and Distributions}, + volume = {16}, + number = {3}, + pages = {321--330}, + issn = {1472-4642}, + doi = {10.1111/j.1472-4642.2010.00641.x}, + abstract = {Aim To demonstrate that multi-modelling methods have effectively been used to combine static species distribution models (SDM), predicting the geographical pattern of suitable habitat, with dynamic landscape and population models to forecast the impacts of environmental change on species' status, an important goal of conservation biogeography. Methods Three approaches were considered: (1) incorporating models of species migration to understand the ability of a species to occupy suitable habitat in new locations; (2) linking models of landscape disturbance and succession to models of habitat suitability; and (3) fully linking models of habitat suitability, habitat dynamics and spatially explicit population dynamics. Results Linking species\textendash environment relationships, landscape dynamics and population dynamics in a multi-modelling framework allows the combined impacts of climate change (affecting species distribution and vital rates) and land cover dynamics (land use change, altered disturbance regimes) on species to be predicted. This approach is only feasible if the life history parameters and habitat requirements of the species are well understood. Main conclusions Forecasts of the impacts of global change on species may be improved by considering multiple causes. A range of methods are available to address the interactions of changing habitat suitability, habitat dynamics and population response that vary in their complexity, realism and data requirements.}, + langid = {english}, + keywords = {Climate change,disturbance,landscape dynamics,metapopulation model,species distribution model,species migration}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2010.00641.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\M47NGK2Z\\Franklin - 2010 - Moving beyond static species distribution models i.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\QTJPQC4Y\\j.1472-4642.2010.00641.html} +} + +@article{franksGeneticsClimateChange2012, + title = {Genetics of {{Climate Change Adaptation}}}, + author = {Franks, Steven J. and Hoffmann, Ary A.}, + year = {2012}, + month = dec, + journal = {Annual Review of Genetics}, + volume = {46}, + number = {1}, + pages = {185--208}, + publisher = {{Annual Reviews}}, + issn = {0066-4197}, + doi = {10.1146/annurev-genet-110711-155511}, + abstract = {The rapid rate of current global climate change is having strong effects on many species and, at least in some cases, is driving evolution, particularly when changes in conditions alter patterns of selection. Climate change thus provides an opportunity for the study of the genetic basis of adaptation. Such studies include a variety of observational and experimental approaches, such as sampling across clines, artificial evolution experiments, and resurrection studies. These approaches can be combined with a number of techniques in genetics and genomics, including association and mapping analyses, genome scans, and transcription profiling. Recent research has revealed a number of candidate genes potentially involved in climate change adaptation and has also illustrated that genetic regulatory networks and epigenetic effects may be particularly relevant for evolution driven by climate change. Although genetic and genomic data are rapidly accumulating, we still have much to learn about the genetic architecture of climate change adaptation.}, + keywords = {epigenetics,evolutionary constraints,genetic response networks,global change,natural selection}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\L6ZEU4D8\\Franks und Hoffmann - 2012 - Genetics of Climate Change Adaptation.pdf} +} + +@article{fraserRangeExpansionInvasive2015, + title = {Range Expansion of an Invasive Species through a Heterogeneous Landscape \textendash{} the Case of {{American}} Mink in {{Scotland}}}, + author = {Fraser, Elaine J. and Lambin, Xavier and Travis, Justin M. J. and Harrington, Lauren A. and Palmer, Stephen C. F. and Bocedi, Greta and Macdonald, David W.}, + year = {2015}, + journal = {Diversity and Distributions}, + volume = {21}, + number = {8}, + pages = {888--900}, + issn = {1472-4642}, + doi = {10.1111/ddi.12303}, + abstract = {Aim The impact of invasive species is one of the main causes of biodiversity loss world-wide, and as a result, there is much interest in understanding the pattern and rate of expansion of species outside their native range. We aimed to characterize the range expansion of the American mink (Neovison vison) invading from multiple introduction points through a varied landscape bounded by coastline to better understand and manage its spread. Location Scotland, UK. Method We collated and used records of mink presence to calculate the historical range and rate of range expansion at successive time intervals. We used a presence-only model to predict habitat suitability and a newly developed individual-based modelling platform, RangeShifter, to simulate range expansion. Results Records showed that mink were distributed throughout Scotland, except in the far north. We found that the rate of spread varied both spatially and temporally and was related to landscape heterogeneity. Habitat suitable for mink in west Scotland is restricted to the coast. Main conclusions We concluded that temporal and spatial variation in range expansion is attributable to heterogeneity within the landscape and also demonstrated that the potential for long-distance dispersal does not necessarily facilitate range expansion when availability of suitable habitat occurs in narrow strips and/or is fragmented. We have highlighted methodological gaps in calculating rates of expansion in invasive species but have demonstrated alternative methods that successfully utilize presence-only data. Our study reaffirms that invasive species will colonize less favourable habitats and highlights the need to remain vigilant of their potential for expansion even when distribution appears to be static for a time.}, + langid = {english}, + keywords = {American mink,biological invasions,habitat availability,heterogeneous landscape,invasive species,multiple introduction points,range expansion}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ddi.12303}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\3GUP8LM2\\Fraser et al. - 2015 - Range expansion of an invasive species through a h.pdf} +} + +@article{friedenbergExperimentalEvolutionDispersal2003, + title = {Experimental Evolution of Dispersal in Spatiotemporally Variable Microcosms}, + author = {Friedenberg, Nicholas A.}, + year = {2003}, + journal = {Ecology Letters}, + volume = {6}, + number = {10}, + pages = {953--959}, + issn = {1461-0248}, + doi = {10.1046/j.1461-0248.2003.00524.x}, + abstract = {The world is an uncertain place. Individuals' fates vary from place to place and from time to time. Natural selection in unpredictable environments should favour individuals that hedge their bets by dispersing offspring. I confirm this basic prediction using Caenorhabditis elegans in experimental microcosms. My results agree with evolutionary models and correlations found previously between habitat stability and individual dispersal propensity in nature. However, I also find that environmental variation that triggers conditional dispersal behaviour may not impose selection on baseline dispersal rates. These findings imply that an increased rate of disturbance in natural systems has the potential to cause an evolutionary response in the life history of impacted organisms.}, + langid = {english}, + keywords = {bet hedging,Caenorhabditis elegans,fluctuating environments,geometric mean fitness,life-history evolution}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1461-0248.2003.00524.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\B6TKT5B8\\Friedenberg - 2003 - Experimental evolution of dispersal in spatiotempo.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\K3GENDHD\\j.1461-0248.2003.00524.html} +} + +@article{fronhoferPickyHitchhikersVector2013a, + title = {Picky Hitch-Hikers: Vector Choice Leads to Directed Dispersal and Fat-Tailed Kernels in a Passively Dispersing Mite}, + shorttitle = {Picky Hitch-Hikers}, + author = {Fronhofer, Emanuel A. and Sperr, Ellen B. and Kreis, Anna and Ayasse, Manfred and Poethke, Hans Joachim and Tschapka, Marco}, + year = {2013}, + journal = {Oikos}, + volume = {122}, + number = {8}, + pages = {1254--1264}, + issn = {1600-0706}, + doi = {10.1111/j.1600-0706.2013.00503.x}, + abstract = {Dispersal is a central life-history trait for most animals and plants: it allows to colonize new habitats, escape from competition or avoid inbreeding. Yet, not all species are mobile enough to perform sufficient dispersal. Such passive dispersers may use more mobile animals as dispersal vectors. If multiple potential vectors are available, an active choice can allow to optimize the dispersal process and to determine the distribution of dispersal distances, i.e. an optimal dispersal kernel. We explore dispersal and vector choice in the neotropical flower mite Spadiseius calyptrogynae using a dual approach which combines experiments with an individual-based simulation model. Spadiseius calyptrogynae is found in lowland rainforests in Costa Rica. It inhabits inflorescences of the understorey palm Calyptrogyne ghiesbreghtiana and is phoretic on a number of flower visitors including bats, beetles and stingless bees. We hypothesised that the mites should optimise their dispersal kernel by actively choosing a specific mix of potential phoretic vectors. In a simple olfactometer setup we showed that the flower mites do indeed discriminate between potential vectors. Subsequently we used an individual-based model to analyse the evolutionary forces responsible for the observed patterns of vector choice. The mites combine vectors exhibiting long-distance dispersal with those allowing for more localized dispersal. This results in a fat-tailed dispersal kernel that guarantees the occasional colonization of new host plant patches (long distance) while optimizing the exploitation of clumped resources (local dispersal). Additionally, kin competition results in a preference for small vectors that transport only few individuals at a time. At the same time, these vectors lead to directed dispersal towards suitable habitat, which increases the stability of this very specialized interaction. Our findings can be applied to other phoretic systems but also to vector-based seed dispersal, for example.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2013.00503.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\FW6TQ7UN\\Fronhofer et al. - 2013 - Picky hitch-hikers vector choice leads to directe.pdf} +} + +@article{fryxellMultipleMovementModes2008, + title = {Multiple Movement Modes by Large Herbivores at Multiple Spatiotemporal Scales}, + author = {Fryxell, John M. and Hazell, Megan and B{\"o}rger, Luca and Dalziel, Ben D. and Haydon, Daniel T. and Morales, Juan M. and McIntosh, Therese and Rosatte, Rick C.}, + year = {2008}, + month = dec, + journal = {Proceedings of the National Academy of Sciences}, + volume = {105}, + number = {49}, + pages = {19114--19119}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.0801737105}, + abstract = {Recent theory suggests that animals should switch facultatively among canonical movement modes as a complex function of internal state, landscape characteristics, motion capacity, and navigational capacity. We tested the generality of this paradigm for free-ranging elk (Cervus elaphus) over 5 orders of magnitude in time (minutes to years) and space (meters to 100 km). At the coarsest spatiotemporal scale, elk shifted from a dispersive to a home-ranging phase over the course of 1\textendash 3 years after introduction into a novel environment. At intermediate spatiotemporal scales, elk continued to alternate between movement modes. During the dispersive phase, elk alternated between encamped and exploratory modes, possibly linked to changes in motivational goals from foraging to social bonding. During the home-ranging phase, elk movements were characterized by a complex interplay between attraction to preferred habitat types and memory of previous movements across the home-range. At the finest temporal and spatial scale, elk used area-restricted search while browsing, interspersed with less sinuous paths when not browsing. Encountering a patch of high-quality food plants triggered the switch from one mode to the next, creating biphasic movement dynamics that were reinforced by local resource heterogeneity. These patterns suggest that multiphasic structure is fundamental to the movement patterns of elk at all temporal and spatial scales tested.}, + chapter = {Research Article}, + copyright = {\textcopyright{} 2008 by The National Academy of Sciences of the USA}, + langid = {english}, + pmid = {19060190}, + keywords = {elk,foraging,group formation,motivation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\NY2W7UKL\\Fryxell et al. - 2008 - Multiple movement modes by large herbivores at mul.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\XMU2FA36\\19114.html} +} + +@article{gallienPredictingPotentialDistributions2010, + title = {Predicting Potential Distributions of Invasive Species: Where to Go from Here?}, + shorttitle = {Predicting Potential Distributions of Invasive Species}, + author = {Gallien, Laure and M{\"u}nkem{\"u}ller, Tamara and Albert, C{\'e}cile H. and Boulangeat, Isabelle and Thuiller, Wilfried}, + year = {2010}, + journal = {Diversity and Distributions}, + volume = {16}, + number = {3}, + pages = {331--342}, + issn = {1472-4642}, + doi = {10.1111/j.1472-4642.2010.00652.x}, + abstract = {Aim There has been considerable recent interest in modelling the potential distributions of invasive species. However, research has developed in two opposite directions: the first, focusing on screening, utilizes phenomenological models; the second, focusing on predictions of invasion dynamics, utilizes mechanistic models. Here, we present hybrid modelling as an approach to bridge the gap and to integrate the advantages of both research directions. Location Global. Methods First, we briefly summarize the characteristics and limitations of both approaches (screening vs. understanding). Then, we review the recent developments of hybrid models, discuss their current problems and offer suggestions to improve them. Results Generally, hybrid models are able to combine the advantages of currently used phenomenological and mechanistic approaches. Main challenges in building hybrid models are the choices of the appropriate degree of detail and efficiency and the decision on how to connect the different sub-models. Given these challenges, we discuss the links between the phenomenological and the mechanistic model parameters, the underlying concepts of fundamental and realized niches and the problem of feedback loops between population dynamics and environmental factors. Main conclusions Once the above challenges have been addressed and the necessary framework has been developed, hybrid models will provide outstanding tools for overcoming past limitations and will provide the means to make reliable and robust predictions of the potential distribution of invasive species, their population dynamics and the potential outcomes of the overall invasion process.}, + langid = {english}, + keywords = {Biological invasions,habitat suitability model,hybrid model,invasion dynamics,mechanistic model,species distribution model}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2010.00652.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\JRSESJ9E\\Gallien et al. - 2010 - Predicting potential distributions of invasive spe.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UAA8SRQH\\j.1472-4642.2010.00652.html} +} + +@article{gardnerSimulatingDispersalReintroduced2004b, + title = {Simulating Dispersal of Reintroduced Species within Heterogeneous Landscapes}, + author = {Gardner, Robert H. and Gustafson, Eric J.}, + year = {2004}, + month = feb, + journal = {Ecological Modelling}, + volume = {171}, + number = {4}, + pages = {339--358}, + issn = {0304-3800}, + doi = {10.1016/j.ecolmodel.2003.08.008}, + abstract = {This paper describes the development and application of a spatially explicit, individual based model of animal dispersal (J-walk) to determine the relative effects of landscape heterogeneity, prey availability, predation risk, and the energy requirements and behavior of dispersing organisms on dispersal success. Significant unknowns exist for the simulation of complex movement behavior within heterogeneous landscapes. Therefore, initial simulations with J-walk examined the relative effect of landscape patterns and species-specific characteristics on dispersal success. Differences in landscape pattern were simulated by random generation of fractal maps with average available energy (i.e. prey) and predation risk expressed as a function of habitat type. Variation in species-specific patterns were then simulated by a series of scenarios that varied the response of dispersing individuals to habitat heterogeneity, including: habitat selection to maximize energy intake, habitat selection to minimize predation risk, or habitat selection contingent on energy reserves. Results showed that significant shifts in dispersal could be related to (1) the unique spatial arrangement of habitat within each map, (2) changes in relative prey abundance, and (3) variation in the relationship between energy availability and predation risk. Hypothetical management scenarios were used to identify critical data needed to assure the persistence of reintroduced populations of American martens (Martes americana).}, + langid = {english}, + keywords = {American marten,Dispersal model,Landscape heterogeneity,Movement behavior,Predation risk,Prediction uncertainty,Prey availability}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\D6I3HGZ2\\Gardner und Gustafson - 2004 - Simulating dispersal of reintroduced species withi.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\XSYTAJKC\\S0304380003003387.html} +} + +@article{gastonGeographicRangeLimits2009, + title = {Geographic Range Limits: Achieving Synthesis}, + shorttitle = {Geographic Range Limits}, + author = {Gaston, Kevin J}, + year = {2009}, + month = apr, + journal = {Proceedings of the Royal Society B: Biological Sciences}, + volume = {276}, + number = {1661}, + pages = {1395--1406}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2008.1480}, + abstract = {Understanding of the determinants of species' geographic range limits remains poorly integrated. In part, this is because of the diversity of perspectives on the issue, and because empirical studies have lagged substantially behind developments in theory. Here, I provide a broad overview, drawing together many of the disparate threads, considering, in turn, how influences on the terms of a simple single-population equation can determine range limits. There is theoretical and empirical evidence for systematic changes towards range limits under some circumstances in each of the demographic parameters. However, under other circumstances, no such changes may take place in particular parameters, or they may occur in a different direction, with limitation still occurring. This suggests that (i) little about range limitation can categorically be inferred from many empirical studies, which document change in only one demographic parameter, (ii) there is a need for studies that document variation in all of the parameters, and (iii) in agreement with theoretical evidence that range limits can be formed in the presence or absence of hard boundaries, environmental gradients or biotic interactions, there may be few general patterns as to the determinants of these limits, with most claimed generalities at least having many exceptions.}, + keywords = {births,deaths,emigration,immigration,population size,range limits}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2WA2DK9B\\Gaston - 2009 - Geographic range limits achieving synthesis.pdf} +} + +@article{gilmanFrameworkCommunityInteractions2010a, + title = {A Framework for Community Interactions under Climate Change}, + author = {Gilman, Sarah E. and Urban, Mark C. and Tewksbury, Joshua and Gilchrist, George W. and Holt, Robert D.}, + year = {2010}, + month = jun, + journal = {Trends in Ecology \& Evolution}, + volume = {25}, + number = {6}, + pages = {325--331}, + issn = {0169-5347}, + doi = {10.1016/j.tree.2010.03.002}, + abstract = {Predicting the impacts of climate change on species is one of the biggest challenges that ecologists face. Predictions routinely focus on the direct effects of climate change on individual species, yet interactions between species can strongly influence how climate change affects organisms at every scale by altering their individual fitness, geographic ranges and the structure and dynamics of their community. Failure to incorporate these interactions limits the ability to predict responses of species to climate change. We propose a framework based on ideas from global-change biology, community ecology, and invasion biology that uses community modules to assess how species interactions shape responses to climate change.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\M5WL4NHK\\Gilman et al. - 2010 - A framework for community interactions under clima.pdf} +} + +@article{gilroyMateFindingOverlookedCritical2012, + title = {Mate-{{Finding}} as an {{Overlooked Critical Determinant}} of {{Dispersal Variation}} in {{Sexually-Reproducing Animals}}}, + author = {Gilroy, James J. and Lockwood, Julie L.}, + year = {2012}, + month = may, + journal = {PLOS ONE}, + volume = {7}, + number = {5}, + pages = {e38091}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0038091}, + abstract = {Dispersal is a critically important process in ecology, but robust predictive models of animal dispersal remain elusive. We identify a potentially ubiquitous component of variation in animal dispersal that has been largely overlooked until now: the influence of mate encounters on settlement probability. We use an individual-based model to simulate dispersal in sexually-reproducing organisms that follow a simple set of movement rules based on conspecific encounters, within an environment lacking spatial habitat heterogeneity. We show that dispersal distances vary dramatically with fluctuations in population density in such a model, even in the absence of variation in dispersive traits between individuals. In a simple random-walk model with promiscuous mating, dispersal distributions become increasingly `fat-tailed' at low population densities due to the increasing scarcity of mates. Similar variation arises in models incorporating territoriality. In a model with polygynous mating, we show that patterns of sex-biased dispersal can even be reversed across a gradient of population density, despite underlying dispersal mechanisms remaining unchanged. We show that some widespread dispersal patterns found in nature (e.g. fat tailed distributions) can arise as a result of demographic variability in the absence of heterogeneity in dispersive traits across the population. This implies that models in which individual dispersal distances are considered to be fixed traits might be unrealistic, as dispersal distances vary widely under a single dispersal mechanism when settlement is influenced by mate encounters. Mechanistic models offer a promising means of advancing our understanding of dispersal in sexually-reproducing organisms.}, + langid = {english}, + keywords = {Behavior,Habitats,Population density,Population size,Probability density,Probability distribution,Random walk,Sex ratio}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\NQGCKTGQ\\Gilroy und Lockwood - 2012 - Mate-Finding as an Overlooked Critical Determinant.pdf} +} + +@article{greenmanImpactEnvironmentalFluctuations2005, + title = {The Impact of Environmental Fluctuations on Structured Discrete Time Population Models: {{Resonance}}, Synchrony and Threshold Behaviour}, + shorttitle = {The Impact of Environmental Fluctuations on Structured Discrete Time Population Models}, + author = {Greenman, J. V. and Benton, T. G.}, + year = {2005}, + month = dec, + journal = {Theoretical Population Biology}, + volume = {68}, + number = {4}, + pages = {217--235}, + issn = {0040-5809}, + doi = {10.1016/j.tpb.2005.06.007}, + abstract = {External forcing of a discrete time ecological system does not just add variation to existing dynamics but can change the dynamics. We study the mechanisms that can bring this about, focusing on the key concepts of excitation and suppression which emerge when analysing the power spectra of the system in linear approximation. Excitation, through resonance between the system dynamics and the external forcing, is the greater the closer the system is to the boundary of the stability region. This amplification means that the extinction of populations becomes possible sooner than expected and, conversely, invasion can be significantly delayed. Suppression and the consequent redistribution of power within the spectrum proves to be a function both of the connectivity of the network graph of the system and the way that external forcing is applied to the system. It is also established that colour in stochastic forcing can have a major impact, by enhancing resonance and by greater redistribution of power. This can mean a higher risk of extinction through larger fluctuations in population numbers and a higher degree of synchrony between populations. The implications of external forcing for stage-structured species, for populations in competition and for trophic web systems are studied using the tools and concepts developed in the paper.}, + langid = {english}, + keywords = {Coloured noise,Environmental noise,Population covariance,Power spectra,Resonance,Synchrony,Threshold behaviour}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Q9AAGDGF\\S0040580905000936.html} +} + +@article{greenwoodMatingSystemsPhilopatry1980, + title = {Mating Systems, Philopatry and Dispersal in Birds and Mammals}, + author = {Greenwood, Paul J.}, + year = {1980}, + month = nov, + journal = {Animal Behaviour}, + volume = {28}, + number = {4}, + pages = {1140--1162}, + issn = {0003-3472}, + doi = {10.1016/S0003-3472(80)80103-5}, + abstract = {Many species of birds and mammals are faithful to their natal and breeding site or group. In most of them one sex is more philopatric than the other. In birds it is usually females which disperse more than males; in mammals it is usually males which disperse more than females. Reproductive enhancement through increased access to mates or resources and the avoidance of inbreeding are important in promoting sex differences in dispersal. It is argued that the direction of the sex bias is a consequence of the type of mating system. Philopatry will favour the evolution of cooperative traits between members of the sedentary sex. Disruptive acts will be a feature of dispersers.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\59TUWI7L\\Greenwood - 1980 - Mating systems, philopatry and dispersal in birds .pdf} +} + +@book{grimmIndividualbasedModelingEcology2005, + title = {Individual-Based {{Modeling}} and {{Ecology}}}, + author = {Grimm, Volker and Railsback, Steven F.}, + year = {2005}, + publisher = {{Princeton University Press}}, + isbn = {978-0-691-09666-7}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ZPBZJJKE\\individual-based-modeling-and-ecology.html} +} + +@article{grosEvolutionSexbiasedDispersal2008, + title = {Evolution of Sex-Biased Dispersal : The Role of Sex-Specific Dispersal Costs, Demographic Stochasticity, and Inbreeding}, + shorttitle = {Evolution of Sex-Biased Dispersal}, + author = {Gros, Andreas and Hovestadt, Thomas and Poethke, Hans Joachim}, + year = {2008}, + abstract = {Abstract: Inbreeding avoidance and asymmetric competition over resources have both been identified as factors favoring the evolution of sex-biased dispersal. It has also been recognized that sex-specific costs of dispersal would select for sex-biased dispersal, but there is little quantitative information on this aspect. In this paper we explore (i) the quantitative relationship between cost-asymmetry and a bias in dispersal, (ii) the influence of demographic stochasticity on this effect, and (iii) how inbreeding and cost-asymmetry interact in their effect on sex-specific dispersal. We adjust an existing analytical model to account for sex-specific costs of dispersal. Based on numerical calculations we predict a severe bias in dispersal already for small differences in dispersal costs. We corroborate these predictions in individual-based simulations, but show that demographic stochasticity generally leads to more balanced dispersal. In combination with inbreeding, cost asymmetries will usually determine which of the two sexes becomes the more dispersive.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QJ4634CE\\Gros et al. - 2008 - Evolution of sex-biased dispersal the role of se.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\GNJFZXMY\\4031.html} +} + +@article{grosSexspecificSpatiotemporalVariability2009, + title = {Sex-Specific Spatio-Temporal Variability in Reproductive Success Promotes the Evolution of Sex-Biased Dispersal}, + author = {Gros, Andreas and Poethke, Hans Joachim and Hovestadt, Thomas}, + year = {2009}, + month = aug, + journal = {Theoretical Population Biology}, + volume = {76}, + number = {1}, + pages = {13--18}, + issn = {1096-0325}, + doi = {10.1016/j.tpb.2009.03.002}, + abstract = {Inbreeding depression, asymmetries in costs or benefits of dispersal, and the mating system have been identified as potential factors underlying the evolution of sex-biased dispersal. We use individual-based simulations to explore how the mating system and demographic stochasticity influence the evolution of sex-specific dispersal in a metapopulation with females competing over breeding sites, and males over mating opportunities. Comparison of simulation results for random mating with those for a harem system (locally, a single male sires all offspring) reveal that even extreme variance in local male reproductive success (extreme male competition) does not induce male-biased dispersal. The latter evolves if the between-patch variance in reproductive success is larger for males than females. This can emerge due to demographic stochasticity if the habitat patches are small. More generally, members of a group of individuals experiencing higher spatio-temporal variance in fitness expectations may evolve to disperse with greater probability than others.}, + langid = {english}, + pmid = {19303892}, + keywords = {Animals,Biological Evolution,Competitive Behavior,Computer Simulation,Demography,Female,Inbreeding,Male,Mammals,Models; Theoretical,Population Dynamics,Probability,Reproduction,Sex Characteristics,Sexual Behavior; Animal,Stochastic Processes}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\KIRQPU2J\\Gros et al. - 2009 - Sex-specific spatio-temporal variability in reprod.pdf} +} + +@article{guillaumeInbreedingLoadBet2009, + title = {Inbreeding {{Load}}, {{Bet Hedging}}, and the {{Evolution}} of {{Sex}}-{{Biased Dispersal}}.}, + author = {Guillaume, Fr{\'e}d{\'e}ric and Perrin, Nicolas}, + year = {2009}, + month = apr, + journal = {The American Naturalist}, + volume = {173}, + number = {4}, + pages = {536--541}, + publisher = {{The University of Chicago Press}}, + issn = {0003-0147}, + doi = {10.1086/597218}, + abstract = {Inbreeding load affects not only the average fecundity of philopatric individuals but also its variance. From bet-hedging theory, this should add further dispersal pressures to those stemming from the mere avoidance of inbreeding. Pressures on both sexes are identical under monogamy or promiscuity. Under polygyny, by contrast, the variance in reproductive output decreases with dispersal rate in females but increases in males, which should induce a female-biased dispersal. To test this prediction, we performed individual-based simulations. From our results, a female-biased dispersal indeed emerges as both polygyny and inbreeding load increase. We conclude that sex-biased dispersal may be selected for as a bet-hedging strategy.}, + keywords = {fecundity variance,inbreeding avoidance,kin competition,mating system,selection,simulation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\XCCVHWDS\\Guillaume und Perrin - 2009 - Inbreeding Load, Bet Hedging, and the Evolution of.pdf} +} + +@article{guillaumeNEMOEvolutionaryPopulation2006, + title = {{{NEMO}}: An Evolutionary and Population Genetics Programming Framework}, + shorttitle = {{{NEMO}}}, + author = {Guillaume, Fr{\'e}d{\'e}ric and Rougemont, Jacques}, + year = {2006}, + month = nov, + journal = {Bioinformatics (Oxford, England)}, + volume = {22}, + pages = {2556--7}, + doi = {10.1093/bioinformatics/btl415}, + abstract = {Unlabelled: Nemo is an individual-based, genetically explicit and stochastic population computer program for the simulation of population genetics and life-history trait evolution in a metapopulation context. It comes as both a C++ programming framework and an executable program file. Its object-oriented programming design gives it the flexibility and extensibility needed to implement a large variety of forward-time evolutionary models. It provides developers with abstract models allowing them to implement their own life-history traits and life-cycle events. Nemo offers a large panel of population models, from the Island model to lattice models with demographic or environmental stochasticity and a variety of already implemented traits (deleterious mutations, neutral markers and more), life-cycle events (mating, dispersal, aging, selection, etc.) and output operators for saving data and statistics. It runs on all major computer platforms including parallel computing environments. Availability: The source code, binaries and documentation are available under the GNU General Public License at http://nemo2.sourceforge.net.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\DFMHPVAE\\Guillaume und Rougemont - 2006 - NEMO an evolutionary and population genetics prog.pdf} +} + +@article{guisanPredictingSpeciesDistribution2005a, + title = {Predicting Species Distribution: Offering More than Simple Habitat Models}, + shorttitle = {Predicting Species Distribution}, + author = {Guisan, Antoine and Thuiller, Wilfried}, + year = {2005}, + journal = {Ecology Letters}, + volume = {8}, + number = {9}, + pages = {993--1009}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2005.00792.x}, + abstract = {In the last two decades, interest in species distribution models (SDMs) of plants and animals has grown dramatically. Recent advances in SDMs allow us to potentially forecast anthropogenic effects on patterns of biodiversity at different spatial scales. However, some limitations still preclude the use of SDMs in many theoretical and practical applications. Here, we provide an overview of recent advances in this field, discuss the ecological principles and assumptions underpinning SDMs, and highlight critical limitations and decisions inherent in the construction and evaluation of SDMs. Particular emphasis is given to the use of SDMs for the assessment of climate change impacts and conservation management issues. We suggest new avenues for incorporating species migration, population dynamics, biotic interactions and community ecology into SDMs at multiple spatial scales. Addressing all these issues requires a better integration of SDMs with ecological theory.}, + langid = {english}, + keywords = {Dispersal,ecological niche theory,future projections,habitat suitability maps,population dynamics,prediction errors,predictive biogeography,spatial scales,species distribution models}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2005.00792.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\TMINZAMA\\Guisan und Thuiller - 2005 - Predicting species distribution offering more tha.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\WHKHQ5FR\\j.1461-0248.2005.00792.html} +} + +@article{hallerSLiMForwardGenetic, + title = {{{SLiM}} 3: {{Forward Genetic Simulations Beyond}} the {{Wright}}\textendash{{Fisher Model}} | {{Molecular Biology}} and {{Evolution}} | {{Oxford Academic}}}, + author = {Haller, Benjamin C. and Messer, Phillip W.}, + journal = {Molecular Biology and Evolution}, + number = {36}, + pages = {632--637}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8CDTMTUW\\5229931.html} +} + +@article{hansenPerceptionClimateChange2012, + title = {Perception of Climate Change}, + author = {Hansen, James and Sato, Makiko and Ruedy, Reto}, + year = {2012}, + month = sep, + journal = {Proceedings of the National Academy of Sciences}, + volume = {109}, + number = {37}, + pages = {E2415-E2423}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.1205276109}, + abstract = {``Climate dice,'' describing the chance of unusually warm or cool seasons, have become more and more ``loaded'' in the past 30 y, coincident with rapid global warming. The distribution of seasonal mean temperature anomalies has shifted toward higher temperatures and the range of anomalies has increased. An important change is the emergence of a category of summertime extremely hot outliers, more than three standard deviations (3{$\sigma$}) warmer than the climatology of the 1951\textendash 1980 base period. This hot extreme, which covered much less than 1\% of Earth's surface during the base period, now typically covers about 10\% of the land area. It follows that we can state, with a high degree of confidence, that extreme anomalies such as those in Texas and Oklahoma in 2011 and Moscow in 2010 were a consequence of global warming because their likelihood in the absence of global warming was exceedingly small. We discuss practical implications of this substantial, growing, climate change.}, + chapter = {PNAS Plus}, + copyright = {\textcopyright{} . Freely available online through the PNAS open access option.}, + langid = {english}, + pmid = {22869707}, + keywords = {climate anomalies,climate impacts,heat waves}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6LR5JE3W\\Hansen et al. - 2012 - Perception of climate change.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\F6ZFUZWL\\E2415.html} +} + +@article{hanskiEcoevolutionaryDynamicsDispersal2011a, + title = {Eco-Evolutionary Dynamics of Dispersal in Spatially Heterogeneous Environments}, + author = {Hanski, Ilkka and Mononen, Tommi}, + year = {2011}, + month = oct, + journal = {Ecology Letters}, + volume = {14}, + number = {10}, + pages = {1025--1034}, + issn = {1461-023X}, + doi = {10.1111/j.1461-0248.2011.01671.x}, + abstract = {Evolutionary changes in natural populations are often so fast that the evolutionary dynamics may influence ecological population dynamics and vice versa. Here we construct an eco-evolutionary model for dispersal by combining a stochastic patch occupancy metapopulation model with a model for changes in the frequency of fast-dispersing individuals in local populations. We test the model using data on allelic variation in the gene phosphoglucose isomerase (Pgi), which is strongly associated with dispersal rate in the Glanville fritillary butterfly. Population-specific measures of immigration and extinction rates and the frequency of fast-dispersing individuals among the immigrants explained 40\% of spatial variation in Pgi allele frequency among 97 local populations. The model clarifies the roles of founder events and gene flow in dispersal evolution and resolves a controversy in the literature about the consequences of habitat loss and fragmentation on the evolution of dispersal.}, + pmcid = {PMC3187866}, + pmid = {21794053}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HTJE2888\\Hanski und Mononen - 2011 - Eco-evolutionary dynamics of dispersal in spatiall.pdf} +} + +@article{hanskiVariationMigrationPropensity2004, + title = {Variation in Migration Propensity among Individuals Maintained by Landscape Structure}, + author = {Hanski, Ilkka and Er{\"a}lahti, Claudia and Kankare, Maaria and Ovaskainen, Otso and Sir{\'e}n, Heli}, + year = {2004}, + journal = {Ecology Letters}, + volume = {7}, + number = {10}, + pages = {958--966}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2004.00654.x}, + abstract = {Metapopulation dynamics lead to predictable patterns of habitat occupancy, population density and trophic structure in relation to landscape features such as habitat patch size and isolation. Comparable patterns may occur in behavioural, physiological and life-history traits but remain little studied. In the Glanville fritillary butterfly, females in newly established populations were more mobile than females in old populations. Among females from new populations, mobility decreased with increasing connectivity (decreasing isolation), but in females from old populations mobility increased with connectivity. The [ATP]/[ADP] ratio of flight muscles following controlled activity showed the same pattern as mobility in relation to population age and connectivity, suggesting that physiological differences in flight metabolic performance contribute to the observed variation in mobility. We demonstrate with an evolutionary metapopulation model parameterised for the Glanville fritillary that increasing spatial variation in landscape structure increases variance in mobility among individuals in a metapopulation, supporting the general notion that complex landscape structure maintains life-history variation.}, + langid = {english}, + keywords = {Connectivity,flight metabolism,Glanville fritillary,landscape structure,life-history evolution,metapopulation dynamics,migration,population age}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2004.00654.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\57ITLBI4\\Hanski et al. - 2004 - Variation in migration propensity among individual.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\9DM6SNTT\\j.1461-0248.2004.00654.html} +} + +@article{hartigConnectingDynamicVegetation2012, + title = {Connecting Dynamic Vegetation Models to Data \textendash{} an Inverse Perspective}, + author = {Hartig, Florian and Dyke, James and Hickler, Thomas and Higgins, Steven I. and O'Hara, Robert B. and Scheiter, Simon and Huth, Andreas}, + year = {2012}, + journal = {Journal of Biogeography}, + volume = {39}, + number = {12}, + pages = {2240--2252}, + issn = {1365-2699}, + doi = {10.1111/j.1365-2699.2012.02745.x}, + abstract = {Dynamic vegetation models provide process-based explanations of the dynamics and the distribution of plant ecosystems. They offer significant advantages over static, correlative modelling approaches, particularly for ecosystems that are outside their equilibrium due to global change or climate change. A persistent problem, however, is their parameterization. Parameters and processes of dynamic vegetation models (DVMs) are traditionally determined independently of the model, while model outputs are compared to empirical data for validation and informal model comparison only. But field data for such independent estimates of parameters and processes are often difficult to obtain, and the desire to include better descriptions of processes such as biotic interactions, dispersal, phenotypic plasticity and evolution in future vegetation models aggravates limitations related to the current parameterization paradigm. In this paper, we discuss the use of Bayesian methods to bridge this gap. We explain how Bayesian methods allow direct estimates of parameters and processes, encoded in prior distributions, to be combined with inverse estimates, encoded in likelihood functions. The combination of direct and inverse estimation of parameters and processes allows a much wider range of vegetation data to be used simultaneously, including vegetation inventories, species traits, species distributions, remote sensing, eddy flux measurements and palaeorecords. The possible reduction of uncertainty regarding structure, parameters and predictions of DVMs may not only foster scientific progress, but will also increase the relevance of these models for policy advice.}, + langid = {english}, + keywords = {Bayesian statistics,calibration,data assimilation,forest models,inverse modelling,model selection,parameterization,plant functional types,predictive uncertainty,process-based models}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2012.02745.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\86DDHZRK\\Hartig et al. - 2012 - Connecting dynamic vegetation models to data – an .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\XJDT75SX\\j.1365-2699.2012.02745.html} +} + +@article{hartigStatisticalInferenceStochastic2011, + title = {Statistical Inference for Stochastic Simulation Models \textendash{} Theory and Application}, + author = {Hartig, Florian and Calabrese, Justin M. and Reineking, Bj{\"o}rn and Wiegand, Thorsten and Huth, Andreas}, + year = {2011}, + journal = {Ecology Letters}, + volume = {14}, + number = {8}, + pages = {816--827}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2011.01640.x}, + abstract = {Ecology Letters (2011) 14: 816\textendash 827 Abstract Statistical models are the traditional choice to test scientific theories when observations, processes or boundary conditions are subject to stochasticity. Many important systems in ecology and biology, however, are difficult to capture with statistical models. Stochastic simulation models offer an alternative, but they were hitherto associated with a major disadvantage: their likelihood functions can usually not be calculated explicitly, and thus it is difficult to couple them to well-established statistical theory such as maximum likelihood and Bayesian statistics. A number of new methods, among them Approximate Bayesian Computing and Pattern-Oriented Modelling, bypass this limitation. These methods share three main principles: aggregation of simulated and observed data via summary statistics, likelihood approximation based on the summary statistics, and efficient sampling. We discuss principles as well as advantages and caveats of these methods, and demonstrate their potential for integrating stochastic simulation models into a unified framework for statistical modelling.}, + langid = {english}, + keywords = {Bayesian statistics,indirect inference,intractable likelihood,inverse modelling,likelihood approximation,likelihood-free inference,maximum likelihood,model selection,parameter estimation,stochastic simulation}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2011.01640.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\W3D7U7DD\\Hartig et al. - 2011 - Statistical inference for stochastic simulation mo.pdf} +} + +@article{hastingsSpatialSpreadInvasions2005, + title = {The Spatial Spread of Invasions: New Developments in Theory and Evidence}, + shorttitle = {The Spatial Spread of Invasions}, + author = {Hastings, Alan and Cuddington, Kim and Davies, Kendi F. and Dugaw, Christopher J. and Elmendorf, Sarah and Freestone, Amy and Harrison, Susan and Holland, Matthew and Lambrinos, John and Malvadkar, Urmila and Melbourne, Brett A. and Moore, Kara and Taylor, Caz and Thomson, Diane}, + year = {2005}, + journal = {Ecology Letters}, + volume = {8}, + number = {1}, + pages = {91--101}, + issn = {1461-0248}, + doi = {10.1111/j.1461-0248.2004.00687.x}, + abstract = {We review and synthesize recent developments in the study of the spread of invasive species, emphasizing both empirical and theoretical approaches. Recent theoretical work has shown that invasive species spread is a much more complex process than the classical models suggested, as long range dispersal events can have a large influence on the rate of range expansion through time. Empirical work goes even further, emphasizing the role of spatial heterogeneity, temporal variability, other species, and evolution. As in some of the classic work on spread, the study of range expansion of invasive species provides unique opportunities to use differences between theory and data to determine the important underlying processes that control spread rates.}, + langid = {english}, + keywords = {Diffusion,dispersal,integro-difference equations,invasions,reaction-diffusion,spatial spread}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2004.00687.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Z59DZSQD\\Hastings et al. - 2005 - The spatial spread of invasions new developments .pdf} +} + +@article{haughlandExplorationCorrelatesSettlement2004, + title = {Exploration Correlates with Settlement: Red Squirrel Dispersal in Contrasting Habitats}, + shorttitle = {Exploration Correlates with Settlement}, + author = {Haughland, Diane L. and Larsen, Karl W.}, + year = {2004}, + journal = {Journal of Animal Ecology}, + volume = {73}, + number = {6}, + pages = {1024--1034}, + issn = {1365-2656}, + doi = {10.1111/j.0021-8790.2004.00884.x}, + abstract = {1 Dispersers in heterogeneous habitat theoretically should target the habitat(s) where reproduction and survival (i.e. fitness) will be highest. However, the cues that dispersing animals respond to are not well understood: differences in habitat quality ultimately may be important, but whether animals respond to these differences may be influenced by their own familiarity with different habitats. 2 To determine if dispersers reacted to differences in habitat, we documented the exploratory movements, dispersal, and settlement patterns of juvenile North American red squirrels (Tamiasciurus hudsonicus) originating in adjacent patches of different habitats. 3 Dispersers originating in mature, closed-canopy forest (linked to higher female reproductive success and smaller territories) did not explore contrasting open forest with lower tree densities, and the magnitude of the dispersers' explorations was relatively similar. In contrast, dispersers from the open forest habitat made explorations that carried them into contrasting, mature forest habitat, and their explorations were more variable across individuals. 4 When settlement occurred, it was strongly philopatric in all groups of dispersers, although the distances and directions favoured during the exploratory phase of dispersal remained strong predictors of where settlement occurred. Overall, processes favouring philopatry (i.e. maternal influences, competitive advantages, etc.) appeared to dominate the dispersal of our study animals, even those that were exposed to higher quality habitat during their explorations. 5 Secondarily, annual stochasticity (or some correlate) affected the scale of exploration and timing of settlement more than the relative quality of habitat in which dispersers were born. 6 Studies such as this that seek to understand the relative importance of individual experience, habitat familiarity, and habitat quality are important to ultimately understanding how individual animals and populations react to habitat heterogeneity.}, + langid = {english}, + keywords = {habitat quality,habitat selection,juvenile experience,movement,natal dispersal,North American red squirrel,seasonal stochasticity.,Tamiasciurus hudsonicus}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.0021-8790.2004.00884.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RWPMJBW5\\Haughland und Larsen - 2004 - Exploration correlates with settlement red squirr.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\3R8H9TSQ\\j.0021-8790.2004.00884.html} +} + +@article{hauserDispersalClobertDanchin2001, + title = {Dispersal. {{J}}. {{Clobert}}, {{E}}. {{Danchin}}, {{A}}. {{A}}. {{Dhondt}} and {{J}}. {{D}}. {{Nichols}} (Eds). {{Oxford University Press}}, {{New York}}. 2001. Pp. 452. {{Price}} \textsterling 24.95, Paperback. {{ISBN}}: 0-19-850659-7.}, + shorttitle = {Dispersal. {{J}}. {{Clobert}}, {{E}}. {{Danchin}}, {{A}}. {{A}}. {{Dhondt}} and {{J}}. {{D}}. {{Nichols}} (Eds). {{Oxford University Press}}, {{New York}}. 2001. Pp. 452. {{Price}} \textsterling 24.95, Paperback. {{ISBN}}}, + author = {Hauser, Lorenz}, + year = {2001}, + journal = {Heredity}, + volume = {87}, + number = {4}, + pages = {508--508}, + issn = {1365-2540}, + doi = {10.1046/j.1365-2540.2001.0963a.x}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1365-2540.2001.0963a.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VT58TDAZ\\Hauser - 2001 - Dispersal. J. Clobert, E. Danchin, A. A. Dhondt an.pdf} +} + +@article{hawkesLinkingMovementBehaviour2009, + title = {Linking Movement Behaviour, Dispersal and Population Processes: Is Individual Variation a Key?}, + shorttitle = {Linking Movement Behaviour, Dispersal and Population Processes}, + author = {Hawkes, Colin}, + year = {2009}, + journal = {Journal of Animal Ecology}, + volume = {78}, + number = {5}, + pages = {894--906}, + issn = {1365-2656}, + doi = {10.1111/j.1365-2656.2009.01534.x}, + abstract = {1 Movement behaviour has become increasingly important in dispersal ecology and dispersal is central to the development of spatially explicit population ecology. The ways in which the elements have been brought together are reviewed with particular emphasis on dispersal distance distributions and the value of mechanistic models. 2 There is a continuous range of movement behaviours and in some species, dispersal is a clearly delineated event but not in others. The biological complexities restrict conclusions to high-level generalizations but there may be principles that are common to dispersal and other movements. 3 Random walk and diffusion models when appropriately elaborated can provide an understanding of dispersal distance relationships on spatial and temporal scales relevant to dispersal. Leptokurtosis in the relationships may be the result of a combination of factors including population heterogeneity, correlation, landscape features, time integration and density dependence. The inclusion in diffusion models of individual variation appears to be a useful elaboration. The limitations of the negative exponential and other phenomenological models are discussed. 4 The dynamics of metapopulation models are sensitive to what appears to be small differences in the assumptions about dispersal. In order to represent dispersal realistically in population models, it is suggested that phenomenological models should be replaced by those based on movement behaviour incorporating individual variation. 5 The conclusions are presented as a set of candidate principles for evaluation. The main features of the principles are that uncorrelated or correlated random walk, not linear movement, is expected where the directions of habitat patches are unpredictable and more complex behaviour when organisms have the ability to orientate or navigate. Individuals within populations vary in their movement behaviour and dispersal; part of this variation is a product of random elements in movement behaviour and some of it is heritable. Local and metapopulation dynamics are influenced by population heterogeneity in dispersal characteristics and heritable changes in dispersal propensity occur on time-scales short enough to impact population dynamics.}, + langid = {english}, + keywords = {diffusion equations,dispersal distance distributions,metapopulations,negative exponential,population heterogeneity}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2656.2009.01534.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Y9F3RVCJ\\Hawkes - 2009 - Linking movement behaviour, dispersal and populati.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\A2375F9G\\j.1365-2656.2009.01534.html} +} + +@article{heikkinenMethodsUncertaintiesBioclimatic2006, + title = {Methods and Uncertainties in Bioclimatic Envelope Modelling under Climate Change}, + author = {Heikkinen, Risto K. and Luoto, Miska and Ara{\'u}jo, Miguel B. and Virkkala, Raimo and Thuiller, Wilfried and Sykes, Martin T.}, + year = {2006}, + month = dec, + journal = {Progress in Physical Geography: Earth and Environment}, + volume = {30}, + number = {6}, + pages = {751--777}, + publisher = {{SAGE Publications Ltd}}, + issn = {0309-1333}, + doi = {10.1177/0309133306071957}, + abstract = {Potential impacts of projected climate change on biodiversity are often assessed using single-species bioclimatic `envelope'models. Such models are a special case of species distribution models in which the current geographical distribution of species is related to climatic variables so to enable projections of distributions under future climate change scenarios. This work reviews a number of critical methodological issues that may lead to uncertainty in predictions from bioclimatic modelling. Particular attention is paid to recent developments of bioclimatic modelling that address some of these issues as well as to the topics where more progress needs to be made. Developing and applying bioclimatic models in a informative way requires good understanding of a wide range of methodologies, including the choice of modelling technique, model validation, collinearity, autocorrelation, biased sampling of explanatory variables, scaling and impacts of non-climatic factors. A key challenge for future research is integrating factors such as land cover, direct CO2 effects, biotic interactions and dispersal mechanisms into species-climate models. We conclude that, although bioclimatic envelope models have a number of important advantages, they need to be applied only when users of models have a thorough understanding of their limitations and uncertainties.}, + langid = {english}, + keywords = {bioclimatic model,climate change,land cover,model performance,modelling methods,niche properties,scale,species distribution model,species geography,uncertainty,validation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\5IV85WML\\Heikkinen et al. - 2006 - Methods and uncertainties in bioclimatic envelope .pdf} +} + +@article{heinoEvolutionMigrationRate2001, + title = {Evolution of Migration Rate in a Spatially Realistic Metapopulation Model}, + author = {Heino, M. and Hanski, I.}, + year = {2001}, + month = may, + journal = {The American Naturalist}, + volume = {157}, + number = {5}, + pages = {495--511}, + issn = {1537-5323}, + doi = {10.1086/319927}, + abstract = {We use an individual-based, spatially realistic metapopulation model to study the evolution of migration rate. We first explore the consequences of habitat change in hypothetical patch networks on a regular lattice. If the primary consequence of habitat change is an increase in local extinction risk as a result of decreased local population sizes, migration rate increases. A nonmonotonic response, with migration rate decreasing at high extinction rate, was obtained only by assuming very frequent catastrophes. If the quality of the matrix habitat deteriorates, leading to increased mortality during migration, the evolutionary response is more complex. As long as habitat patch occupancy does not decrease markedly with increased migration mortality, reduced migration rate evolves. However, once mortality becomes so high that empty patches remain uncolonized for a long time, evolution tends to increase migration rate, which may lead to an "evolutionary rescue" in a fragmented landscape. Kin competition has a quantitative effect on the evolution of migration rate in our model, but these patterns in the evolution of migration rate appear to be primarily caused by spatiotemporal variation in fitness and mortality during migration. We apply the model to real habitat patch networks occupied by two checkerspot butterfly (Melitaea) species, for which sufficient data are available to estimate rigorously most of the model parameters. The model-predicted migration rate is not significantly different from the empirically observed one. Regional variation in patch areas and connectivities leads to regional variation in the optimal migration rate, predictions that can be tested empirically.}, + langid = {english}, + pmid = {18707258}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\MMH6N8F5\\Heino und Hanski - 2001 - Evolution of migration rate in a spatially realist.pdf} +} + +@article{heinoExtinctionRiskColoured2000, + title = {Extinction Risk under Coloured Environmental Noise}, + author = {Heino, Mikko and Ripa, J{\"o}rgen and Kaitala, Veijo}, + year = {2000}, + journal = {Ecography}, + volume = {23}, + number = {2}, + pages = {177--184}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2000.tb00273.x}, + abstract = {Positively autocorrelated red environmental noise is characterized by a strong dependence of expected sample variance on sample length. This dependence has to be taken into account when assessing extinction risk under red and white uncorrelated environmental noise. To facilitate a comparison between red and white noise, their expected variances can be scaled to be equal, but only at a chosen time scale. We show with a simple one-dimensional population dynamics model that the different but equally reasonable choices of the time scale yield qualitatively different results on the dependence of extinction risk on the colour of environmental noise: extinction risk might increase as well as decrease when the temporal correlation of noise increases.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2000.tb00273.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\4E9UG5N7\\Heino et al. - 2000 - Extinction risk under coloured environmental noise.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\6YEG4YTK\\j.1600-0587.2000.tb00273.html} +} + +@article{heinoExtinctionRiskColoured2000a, + title = {Extinction Risk under Coloured Environmental Noise}, + author = {Heino, Mikko and Ripa, J{\"o}rgen and Kaitala, Veijo}, + year = {2000}, + journal = {Ecography}, + volume = {23}, + number = {2}, + pages = {177--184}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2000.tb00273.x}, + abstract = {Positively autocorrelated red environmental noise is characterized by a strong dependence of expected sample variance on sample length. This dependence has to be taken into account when assessing extinction risk under red and white uncorrelated environmental noise. To facilitate a comparison between red and white noise, their expected variances can be scaled to be equal, but only at a chosen time scale. We show with a simple one-dimensional population dynamics model that the different but equally reasonable choices of the time scale yield qualitatively different results on the dependence of extinction risk on the colour of environmental noise: extinction risk might increase as well as decrease when the temporal correlation of noise increases.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2000.tb00273.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RXXNNDM2\\Heino et al. - 2000 - Extinction risk under coloured environmental noise.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\SLQHME3R\\j.1600-0587.2000.tb00273.html} +} + +@article{heinzAdaptivePatchSearching2006, + title = {Adaptive {{Patch Searching Strategies}} in {{Fragmented Landscapes}}}, + author = {Heinz, S. K. and Strand, E.}, + year = {2006}, + journal = {Evolutionary Ecology}, + number = {20}, + pages = {113--130} +} + +@article{hellmannInfluenceSpeciesInteractions2012, + title = {The Influence of Species Interactions on Geographic Range Change under Climate Change}, + author = {Hellmann, Jessica J. and Prior, Kirsten M. and Pelini, Shannon L.}, + year = {2012}, + month = feb, + journal = {Annals of the New York Academy of Sciences}, + volume = {1249}, + pages = {18--28}, + issn = {1749-6632}, + doi = {10.1111/j.1749-6632.2011.06410.x}, + abstract = {The fossil record tells us that many species shifted their geographic distributions during historic climate changes, but this record does not portray the complete picture of future range change in response to climate change. In particular, it does not provide information on how species interactions will affect range shifts. Therefore, we also need modern research to generate understanding of range change. This paper focuses on the role that species interactions play in promoting or preventing geographic ranges shifts under current and future climate change, and we illustrate key points using empirical case studies from an integrated study system. Case studies can have limited generalizability, but they are critical to defining possible outcomes under climate change. Our case studies emphasize host limitation that could reduce range shifts and enemy release that could facilitate range expansion. We also need improvements in modeling that explicitly consider species interactions, and this modeling can be informed by empirical research. Finally, we discuss how species interactions have implications for range management by people.}, + langid = {english}, + pmid = {22329888}, + keywords = {Animals,Climate Change,Conservation of Natural Resources,Ecosystem,Fossils,Geography,Population Dynamics,Species Specificity} +} + +@article{henryEcoevolutionaryDynamicsRange2012, + title = {Eco-Evolutionary Dynamics of Range Shifts: {{Elastic}} Margins and Critical Thresholds}, + shorttitle = {Eco-Evolutionary Dynamics of Range Shifts}, + author = {Henry, Roslyn and Bocedi, Greta and Travis, Justin}, + year = {2012}, + month = dec, + journal = {Journal of theoretical biology}, + volume = {321}, + doi = {10.1016/j.jtbi.2012.12.004} +} + +@article{herefordQuantitativeSurveyLocal2009, + title = {A Quantitative Survey of Local Adaptation and Fitness Trade-Offs}, + author = {Hereford, Joe}, + year = {2009}, + month = may, + journal = {The American Naturalist}, + volume = {173}, + number = {5}, + pages = {579--588}, + issn = {1537-5323}, + doi = {10.1086/597611}, + abstract = {The long history of reciprocal transplant studies testing the hypothesis of local adaptation has shown that populations are often adapted to their local environments. Yet many studies have not demonstrated local adaptation, suggesting that sometimes native populations are no better adapted than are genotypes from foreign environments. Local adaptation may also lead to trade-offs, in which adaptation to one environment comes at a cost of adaptation to another environment. I conducted a survey of published studies of local adaptation to quantify its frequency and magnitude and the costs associated with local adaptation. I also quantified the relationship between local adaptation and environmental differences and the relationship between local adaptation and phenotypic divergence. The overall frequency of local adaptation was 0.71, and the magnitude of the native population advantage in relative fitness was 45\%. Divergence between home site environments was positively associated with the magnitude of local adaptation, but phenotypic divergence was not. I found a small negative correlation between a population's relative fitness in its native environment and its fitness in a foreign environment, indicating weak trade-offs associated with local adaptation. These results suggest that populations are often locally adapted but stochastic processes such as genetic drift may limit the efficacy of divergent selection.}, + langid = {english}, + pmid = {19272016}, + keywords = {Adaptation; Biological,Environment,Phenotype} +} + +@article{higginsNicheBiologySpecies2012, + title = {A Niche for Biology in Species Distribution Models}, + author = {Higgins, Steven I. and O'Hara, Robert B. and R{\"o}mermann, Christine}, + year = {2012}, + journal = {Journal of Biogeography}, + volume = {39}, + number = {12}, + pages = {2091--2095}, + issn = {1365-2699}, + doi = {10.1111/jbi.12029}, + abstract = {Why species are found where they are is a central question in biogeography. The most widely used tool for understanding the controls on distribution is species distribution modelling. Species distribution modelling is now a well-established method in both the theoretical and applied ecological literature. In this special issue we examine the current state of the art in species distribution modelling and explore avenues for including more biological processes in such models. In particular we focus on physiological, demographic, dispersal, competitive and ecological-modulation processes. This overview highlights opportunities for new species distribution model concepts and developments, as well as a statistical agenda for implementing such models.}, + langid = {english}, + keywords = {Biodiversity,correlative models,model fitting,niche,process-based models,species distributions}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/jbi.12029}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\3Q5L563J\\Higgins et al. - 2012 - A niche for biology in species distribution models.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\K3SJU7UM\\jbi.html} +} + +@article{hobanComputerSimulationsTools2012, + title = {Computer Simulations: Tools for Population and Evolutionary Genetics}, + shorttitle = {Computer Simulations}, + author = {Hoban, Sean and Bertorelle, Giorgio and Gaggiotti, Oscar E.}, + year = {2012}, + month = jan, + journal = {Nature Reviews. Genetics}, + volume = {13}, + number = {2}, + pages = {110--122}, + issn = {1471-0064}, + doi = {10.1038/nrg3130}, + abstract = {Computer simulations are excellent tools for understanding the evolutionary and genetic consequences of complex processes whose interactions cannot be analytically predicted. Simulations have traditionally been used in population genetics by a fairly small community with programming expertise, but the recent availability of dozens of sophisticated, customizable software packages for simulation now makes simulation an accessible option for researchers in many fields. The in silico genetic data produced by simulations, along with greater availability of population-genomics data, are transforming genetic epidemiology, anthropology, evolutionary and population genetics and conservation. In this Review of the state-of-the-art of simulation software, we identify applications of simulations, evaluate simulator capabilities, provide a guide for their use and summarize future directions.}, + langid = {english}, + pmid = {22230817}, + keywords = {Animals,Computer Simulation,Evolution; Molecular,Genetics; Population,Humans,Models; Genetic,Plants,Research Design,Software}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8WYHR6UG\\Hoban et al. - 2012 - Computer simulations tools for population and evo.pdf} +} + +@article{hobbsEstimatesHabitatCarrying1985, + title = {Estimates of Habitat Carrying Capacity Incorporating Explicit Nutritional Constraints}, + author = {Hobbs, N.}, + year = {1985}, + doi = {10.2307/3801716}, + abstract = {Presentation d'un algorithme pour estimer la densite supportable d'herbivores consommant des ressources alimentaires a des degres divers de qualite nutritive. Influence des brulis. On prend pour exemple Odocoileus hemionus et Ovis canadensis} +} + +@article{hodgsonClimateChangeConnectivity2009a, + title = {Climate Change, Connectivity and Conservation Decision Making: Back to Basics}, + shorttitle = {Climate Change, Connectivity and Conservation Decision Making}, + author = {Hodgson, Jenny A. and Thomas, Chris D. and Wintle, Brendan A. and Moilanen, Atte}, + year = {2009}, + journal = {Journal of Applied Ecology}, + volume = {46}, + number = {5}, + pages = {964--969}, + issn = {1365-2664}, + doi = {10.1111/j.1365-2664.2009.01695.x}, + abstract = {1. The challenge of climate change forces us to re-examine the assumptions underlying conservation planning. 2. Increasing `connectivity' has emerged as the most favoured option for conservation in the face of climate change. 3. We argue that the importance of connectivity is being overemphasized: quantifying the benefits of connectivity per se is plagued with uncertainty, and connectivity can be co-incidentally improved by targeting more concrete metrics: habitat area and habitat quality. 4. Synthesis and applications. Before investing in connectivity projects, conservation practitioners should analyse the benefits expected to arise from increasing connectivity and compare them with alternative investments, to ensure as much biodiversity conservation and resilience to climate change as possible within their budget. Strategies that we expect to remain robust in the face of climate change include maintaining and increasing the area of high quality habitats, prioritizing areas that have high environmental heterogeneity and controlling other anthropogenic threatening processes.}, + langid = {english}, + keywords = {adaptation,biodiversity,conservation prioritization,habitat quality,landscape planning,spatial ecology,species–area relationship,uncertainty}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2664.2009.01695.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6E8TD9JR\\Hodgson et al. - 2009 - Climate change, connectivity and conservation deci.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\4PV2BC2M\\j.1365-2664.2009.01695.html} +} + +@article{hodgsonHabitatAreaQuality2011a, + title = {Habitat Area, Quality and Connectivity: Striking the Balance for Efficient Conservation}, + shorttitle = {Habitat Area, Quality and Connectivity}, + author = {Hodgson, Jenny A. and Moilanen, Atte and Wintle, Brendan A. and Thomas, Chris D.}, + year = {2011}, + journal = {Journal of Applied Ecology}, + volume = {48}, + number = {1}, + pages = {148--152}, + issn = {1365-2664}, + doi = {10.1111/j.1365-2664.2010.01919.x}, + abstract = {1. Population viability can depend on habitat area, habitat quality, the spatial arrangement of habitats (aggregations and connections) and the properties of the intervening non-breeding (matrix) land. Hodgson et al. [Journal of Applied Ecology46 (2009) 964] and Doerr, Barrett \& Doerr (Journal of Applied Ecology, 2011) disagree on the relative importance of these landscape attributes in enabling species to persist and change their distributions in response to climate change. 2. A brief review of published evidence suggests that variations in habitat area and quality have bigger effects than variations in spatial arrangement of habitats or properties of the intervening land. Even if structural features in the matrix have a measurable effect on dispersal rates, this does not necessarily lead to significant increases in population viability. 3. Large and high-quality habitats provide source populations and locations for colonisation, so they are the main determinants of the capacity of species to shift their distributions in response to climate change because populations must be established successively in each new region. 4. Synthesis and applications. Retaining as much high quality natural and semi-natural habitat as possible should remain the key focus for conservation, especially during a period of climate change.}, + langid = {english}, + keywords = {aggregation,climate change,conservation planning,corridor,landscape,matrix,uncertainty}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2664.2010.01919.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2HKI9D57\\Hodgson et al. - 2011 - Habitat area, quality and connectivity striking t.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\RH6SCBLK\\j.1365-2664.2010.01919.html} +} + +@article{hodgsonSpeedRangeShifts2012, + title = {The {{Speed}} of {{Range Shifts}} in {{Fragmented Landscapes}}}, + author = {Hodgson, Jenny A. and Thomas, Chris D. and Dytham, Calvin and Travis, Justin M. J. and Cornell, Stephen J.}, + year = {2012}, + month = oct, + journal = {PLOS ONE}, + volume = {7}, + number = {10}, + pages = {e47141}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0047141}, + abstract = {Species may be driven extinct by climate change, unless their populations are able to shift fast enough to track regions of suitable climate. Shifting will be faster as the proportion of suitable habitat in the landscape increases. However, it is not known how the spatial arrangement of habitat will affect the speed of range advance, especially when habitat is scarce, as is the case for many specialist species. We develop methods for calculating the speed of advance that are appropriate for highly fragmented, stochastic systems. We reveal that spatial aggregation of habitat tends to reduce the speed of advance throughout a wide range of species parameters: different dispersal distances and dispersal kernel shapes, and high and low extinction probabilities. In contrast, aggregation increases the steady-state proportion of habitat that is occupied (without climate change). Nonetheless, we find that it is possible to achieve both rapid advance and relatively high patch occupancy when the habitat has a ``channeled'' pattern, resembling corridors or chains of stepping stones. We adapt techniques from electrical circuit theory to predict the rate of advance efficiently for complex, realistic landscape patterns, whereas the rate cannot be predicted by any simple statistic of aggregation or fragmentation. Conservationists are already advocating corridors and stepping stones as important conservation tools under climate change, but they are vaguely defined and have so far lacked a convincing basis in fundamental population biology. Our work shows how to discriminate properties of a landscape's spatial pattern that affect the speed of colonization (including, but not limited to, patterns like corridors and chains of stepping stones), and properties that affect a species' probability of persistence once established. We can therefore point the way to better land use planning approaches, which will provide functional habitat linkages and also maintain local population viability.}, + langid = {english}, + keywords = {Climate change,Conservation science,Electric conductivity,Extinction risk,Fractals,Habitats,Species colonization,Species extinction}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\L758T9YL\\Hodgson et al. - 2012 - The Speed of Range Shifts in Fragmented Landscapes.pdf} +} + +@article{hodgsonSpeedRangeShifts2012a, + title = {The {{Speed}} of {{Range Shifts}} in {{Fragmented Landscapes}}}, + author = {Hodgson, Jenny A. and Thomas, Chris D. and Dytham, Calvin and Travis, Justin M. J. and Cornell, Stephen J.}, + year = {2012}, + month = oct, + journal = {PLOS ONE}, + volume = {7}, + number = {10}, + pages = {e47141}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0047141}, + abstract = {Species may be driven extinct by climate change, unless their populations are able to shift fast enough to track regions of suitable climate. Shifting will be faster as the proportion of suitable habitat in the landscape increases. However, it is not known how the spatial arrangement of habitat will affect the speed of range advance, especially when habitat is scarce, as is the case for many specialist species. We develop methods for calculating the speed of advance that are appropriate for highly fragmented, stochastic systems. We reveal that spatial aggregation of habitat tends to reduce the speed of advance throughout a wide range of species parameters: different dispersal distances and dispersal kernel shapes, and high and low extinction probabilities. In contrast, aggregation increases the steady-state proportion of habitat that is occupied (without climate change). Nonetheless, we find that it is possible to achieve both rapid advance and relatively high patch occupancy when the habitat has a ``channeled'' pattern, resembling corridors or chains of stepping stones. We adapt techniques from electrical circuit theory to predict the rate of advance efficiently for complex, realistic landscape patterns, whereas the rate cannot be predicted by any simple statistic of aggregation or fragmentation. Conservationists are already advocating corridors and stepping stones as important conservation tools under climate change, but they are vaguely defined and have so far lacked a convincing basis in fundamental population biology. Our work shows how to discriminate properties of a landscape's spatial pattern that affect the speed of colonization (including, but not limited to, patterns like corridors and chains of stepping stones), and properties that affect a species' probability of persistence once established. We can therefore point the way to better land use planning approaches, which will provide functional habitat linkages and also maintain local population viability.}, + langid = {english}, + keywords = {Climate change,Conservation science,Electric conductivity,Extinction risk,Fractals,Habitats,Species colonization,Species extinction}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\I88PSM6F\\Hodgson et al. - 2012 - The Speed of Range Shifts in Fragmented Landscapes.pdf} +} + +@article{hoegh-guldbergAssistedColonizationRapid2008, + title = {Assisted {{Colonization}} and {{Rapid Climate Change}}}, + author = {{Hoegh-Guldberg}, O. and Hughes, L. and McIntyre, S. and Lindenmayer, D. B. and Parmesan, C. and Possingham, H. P. and Thomas, C. D.}, + year = {2008}, + month = jul, + journal = {Science}, + volume = {321}, + number = {5887}, + pages = {345--346}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.1157897}, + abstract = {Moving species outside their historic ranges may mitigate loss of biodiversity in the face of global climate change. Moving species outside their historic ranges may mitigate loss of biodiversity in the face of global climate change.}, + chapter = {Policy Forum}, + copyright = {\textcopyright{} 2008 American Association for the Advancement of Science}, + langid = {english}, + pmid = {18635780}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Q9T3HJJW\\Hoegh-Guldberg et al. - 2008 - Assisted Colonization and Rapid Climate Change.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\N4MI9DZH\\345.html} +} + +@article{hoffmannClimateChangeEvolutionary2011, + title = {Climate Change and Evolutionary Adaptation}, + author = {Hoffmann, Ary A. and Sgr{\`o}, Carla M.}, + year = {2011}, + month = feb, + journal = {Nature}, + volume = {470}, + number = {7335}, + pages = {479--485}, + publisher = {{Nature Publishing Group}}, + issn = {1476-4687}, + doi = {10.1038/nature09670}, + abstract = {Natural populations are responding to global climate change by shifting their geographical distribution and the timing of their growth and reproduction, but for many species, such responses are likely to be inadequate to counter the speed and magnitude of climate change. Can evolutionary change help their cause? Ary Hoffmann and Carla Sgr\`o review the evidence for evolutionary adaptation in response to recent climate change and consider the implications for population and ecosystem management.}, + copyright = {2011 Nature Publishing Group, a division of Macmillan Publishers Limited. All Rights Reserved.}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Reviews Subject\_term: Climate-change adaptation;Genetic variation Subject\_term\_id: climate-change-adaptation;genetic-variation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\EE3BF8KJ\\Hoffmann und Sgrò - 2011 - Climate change and evolutionary adaptation.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\EVQ3W24A\\nature09670.html} +} + +@article{holtEvolutionaryEcologySpecies2003, + title = {On the Evolutionary Ecology of Species' Ranges}, + author = {Holt, R.}, + year = {2003}, + month = feb, + journal = {Evolutionary Ecology Research}, + volume = {5}, + pages = {159--178}, + abstract = {A species' range limits may shift in space either because of changes in ecological factors (e.g. climate, the abundances of interacting species) or because the traits which influence range limits (e.g. dispersal, niche characteristics) evolve by natural selection. In Geographical Ecology, Robert MacArthur (1972) provided a synthesis of the evolutionary factors that may drive range dynamics. In this paper, I revisit this theme in the light of recent theoretical studies of evolution in heterogeneous environments. These studies suggest that a rich range of evolutionary patterns in species' ranges may occur, including expansions or contractions, leading to dynamism in ranges even in epochs without strong directional environmental change.} +} + +@article{holtTheoreticalModelsSpecies2005, + title = {Theoretical Models of Species' Borders: Single Species Approaches}, + shorttitle = {Theoretical Models of Species' Borders}, + author = {Holt, Robert D. and Keitt, Timothy H. and Lewis, Mark A. and Maurer, Brian A. and Taper, Mark L.}, + year = {2005}, + journal = {Oikos}, + volume = {108}, + number = {1}, + pages = {18--27}, + issn = {1600-0706}, + doi = {10.1111/j.0030-1299.2005.13147.x}, + abstract = {The range of potential mechanisms limiting species' distributions in space is nearly as varied and complex as the diversity of life itself. Yet viewed abstractly, a species' border is a geographic manifestation of a species' demographic responses to a spatially and temporally varying world. Population dynamic models provide insight into the different routes by which range limits can arise owing to gradients in demographic rates. In a metapopulation context, for example, range limits may be caused by gradients in extinction rates, colonization rates or habitat availability. We have consider invasion models in uniform and heterogeneous environments as a framework for understanding non-equilibrium range limits, and explore conditions under which invasions may cease to spread leaving behind a stationary range limit. We conclude that non-equilibrial range dynamics need further theoretical and empirical attention.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.0030-1299.2005.13147.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\N9YWIB4T\\Holt et al. - 2005 - Theoretical models of species’ borders single spe.pdf} +} + +@article{holyoakTrendsMissingParts2008, + title = {Trends and Missing Parts in the Study of Movement Ecology}, + author = {Holyoak, Marcel and Casagrandi, Renato and Nathan, Ran and Revilla, Eloy and Spiegel, Orr}, + year = {2008}, + month = dec, + journal = {Proceedings of the National Academy of Sciences}, + volume = {105}, + number = {49}, + pages = {19060--19065}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.0800483105}, + abstract = {Movement is important to all organisms, and accordingly it is addressed in a huge number of papers in the literature. Of nearly 26,000 papers referring to movement, an estimated 34\% focused on movement by measuring it or testing hypotheses about it. This enormous amount of information is difficult to review and highlights the need to assess the collective completeness of movement studies and identify gaps. We surveyed 1,000 randomly selected papers from 496 journals and compared the facets of movement studied with a suggested framework for movement ecology, consisting of internal state (motivation, physiology), motion and navigation capacities, and external factors (both the physical environment and living organisms), and links among these components. Most studies simply measured and described the movement of organisms without reference to ecological or internal factors, and the most frequently studied part of the framework was the link between external factors and motion capacity. Few studies looked at the effects on movement of navigation capacity, or internal state, and those were mainly from vertebrates. For invertebrates and plants most studies were at the population level, whereas more vertebrate studies were conducted at the individual level. Consideration of only population-level averages promulgates neglect of between-individual variation in movement, potentially hindering the study of factors controlling movement. Terminology was found to be inconsistent among taxa and subdisciplines. The gaps identified in coverage of movement studies highlight research areas that should be addressed to fully understand the ecology of movement.}, + chapter = {Review}, + copyright = {\textcopyright{} 2008 by The National Academy of Sciences of the USA}, + langid = {english}, + pmid = {19060194}, + keywords = {dispersal,foraging,migration,navigation,physiology}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VH2J4QFJ\\Holyoak et al. - 2008 - Trends and missing parts in the study of movement .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\7CKNWVRG\\19060.html} +} + +@article{hovestadtAllInterpatchMovements2011, + title = {Do All Inter-Patch Movements Represent Dispersal? {{A}} Mixed Kernel Study of Butterfly Mobility in Fragmented Landscapes}, + shorttitle = {Do All Inter-Patch Movements Represent Dispersal?}, + author = {Hovestadt, Thomas and Binzenh{\"o}fer, Birgit and Nowicki, Piotr and Settele, Josef}, + year = {2011}, + month = sep, + journal = {The Journal of Animal Ecology}, + volume = {80}, + number = {5}, + pages = {1070--1077}, + issn = {1365-2656}, + doi = {10.1111/j.1365-2656.2011.01848.x}, + abstract = {1. In times of ongoing habitat fragmentation, the persistence of many species is determined by their dispersal abilities. Consequently, understanding the rules underlying movement between habitat patches is a key issue in conservation ecology. 2. We have analysed mark-release-recapture (MRR) data on inter-patches movements of the Dusky Large Blue butterfly Maculinea nausithous in a fragmented landscape in northern Bavaria, Germany. The aim of the analysis was to quantify distance dependence of dispersal as well as to evaluate the effect of target patch area on immigration probability. For statistical evaluation, we apply a 'reduced version' of the virtual migration model (VM), only fitting parameters for dispersal distance and immigration. In contrast to other analyses, we fit a mixed dispersal kernel to the MRR data. 3. A large fraction of recaptures happened in other habitat patches than those where individuals were initially caught. Further, we found significant evidence for the presence of a mixed dispersal kernel. The results indicate that individuals follow different strategies in their movements. Most movements are performed over small distances, nonetheless involving travelling between nearby habitat patches (median distance c. 480 m). A small fraction (c. 0{$\cdot$}025) of the population has a tendency to move over larger distances (median distance c. 3800 m). Further, immigration was positively affected by patch area (I{$\sim$}A({$\zeta$}) ), with the scaling parameter {$\zeta$} = 0{$\cdot$}5. 4. Our findings should help to resolve the long-lasting dispute over the suitability of the negative exponential function vs. inverse-power one for modelling dispersal. Previous studies on various organisms found that the former typically gives better overall fit to empirical distance distributions, but that the latter better represents long-distance movement probabilities. As long-distance movements are more important for landscape-level effects and thus, e.g. for conservation-oriented analyses like PVAs, fitting inverse-power kernels has often been preferred. 5. We conclude that the above discrepancy may simply stem from the fact that recorded inter-patch movements are an outcome of two different processes: daily routine movements and genuine dispersal. Consequently, applying mixed dispersal kernels to disentangle the two processes is recommended.}, + langid = {english}, + pmid = {21585369}, + keywords = {Animal Migration,Animals,Butterflies,Ecosystem,Germany,Models; Biological} +} + +@incollection{hovestadtEvolutionEmergenceDispersal2012, + title = {Evolution and Emergence of Dispersal Kernels\textemdash a Brief Theoretical Evaluation}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Hovestadt, Thomas and Bonte, Dries and Dytham, Calvin and Poethke, Hans Joachim}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0016}, + abstract = {This chapter discusses hypothetical kernels for single individuals since this kernel defines the long-term average success of a dispersal strategy, and is the ultimate target of selection; consequently, it is the appropriate definition in the context of models of dispersal. It is vital to have a detailed knowledge of dispersal kernels when predicting the expansion of invasive species, for example, or the recolonisation of sites in fragmented landscapes. The chapter starts with a definition of the term `dispersal kernel', as its definition is not consistent throughout the literature. There is ambiguity in certain respects. Firstly, it has been used to describe the density probability density function. Secondly, it has been used as the summary description of dispersal events for a whole population or of a single individual. Finally, it has also been used as the statistical description of real dispersal data or of a `hypothetical' kernel from which a single dispersal event is drawn as a random realization.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {dispersal kernels,dispersal strategy,hypothetical kernels,models of dispersal,random realization} +} + +@article{hovestadtEvolutionReducedDispersal2001, + title = {Evolution of Reduced Dispersal Mortality and 'fat-Tailed' Dispersal Kernels in Autocorrelated Landscapes.}, + author = {Hovestadt, T. and Messner, S. and Poethke, H. J.}, + year = {2001}, + month = feb, + journal = {Proceedings of the Royal Society B: Biological Sciences}, + volume = {268}, + number = {1465}, + pages = {385--391}, + issn = {0962-8452}, + doi = {10.1098/rspb.2000.1379}, + abstract = {Models describing the evolution of dispersal strategies have mostly focused on the evolution of dispersal rates. Taking trees as a model for organisms with undirected, passive dispersal, we have developed an individual-based, spatially explicit simulation tool to investigate the evolution of the dispersal kernel, P(r), and its resulting cumulative seed-density distribution, D(r). Simulations were run on a variety of fractal landscapes differing in the fraction of suitable habitat and the spatial autocorrelation. Starting from a uniform D(r), evolution led to an increase in the fraction of seeds staying in the home cell, a reduction of the dispersal mortality (arrival in unsuitable habitat), and the evolution of 'fat-tailed' D(r) in autocorrelated landscapes and approximately uniform D(r) in random landscapes. The evolutionary process was characterized by long periods of stasis with a few bouts of rapid change in the dispersal rate.}, + pmcid = {PMC1088618}, + pmid = {11270435}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\TB9UDVEL\\Hovestadt et al. - 2001 - Evolution of reduced dispersal mortality and 'fat-.pdf} +} + +@article{hovestadtInformationProcessingModels2010, + title = {Information Processing in Models for Density-Dependent Emigration: {{A}} Comparison}, + shorttitle = {Information Processing in Models for Density-Dependent Emigration}, + author = {Hovestadt, Thomas and Kubisch, Alexander and Poethke, Hans-Joachim}, + year = {2010}, + month = feb, + journal = {Ecological Modelling}, + volume = {221}, + number = {3}, + pages = {405--410}, + issn = {0304-3800}, + doi = {10.1016/j.ecolmodel.2009.11.005}, + abstract = {Density-dependent emigration has been recognized as a fitness enhancing strategy. Yet, especially in the modelling literature there is no consensus about how density-dependent emigration should quantitatively be incorporated into metapopulation models. In this paper we compare the performance of five different dispersal strategies (defined by the functional link between density and emigration probability). Four of these strategies are based on published functional relationships between local population density and emigration probability, one assumes density-independent dispersal. We use individual-based simulations of time-discrete metapopulation dynamics and conduct evolution experiments for a broad range of values for dispersal mortality and environmental stochasticity. For each set of these conditions we analyze the evolution of emigration rates in `monoculture experiments' (with only one type of dispersal strategy used by all individuals in the metapopulation) as well as in selection experiments that allow a pair-wise comparison of the performance of each functional type. We find that a single-parameter `asymptotic threshold' strategy \textendash{} derived from the marginal value theorem \textendash{} with a decelerating increase of emigration rate with increasing population density, out-competes any other strategy, i.e. density-independent emigration, a `linear threshold' strategy and a flexible three-parameter strategy. Only when environmental conditions select for extremely high emigration probabilities (close to one), strategies may perform approximately equally. A simple threshold strategy derived for the case of continuous population growth performs even worse than the density-independent strategy. As the functional type of the dispersal function implemented in metapopulation models may severely affect predictions concerning the survival of populations, range expansion, or community changes we clearly recommend to carefully select adequate functions to model density-dependent dispersal.}, + langid = {english}, + keywords = {Density-dependent dispersal,Evolutionary contest,Individual-based simulation,Information processing}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\7F2FMY3M\\Hovestadt et al. - 2010 - Information processing in models for density-depen.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\XZ8PTT8W\\S0304380009007510.html} +} + +@article{hughesEvolutionaryTradeoffsReproduction2003, + title = {Evolutionary Trade-Offs between Reproduction and Dispersal in Populations at Expanding Range Boundaries}, + author = {Hughes, Clare L. and Hill, Jane K. and Dytham, Calvin}, + year = {2003}, + month = nov, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {270}, + number = {suppl\_2}, + pages = {S147-S150}, + publisher = {{Royal Society}}, + doi = {10.1098/rsbl.2003.0049}, + abstract = {During recent climate warming, some species have expanded their ranges northwards to keep track of climate changes. Evolutionary changes in dispersal have been demonstrated in these expanding populations and here we show that increased dispersal is associated with reduced investment in reproduction in populations of the speckled wood butterfly, Pararge aegeria. Evolutionary changes in flight versus reproduction will affect the pattern and rate of expansion at range boundaries in the future, and understanding these responses will be crucial for predicting the distribution of species in the future as climates continue to warm.}, + keywords = {Climate Change,Flight Morphology,Parargeaegeria,Range Expansion,Trade-Off}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\SESHT37A\\Hughes et al. - 2003 - Evolutionary trade-offs between reproduction and d.pdf} +} + +@article{hughesModellingAnalysingEvolution2007, + title = {Modelling and Analysing Evolution of Dispersal in Populations at Expanding Range Boundaries}, + author = {Hughes, Clare L. and Dytham, Calvin and Hill, Jane K.}, + year = {2007}, + journal = {Ecological Entomology}, + volume = {32}, + number = {5}, + pages = {437--445}, + issn = {1365-2311}, + doi = {10.1111/j.1365-2311.2007.00890.x}, + abstract = {1. Species would be expected to shift northwards in response to current climate warming, but many are failing to do so because of fragmentation of breeding habitats. Dispersal is important for colonisation and an individual-based spatially explicit model was developed to investigate impacts of habitat availability on the evolution of dispersal in expanding populations. Model output was compared with field data from the speckled wood butterfly Pararge aegeria, which currently is expanding its range in Britain. 2. During range expansion, models simulated positive linear relationships between dispersal and distance from the seed location. This pattern was observed regardless of quantity (100\% to 10\% habitat availability) or distribution (random vs. gradient distribution) of habitat, although higher dispersal evolved at expanding range margins in landscapes with greater quantity of habitat and in gradient landscapes. Increased dispersal was no longer evident in any landscape once populations had reached equilibrium; dispersal values returned to those of seed populations. However, in landscapes with the least quantity of habitat, reduced dispersal (below that of seed populations) was observed at equilibrium. 3. Evolutionary changes in adult flight morphology were examined in six populations of P. aegeria along a transect from the distribution core to an expanding range margin in England (spanning a latitudinal distance of {$>$}200 km). Empirical data were in agreement with model output and showed increased dispersal ability (larger and broader thoraxes, smaller abdomens, higher wing aspect ratios) with increasing distance from the distribution core. Increased dispersal ability was evident in populations from areas colonised {$>$}30 years previously, although dispersal changes were generally evident only in females. 4. Evolutionary increases in dispersal ability in expanding populations may help species track future climate changes and counteract impacts of habitat fragmentation by promoting colonisation. However, at the highest levels of habitat loss, increased dispersal was less evident during expansion and reduced dispersal was observed at equilibrium indicating that, for many species, continued habitat fragmentation is likely to outweigh any benefits from dispersal.}, + langid = {english}, + keywords = {Climate change,flight morphology,invasion,Lepidoptera,metapopulation}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2311.2007.00890.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\24C8RLRB\\Hughes et al. - 2007 - Modelling and analysing evolution of dispersal in .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\G3CQC3PD\\j.1365-2311.2007.00890.html} +} + +@article{huntleyBioclimaticEnvelopesDynamic2010, + title = {Beyond Bioclimatic Envelopes: Dynamic Species' Range and Abundance Modelling in the Context of Climatic Change}, + shorttitle = {Beyond Bioclimatic Envelopes}, + author = {Huntley, Brian and Barnard, Phoebe and Altwegg, Res and Chambers, Lynda and Coetzee, Bernard W. T. and Gibson, Lesley and Hockey, Philip A. R. and Hole, David G. and Midgley, Guy F. and Underhill, Les G. and Willis, Stephen G.}, + year = {2010}, + journal = {Ecography}, + volume = {33}, + number = {3}, + pages = {621--626}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2009.06023.x}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2009.06023.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\3HQTNQ3N\\Huntley et al. - 2010 - Beyond bioclimatic envelopes dynamic species' ran.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UDN8BWLC\\j.1600-0587.2009.06023.html} +} + +@article{jeltschIntegratingMovementEcology2013a, + title = {Integrating Movement Ecology with Biodiversity Research - Exploring New Avenues to Address Spatiotemporal Biodiversity Dynamics}, + author = {Jeltsch, Florian and Bonte, Dries and Pe'er, Guy and Reineking, Bj{\"o}rn and Leimgruber, Peter and Balkenhol, Niko and Schr{\"o}der, Boris and Buchmann, Carsten M. and Mueller, Thomas and Blaum, Niels and Zurell, Damaris and {B{\"o}hning-Gaese}, Katrin and Wiegand, Thorsten and Eccard, Jana A. and Hofer, Heribert and Reeg, Jette and Eggers, Ute and Bauer, Silke}, + year = {2013}, + month = aug, + journal = {Movement Ecology}, + volume = {1}, + number = {1}, + pages = {6}, + issn = {2051-3933}, + doi = {10.1186/2051-3933-1-6}, + abstract = {Movement of organisms is one of the key mechanisms shaping biodiversity, e.g. the distribution of genes, individuals and species in space and time. Recent technological and conceptual advances have improved our ability to assess the causes and consequences of individual movement, and led to the emergence of the new field of `movement ecology'. Here, we outline how movement ecology can contribute to the broad field of biodiversity research, i.e. the study of processes and patterns of life among and across different scales, from genes to ecosystems, and we propose a conceptual framework linking these hitherto largely separated fields of research. Our framework builds on the concept of movement ecology for individuals, and demonstrates its importance for linking individual organismal movement with biodiversity. First, organismal movements can provide `mobile links' between habitats or ecosystems, thereby connecting resources, genes, and processes among otherwise separate locations. Understanding these mobile links and their impact on biodiversity will be facilitated by movement ecology, because mobile links can be created by different modes of movement (i.e., foraging, dispersal, migration) that relate to different spatiotemporal scales and have differential effects on biodiversity. Second, organismal movements can also mediate coexistence in communities, through `equalizing' and `stabilizing' mechanisms. This novel integrated framework provides a conceptual starting point for a better understanding of biodiversity dynamics in light of individual movement and space-use behavior across spatiotemporal scales. By illustrating this framework with examples, we argue that the integration of movement ecology and biodiversity research will also enhance our ability to conserve diversity at the genetic, species, and ecosystem levels.}, + keywords = {Biodiversity conservation,Community dynamics,Individual based modeling,Landscape genetics,Long distance movement,Mobile links,Species coexistence}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\4YXDG6ZL\\Jeltsch et al. - 2013 - Integrating movement ecology with biodiversity res.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\88THE2A8\\2051-3933-1-6.html} +} + +@article{johstExtinctionRiskTemporally1997, + title = {Extinction Risk in a Temporally Correlated Fluctuating Environment}, + author = {Johst, K. and Wissel, C.}, + year = {1997}, + month = oct, + journal = {Theoretical Population Biology}, + volume = {52}, + number = {2}, + pages = {91--100}, + issn = {0040-5809}, + doi = {10.1006/tpbi.1997.1322}, + abstract = {Usually extinction risk due to environmental stochasticity is estimated under the assumption of white environmental noise. This holds for a sufficiently short correlation time tauc of the fluctuations compared to the internal time scale of population growth r-1 (tauc/r-1{$<<$}1). Using a time-discrete simulation model we investigate when the white noise approximation is misleading. Environmental fluctuations are related to fluctuations of the birth and death rates of the species and the temporal correlation of these fluctuations (coloured noise) is described by a first-order autoregressive process. We found that extinction risk increases rapidly with correlation time tauc if the strength of noise is large. In this case the white noise approximation underestimates extinction risk essentially unless temporal correlation is very small (tauc/r-1{$<<$}0.1). Extinction risk increases only slowly with correlation time if the strength of noise is small. Then the white noise approximation may be used even for stronger temporal correlations (tauc/r-1{$>$}/=0.1). Thus, the estimation of extinction risk on the basis of white or coloured noise must be justified by time scale and strength of the fluctuations. Especially for species that are sensitive to environmental fluctuations the applicability of the white noise approximation should be carefully checked.}, + langid = {english}, + pmid = {9356326}, + keywords = {Animals,Artifacts,Bias,Birth Rate,Demography,Environment,Humans,Logistic Models,Models; Statistical,Mortality,Population Growth,Regression Analysis,Reproducibility of Results,Risk Factors,Species Specificity,Stochastic Processes,Time} +} + +@article{johstMetapopulationPersistenceDynamic2002, + title = {Metapopulation Persistence in Dynamic Landscapes: The Role of Dispersal Distance}, + shorttitle = {Metapopulation Persistence in Dynamic Landscapes}, + author = {Johst, Karin and Brandl, Roland and Eber, Sabine}, + year = {2002}, + journal = {Oikos}, + volume = {98}, + number = {2}, + pages = {263--270}, + issn = {1600-0706}, + doi = {10.1034/j.1600-0706.2002.980208.x}, + abstract = {Species associated with transient habitats need efficient dispersal strategies to ensure their regional survival. Using a spatially explicit metapopulation model, we studied the effect of the dispersal range on the persistence of a metapopulation as a function of the local population and landscape dynamics (including habitat patch destruction and subsequent regeneration). Our results show that the impact of the dispersal range depends on both the local population and patch growth. This is due to interactions between dispersal and the dynamics of patches and populations via the number of potential dispersers. In general, long-range dispersal had a positive effect on persistence in a dynamic landscape compared to short-range dispersal. Long-range dispersal increases the number of couplings between the patches and thus the colonisation of regenerated patches. However, long-range dispersal lost its advantage for long-term persistence when the number of potential dispersers was low due to small population growth rates and/or small patch growth rates. Its advantage also disappeared with complex local population dynamics and in a landscape with clumped patch distribution.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1034/j.1600-0706.2002.980208.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\F9GL83GZ\\Johst et al. - 2002 - Metapopulation persistence in dynamic landscapes .pdf} +} + +@article{jongejansDispersalDemographySpatial2008, + title = {Dispersal, Demography and Spatial Population Models for Conservation and Control Management}, + author = {Jongejans, Eelke and Skarpaas, Olav and Shea, Katriona}, + year = {2008}, + month = mar, + journal = {Perspectives in Plant Ecology, Evolution and Systematics}, + series = {Space Matters - {{Novel}} Developments in Plant Ecology through Spatial Modelling}, + volume = {9}, + number = {3}, + pages = {153--170}, + issn = {1433-8319}, + doi = {10.1016/j.ppees.2007.09.005}, + abstract = {Spatial population dynamics can seldom be ignored in management aimed at conserving or controlling plant species in a spatial context. Therefore, spatial population models, that bring together knowledge about a species' local demography and dispersal behavior, are of growing applied importance. Here, we survey increasingly complex analytical and simulation models that are being developed to describe both demography and dispersal in applied studies. Local population dynamics can be modeled in an unstructured way, by specifying age- or stage-structure or by modeling each individual. Dispersal is often summarized in population-spread models with descriptive and simple statistical models. Mechanistic models that incorporate the physical or behavioral dynamics of dispersal vectors, however, provide more insight and can more readily be applied to novel situations. Importantly, mechanistic models provide a tool for linking variation in species traits and environments to dispersal and population spread. Spatial population models span a wide range: from diffusion models, metapopulation models, integrodifference equation models, and Neubert\textendash Caswell models, to spatially explicit individual-based models. The complexity (and biological realism) of such models often trades off with tractability: for instance, individual-based simulation models allow for unlimited incorporation of biological detail, but rarely for analytical exploration of the model dynamics. We discuss the advantages and disadvantages of these various spatial population models; the choice of the most appropriate model will depend on the management objective, the biological complexity, available data and the principle of parsimony. We present five case studies of endangered and invasive species for which spatial population models have been developed to inform management, for instance to decrease the spread rate of invasive species or to improve the regional persistence of endangered species. We also anticipate exciting new developments in both spatial analytical and spatial simulation models with increasing demographic, dispersal and spatial sophistication.}, + langid = {english}, + keywords = {Demography,Seed dispersal,Spatial population models,Species management}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2V5QTP82\\S1433831907000467.html} +} + +@article{keithPredictingExtinctionRisks2008, + title = {Predicting Extinction Risks under Climate Change: Coupling Stochastic Population Models with Dynamic Bioclimatic Habitat Models}, + shorttitle = {Predicting Extinction Risks under Climate Change}, + author = {Keith, David A and Ak{\c c}akaya, H. Resit and Thuiller, Wilfried and Midgley, Guy F and Pearson, Richard G and Phillips, Steven J and Regan, Helen M and Ara{\'u}jo, Miguel B and Rebelo, Tony G}, + year = {2008}, + month = oct, + journal = {Biology Letters}, + volume = {4}, + number = {5}, + pages = {560--563}, + publisher = {{Royal Society}}, + doi = {10.1098/rsbl.2008.0049}, + abstract = {Species responses to climate change may be influenced by changes in available habitat, as well as population processes, species interactions and interactions between demographic and landscape dynamics. Current methods for assessing these responses fail to provide an integrated view of these influences because they deal with habitat change or population dynamics, but rarely both. In this study, we linked a time series of habitat suitability models with spatially explicit stochastic population models to explore factors that influence the viability of plant species populations under stable and changing climate scenarios in South African fynbos, a global biodiversity hot spot. Results indicate that complex interactions between life history, disturbance regime and distribution pattern mediate species extinction risks under climate change. Our novel mechanistic approach allows more complete and direct appraisal of future biotic responses than do static bioclimatic habitat modelling approaches, and will ultimately support development of more effective conservation strategies to mitigate biodiversity losses due to climate change.}, + keywords = {bioclimatic envelope,fire,fynbos,niche model,population viability analysis,uncertainty}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\28GGBZYF\\Keith et al. - 2008 - Predicting extinction risks under climate change .pdf} +} + +@article{kendallUnstructuredIndividualVariation2003, + title = {Unstructured {{Individual Variation}} and {{Demographic Stochasticity}}}, + author = {Kendall, Bruce E. and Fox, Gordon A.}, + year = {2003}, + journal = {Conservation Biology}, + volume = {17}, + number = {4}, + pages = {1170--1172}, + publisher = {{[Wiley, Society for Conservation Biology]}}, + issn = {0888-8892} +} + +@article{knowltonUsingBehavioralLandscape2010, + title = {Using Behavioral Landscape Ecology to Predict Species' Responses to Land-Use and Climate Change}, + author = {Knowlton, Jessie L. and Graham, Catherine H.}, + year = {2010}, + month = jun, + journal = {Biological Conservation}, + volume = {143}, + number = {6}, + pages = {1342--1354}, + issn = {0006-3207}, + doi = {10.1016/j.biocon.2010.03.011}, + abstract = {Climate change and habitat destruction are widely recognized as major threats to species' survival. As a result of these anthropogenic impacts, species are often forced into novel landscapes where their persistence is difficult to predict. Knowledge of how individuals move or disperse through the landscape, choose habitat in which to settle, and produce offspring which survive to repeat the process can greatly improve our ability to predict species' persistence. The field of behavioral landscape ecology uses a strong theoretical base to explore, often experimentally, how the behavior of a particular species is affected by heterogeneous and rapidly changing landscapes and can offer valuable insight for managing species in the face of human-induced environmental changes. When interpreted by modelers, results of landscape-level behavioral experiments can be quantified for use in predictive models. To this end, we summarize the methods and results of research using direct experimental manipulation techniques broken into the following categories: translocations, playback experiments, food resource manipulations, manipulations of reproductive success, direct manipulations of the landscape, and manipulations of predation risk. We review and place in a theoretical framework the results from this emerging body of research regarding how organisms move in and respond to different types of landscapes, both natural and human-altered. We go onto highlight the potential of each experimental method to quantify different processes, which may be useful when interpreted by modelers attempting to parameterize predictive models. Finally, we suggest future directions for experimental research that will allow for greater integration of behavioral landscape ecology and predictive modeling.}, + langid = {english}, + keywords = {Experiments,Fragmentation,Individual-based,Metapopulation,Movement,Predictive models,Spatially explicit}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ST67FW3K\\Knowlton und Graham - 2010 - Using behavioral landscape ecology to predict spec.pdf} +} + +@article{kokkoIndividualDispersalSpecies2006, + title = {From {{Individual Dispersal}} to {{Species Ranges}}: {{Perspectives}} for a {{Changing World}}}, + shorttitle = {From {{Individual Dispersal}} to {{Species Ranges}}}, + author = {Kokko, Hanna and {L{\'o}pez-Sepulcre}, Andr{\'e}s}, + year = {2006}, + month = aug, + journal = {Science}, + volume = {313}, + number = {5788}, + pages = {789--791}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.1128566}, + abstract = {Dispersal is often risky to the individual, yet the long-term survival of populations depends on having a sufficient number of individuals that move, find each other, and locate suitable breeding habitats. This tension has consequences that rarely meet our conservation or management goals. This is particularly true in changing environments, which makes the study of dispersal urgently topical in a world plagued with habitat loss, climate change, and species introductions. Despite the difficulty of tracking mobile individuals over potentially vast ranges, recent research has revealed a multitude of ways in which dispersal evolution can either constrain, or accelerate, species' responses to environmental changes.}, + chapter = {Special Perspectives}, + copyright = {American Association for the Advancement of Science}, + langid = {english}, + pmid = {16902127}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HDS46C8H\\Kokko und López-Sepulcre - 2006 - From Individual Dispersal to Species Ranges Persp.pdf} +} + +@article{kramer-schadtFragmentedLandscapesRoad2004, + title = {Fragmented Landscapes, Road Mortality and Patch Connectivity: Modelling Influences on the Dispersal of {{Eurasian}} Lynx}, + shorttitle = {Fragmented Landscapes, Road Mortality and Patch Connectivity}, + author = {{Kramer-Schadt}, Stephanie and Revilla, Eloy and Wiegand, Thorsten and Breitenmoser, Urs}, + year = {2004}, + journal = {Journal of Applied Ecology}, + volume = {41}, + number = {4}, + pages = {711--723}, + issn = {1365-2664}, + doi = {10.1111/j.0021-8901.2004.00933.x}, + abstract = {1 Although many reintroduction schemes for the Eurasian lynx Lynx lynx in Germany have been discussed, the implications of connectivity between suitable patches have not been assessed. 2 We introduce an individual-based, spatially explicit dispersal model to assess the probability of a dispersing animal reaching another suitable patch in the complex heterogeneous German landscape, with its dense transport system. The dispersal model was calibrated using telemetric data from the Swiss Jura and based on a map of potential lynx dispersal habitat. 3 Most suitable patches could be interconnected by movements of dispersing lynx within 10 years of reintroduction. However, when realistic levels of mortality risks on roads were applied, most patches become isolated except along the German\textendash Czech border. Consequently, patch connectivity is limited not so much by the distribution of dispersal habitat but by the high mortality of dispersing lynx. Accordingly, rather than solely investing in habitat restoration, management efforts should try to reduce road mortality. 4 Synthesis and applications. Our approach illustrates how spatially explicit dispersal models can guide conservation efforts and reintroduction programmes even where data are scarce. Clear limits imposed by substantial road mortality will affect dispersing lynx as well as other large carnivores, unless offset by careful road-crossing management or by the careful selection of release points in reintroduction programmes.}, + langid = {english}, + keywords = {conservation,large carnivores,large-scale approach,Lynx lynx,movement,spatially explicit individual-based model,species reintroduction}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.0021-8901.2004.00933.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\7QQGM4EP\\Kramer-Schadt et al. - 2004 - Fragmented landscapes, road mortality and patch co.pdf} +} + +@article{krosbyEcologicalConnectivityChanging2010a, + title = {Ecological {{Connectivity}} for a {{Changing Climate}}}, + author = {KROSBY, MEADE and TEWKSBURY, JOSHUA and HADDAD, NICK M. and HOEKSTRA, JONATHAN}, + year = {2010}, + journal = {Conservation Biology}, + volume = {24}, + number = {6}, + pages = {1686--1689}, + publisher = {{[Wiley, Society for Conservation Biology]}}, + issn = {0888-8892} +} + +@article{kubischDensitydependentDispersalFormation2011, + title = {Density-Dependent Dispersal and the Formation of Range Borders}, + author = {Kubisch, Alexander and Poethke, Hans-Joachim and Hovestadt, Thomas}, + year = {2011}, + journal = {Ecography}, + volume = {34}, + number = {6}, + pages = {1002--1008}, + publisher = {{Wiley}}, + issn = {0906-7590}, + abstract = {Knowledge about the mechanisms of range formation is crucial for scientifically based species conservation strategies in the face of ongoing global climate change. In recent years an increasing amount of studies have focused on the influences of density-dependent dispersal on demographic and biogeographical patterns. However, it still remains unclear, to what extent and in what ways this strategy would affect the range formation of species. In order to fill this gap, we present a study using individual-based simulations of a species with discrete generations living along a dispersal mortality gradient. We compare the evolution of range sizes for species following density-dependent and density-independent emigration. Furthermore we assess the influence of environmental stochasticity and Allee effects on range formation, as both processes are known to play an important role for dispersal evolution. We find that density-dependent dispersal always results in much wider ranges than unconditional dispersal. Increasing environmental stochasticity, a predicted consequence of climate change, can remarkably expand the ranges of species living in such connectivity gradients if dispersal decisions are based on local population density. A strong Allee effect causes range contraction for both strategies, but the effect is considerably less dramatic under density-dependent compared to density-independent emigration. We strongly recommend accounting for these findings in future attempts to model species' range shifts due to climate change.} +} + +@article{kubischElasticityRangeLimits2010, + title = {On the Elasticity of Range Limits during Periods of Expansion}, + author = {Kubisch, Alexander and Hovestadt, Thomas and Poethke, Hans-Joachim}, + year = {2010}, + month = oct, + journal = {Ecology}, + volume = {91}, + number = {10}, + pages = {3094--3099}, + issn = {0012-9658}, + doi = {10.1890/09-2022.1}, + abstract = {Dispersal is known to play a crucial role in the formation of species' ranges. Recent studies demonstrate that dispersiveness increases rapidly during the range expansion of species due to a fitness increase for dispersers at the expanding front. R. D. Holt concluded, however, that emigration should decline after the period of invasion and hence predicted some range contraction following the initial expansion phase. In this study, we evaluate this hypothesis using a spatially explicit individual-based model of populations distributed along environmental gradients. In our experiments we allow the species to spread along a gradient of declining conditions. Results show that range contraction did emerge in a gradient of dispersal mortality, caused by the rapid increase in emigration probability during invasion and selection disfavoring dispersal, once a stable range is formed. However, gradients in growth rate, local extinction rate, and patch capacity did not lead to a noticeable contraction of the range. We conclude, that the phenomenon of range contraction may emerge, but only under conditions that select for a reduction in dispersal at the range edge in comparison to the core region once the expansion period is over.}, + langid = {english}, + pmid = {21058568}, + keywords = {Computer Simulation,Demography,Ecosystem,Models; Biological} +} + +@article{kubischPredictingRangeShifts2013, + title = {Predicting Range Shifts under Global Change: The Balance between Local Adaptation and Dispersal}, + shorttitle = {Predicting Range Shifts under Global Change}, + author = {Kubisch, Alexander and Degen, Tobias and Hovestadt, Thomas and Poethke, Hans Joachim}, + year = {2013}, + journal = {Ecography}, + volume = {36}, + number = {8}, + pages = {873--882}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2012.00062.x}, + abstract = {Bioclimate envelope models (BEMs) have often been criticized as being too simplistic due to e.g. not incorporating effects of biotic interactions or evolutionary adaptation. However, BEMs are widely applied and have proven to be often useful. Here we investigate, under which conditions evolution of dispersal, local adaptation or interspecific competition may be of minor importance for forecasting future range shifts. Therefore we use individual-based simulations of metapopulations under climate change living in spatial temperature gradients. Scenarios incorporate single-species systems or systems with competing species, respectively. Dispersal rate is evolving and adaptation to local conditions may also evolve in some scenarios. Results show that in single-species scenarios excluding evolutionary adaptation, species either follow optimal habitat conditions or go extinct if habitat connectivity is too low. These simulations are in close accordance to predictions from BEMs. Including evolutionary adaptation qualitatively changes these results. In the absence of competing species the species either completely invades the world or goes extinct. With competitors, results strongly depend on habitat fragmentation. For highly connected habitats the range border may shift as predicted by BEMs, for intermediate connectivity it will lag behind, while species will go extinct if fragmentation is too high. Our results indicate that (simple) BEMs may work well if habitats are well connected and species will not encounter many difficulties in dispersing to new sites. Selection in this case may promote evolution of even higher dispersal activities. We thus show that the presence of biotic interactions may be ignored for predictions of range shifts when high dispersal can be expected.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2012.00062.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ZGXWGBLN\\Kubisch et al. - 2013 - Predicting range shifts under global change the b.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\XHBH8TMS\\j.1600-0587.2012.00062.html} +} + +@article{kubischRangeBorderFormation2011, + title = {Range Border Formation in a World with Increasing Climatic Variance}, + author = {Kubisch, Alexander and Poethke, Hans}, + year = {2011}, + month = feb, + journal = {Evolutionary Ecology Research}, + volume = {13}, + pages = {159--169}, + abstract = {Questions: How will a change in climatic conditions characterized by an increase in the variance of environmental conditions affect the distribution of species along spatial environmental gradients? How does the specific type of gradient influence their response? Features of the model: Spatially explicit individual-based simulation of a metapopulation. Logistic population growth and density-dependent emigration. Spatial gradients in habitat isolation, quality, and size. Ranges of the key variables: Environmental stochasticity was modelled as a variation of net reproductive rate (lambda). For a mean reproductive rate of lambda = 2, the standard deviation (sigma) was varied in the range of 0 to 3. Conclusions: When the range margin was predominantly determined by a lack of colonizers, ranges initially expanded with increasing environmental fluctuations, but contracted again when these fluctuations became too strong (sigma textgreater 1). When extinction risk was more important for range formation, the initial expansion was damped or completely absent. When the climate changed too fast to allow for local adaptation of dispersal behaviour, the described patterns were less pronounced.} +} + +@article{kunEvolutionDensityDependentDispersal2006, + title = {The {{Evolution}} of {{Density-Dependent Dispersal}} in a {{Noisy Spatial Population Model}}}, + author = {Kun, {\'A}d{\'a}m and Scheuring, Istv{\'a}n}, + year = {2006}, + journal = {Oikos}, + volume = {115}, + number = {2}, + pages = {308--320}, + publisher = {{[Nordic Society Oikos, Wiley]}}, + issn = {0030-1299}, + abstract = {It is well-known that dispersal is advantageous in many different ecological situations, e.g. to survive local catastrophes where populations live in spatially and temporally heterogeneous habitats. However, the key question, what kind of dispersal strategy is optimal in a particular situation, has remained unanswered. We studied the evolution of density-dependent dispersal in a coupled map lattice model, where the population dynamics are perturbed by external environmental noise. We used a very flexible dispersal function to enable evolution to select from practically all possible types of monotonous density-dependent dispersal functions. We treated the parameters of the dispersal function as continuously changing phenotypic traits. The evolutionary stable dispersal strategies were investigated by numerical simulations. We pointed out that irrespective of the cost of dispersal and the strength of environmental noise, this strategy leads to a very weak dispersal below a threshold density, and dispersal rate increases in an accelerating manner above this threshold. Decreasing the cost of dispersal increases the skewness of the population density distribution, while increasing the environmental noise causes more pronounced bimodality in this distribution. In case of positive temporal autocorrelation of the environmental noise, there is no dispersal below the threshold, and only low dispersal below it, on the other hand with negative autocorrelation practically all individual disperses above the threshold. We found our results to be in good concordance with empirical observations.} +} + +@incollection{lambinHighConnectivityHigh2012, + title = {High Connectivity despite High Fragmentation: Iterated Dispersal in a Vertebrate Metapopulation}, + shorttitle = {High Connectivity despite High Fragmentation}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Lambin, Xavier and Bouille, Diane Le and Oliver, Matthew K and Sutherland, Chris and Tedesco, Edoardo and Douglas, Alex}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0032}, + abstract = {This chapter reviews published and unpublished studies on dispersal by water voles inhabiting fragmented habitats and organized as metapopulations. Studies of dispersal that have checked the consistency of pattern emerging at behavioural, individual, and population scale are rare or altogether lacking. This chapter describes how inferences have been drawn from exceptionally large-scale, but largely descriptive, studies of dispersal through the use of molecular markers, combined with small-scale individual-level experiments. These studies reveal a high degree of connectivity through dispersal between geographically isolated water vole colonies. Experiments with `enforced dispersers' show how water vole behaviour during the transience phase of dispersal might bring this about, if dispersal takes place over a long time through multiple stepping-stone movements.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {enforced dispersers,fragmented habitats,molecular markers,stepping-stone movements,transience phase,water voles} +} + +@article{landeEstimatingDensityDependence2006, + title = {Estimating {{Density Dependence}} from {{Time Series}} of {{Population Age Structure}}}, + author = {Lande, Russell and Engen, Steinar and S{\ae}ther, Bernt-Erik and Coulson, Tim and Solow, Associate Editor: Andrew R. and DeAngelis, Editor: Donald L.}, + year = {2006}, + journal = {The American Naturalist}, + volume = {168}, + number = {1}, + pages = {76--87}, + publisher = {{[The University of Chicago Press, The American Society of Naturalists]}}, + issn = {0003-0147}, + doi = {10.1086/504851}, + abstract = {Abstract: Population fluctuations are caused by demographic and environmental stochasticity, time lags due to life history, and density dependence. We model a general life history allowing density dependence within and among age or stage classes in a population undergoing small or moderate fluctuations around a stable equilibrium. We develop a method for estimating the overall strength of density dependence measured by the rate of return toward equilibrium, and we also consider a simplified population description and forecasting using the density-dependent reproductive value. This generality comes at the cost of requiring a time series of the population age or stage structure instead of a univariate time series of adult or total population size. The method is illustrated by analyzing the dynamics of a fully censused population of red deer (Cervus elaphus) based on annual fluctuations of age structure through 21 years.} +} + +@article{lawsonhandleyAdvancesOurUnderstanding2007, + title = {Advances in Our Understanding of Mammalian Sex-Biased Dispersal}, + author = {Lawson Handley, L. J. and Perrin, N.}, + year = {2007}, + month = apr, + journal = {Molecular Ecology}, + volume = {16}, + number = {8}, + pages = {1559--1578}, + issn = {0962-1083}, + doi = {10.1111/j.1365-294X.2006.03152.x}, + abstract = {Sex-biased dispersal is an almost ubiquitous feature of mammalian life history, but the evolutionary causes behind these patterns still require much clarification. A quarter of a century since the publication of seminal papers describing general patterns of sex-biased dispersal in both mammals and birds, we review the advances in our theoretical understanding of the evolutionary causes of sex-biased dispersal, and those in statistical genetics that enable us to test hypotheses and measure dispersal in natural populations. We use mammalian examples to illustrate patterns and proximate causes of sex-biased dispersal, because by far the most data are available and because they exhibit an enormous diversity in terms of dispersal strategy, mating and social systems. Recent studies using molecular markers have helped to confirm that sex-biased dispersal is widespread among mammals and varies widely in direction and intensity, but there is a great need to bridge the gap between genetic information, observational data and theory. A review of mammalian data indicates that the relationship between direction of sex-bias and mating system is not a simple one. The role of social systems emerges as a key factor in determining intensity and direction of dispersal bias, but there is still need for a theoretical framework that can account for the complex interactions between inbreeding avoidance, kin competition and cooperation to explain the impressive diversity of patterns.}, + langid = {english}, + pmid = {17402974}, + keywords = {Animal Migration,Animals,Biological Evolution,Female,Gene Flow,Genetic Markers,Humans,Male,Mammals,Models; Biological,Sex Factors,Sexual Behavior; Animal,Social Behavior}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\JMH9UKXM\\Lawson Handley und Perrin - 2007 - Advances in our understanding of mammalian sex-bia.pdf} +} + +@incollection{legalliardDispersalRangeDynamics2012, + title = {Dispersal and Range Dynamics in Changing Climates: A Review}, + shorttitle = {Dispersal and Range Dynamics in Changing Climates}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Le Galliard, Jean Fran{\c c}ois Le and Massot, Manuel and Clobert, Jean}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0025}, + abstract = {This chapter presents an attempt to summarize existing results and methods in the development of predictive models of ecological responses to climate change, with the aim of highlighting existing patterns and trends in the current data, the most important knowledge gaps, and some fruitful avenues for future research. It highlights the urgent need for a good understanding of the effects of climate change on dispersal. Global climate changes, in fact, have been responsible for the growing awareness and recent surge of interest in studies of dispersal aimed at understanding and predicting the ecological effects of climate change. One of the most common ecological responses to climate change involves range or habitat shifts due to spatial expansions at the cool range margins and spatial retractions at the warm range margins.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {climate change,ecological effects,ecological responses,habitat shifts,spatial expansions,spatial retractions} +} + +@article{legalliardPatternsProcessesDispersal2012, + title = {Patterns and Processes of Dispersal Behaviour in Arvicoline Rodents}, + author = {Le Galliard, Jean-Fran{\c c}ois and R{\'e}my, Alice and Ims, Rolf A. and Lambin, Xavier}, + year = {2012}, + month = feb, + journal = {Molecular Ecology}, + volume = {21}, + number = {3}, + pages = {505--523}, + issn = {1365-294X}, + doi = {10.1111/j.1365-294X.2011.05410.x}, + abstract = {A good understanding of mammalian societies requires measuring patterns and comprehending processes of dispersal in each sex. We investigated dispersal behaviour in arvicoline rodents, a subfamily of mammals widespread in northern temperate environments and characterized by a multivoltine life cycle. In arvicoline rodents, variation in life history strategies occurs along a continuum from precocial to delayed maturation that reflects seasonal and ecological fluctuations. We compared dispersal across and within species focusing on the effects of external (condition-dependent) and internal (phenotype-dependent) factors. Our data revealed substantial, unexplained variation between species for dispersal distances and a strong variation within species for both dispersal distance and fraction. Some methodological aspects explained variation across studies, which cautions against comparisons that do not control for them. Overall, the species under consideration display frequent short-distance dispersal events and extremely flexible dispersal strategies, but they also have hitherto unexpected capacity to disperse long distances. Female arvicolines are predominantly philopatric relative to males, but we found no clear association between the mating system and the degree of sex bias in dispersal across species. Dispersal is a response to both various proximate and ultimate factors, including competition, inbreeding avoidance, mate searching and habitat quality. In particular, our review suggests that costs and benefits experienced during transience and settlement are prime determinants of condition dependence. Patterns of phenotype-dependent dispersal are idiosyncratic, except for a widespread association between an exploration/activity syndrome and natal dispersal. Consequences for population dynamics and genetic structures are discussed.}, + langid = {english}, + pmid = {22211403}, + keywords = {Animal Migration,Animals,Arvicolinae,Ecosystem,Female,Homing Behavior,Inbreeding,Male,Population Dynamics,Sex Characteristics,Sexual Behavior; Animal,Species Specificity}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\K2MXWVEX\\Le Galliard et al. - 2012 - Patterns and processes of dispersal behaviour in a.pdf} +} + +@incollection{legendreAgeStructureMating2004, + title = {Age {{Structure}}, {{Mating System}}, and {{Population Viability}}}, + booktitle = {Evolutionary {{Conservation Biology}}}, + author = {Legendre, St{\'e}phane}, + editor = {Couvet, Denis and Ferri{\`e}re, R{\'e}gis and Dieckmann, Ulf}, + year = {2004}, + series = {Cambridge {{Studies}} in {{Adaptive Dynamics}}}, + pages = {41--58}, + publisher = {{Cambridge University Press}}, + address = {{Cambridge}}, + doi = {10.1017/CBO9780511542022.005}, + abstract = {IntroductionThe fate of populations depends on the life-history traits of the species and possible adaptive changes in these traits in response to selective pressure. In unstructured population models, life-history traits are compounded into few parameters, like the intrinsic growth rate r and the carrying capacity K (see Chapter 2). Structured population models, based on life-cycle graphs, allow the effects of specific life-history traits (survival rates, fecundities, generation time, age at maturity) on population dynamics to be investigated. For example, sensitivities of the growth rate to changes in life-cycle transitions can be computed. Individual life-history traits are important determinants of a population's extinction risk, and are also both factors in and targets of a population's adaptive response to environmental change.When population size is small \textendash{} always a concern in conservation biology \textendash{} both individual life-history traits and the structure of interactions between individuals and the genetic system are expected to influence viability. The mating system, for example, may be conducive to an Allee effect (see Chapter 2), and inbreeding depression is a potentially important factor of the extinction process of small populations. In this chapter, we study the interplay between population structure, in terms of age and sex, and population persistence. Two-sex structured models that incorporate specific features of the social mating system and possible differences in male and female life cycles are analyzed. Also, attempts to merge genetic factors and demography into integrated models are presented.}, + isbn = {978-0-521-82700-3}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2JPB2JW7\\Legendre - 2004 - Age Structure, Mating System, and Population Viabi.pdf} +} + +@article{lenoirSignificantUpwardShift2008, + title = {A {{Significant Upward Shift}} in {{Plant Species Optimum Elevation During}} the 20th {{Century}}}, + author = {Lenoir, J. and G{\'e}gout, J. C. and Marquet, P. A. and de Ruffray, P. and Brisse, H.}, + year = {2008}, + month = jun, + journal = {Science}, + volume = {320}, + number = {5884}, + pages = {1768--1771}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.1156831}, + abstract = {Spatial fingerprints of climate change on biotic communities are usually associated with changes in the distribution of species at their latitudinal or altitudinal extremes. By comparing the altitudinal distribution of 171 forest plant species between 1905 and 1985 and 1986 and 2005 along the entire elevation range (0 to 2600 meters above sea level) in west Europe, we show that climate warming has resulted in a significant upward shift in species optimum elevation averaging 29 meters per decade. The shift is larger for species restricted to mountain habitats and for grassy species, which are characterized by faster population turnover. Our study shows that climate change affects the spatial core of the distributional range of plant species, in addition to their distributional margins, as previously reported. A 100-year survey shows that the optimal elevations for growth of plant species in European temperate forests have shifted upward by about 30 meters per decade. A 100-year survey shows that the optimal elevations for growth of plant species in European temperate forests have shifted upward by about 30 meters per decade.}, + chapter = {Report}, + copyright = {American Association for the Advancement of Science}, + langid = {english}, + pmid = {18583610}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\JEYP24ZQ\\Lenoir et al. - 2008 - A Significant Upward Shift in Plant Species Optimu.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\YTEYEHUC\\1768.html} +} + +@article{lesserContributionsLongdistanceDispersal2013, + title = {Contributions of Long-Distance Dispersal to Population Growth in Colonising {{Pinus}} Ponderosa Populations}, + author = {Lesser, Mark R. and Jackson, Stephen T.}, + year = {2013}, + month = mar, + journal = {Ecology Letters}, + volume = {16}, + number = {3}, + pages = {380--389}, + issn = {1461-0248}, + doi = {10.1111/ele.12053}, + abstract = {Long-distance dispersal is an integral part of plant species migration and population development. We aged and genotyped 1125 individuals in four disjunct populations of Pinus ponderosa that were initially established by long-distance dispersal in the 16th and 17th centuries. Parentage analysis was used to determine if individuals were the product of local reproductive events (two parents present), long-distance pollen dispersal (one parent present) or long-distance seed dispersal (no parents present). All individuals established in the first century at each site were the result of long-distance dispersal. Individuals reproduced at younger ages with increasing age of the overall population. These results suggest Allee effects, where populations were initially unable to expand on their own, and were dependent on long-distance dispersal to overcome a minimum-size threshold. Our results demonstrate that long-distance dispersal was not only necessary for initial colonisation but also to sustain subsequent population growth during early phases of expansion.}, + langid = {english}, + pmid = {23279647}, + keywords = {Age Factors,Genotype,Pinus ponderosa,Pollen,Population Growth,Seed Dispersal,Wyoming} +} + +@article{limaBehavioralEcologyEcological1996, + title = {Towards a Behavioral Ecology of Ecological Landscapes}, + author = {Lima, Steven L. and Zollner, Patrick A.}, + year = {1996}, + month = mar, + journal = {Trends in Ecology \& Evolution}, + volume = {11}, + number = {3}, + pages = {131--135}, + issn = {0169-5347}, + doi = {10.1016/0169-5347(96)81094-9}, + abstract = {Recent developments in landscape-level ecological modeling rest upon poorly understood behavioral phenomena. Surprisingly, these phenomena include animal movement and habitat selection, two areas with a long history of study in behavioral ecology. A major problem in applying traditional behavioral ecology to landscape-level ecological problems is that ecologists and behaviorists work at very different spatial scales. Thus a behavioral ecology of ecological landscapes would strive to overcome this inopportune differential in spatial scales. Such a landscape-conscious behavioral undertaking would not only establish more firmly the link between behavior and ecological systems, but also catalyze the study of basic biological phenomena of Interest to behaviorists and ecologists alike.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RSMHXEG9\\Lima und Zollner - 1996 - Towards a behavioral ecology of ecological landsca.pdf} +} + +@article{lindstromSexualReproductionPopulation1998, + title = {Sexual Reproduction and Population Dynamics: The Role of Polygyny and Demographic Sex Differences}, + shorttitle = {Sexual Reproduction and Population Dynamics}, + author = {Lindstr{\"o}m, Jan and Kokko, Hanna}, + year = {1998}, + month = mar, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {265}, + number = {1395}, + pages = {483--488}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.1998.0320}, + abstract = {Most models of population dynamics do not take sexual reproduction into account (i.e. they do not consider the role of males). However, assumptions behind this practice\textemdash that no demographic sex differences exist and males are always abundant enough to fertilize all the females\textemdash are usually not justified in natural populations. On the contrary, demographic sex differences are common, especially in polygynous species. Previous models that consider sexual reproduction report a stabilizing effect through mixing of different genotypes, thus suggesting a decrease in the propensity for complex dynamics in sexually reproducing populations. Here we show that considering the direct role of males in reproduction and density dependence leads to the conclusion that a two\textendash sex model is not necessarily more stable compared with the corresponding one\textendash sex model. Although solutions exist where sexual reproduction has a stabilizing effect even when no genotypic variability is included (primarily when associated with monogamy), factors like polygyny, sex differences in survival or density dependence, and possible alterations of the primary sex ratio (the Trivers\textendash Willard mechanism), may enlarge the parametric region of complex dynamics. Sexual reproduction therefore does not necessarily increase the stability of population dynamics and can have destabilizing effects, at least in species with complicated mating systems and sexual dimorphism.}, + keywords = {chaos,polygyny,population dynamics,sexual reproduction,Trivers–Willard,two–sex model}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\LPZI96MA\\Lindström und Kokko - 1998 - Sexual reproduction and population dynamics the r.pdf} +} + +@article{loarieVelocityClimateChange2009, + title = {The Velocity of Climate Change}, + author = {Loarie, Scott R. and Duffy, Philip B. and Hamilton, Healy and Asner, Gregory P. and Field, Christopher B. and Ackerly, David D.}, + year = {2009}, + month = dec, + journal = {Nature}, + volume = {462}, + number = {7276}, + pages = {1052--1055}, + publisher = {{Nature Publishing Group}}, + issn = {1476-4687}, + doi = {10.1038/nature08649}, + abstract = {In the event of climate change, species have to move if they are to remain in an area with the same average temperature: their chances of survival therefore depend on the ability to keep pace with a moving climate as well as on the extent of change in temperature and other climate factors. To put this pressure on species into context, a novel index designed to quantify climate change in the coming century has been developed. Its value gives the local velocity along the Earth's surface needed to maintain constant temperatures, and is derived from temperature gradients scaled by distance (\textdegree C per km) and time (\textdegree C per year). The index provides a quantitative view of the role of topography in buffering climate change as it would affect plants and animals: on the IPCC's A1B emission scenario the index has a global mean of 0.42 km per year, compared to extremes of 0.08 and 1.26 km per year for mountains forest biomes and flooded grasslands, respectively. Climate change velocity, it turns out, is large relative to species migration speeds and the sizes of protected habitats. The data suggest that, in some ecosystems, helping species to relocate more rapidly via habitat corridors or new reserves could be an important contribution to conservation.}, + copyright = {2009 Macmillan Publishers Limited. All rights reserved}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Research}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8H63BYT5\\Loarie et al. - 2009 - The velocity of climate change.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\QLK855B9\\nature08649.html} +} + +@article{lossAssistedColonizationIntegrating2011, + title = {Assisted Colonization: {{Integrating}} Conservation Strategies in the Face of Climate Change}, + shorttitle = {Assisted Colonization}, + author = {Loss, Scott R. and Terwilliger, Lauren A. and Peterson, Anna C.}, + year = {2011}, + month = jan, + journal = {Biological Conservation}, + volume = {144}, + number = {1}, + pages = {92--100}, + issn = {0006-3207}, + doi = {10.1016/j.biocon.2010.11.016}, + abstract = {Global climate change poses an immense challenge for conservation biologists seeking to mitigate impacts to species and ecosystems. Species persistence will depend on geographic range shifts or adaptation in response to warming patterns as novel climates and community assemblages arise. Assisted colonization has been proposed as a method for addressing these challenges. This technique, which consists of transporting species to a new range that is predicted to be favorable for persistence under future climate scenarios, has become the subject of controversy and discussion in the conservation community due to its highly manipulative nature, questions about widespread feasibility, and uncertainty associated with the likelihood of translocated species becoming invasive. We reviewed the discussion and criticism associated with assisted colonization and sought to identify other conservation techniques that also display potential to promote the colonization and adaptation of species in response to climate change. We propose an integrated conservation strategy that includes management for habitat connectivity, conservation genetics, and when necessary, assisted colonization of species that are still unable to shift their ranges even given implementation of the above standard conservation approaches. We argue that this integrated approach will facilitate persistence for a larger proportion of species than is possible by solely using assisted colonization. Furthermore, a multi-faceted approach will likely reduce the uncertainty of conservation outcomes and will become increasingly necessary for conservation of biodiversity in a changing climate.}, + langid = {english}, + keywords = {Assisted colonization,Assisted migration,Climate change,Conservation genetics,Landscape connectivity,Managed relocation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\98DAYUGC\\Loss et al. - 2011 - Assisted colonization Integrating conservation st.pdf} +} + +@article{manelLandscapeGeneticsCombining2003a, + title = {Landscape Genetics: Combining Landscape Ecology and Population Genetics}, + shorttitle = {Landscape Genetics}, + author = {Manel, St{\'e}phanie and Schwartz, Michael K. and Luikart, Gordon and Taberlet, Pierre}, + year = {2003}, + month = apr, + journal = {Trends in Ecology \& Evolution}, + volume = {18}, + number = {4}, + pages = {189--197}, + issn = {0169-5347}, + doi = {10.1016/S0169-5347(03)00008-9}, + abstract = {Understanding the processes and patterns of gene flow and local adaptation requires a detailed knowledge of how landscape characteristics structure populations. This understanding is crucial, not only for improving ecological knowledge, but also for managing properly the genetic diversity of threatened and endangered populations. For nearly 80 years, population geneticists have investigated how physiognomy and other landscape features have influenced genetic variation within and between populations. They have relied on sampling populations that have been identified beforehand because most population genetics methods have required discrete populations. However, a new approach has emerged for analyzing spatial genetic data without requiring that discrete populations be identified in advance. This approach, landscape genetics, promises to facilitate our understanding of how geographical and environmental features structure genetic variation at both the population and individual levels, and has implications for ecology, evolution and conservation biology. It differs from other genetic approaches, such as phylogeography, in that it tends to focus on processes at finer spatial and temporal scales. Here, we discuss, from a population genetic perspective, the current tools available for conducting studies of landscape genetics.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VHXZ67SP\\S0169534703000089.html} +} + +@article{mathiasDivergentEvolutionDispersal2001, + title = {Divergent {{Evolution}} of {{Dispersal}} in a {{Heterogeneous Landscape}}}, + author = {Mathias, Andrea and Kisdi, Eva and Olivieri, Isabelle}, + year = {2001}, + journal = {Evolution}, + volume = {55}, + number = {2}, + pages = {246--259}, + publisher = {{[Society for the Study of Evolution, Wiley]}}, + issn = {0014-3820}, + abstract = {The evolution of dispersal is investigated in a landscape of many patches with fluctuating carrying capacities and spatial heterogeneity in temporal fluctuations. Although asynchronous temporal fluctuations select for dispersal, spatial heterogeneity in the distribution of fluctuating environmental variables selects against it. We find evolutionary branching in dispersal rate leading to the evolutionarily stable coexistence of a high- and a low-dispersal phenotype. We study how the opposing forces of selection for and against dispersal change with the relative size and the environmental qualities of the source and sink habitats. Our results suggest that the evolution of dispersal dimorphism could be a first step towards speciation and local adaptation.} +} + +@article{matthysenDensitydependentDispersalBirds2005, + title = {Density-Dependent Dispersal in Birds and Mammals}, + author = {Matthysen, Erik}, + year = {2005}, + journal = {Ecography}, + volume = {28}, + number = {3}, + pages = {403--416}, + issn = {1600-0587}, + doi = {10.1111/j.0906-7590.2005.04073.x}, + abstract = {Density-dependent dispersal can be caused by various mechanisms, from competition inducing individuals to emigrate (positive density-dependence) to social crowding effects impeding free movement (negative density-dependence). Various spatial population models have incorporated positively density-dependent dispersal algorithms, and recent theoretical models have explored the conditions for density-dependent dispersal (DD) to evolve. However, while the existence of DD is well documented in some taxa such as insects, there is no clear picture on its generality in vertebrates. Here I review the available empirical data on DD in birds and mammals, focusing mainly on variation in dispersal between years and on experimental density manipulations. Surprisingly few studies have explicitly focused on DD, and interpretation of the available data is often hampered by differences in approach, small sample sizes and/or statistical shortcomings. Positive DD was reported in 50 and 33\% of the selected mammal and bird studies, respectively, while two studies on mammals (out of eight) reported negative DD. Among bird studies, DD was more often reported for emigration rates or long-distance recoveries than for average distances within finite study areas. Experimental studies manipulating densities (mainly on mammals) have consistently generated positive DD, typically showing reduced emigration in response to partial population removal. Studies that examined dispersal in relation to seasonal changes in density (small mammals only) have more often reported negative DD. Studies that compared dispersal between sites differing in density, also show a mixture of positive and negative DD. This suggests that dispersal changes in a more complex way with seasonal and spatial density variation than with annual densities, and/or that these results are confounded by other factors differing between seasons and sites, such as habitat quality. I conclude that both correlational and experimental studies support the existence of positive, rather than negative, density-dependent dispersal in birds and mammals.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.0906-7590.2005.04073.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\LV8BYIUJ\\Matthysen - 2005 - Density-dependent dispersal in birds and mammals.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\FT5PD7Y5\\j.0906-7590.2005.04073.html} +} + +@incollection{matthysenMulticausalityDispersalReview2012, + title = {Multicausality of Dispersal: A Review}, + shorttitle = {Multicausality of Dispersal}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Matthysen, Erik}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0001}, + abstract = {This chapter reviews the main causes leading to dispersal, and emphasises its proximate factors. Dispersal is the main mechanism leading to gene flow within and between populations, and is defined as the movement of an individual from site of birth to site of reproduction or its movement between successive sites of reproduction. Causality in dispersal here is considered as any factor that explains variation among individuals in any component of dispersal. Following a general introduction, the different types of causal factors that may explain dispersal patterns are reviewed. The chapter begins with a discussion of the concept of dispersal. This is followed by a brief discussion of its ultimate explications. Lastly, an overview of its different possible mechanisms.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {causality in dispersal,dispersal,gene flow,site of birth,site of reproduction} +} + +@article{mclaughlinClimateChangeHastens2002, + title = {{Climate change hastens population extinctions}}, + author = {McLaughlin, John F. and Hellmann, Jessica J. and Boggs, Carol L. and Ehrlich, Paul R.}, + year = {2002}, + month = apr, + journal = {Proceedings of the National Academy of Sciences of the United States of America}, + volume = {99}, + number = {9}, + pages = {6070--6074}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424}, + doi = {10.1073/pnas.052131199}, + langid = {English (US)}, + pmid = {11972020}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ZBIGGYI2\\McLaughlin et al. - 2002 - Climate change hastens population extinctions.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\FNQ8GFK8\\climate-change-hastens-population-extinctions.html} +} + +@article{mcpeekEvolutionDispersalSpatially1992, + title = {The {{Evolution}} of {{Dispersal}} in {{Spatially}} and {{Temporally Varying Environments}}}, + author = {McPeek, Mark A. and Holt, Robert D.}, + year = {1992}, + journal = {The American Naturalist}, + volume = {140}, + number = {6}, + pages = {1010--1027}, + publisher = {{[University of Chicago Press, American Society of Naturalists]}}, + issn = {0003-0147}, + abstract = {Using a simple two-patch model, we examine how patterns of spatial and temporal variation in carrying capacities affect natural selection on dispersal. The size of the population in each patch is regulated separately, according to a discrete-generation logistic equation, and individuals disperse from each patch at propensities determined by their genotype. We consider genotypes that express the same dispersal propensities in both patches and genotypes that express patch-specific disperal propensities. Contrary to previous analyses, our results show that some level of dispersal is favored by selection under almost all regimes of habitat variability, including a spatially varying and temporally constant environment. Furthermore, two very different polymorphisms are favored under different conditions. When carrying capacities vary spatially but not temporally, any number of genotypes with patch-specific dispersal propensities in ratios inversely proportional to the ratio of the carrying capacities can coexist. This result extends previous analyses to show that dispersal is favored in such an environment if individuals can alter dispersal propensities in response to environmental cues. In contrast, when carrying capacities vary both spatially and temporally but differ in mean or variance, a polymorphism of only two genotypes (a high-dispersal and a no-dispersal genotype) is favored when the only genotypes possible are ones expressing the same dispersal propensity in both patches. However, this dimorphism can be invaded and replaced by one genotype with a particular combination of patch-specific dispersal propensities in a ratio also inversely proportional to the ratio of the average population sizes. We discuss a number of testable predictions this model suggests about the amounts of phenotypic and genetic variation in dispersal characters that are expected both within and between populations, and the degree to which the expression of phenotypic characters affecting dispersal propensity should be sensitive to environmental conditions. The model also suggests novel mechanisms for coexistence between competing species in varying environments.} +} + +@article{merckxEvolutionMovementsBehaviour2003, + title = {The Evolution of Movements and Behaviour at Boundaries in Different Landscapes: A Common Arena Experiment with Butterflies}, + shorttitle = {The Evolution of Movements and Behaviour at Boundaries in Different Landscapes}, + author = {Merckx, Thomas and Dyck, Hans Van and Karlsson, Bengt and Leimar, Olof}, + year = {2003}, + month = sep, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {270}, + number = {1526}, + pages = {1815--1821}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2003.2459}, + abstract = {As landscapes change, mobility patterns of species may alter. Different mechanistic scenarios may, however, lead to particular patterns. Here, we tested conflicting predictions from two hypotheses on butterfly movements in relation to habitat fragmentation. According to the resource distribution hypothesis, butterflies in more fragmented landscapes would have higher levels of mobility as resources are more scattered. However, these butterflies could have lower levels of mobility as they experience `hard' habitat boundaries more frequently (i.e. higher crossing costs) compared with butterflies in landscapes with continuous habitat; i.e. the behaviour\textendash at\textendash boundaries hypothesis. We studied movements, habitat boundary crossing and habitat preference of laboratory\textendash reared individuals of Pararge aegeria that originated from woodland and agricultural landscapes, by using an experimental landscape as a common environment (outdoor cages) to test the predictions, taking into account sexual differences and weather. Woodland butterflies covered longer distances, were more prone to cross open\textendash shade boundaries, travelled more frequently between woodland parts of the cages and were more at flight than agricultural butterflies. Our results support the behaviour\textendash at\textendash boundaries hypothesis, with `softer' boundaries for woodland landscapes. Because the butterflies were reared in a common environment, the observed behavioural differences rely on heritable variation between populations from woodland and agricultural landscapes.}, + keywords = {butterflies,dispersal,fragmentation,habitat exploration,movements}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HA5VVEYF\\Merckx et al. - 2003 - The evolution of movements and behaviour at bounda.pdf} +} + +@article{merckxLandscapeStructurePhenotypic2006, + title = {Landscape Structure and Phenotypic Plasticity in Flight Morphology in the Butterfly {{Pararge}} Aegeria}, + author = {Merckx, Thomas and Dyck, Hans Van}, + year = {2006}, + journal = {Oikos}, + volume = {113}, + number = {2}, + pages = {226--232}, + issn = {1600-0706}, + doi = {10.1111/j.2006.0030-1299.14501.x}, + abstract = {In evolutionary time, varying environments may lead to different morphs as a result of genetic adaptation and divergence or phenotypic plasticity. Landscapes that differ in the extent of habitat fragmentation may provide different selection regimes for dispersal, but also for other ecological functions. Several studies on flying insects have shown differences in flight morphology between landscapes, but whether such differences result from plastic responses have rarely been tested. We did a reciprocal transplant experiment with offspring of speckled wood butterfly females (Parargeaegeria) from three types of landscape differing in fragmentation: woodland landscape, landscape with woodland fragments and agricultural landscape with only hedgerows. Young caterpillars were allowed to grow individually on potted host grasses in small enclosures under the three landscape conditions (split-brood design). Mortality in caterpillars was much higher in agricultural landscape compared to the other landscapes. Additive to the effect of landscape of development, landscape of origin also affected mortality rate in a similar way. Flight morphology of the adults resulting from the experiment differed significantly with landscape. Independent of the landscape of origin, males and females that developed in agricultural landscape were the heaviest and had the greatest wing loadings. Females that developed in agricultural landscape had higher relative thorax mass (i.e. greater flight muscle allocation) in line with adaptive predictions on altered dispersal behaviour with type of landscape. In males, relative thorax mass did not respond significantly relative to landscape of development, but males originating from landscape with woodland fragments allocated more into their thorax compared to males from the other types. We found significant G\texttimes E interactions for total dry mass and wing loading. Our results suggest the existence of phenotypic plasticity in butterfly flight morphology associated with landscape structure.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.2006.0030-1299.14501.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\D9SH6LTA\\Merckx und Dyck - 2006 - Landscape structure and phenotypic plasticity in f.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\ACGPY298\\j.2006.0030-1299.14501.html} +} + +@article{metzHowShouldWe2001, + title = {How Should We Define Fitness in Structured Metapopulation Models? {{Including}} an Application to the Calculation of Evolutionarily Stable Dispersal Strategies}, + shorttitle = {How Should We Define Fitness in Structured Metapopulation Models?}, + author = {Metz, J. a. J. and Gyllenberg, M.}, + year = {2001}, + month = mar, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {268}, + number = {1466}, + pages = {499--508}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2000.1373}, + abstract = {We define a fitness concept applicable to structured metapopulations consisting of infinitely many equally coupled patches. In addition, we introduce a more easily calculated quantity Rm that relates to fitness in the same manner as R0 relates to fitness in ordinary population dynamics: the Rm of a mutant is only defined when the resident population dynamics converges to a point equilibrium and Rm is larger (smaller) than 1 if and only if mutant fitness is positive (negative). Rm corresponds to the average number of newborn dispersers resulting from the (on average less than one) local colony founded by a newborn disperser. Efficient algorithms for calculating its numerical value are provided. As an example of the usefulness of these concepts we calculate the evolutionarily stable conditional dispersal strategy for individuals that can account for the local population density in their dispersal decisions. Below a threshold density \~a, at which staying and leaving are equality profitable, everybody should stay and above \~a everybody should leave, where profitability is measured as the mean number of dispersers produced through lines of descent consisting of only non\textendash dispersers.}, + keywords = {dispersal,evolutionary ecology,fitness,metapopulation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GHK3HBZM\\Metz und Gyllenberg - 2001 - How should we define fitness in structured metapop.pdf} +} + +@article{midgleyBioMoveIntegratedPlatform2010, + title = {{{BioMove}} \textendash{} an Integrated Platform Simulating the Dynamic Response of Species to Environmental Change}, + author = {Midgley, Guy F. and Davies, Ian D. and Albert, C{\'e}cile H. and Altwegg, Res and Hannah, Lee and Hughes, Gregory O. and O'Halloran, Lydia R. and Seo, Changwan and Thorne, James H. and Thuiller, Wilfried}, + year = {2010}, + journal = {Ecography}, + volume = {33}, + number = {3}, + pages = {612--616}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2009.06000.x}, + abstract = {BioMove simulates plant species' geographic range shifts in response to climate, habitat structure and disturbance, at annual time steps. This spatially explicit approach integrates species' bioclimatic suitability and population-level demographic rates with simulation of landscape-level processes (dispersal, disturbance, species' response to dynamic dominant vegetation structure). Species population dynamics are simulated through matrix modelling that includes scaling demographic rates by climatic suitability. Dispersal functions simulate population spread. User-specified plant functional types (PFTs) provide vegetation structure that determines resource competition and disturbance. PFTs respond annually through dispersal, inter-PFT competition and demographic shifts. BioMove provides a rich framework for dynamic range simulations.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2009.06000.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GEVPZ5KT\\Midgley et al. - 2010 - BioMove – an integrated platform simulating the dy.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\SAGTYKRD\\j.1600-0587.2009.06000.html} +} + +@article{millerSexbiasedDispersalSpeed2011, + title = {Sex-Biased Dispersal and the Speed of Two-Sex Invasions}, + author = {Miller, Tom E. X. and Shaw, Allison K. and Inouye, Brian D. and Neubert, Michael G.}, + year = {2011}, + month = may, + journal = {The American Naturalist}, + volume = {177}, + number = {5}, + pages = {549--561}, + issn = {1537-5323}, + doi = {10.1086/659628}, + abstract = {Population models that combine demography and dispersal are important tools for forecasting the spatial spread of biological invasions. Current models describe the dynamics of only one sex (typically females). Such models cannot account for the sex-related biases in dispersal and mating behavior that are typical of many animal species. In this article, we construct a two-sex integrodifference equation model that overcomes these limitations. We derive an explicit formula for the invasion speed from the model and use it to show that sex-biased dispersal may significantly increase or decrease the invasion speed by skewing the operational sex ratio at the invasion's low-density leading edge. Which of these possible outcomes occurs depends sensitively on complex interactions among the direction of dispersal bias, the magnitude of bias, and the relative contributions of females and males to local population growth.}, + langid = {english}, + pmid = {21508603}, + keywords = {Animals,Female,Introduced Species,Male,Models; Biological,Population Dynamics,Sex Characteristics}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VSWI5WN7\\Miller et al. - 2011 - Sex-biased dispersal and the speed of two-sex inva.pdf} +} + +@article{millerSexStochasticityAffect2013, + title = {Sex and Stochasticity Affect Range Expansion of Experimental Invasions}, + author = {Miller, Tom E. X. and Inouye, Brian D.}, + year = {2013}, + month = mar, + journal = {Ecology Letters}, + volume = {16}, + number = {3}, + pages = {354--361}, + issn = {1461-0248}, + doi = {10.1111/ele.12049}, + abstract = {Understanding and predicting range expansion are key objectives in many basic and applied contexts. Among dioecious organisms, there is strong evidence for sex differences in dispersal, which could alter the sex ratio at the expansion's leading edge. However, demographic stochasticity could also affect leading-edge sex ratios, perhaps overwhelming sex-biased dispersal. We used insects in laboratory mesocosms to test the effects of sex-biased dispersal on range expansion, and a simulation model to explore interactive effects of sex-biased dispersal and demographic stochasticity. Sex-biased dispersal created spatial clines in the sex ratio, which influenced offspring production at the front and altered invasion velocity. Increasing female dispersal relative to males accelerated spread, despite the prediction that demographic stochasticity would weaken a signal of sex-biased dispersal. Our results provide the first experimental evidence for an influence of sex-biased dispersal on invasion velocity, highlighting the value of accounting for sex structure in studies of range expansion.}, + langid = {english}, + pmid = {23237200}, + keywords = {Animal Distribution,Animals,Coleoptera,Computer Simulation,Female,Male,Models; Biological,Population Growth,Sex Factors}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\FILVYCMY\\Miller und Inouye - 2013 - Sex and stochasticity affect range expansion of ex.pdf} +} + +@article{mitikkaRangeExpansionEuropean2010, + title = {The Range Expansion of the {{European}} Map Butterfly in {{Finland}}}, + author = {Mitikka, Varpu}, + year = {2010}, + month = mar, + publisher = {{Helsingin yliopisto}}, + abstract = {Climate change will influence the living conditions of all life on Earth. For some species the change in the environmental conditions that has occurred so far has already increased the risk of extinction, and the extinction risk is predicted to increase for large numbers of species in the future. Some species may have time to adapt to the changing environmental conditions, but the rate and magnitude of the change are too great to allow many species to survive via evolutionary changes. Species responses to climate change have been documented for some decades. Some groups of species, like many insects, respond readily to changes in temperature conditions and have shifted their distributions northwards to new climatically suitable regions. Such range shifts have been well documented especially in temperate zones. In this context, butterflies have been studied more than any other group of species, partly for the reason that their past geographical ranges are well documented, which facilitates species-climate modelling and other analyses. The aim of the modelling studies is to examine to what extent shifts in species distributions can be explained by climatic and other factors. Models can also be used to predict the future distributions of species. In this thesis, I have studied the response to climate change of one species of butterfly within one geographically restricted area. The study species, the European map butterfly (Araschnia levana), has expanded rapidly northwards in Finland during the last two decades. I used statistical and dynamic modelling approaches in combination with field studies to analyse the effects of climate warming and landscape structure on the expansion. I studied possible role of molecular variation in phosphoglucose isomerase (PGI), a glycolytic enzyme affecting flight metabolism and thereby flight performance, in the observed expansion of the map butterfly at two separate expansion fronts in Finland. The expansion rate of the map butterfly was shown to be correlated with the frequency of warmer than average summers during the study period. The result is in line with the greater probability of occurrence of the second generation during warm summers and previous results on this species showing greater mobility of the second than first generation individuals. The results of a field study in this thesis indicated low mobility of the first generation butterflies. Climatic variables alone were not sufficient to explain the observed expansion in Finland. There are also problems in transferring the climate model to new regions from the ones from which data were available to construct the model. The climate model predicted a wider distribution in the south-western part of Finland than what has been observed. Dynamic modelling of the expansion in response to landscape structure suggested that habitat and landscape structure influence the rate of expansion. In southern Finland the landscape structure may have slowed down the expansion rate. The results on PGI suggested that allelic variation in this enzyme may influence flight performance and thereby the rate of expansion. Genetic differences of the populations at the two expansion fronts may explain at least partly the observed differences in the rate of expansion. Individuals with the genotype associated with high flight metabolic rate were most frequent in eastern Finland, where the rate of range expansion has been highest.}, + copyright = {Julkaisu on tekij\"anoikeuss\"a\"ann\"osten alainen. Teosta voi lukea ja tulostaa henkil\"okohtaista k\"aytt\"o\"a varten. K\"aytt\"o kaupallisiin tarkoituksiin on kielletty.}, + isbn = {9789521061462}, + langid = {english}, + annotation = {Accepted: 2010-11-25T13:18:36Z}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ECPF4G3G\\Mitikka - 2010 - The range expansion of the European map butterfly .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\B65UEQXI\\22114.html} +} + +@article{moralesBehaviorHabitatBoundaries2002, + title = {Behavior at {{Habitat Boundaries Can Produce Leptokurtic Movement Distributions}}.}, + author = {Morales, Juan Manuel}, + year = {2002}, + month = oct, + journal = {The American Naturalist}, + volume = {160}, + number = {4}, + pages = {531--538}, + publisher = {{The University of Chicago Press}}, + issn = {0003-0147}, + doi = {10.1086/342076}, + keywords = {correlated random walk,diffusion,edge effects,kurtosis,landscape heterogeneity,movement}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\H7T3TLJK\\Morales - 2002 - Behavior at Habitat Boundaries Can Produce Leptoku.pdf} +} + +@article{moralesBuildingBridgeAnimal2010a, + title = {Building the Bridge between Animal Movement and Population Dynamics}, + author = {Morales, Juan M. and Moorcroft, Paul R. and Matthiopoulos, Jason and Frair, Jacqueline L. and Kie, John G. and Powell, Roger A. and Merrill, Evelyn H. and Haydon, Daniel T.}, + year = {2010}, + month = jul, + journal = {Philosophical Transactions of the Royal Society B: Biological Sciences}, + volume = {365}, + number = {1550}, + pages = {2289--2301}, + publisher = {{Royal Society}}, + doi = {10.1098/rstb.2010.0082}, + abstract = {While the mechanistic links between animal movement and population dynamics are ecologically obvious, it is much less clear when knowledge of animal movement is a prerequisite for understanding and predicting population dynamics. GPS and other technologies enable detailed tracking of animal location concurrently with acquisition of landscape data and information on individual physiology. These tools can be used to refine our understanding of the mechanistic links between behaviour and individual condition through `spatially informed' movement models where time allocation to different behaviours affects individual survival and reproduction. For some species, socially informed models that address the movements and average fitness of differently sized groups and how they are affected by fission\textendash fusion processes at relevant temporal scales are required. Furthermore, as most animals revisit some places and avoid others based on their previous experiences, we foresee the incorporation of long-term memory and intention in movement models. The way animals move has important consequences for the degree of mixing that we expect to find both within a population and between individuals of different species. The mixing rate dictates the level of detail required by models to capture the influence of heterogeneity and the dynamics of intra- and interspecific interaction.}, + keywords = {demography,dispersal,perfect mixing,redistribution kernels,spatial ecology,time budgets}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\49RJGBRA\\Morales et al. - 2010 - Building the bridge between animal movement and po.pdf} +} + +@article{moralesScalingAnimalMovements2002, + title = {Scaling up {{Animal Movements}} in {{Heterogeneous Landscapes}}: {{The Importance}} of {{Behavior}}}, + shorttitle = {Scaling up {{Animal Movements}} in {{Heterogeneous Landscapes}}}, + author = {Morales, Juan Manuel and Ellner, Stephen P.}, + year = {2002}, + journal = {Ecology}, + volume = {83}, + number = {8}, + pages = {2240--2247}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + doi = {10.2307/3072055}, + abstract = {Two major challenges of spatial ecology are understanding the effects of landscape heterogeneity on movement, and translating observations taken at small spatial and temporal scales into expected patterns at greater scales. Using a combination of computer simulations and micro-landscape experiments with Tribolium confusum beetles we found that conventional correlated random walk models with constant parameters severely underestimated spatial spread because organisms changed movement behaviors over time. However, a model incorporating behavioral heterogeneity between individuals, and within individuals over time, was able to account for observed patterns of spread. Our results suggest that the main challenge for scaling up movement patterns resides in the complexities of individual behavior rather than in the spatial structure of the landscape.} +} + +@article{munozWindLongDistanceDispersal2004, + title = {Wind as a {{Long-Distance Dispersal Vehicle}} in the {{Southern Hemisphere}}}, + author = {Mu{\~n}oz, Jes{\'u}s and Felic{\'i}simo, {\'A}ngel M. and Cabezas, Francisco and Burgaz, Ana R. and Mart{\'i}nez, Isabel}, + year = {2004}, + month = may, + journal = {Science}, + volume = {304}, + number = {5674}, + pages = {1144--1147}, + publisher = {{American Association for the Advancement of Science}}, + issn = {0036-8075, 1095-9203}, + doi = {10.1126/science.1095210}, + abstract = {Anisotropic (direction-dependent) long-distance dispersal (LDD) by wind has been invoked to explain the strong floristic affinities shared among landmasses in the Southern Hemisphere. Its contribution has not yet been systematically tested because of the previous lack of global data on winds. We used global winds coverage from the National Aeronautics and Space Administration SeaWinds scatterometer to test whether floristic similarities of Southern Hemisphere moss, liverwort, lichen, and pteridophyte floras conform better with (i) the anisotropic LDD hypothesis, which predicts that connection by ``wind highways'' increases floristic similarities, or (ii) a direction-independent LDD hypothesis, which predicts that floristic similarities among sites increase with geographic proximity. We found a stronger correlation of floristic similarities with wind connectivity than with geographic proximities, which supports the idea that wind is a dispersal vehicle for many organisms in the Southern Hemisphere. Wind patterns, not geographical proximity, best explain the distribution of lower plants in the Southern Hemisphere. Wind patterns, not geographical proximity, best explain the distribution of lower plants in the Southern Hemisphere.}, + chapter = {Report}, + copyright = {American Association for the Advancement of Science}, + langid = {english}, + pmid = {15155945}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\7BWCQBSH\\Muñoz et al. - 2004 - Wind as a Long-Distance Dispersal Vehicle in the S.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\V7BXQ37E\\1144.html} +} + +@article{murrellEvolutionDispersalDistance2002, + title = {The Evolution of Dispersal Distance in Spatially Structured Populations}, + author = {Murrell, David and Travis, Justin and Dytham, Calvin}, + year = {2002}, + month = may, + journal = {Oikos}, + volume = {97}, + doi = {10.1034/j.1600-0706.2002.970209.x}, + abstract = {Most evolutionary models of dispersal have concentrated on dispersal rate, with emigration being either global or restricted to nearest neighbours. Yet most organisms fall into an intermediate region where most dispersal is local but there is a wide range of dispersal distances. We use an individual-based model with 2500 patches each with identical local dynamics and show that the dispersal distance is under selection pressure. The dispersal distance that evolves is critically dependent on the ecological dynamics. When the cost of dispersal increases linearly with distance, selection is for short-distance dispersal under stable and damped local dynamics but longer distance dispersal is favoured as local dynamics become more complex. For the cases of stable, damped and periodic patch dynamics global patch synchrony occurs even with very short-distance dispersal. Increasing the scale of dispersal for chaotic local dynamics increases the scale of synchrony but global synchrony does not neccesarily occur. We discuss these results in the light of other possible causes of dispersal and argue for the importance of incorporating non-equilibrium population dynamics into evolutionary models of dispersal distance.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ENLB2BRA\\Murrell et al. - 2002 - The evolution of dispersal distance in spatially s.pdf} +} + +@article{mustinDynamicsClimateInducedRange2009, + title = {The {{Dynamics}} of {{Climate-Induced Range Shifting}}; {{Perspectives}} from {{Simulation Modelling}}}, + author = {Mustin, Karen and Benton, Tim G. and Dytham, Calvin and Travis, Justin M. J.}, + year = {2009}, + journal = {Oikos}, + volume = {118}, + number = {1}, + pages = {131--137}, + publisher = {{[Nordic Society Oikos, Wiley]}}, + issn = {0030-1299}, + abstract = {Predicted future climate change will alter species' distributions as they attempt to track the most suitable ' climate window'. Climate envelope models indicate the direction of likely range changes but do not incorporate population dynamics, therefore observed responses may differ greatly from these projections. We use simulation modelling to explore the consequences of a period of environmental change for a species structured across an environmental gradient. Results indicate that a species' range may lag behind its climate envelope and demonstrate that the rate of movement of a range can accelerate during a period of climate change. We conclude that the inclusion of both population dynamics and spatial environmental variability is vital to develop models that can both predict, and be used to manage, the impact of changing climate on species' biogeography.} +} + +@article{mustinRedNoiseIncreases2013, + title = {Red Noise Increases Extinction Risk during Rapid Climate Change}, + author = {Mustin, Karen and Dytham, Calvin and Benton, Tim G. and Travis, Justin M. J.}, + year = {2013}, + journal = {Diversity and Distributions}, + volume = {19}, + number = {7}, + pages = {815--824}, + issn = {1472-4642}, + doi = {10.1111/ddi.12038}, + abstract = {Aim As the global climate is changing rapidly, there is a need to make conservation decisions to facilitate species' persistence under climate change. Models employed to make predictions regarding the impacts of climate change on species' distributions, and ultimately persistence, typically assume that interannual variability in environmental conditions is independent between years. However, the colour of environmental noise has been shown to affect extinction risk in populations occupying spatially static environments, and should therefore affect persistence during climate change. This study aims to investigate the importance of noise colour for extinction risk during climate-induced range shifts. Methods We use a spatially explicit coupled map lattice with a latitudinal gradient in climatic suitability, together with time series of environmental noise, to simulate periods of directional climate change and investigate the effects of noise colour on extinction risk and range size. Results Extinction risk increases with reddening of the environmental noise, and this effect is particularly pronounced over short time frames when climate change is rapid. Main conclusions Given that management decisions are typically made over such short time frames, and the rapid rates of climate change currently being experienced, we highlight the importance of incorporating realistic time series of environmental noise into models used for conservation planning under climate change.}, + langid = {english}, + keywords = {Climate change,colour,environmental noise,extinction risk,range shifting,spatial population dynamics}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ddi.12038}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\CSU2RWSB\\Mustin et al. - 2013 - Red noise increases extinction risk during rapid c.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\W7EQWYA9\\ddi.html} +} + +@article{nathanDispersalKernelsReview2012, + title = {Dispersal Kernels: Review. {{Chapter}} 15}, + shorttitle = {Dispersal Kernels}, + author = {Nathan, Ran and Klein, Etienne and {Robledo-Anuncio}, J.J. and Revilla, Eloy}, + year = {2012}, + month = jan, + journal = {Dispersal Ecology and Evolution}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\9NC3YWW6\\Nathan et al. - 2012 - Dispersal kernels review. Chapter 15.pdf} +} + +@article{nathanMovementEcologyParadigm2008a, + title = {A Movement Ecology Paradigm for Unifying Organismal Movement Research}, + author = {Nathan, Ran and Getz, Wayne M. and Revilla, Eloy and Holyoak, Marcel and Kadmon, Ronen and Saltz, David and Smouse, Peter E.}, + year = {2008}, + month = dec, + journal = {Proceedings of the National Academy of Sciences}, + volume = {105}, + number = {49}, + pages = {19052--19059}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.0800375105}, + abstract = {Movement of individual organisms is fundamental to life, quilting our planet in a rich tapestry of phenomena with diverse implications for ecosystems and humans. Movement research is both plentiful and insightful, and recent methodological advances facilitate obtaining a detailed view of individual movement. Yet, we lack a general unifying paradigm, derived from first principles, which can place movement studies within a common context and advance the development of a mature scientific discipline. This introductory article to the Movement Ecology Special Feature proposes a paradigm that integrates conceptual, theoretical, methodological, and empirical frameworks for studying movement of all organisms, from microbes to trees to elephants. We introduce a conceptual framework depicting the interplay among four basic mechanistic components of organismal movement: the internal state (why move?), motion (how to move?), and navigation (when and where to move?) capacities of the individual and the external factors affecting movement. We demonstrate how the proposed framework aids the study of various taxa and movement types; promotes the formulation of hypotheses about movement; and complements existing biomechanical, cognitive, random, and optimality paradigms of movement. The proposed framework integrates eclectic research on movement into a structured paradigm and aims at providing a basis for hypothesis generation and a vehicle facilitating the understanding of the causes, mechanisms, and spatiotemporal patterns of movement and their role in various ecological and evolutionary processes. ''Now we must consider in general the common reason for moving with any movement whatever.`` (Aristotle, De Motu Animalium, 4th century B.C.)}, + chapter = {Perspective}, + copyright = {\textcopyright{} 2008 by The National Academy of Sciences of the USA}, + langid = {english}, + pmid = {19060196}, + keywords = {dispersal,foraging,migration,motion capacity,navigation capacity}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\A9QGRRWW\\Nathan et al. - 2008 - A movement ecology paradigm for unifying organisma.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\63VHJ7ZD\\19052.html} +} + +@article{nathanSpreadNorthAmerican2011, + title = {Spread of {{North American}} Wind-dispersed Trees in Future Environments}, + author = {Nathan, R. and Horvitz, N and He, Y and Kuparinen, A and Schurr, F. M. and Katul, G. G.}, + year = {2011}, + journal = {Ecology Letters}, + number = {14}, + pages = {211--219}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\TLLVVDB3\\j.1461-0248.2010.01573.html} +} + +@article{neubertDensitydependentVitalRates2000, + title = {Density-Dependent Vital Rates and Their Population Dynamic Consequences}, + author = {Neubert, M. G. and Caswell, H. C.}, + year = {2000}, + month = aug, + journal = {Journal of Mathematical Biology}, + volume = {41}, + number = {2}, + pages = {103--121}, + issn = {0303-6812}, + doi = {10.1007/s002850070001}, + abstract = {We explore a set of simple, nonlinear, two-stage models that allow us to compare the effects of density dependence on population dynamics among different kinds of life cycles. We characterize the behavior of these models in terms of their equilibria, bifurcations. and nonlinear dynamics, for a wide range of parameters. Our analyses lead to several generalizations about the effects of life history and density dependence on population dynamics. Among these are: (1) iteroparous life histories are more likely to be stable than semelparous life histories; (2) an increase in juvenile survivorship tends to be stabilizing; (3) density-dependent adult survival cannot control population growth when reproductive output is high: (4) density-dependent reproduction is more likely to cause chaotic dynamics than density dependence in other vital rates; and (5) changes in development rate have only small effects on bifurcation patterns.}, + langid = {english}, + pmid = {11039693}, + keywords = {Animals,Birds,Fishes,Humans,Insecta,Mammals,Models; Biological,Numerical Analysis; Computer-Assisted,Plant Development,Population Density,Population Dynamics} +} + +@article{norbergEcoevolutionaryResponsesBiodiversity2012, + title = {Eco-Evolutionary Responses of Biodiversity to Climate Change}, + author = {Norberg, Jon and Urban, Mark C. and Vellend, Mark and Klausmeier, Christopher A. and Loeuille, Nicolas}, + year = {2012}, + month = oct, + journal = {Nature Climate Change}, + volume = {2}, + number = {10}, + pages = {747--751}, + publisher = {{Nature Publishing Group}}, + issn = {1758-6798}, + doi = {10.1038/nclimate1588}, + abstract = {This study describes the development of a multi-species model used to explore the integrated eco-evolutionary responses to climate change. The results should help to understand and predict the responses of biological diversity, ecosystems, and ecological services to changing climate.}, + copyright = {2012 Nature Publishing Group}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Research Subject\_term: Biodiversity;Climate change;Evolutionary ecology Subject\_term\_id: biodiversity;climate-change;evolutionary-ecology}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\YGNYRLK5\\nclimate1588.html} +} + +@article{northEvolutionaryResponsesDispersal2011, + title = {Evolutionary Responses of Dispersal Distance to Landscape Structure and Habitat Loss}, + author = {North, Ace and Cornell, Stephen and Ovaskainen, Otso}, + year = {2011}, + month = jun, + journal = {Evolution; International Journal of Organic Evolution}, + volume = {65}, + number = {6}, + pages = {1739--1751}, + issn = {1558-5646}, + doi = {10.1111/j.1558-5646.2011.01254.x}, + abstract = {It is generally well understood that some ecological factors select for increased and others for decreased dispersal. However, it has remained difficult to assess how the evolutionary dynamics are influenced by the spatio-temporal structure of the environment. We address this question with an individual-based model that enables habitat structure to be controlled through variables such as patch size, patch turnover rate, and patch quality. Increasing patch size at the expense of patch density can select for more or less dispersal, depending on the initial configuration. In landscapes consisting of high-quality and long-lived habitat patches, patch degradation selects for increased dispersal, yet patch loss may select for reduced dispersal. These trends do not depend on the component of life-history that is affected by habitat quality or the component of life-history through which density-dependence operates. Our results are based on a mathematical method that enables derivation of both the evolutionary stable strategy and the stationary genotype distribution that evolves in a polymorphic population. The two approaches generally lead to similar predictions. However, the evolutionary stable strategy assumes that the ecological and evolutionary time scales can be separated, and we find that violation of this assumption can critically alter the evolutionary outcome.}, + langid = {english}, + pmid = {21644960}, + keywords = {Biological Evolution,Ecosystem,Logistic Models,Models; Biological,Mutation,Polymorphism; Genetic,Population Dynamics,Selection; Genetic}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\AWCPHKBY\\North et al. - 2011 - Evolutionary responses of dispersal distance to la.pdf} +} + +@article{okamotoFrameworkHighthroughputEcoevolutionary2018, + title = {A Framework for High-Throughput Eco-Evolutionary Simulations Integrating Multilocus Forward-Time Population Genetics and Community Ecology}, + author = {Okamoto, Kenichi W. and Amarasekare, Priyanga}, + year = {2018}, + journal = {Methods in Ecology and Evolution}, + volume = {9}, + number = {3}, + pages = {525--534}, + issn = {2041-210X}, + doi = {10.1111/2041-210X.12889}, + abstract = {The evolutionary dynamics of quantitative traits in a species depends on demographic structure (e.g. age- and size-dependent vital rates, migration across subpopulations, mate preferences, and the presence or absence of overlapping generations), which in turn can depend on interspecific interactions with other evolving species. Furthermore, biologists increasingly appreciate that evolutionary change in a single species can substantively affect broader ecological processes, such as community assembly and ecosystem functioning. Models integrating insights from classical population and quantitative genetics, on the one hand, and community ecology theory, on the other, are therefore critical to elucidating the interplay between ecological and evolutionary processes. However, few modelling approaches integrate ecological and genetic details into a comprehensive framework. Such models are needed to account for the reciprocal feedback between evolutionary change and ecological dynamics, and develop effective responses to anthropogenic disturbances on natural communities, improve agricultural practices and manage global health risks such as emerging pathogens. Here we introduce an open-source, multi-species forward-time population genetics simulator and framework for rapidly simulating eco-evolutionary dynamics. Our approach permits building models that can account for alternative genetic architectures, non-standard population dynamics and demographic structures, including those driven by interspecific interactions with other evolving species and the spatial dynamics of metacommunities. By integrating these processes into a common framework, we aim to facilitate the development of models that can further elucidate eco-evolutionary dynamics. While multi-species, forward-time population genetic models can be computationally expensive, we show how our framework leverages relatively economical graphics cards installed in modern desktops. We illustrate the versatility and general applicability of our approach for two very different case studies: antagonistic coevolution in space, and the evolution of life-history traits in response to resource dynamics in physiologically structured populations. We find that our analyses can run up to c. 200 times faster on a single commodity graphics card than on a single CPU core, comparable to the performance gains on small-to-medium sized computer clusters. Our approach therefore substantively reduces implementation difficulties to integrating ecological and evolutionary theory.}, + langid = {english}, + keywords = {community ecology,cuda,eco-evolutionary dynamics,forward-time population genetics models,individual-based models,parallel computing}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/2041-210X.12889}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\TMSBSGVN\\Okamoto und Amarasekare - 2018 - A framework for high-throughput eco-evolutionary s.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\3BIUZ9BL\\2041-210X.html} +} + +@article{oldenContextdependentPerceptualRanges2004, + title = {Context-Dependent Perceptual Ranges and Their Relevance to Animal Movements in Landscapes}, + author = {Olden, Julian D. and Schooley, Robert L. and Monroe, Jeremy B. and Poff, N. Leroy}, + year = {2004}, + journal = {Journal of Animal Ecology}, + volume = {73}, + number = {6}, + pages = {1190--1194}, + issn = {1365-2656}, + doi = {10.1111/j.0021-8790.2004.00889.x}, + abstract = {1 An animal's perceptual range defines the spatial extent of the landscape for which information is available to make movement decisions. Ecologists studying and modelling animal dispersal have commonly assumed that individual movements arise from a predefined set of local decision rules operating within a static isotropic (i.e. circular) perceptual range. 2 We discuss how this assumption fails to recognize the potential for plasticity in perceptual ranges and present a conceptual model that illustrates how anisotropic perceptual ranges can arise from animal orientation to environmental stimuli. 3 Using model simulations we show how perceptual distance (i.e. greatest Euclidean distance at which habitat patches can be perceived), horizon (i.e. panoramic view or angular degrees of the landscape perceived) and breadth (i.e. areal extent of the landscape perceived), change as a function of increased strength of a hypothetical stimuli. 4 Our results show that anisotropic perceptual ranges can differ substantially from traditional, isotropic perceptual ranges in all three aspects depending on the strength of the stimuli and nature in which it interacts with other elements of the landscape. 5 We highlight the implications of these findings for modelling animal movements in ecological landscapes with the hope that context-dependent perceptual ranges are considered in future studies.}, + langid = {english}, + keywords = {anisotropic,behaviour,connectivity,isotropic,orientation,patch context}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.0021-8790.2004.00889.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QFFEYIVB\\Olden et al. - 2004 - Context-dependent perceptual ranges and their rele.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\ADLCYEJ2\\j.0021-8790.2004.00889.html} +} + +@article{opdamClimateChangeMeets2004, + title = {Climate Change Meets Habitat Fragmentation: Linking Landscape and Biogeographical Scale Levels in Research and Conservation}, + shorttitle = {Climate Change Meets Habitat Fragmentation}, + author = {Opdam, Paul and Wascher, Dirk}, + year = {2004}, + month = may, + journal = {Biological Conservation}, + volume = {117}, + number = {3}, + pages = {285--297}, + issn = {0006-3207}, + doi = {10.1016/j.biocon.2003.12.008}, + abstract = {Climate change and habitat fragmentation are considered key pressures on biodiversity. In this paper we explore the potential synergetic effects between these factors. We argue that processes at two levels of spatial scale interact: the metapopulation level and the species range level. Current concepts of spatially dynamic metapopulations and species ranges are consistent, and integration improves our understanding of the interaction of landscape level and geographical range level processes. In landscape zones in which the degree of habitat fragmentation allows persistence, the shifting of ranges is inhibited, but not blocked. In areas where the spatial cohesion of the habitat is below the critical level of metapopulation persistence, the expansion of ranges will be blocked. An increased frequency of large-scale disturbances caused by extreme weather events will cause increasing gaps and an overall contraction of the distribution range, particularly in areas with relatively low levels of spatial cohesion. Taking into account the effects of climate change on metapopulations, habitat distribution and land use changes, future biodiversity research and conservation strategies are facing the challenge to re-orient their focus and scope by integrating spatially and conceptually more dynamic aspects at the landscape level.}, + langid = {english}, + keywords = {Climate change,Geographical range,Habitat fragmentation,Habitat network,Metapopulation dynamics}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QRBYM366\\Opdam und Wascher - 2004 - Climate change meets habitat fragmentation linkin.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\PPS5IQ8F\\S0006320703004890.html} +} + +@article{ovaskainenBiasedMovementBoundary2003, + title = {Biased {{Movement}} at a {{Boundary}} and {{Conditional Occupancy Times}} for {{Diffusion Processes}}}, + author = {Ovaskainen, Otso and Cornell, Stephen J.}, + year = {2003}, + journal = {Journal of Applied Probability}, + volume = {40}, + number = {3}, + pages = {557--580}, + publisher = {{Applied Probability Trust}}, + issn = {0021-9002}, + abstract = {Motivated by edge behaviour reported for biological organisms, we show that random walks with a bias at a boundary lead to a discontinuous probability density across the boundary. We continue by studying more general diffusion processes with such a discontinuity across an interior boundary. We show how hitting probabilities, occupancy times and conditional occupancy times may be solved from problems that are adjoint to the original diffusion problem. We highlight our results with a biologically motivated example, where we analyze the movement behaviour of an individual in a network of habitat patches surrounded by dispersal habitat.} +} + +@article{ovaskainenEmpiricalTestDiffusion2008, + title = {An Empirical Test of a Diffusion Model: Predicting Clouded Apollo Movements in a Novel Environment}, + shorttitle = {An Empirical Test of a Diffusion Model}, + author = {Ovaskainen, Otso and Luoto, Miska and Ikonen, Iiro and Rekola, Hanna and Meyke, Evgeniy and Kuussaari, Mikko}, + year = {2008}, + month = may, + journal = {The American Naturalist}, + volume = {171}, + number = {5}, + pages = {610--619}, + issn = {1537-5323}, + doi = {10.1086/587070}, + abstract = {Functional connectivity is a fundamental concept in conservation biology because it sets the level of migration and gene flow among local populations. However, functional connectivity is difficult to measure, largely because it is hard to acquire and analyze movement data from heterogeneous landscapes. Here we apply a Bayesian state-space framework to parameterize a diffusion-based movement model using capture-recapture data on the endangered clouded apollo butterfly. We test whether the model is able to disentangle the inherent movement behavior of the species from landscape structure and sampling artifacts, which is a necessity if the model is to be used to examine how movements depend on landscape structure. We show that this is the case by demonstrating that the model, parameterized with data from a reference landscape, correctly predicts movements in a structurally different landscape. In particular, the model helps to explain why a movement corridor that was constructed as a management measure failed to increase movement among local populations. We illustrate how the parameterized model can be used to derive biologically relevant measures of functional connectivity, thus linking movement data with models of spatial population dynamics.}, + langid = {english}, + pmid = {18419523}, + keywords = {Algorithms,Animals,Bayes Theorem,Butterflies,Conservation of Natural Resources,Demography,Ecosystem,Finland,Models; Theoretical,Motor Activity,Population Dynamics} +} + +@article{ovaskainenHabitatSpecificMovementParameters2004, + title = {Habitat-{{Specific Movement Parameters Estimated Using Mark}}\textendash{{Recapture Data}} and a {{Diffusion Model}}}, + author = {Ovaskainen, Otso}, + year = {2004}, + journal = {Ecology}, + volume = {85}, + number = {1}, + pages = {242--257}, + issn = {1939-9170}, + doi = {10.1890/02-0706}, + abstract = {I describe a diffusion model aimed at the quantitative analysis of movement in heterogeneous landscapes. The model is based on classifying a landscape into a number of habitat types, which are assumed to differ from each other in terms of the movement behavior of the focal species. In addition to habitat-specific diffusion and mortality coefficients, the model accounts for edge-mediated behavior, meaning biased behavior close to boundaries between the habitat types. I illustrate the model with three examples. In the first example, I examine how the strength of edge-mediated behavior and the size of a habitat patch affect the probability that an individual will immigrate to a patch, the probability that an individual will emigrate from a patch, and the time that an individual is expected to spend in a patch. In the second example, I study how a dispersal corridor affects the probability that an individual will move through a landscape. In the third example, I estimate the movement parameters for a species of butterfly from mark\textendash recapture data. In the butterfly example, I classify the landscape into habitat patches, other open areas, and forests. Edge-mediated behavior is found to have a highly significant effect on the general dispersal pattern of the butterfly: the model predicts that the density of butterflies inside habitat patches is {$>$}100 times the density of butterflies in adjacent areas.}, + langid = {english}, + keywords = {butterflies,correlated random walk,diffusion model,dispersal corridor,edge-mediated behavior,habitat patch size,heterogeneous landscape,mark–recapture,Melitaea diamina,movement parameters}, + annotation = {\_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/02-0706}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ISFBXGBV\\Ovaskainen - 2004 - Habitat-Specific Movement Parameters Estimated Usi.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\IYFJ6IXN\\02-0706.html} +} + +@article{ovaskainenModelingAnimalMovement2009, + title = {{Modeling animal movement with diffusion}}, + author = {Ovaskainen, Otso and Crone, E. E.}, + year = {2009}, + journal = {Spatial Ecology}, + publisher = {{Chapman \& Hall / CRC}}, + langid = {finnish}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GZEAIB96\\modeling-animal-movement-with-diffusion.html} +} + +@article{ovaskainenTrackingButterflyMovements2008, + title = {Tracking Butterfly Movements with Harmonic Radar Reveals an Effect of Population Age on Movement Distance}, + author = {Ovaskainen, Otso and Smith, Alan D. and Osborne, Juliet L. and Reynolds, Don R. and Carreck, Norman L. and Martin, Andrew P. and Niitep{\~o}ld, Kristjan and Hanski, Ilkka}, + year = {2008}, + month = dec, + journal = {Proceedings of the National Academy of Sciences}, + volume = {105}, + number = {49}, + pages = {19090--19095}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.0802066105}, + abstract = {We used harmonic radar to track freely flying Glanville fritillary butterfly (Melitaea cinxia) females within an area of 30 ha. Butterflies originated from large and continuous populations in China and Estonia, and from newly established or old ({$>$} 5 years) small local populations in a highly fragmented landscape in Finland. Caterpillars were raised under common garden conditions and unmated females were tested soon after eclosion. The reconstructed flight paths for 66 individuals comprised a total distance of 51 km with high spatial resolution. Butterflies originating from large continuous populations and from old local populations in Finland exhibited similar movement behaviors, whereas butterflies originating from newly established local populations in the fragmented landscape in Finland moved significantly more than the others. There was no difference in the lengths of individual flight bouts, but the new-population females flew more frequently, resulting in longer daily movement tracks. The flight activity of all individuals was affected by environmental conditions, peaking at 19\textendash 23\textdegree C (depending on population type), in the early afternoon, and during calm weather. Butterflies from all population types showed a strong tendency to follow habitat edges between the open study area and the neighboring woodlands.}, + chapter = {Research Article}, + copyright = {\textcopyright{} 2008 by The National Academy of Sciences of the USA}, + langid = {english}, + pmid = {19060191}, + keywords = {edge-following,evolution of dispersal,fight behavior,fragmented habitat,Glanville fritillary}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VTIJCXS8\\Ovaskainen et al. - 2008 - Tracking butterfly movements with harmonic radar r.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UKZANMR3\\19090.html} +} + +@article{pagelForecastingSpeciesRanges2012a, + title = {Forecasting Species Ranges by Statistical Estimation of Ecological Niches and Spatial Population Dynamics}, + author = {Pagel, J{\"o}rn and Schurr, Frank M.}, + year = {2012}, + journal = {Global Ecology and Biogeography}, + volume = {21}, + number = {2}, + pages = {293--304}, + issn = {1466-8238}, + doi = {10.1111/j.1466-8238.2011.00663.x}, + abstract = {Aim The study and prediction of species\textendash environment relationships is currently mainly based on species distribution models. These purely correlative models neglect spatial population dynamics and assume that species distributions are in equilibrium with their environment. This causes biased estimates of species niches and handicaps forecasts of range dynamics under environmental change. Here we aim to develop an approach that statistically estimates process-based models of range dynamics from data on species distributions and permits a more comprehensive quantification of forecast uncertainties. Innovation We present an approach for the statistical estimation of process-based dynamic range models (DRMs) that integrate Hutchinson's niche concept with spatial population dynamics. In a hierarchical Bayesian framework the environmental response of demographic rates, local population dynamics and dispersal are estimated conditional upon each other while accounting for various sources of uncertainty. The method thus: (1) jointly infers species niches and spatiotemporal population dynamics from occurrence and abundance data, and (2) provides fully probabilistic forecasts of future range dynamics under environmental change. In a simulation study, we investigate the performance of DRMs for a variety of scenarios that differ in both ecological dynamics and the data used for model estimation. Main conclusions Our results demonstrate the importance of considering dynamic aspects in the collection and analysis of biodiversity data. In combination with informative data, the presented framework has the potential to markedly improve the quantification of ecological niches, the process-based understanding of range dynamics and the forecasting of species responses to environmental change. It thereby strengthens links between biogeography, population biology and theoretical and applied ecology.}, + langid = {english}, + keywords = {Biogeography,ecological forecasts,global change,hierarchical Bayesian statistics,long-distance dispersal,niche theory,process-based model,range shifts,spatial demography,species distribution modelling}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-8238.2011.00663.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\4PCDDTAG\\Pagel und Schurr - 2012 - Forecasting species ranges by statistical estimati.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UAJ6JBTS\\j.1466-8238.2011.00663.html} +} + +@article{palmerInterindividualVariabilityDispersal2014, + title = {Inter-Individual Variability in Dispersal Behaviours Impacts Connectivity Estimates}, + author = {Palmer, Stephen C. F. and Coulon, Aur{\'e}lie and Travis, Justin M. J.}, + year = {2014}, + journal = {Oikos}, + volume = {123}, + number = {8}, + pages = {923--932}, + issn = {1600-0706}, + doi = {10.1111/oik.01248}, + abstract = {The importance of landscape connectivity in determining biodiversity outcomes under environmental change has led to indices of connectivity becoming amongst the most widely used measures in conservation. Thus, it is vital that our understanding of connectivity and our use of indices describing it are reliable. Dispersal is the key ecological process involved in determining connectivity, and there is increasing evidence of substantial within-population variability in dispersal behaviours. Here, we incorporate this inter-individual variability into two approaches for estimating connectivity, least cost path analysis and stochastic movement simulation. Illustrative results demonstrate that including dispersal variability can yield substantially different estimates of connectivity. While connectivity is typically similar between nearby patches, the frequency of movements between patches further apart is often substantially increased when inter-individual variability is included. Given the disproportionate role that unusual long-distance dispersal events play in spatial dynamics, connectivity indices should seek to incorporate variability in dispersal behaviour.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/oik.01248}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\V8T4KEHW\\Palmer et al. - 2014 - Inter-individual variability in dispersal behaviou.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\5U6B8LDI\\oik.html} +} + +@article{palmerIntroducingStochasticMovement2011, + title = {Introducing a `Stochastic Movement Simulator' for Estimating Habitat Connectivity}, + author = {Palmer, Stephen C. F. and Coulon, Aur{\'e}lie and Travis, Justin M. J.}, + year = {2011}, + journal = {Methods in Ecology and Evolution}, + volume = {2}, + number = {3}, + pages = {258--268}, + issn = {2041-210X}, + doi = {10.1111/j.2041-210X.2010.00073.x}, + abstract = {1. Estimating and improving landscape connectivity has become a key topic in conservation biology. While a range of connectivity indices exist and are widely used to inform spatial planning, they have potentially serious limitations. 2. We introduce a new method for modelling animals moving between habitat patches across a heterogeneous matrix. Our approach integrates features of least cost path analysis with stochastic movement modelling. Importantly, it relaxes assumptions that are implicit in the least cost path algorithm: our method does not assume omniscience nor does it assume that an individual has a planned destination when it leaves a habitat patch. The algorithm incorporates resistance values for matrix elements and parameters that relate to both perceptual range and to the degree of correlation in movement. By simulating sets of movements for individuals emigrating from habitat patches, relative connectivities between habitat patches are estimated. 3. Using an already published stylised landscape, we demonstrate that the connectivities estimated using our new method can differ considerably from those provided by structural methods and by least cost path analysis. Further, our results emphasise the sensitivity of the relative connectivities to an organism's perceptual range and the degree of correlation between movement steps. 4. We believe that using stochastic movement modelling can improve estimates of connectivity and also provide a method for determining how robust the indices derived from simpler methods are likely to be for different types of organisms.}, + langid = {english}, + keywords = {dispersal,habitat fragmentation,individual-based model,perceptual range}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.2041-210X.2010.00073.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\EDWNZBEL\\Palmer et al. - 2011 - Introducing a ‘stochastic movement simulator’ for .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\I7JJNEUN\\j.2041-210X.2010.00073.html} +} + +@article{parmesanGloballyCoherentFingerprint2003, + title = {A Globally Coherent Fingerprint of Climate Change Impacts across Natural Systems}, + author = {Parmesan, Camille and Yohe, Gary}, + year = {2003}, + month = jan, + journal = {Nature}, + volume = {421}, + number = {6918}, + pages = {37--42}, + publisher = {{Nature Publishing Group}}, + issn = {1476-4687}, + doi = {10.1038/nature01286}, + abstract = {Causal attribution of recent biological trends to climate change is complicated because non-climatic influences dominate local, short-term biological changes. Any underlying signal from climate change is likely to be revealed by analyses that seek systematic trends across diverse species and geographic regions; however, debates within the Intergovernmental Panel on Climate Change (IPCC) reveal several definitions of a `systematic trend'. Here, we explore these differences, apply diverse analyses to more than 1,700 species, and show that recent biological trends match climate change predictions. Global meta-analyses documented significant range shifts averaging 6.1\,km per decade towards the poles (or metres per decade upward), and significant mean advancement of spring events by 2.3 days per decade. We define a diagnostic fingerprint of temporal and spatial `sign-switching' responses uniquely predicted by twentieth century climate trends. Among appropriate long-term/large-scale/multi-species data sets, this diagnostic fingerprint was found for 279 species. This suite of analyses generates `very high confidence' (as laid down by the IPCC) that climate change is already affecting living systems.}, + copyright = {2003 Macmillan Magazines Ltd.}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Research}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6NY7WUQZ\\Parmesan und Yohe - 2003 - A globally coherent fingerprint of climate change .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\3CICWYLS\\nature01286.html} +} + +@article{parmesanPolewardShiftsGeographical1999, + title = {Poleward Shifts in Geographical Ranges of Butterfly Species Associated with Regional Warming}, + author = {Parmesan, Camille and Ryrholm, Nils and Stefanescu, Constant{\'i} and Hill, Jane K. and Thomas, Chris D. and Descimon, Henri and Huntley, Brian and Kaila, Lauri and Kullberg, Jaakko and Tammaru, Toomas and Tennent, W. John and Thomas, Jeremy A. and Warren, Martin}, + year = {1999}, + month = jun, + journal = {Nature}, + volume = {399}, + number = {6736}, + pages = {579--583}, + publisher = {{Nature Publishing Group}}, + issn = {1476-4687}, + doi = {10.1038/21181}, + abstract = {Mean global temperatures have risen this century, and further warming is predicted to continue for the next 50\textendash 100 years1,2,3. Some migratory species can respond rapidly to yearly climate variation by altering the timing or destination of migration4, but most wildlife is sedentary and so is incapable of such a rapid response. For these species, responses to the warming trend should be slower, reflected in poleward shifts of the range. Such changes in distribution would occur at the level of the population, stemming not from changes in the pattern of individuals' movements, but from changes in the ratios of extinctions to colonizations at the northern and southern boundaries of the range. A northward range shift therefore occurs when there is net extinction at the southern boundary or net colonization at the northern boundary. However, previous evidence has been limited to a single species5 or to only a portion of the species' range6,7. Here we provide the first large-scale evidence of poleward shifts in entire species' ranges. In a sample of 35 non-migratory European butterflies, 63\% have ranges that have shifted to the north by 35\textendash 240\,km during this century, and only 3\% have shifted to the south.}, + copyright = {1999 Macmillan Magazines Ltd.}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Research}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\NQDYEF5R\\Parmesan et al. - 1999 - Poleward shifts in geographical ranges of butterfl.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\XSUEU8LT\\21181.html} +} + +@article{pattersonStateSpaceModels2008, + title = {State\textendash Space Models of Individual Animal Movement}, + author = {Patterson, Toby A. and Thomas, Len and Wilcox, Chris and Ovaskainen, Otso and Matthiopoulos, Jason}, + year = {2008}, + month = feb, + journal = {Trends in Ecology \& Evolution}, + volume = {23}, + number = {2}, + pages = {87--94}, + issn = {0169-5347}, + doi = {10.1016/j.tree.2007.10.009}, + abstract = {Detailed observation of the movement of individual animals offers the potential to understand spatial population processes as the ultimate consequence of individual behaviour, physiological constraints and fine-scale environmental influences. However, movement data from individuals are intrinsically stochastic and often subject to severe observation error. Linking such complex data to dynamical models of movement is a major challenge for animal ecology. Here, we review a statistical approach, state\textendash space modelling, which involves changing how we analyse movement data and draw inferences about the behaviours that shape it. The statistical robustness and predictive ability of state\textendash space models make them the most promising avenue towards a new type of movement ecology that fuses insights from the study of animal behaviour, biogeography and spatial population dynamics.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\CISHUFMZ\\S0169534707003588.html} +} + +@article{pearsonPredictingImpactsClimate2003, + title = {Predicting the Impacts of Climate Change on the Distribution of Species: Are Bioclimate Envelope Models Useful?}, + shorttitle = {Predicting the Impacts of Climate Change on the Distribution of Species}, + author = {Pearson, Richard G. and Dawson, Terence P.}, + year = {2003}, + journal = {Global Ecology and Biogeography}, + volume = {12}, + number = {5}, + pages = {361--371}, + issn = {1466-8238}, + doi = {10.1046/j.1466-822X.2003.00042.x}, + abstract = {Modelling strategies for predicting the potential impacts of climate change on the natural distribution of species have often focused on the characterization of a species' bioclimate envelope. A number of recent critiques have questioned the validity of this approach by pointing to the many factors other than climate that play an important part in determining species distributions and the dynamics of distribution changes. Such factors include biotic interactions, evolutionary change and dispersal ability. This paper reviews and evaluates criticisms of bioclimate envelope models and discusses the implications of these criticisms for the different modelling strategies employed. It is proposed that, although the complexity of the natural system presents fundamental limits to predictive modelling, the bioclimate envelope approach can provide a useful first approximation as to the potentially dramatic impact of climate change on biodiversity. However, it is stressed that the spatial scale at which these models are applied is of fundamental importance, and that model results should not be interpreted without due consideration of the limitations involved. A hierarchical modelling framework is proposed through which some of these limitations can be addressed within a broader, scale-dependent context.}, + langid = {english}, + keywords = {bioclimate envelope,climate change,climate space,ecological modelling,ecological niche,hierarchy,scale}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1466-822X.2003.00042.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\CLWUT8UI\\Pearson und Dawson - 2003 - Predicting the impacts of climate change on the di.pdf} +} + +@article{peerBreakingFunctionalConnectivity2011, + title = {Breaking {{Functional Connectivity}} into {{Components}}: {{A Novel Approach Using}} an {{Individual-Based Model}}, and {{First Outcomes}}}, + shorttitle = {Breaking {{Functional Connectivity}} into {{Components}}}, + author = {Pe'er, Guy and Henle, Klaus and Dislich, Claudia and Frank, Karin}, + year = {2011}, + month = aug, + journal = {PLOS ONE}, + volume = {6}, + number = {8}, + pages = {e22355}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0022355}, + abstract = {Landscape connectivity is a key factor determining the viability of populations in fragmented landscapes. Predicting `functional connectivity', namely whether a patch or a landscape functions as connected from the perspective of a focal species, poses various challenges. First, empirical data on the movement behaviour of species is often scarce. Second, animal-landscape interactions are bound to yield complex patterns. Lastly, functional connectivity involves various components that are rarely assessed separately. We introduce the spatially explicit, individual-based model FunCon as means to distinguish between components of functional connectivity and to assess how each of them affects the sensitivity of species and communities to landscape structures. We then present the results of exploratory simulations over six landscapes of different fragmentation levels and across a range of hypothetical bird species that differ in their response to habitat edges. i) Our results demonstrate that estimations of functional connectivity depend not only on the response of species to edges (avoidance versus penetration into the matrix), the movement mode investigated (home range movements versus dispersal), and the way in which the matrix is being crossed (random walk versus gap crossing), but also on the choice of connectivity measure (in this case, the model output examined). ii) We further show a strong effect of the mortality scenario applied, indicating that movement decisions that do not fully match the mortality risks are likely to reduce connectivity and enhance sensitivity to fragmentation. iii) Despite these complexities, some consistent patterns emerged. For instance, the ranking order of landscapes in terms of functional connectivity was mostly consistent across the entire range of hypothetical species, indicating that simple landscape indices can potentially serve as valuable surrogates for functional connectivity. Yet such simplifications must be carefully evaluated in terms of the components of functional connectivity they actually predict.}, + langid = {english}, + keywords = {Animal behavior,Birds,Community structure,Forests,Habitats,Random walk,Simulation and modeling,Statistical dispersion}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\RXZJNWG8\\Pe'er et al. - 2011 - Breaking Functional Connectivity into Components .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\INFAXPUX\\article.html} +} + +@article{peerIncorporatingPerceptualRange2008, + title = {Incorporating the Perceptual Range of Animals into Connectivity Models}, + author = {Pe'er, Guy and {Kramer-Schadt}, Stephanie}, + year = {2008}, + month = apr, + journal = {Ecological Modelling}, + volume = {213}, + number = {1}, + pages = {73--85}, + issn = {0304-3800}, + doi = {10.1016/j.ecolmodel.2007.11.020}, + abstract = {The perceptual range of an animal towards different landscape elements affects its movements through heterogeneous landscapes. However, empirical knowledge and modeling tools are lacking to assess the consequences of variation in the perceptual range for movement patterns and connectivity. In this study we tested how changes in the assumed perception of different landscape elements affect the outcomes of a connectivity model. We used an existing individual-based, spatially explicit model for the dispersal of Eurasian lynx (Lynx lynx). We systematically altered the perceptual range in which animals recognize forest fragments, water bodies or cities, as well as the probability that they respond to these landscape elements. Overall, increasing the perceptual range of the animals enhanced connectivity substantially, both qualitatively and quantitatively. An enhanced range of attraction to forests had the strongest impact, doubling immigration success; an enhanced range of attraction to rivers had a slightly lower impact; and an enhanced range of avoidance of cities had the lowest impact. Correcting the enhancement in connectivity by the abundance of each of the landscape elements in question reversed the results, indicating the potential sensitivity of connectivity models to rare landscape elements (in our case barriers such as cities). Qualitatively, the enhanced perception resulted in strong changes in movement patterns and connectivity. Furthermore, model results were highly parameter-specific and patch-specific. These results emphasize the need for further empirical research on the perceptual capabilities of different animals in different landscapes and conditions. They further indicate the usefulness of spatially explicit individual-based simulation models for recognizing consistent patterns that emerge, despite uncertainty regarding animals' movement behavior. Altogether, this study demonstrates the need to extend the concept of `perceptual ranges' beyond patch detection processes, to encompass the wide range of elements that can direct animal movements during dispersal through heterogeneous landscapes.}, + langid = {english}, + keywords = {Connectivity,Directing stimuli,Dispersal,Eurasian lynx,Heuristic model,Individual-based spatially explicit model,Movement decisions,Perceptual range,Spatial gradients,Spatial heterogeneity}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\R4A28CIL\\S0304380007006199.html} +} + +@article{peerSimpleProcessBasedSimulators2013, + title = {Simple {{Process-Based Simulators}} for {{Generating Spatial Patterns}} of {{Habitat Loss}} and {{Fragmentation}}: {{A Review}} and {{Introduction}} to the {{G-RaFFe Model}}}, + shorttitle = {Simple {{Process-Based Simulators}} for {{Generating Spatial Patterns}} of {{Habitat Loss}} and {{Fragmentation}}}, + author = {Pe'er, Guy and Zurita, Gustavo A. and Schober, Lucia and Bellocq, Maria I. and Strer, Maximilian and M{\"u}ller, Michael and P{\"u}tz, Sandro}, + year = {2013}, + month = may, + journal = {PLOS ONE}, + volume = {8}, + number = {5}, + pages = {e64968}, + publisher = {{Public Library of Science}}, + issn = {1932-6203}, + doi = {10.1371/journal.pone.0064968}, + abstract = {Landscape simulators are widely applied in landscape ecology for generating landscape patterns. These models can be divided into two categories: pattern-based models that generate spatial patterns irrespective of the processes that shape them, and process-based models that attempt to generate patterns based on the processes that shape them. The latter often tend toward complexity in an attempt to obtain high predictive precision, but are rarely used for generic or theoretical purposes. Here we show that a simple process-based simulator can generate a variety of spatial patterns including realistic ones, typifying landscapes fragmented by anthropogenic activities. The model ``G-RaFFe'' generates roads and fields to reproduce the processes in which forests are converted into arable lands. For a selected level of habitat cover, three factors dominate its outcomes: the number of roads (accessibility), maximum field size (accounting for land ownership patterns), and maximum field disconnection (which enables field to be detached from roads). We compared the performance of G-RaFFe to three other models: Simmap (neutral model), Qrule (fractal-based) and Dinamica EGO (with 4 model versions differing in complexity). A PCA-based analysis indicated G-RaFFe and Dinamica version 4 (most complex) to perform best in matching realistic spatial patterns, but an alternative analysis which considers model variability identified G-RaFFe and Qrule as performing best. We also found model performance to be affected by habitat cover and the actual land-uses, the latter reflecting on land ownership patterns. We suggest that simple process-based generators such as G-RaFFe can be used to generate spatial patterns as templates for theoretical analyses, as well as for gaining better understanding of the relation between spatial processes and patterns. We suggest caution in applying neutral or fractal-based approaches, since spatial patterns that typify anthropogenic landscapes are often non-fractal in nature.}, + langid = {english}, + keywords = {Farms,Forests,Habitats,Land use,Principal component analysis,Regression analysis,Roads,Trees}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\YDCNGWDB\\Pe'er et al. - 2013 - Simple Process-Based Simulators for Generating Spa.pdf} +} + +@article{perrinDispersalInbreedingAvoidance1999, + title = {Dispersal and {{Inbreeding Avoidance}}}, + author = {Perrin, Nicolas and Mazalov, Vladimir}, + year = {1999}, + month = sep, + journal = {The American Naturalist}, + volume = {154}, + number = {3}, + pages = {282--292}, + issn = {1537-5323}, + doi = {10.1086/303236}, + abstract = {Using a game-theoretical approach, we investigate the dispersal patterns expected if inbreeding avoidance were the only reason for dispersal. The evolutionary outcome is always complete philopatry by one sex. The rate of dispersal by the other sex depends on patch size and mating system, as well as inbreeding and dispersal costs. If such costs are sex independent, then two stable equilibria coexist (male or female philopatry), with symmetric domains of attraction. Which sex disperses is determined entirely by history, genetic drift, and gene flow. An asymmetry in costs makes one domain of attraction extend at the expense of the other. In such a case, the dispersing sex might also be, paradoxically, the one that incurs the higher dispersal costs. As asymmetry increases, one equilibrium eventually disappears, which may result in a sudden evolutionary shift in the identity of the dispersing sex. Our results underline the necessity to control for phylogenetic relationships (e.g., through the use of independent-comparisons methods) when investigating empirical trends in dispersal. Our model also makes quantitative predictions on the rate of dispersal by the dispersing sex and suggests that inbreeding avoidance may only rarely be the sole reason for dispersal.}, + langid = {english}, + pmid = {10506544}, + keywords = {evolutionarily stable strategy,mating systems,polygyny,sex‐biased dispersal} +} + +@article{perrinLocalCompetitionInbreeding2000, + title = {Local {{Competition}}, {{Inbreeding}}, and the {{Evolution}} of {{Sex-Biased Dispersal}}}, + author = {Perrin, Nicolas and Mazalov, Vladimir}, + year = {2000}, + month = jan, + journal = {The American Naturalist}, + volume = {155}, + number = {1}, + pages = {116--127}, + issn = {1537-5323}, + doi = {10.1086/303296}, + abstract = {Using game theory, we developed a kin-selection model to investigate the consequences of local competition and inbreeding depression on the evolution of natal dispersal. Mating systems have the potential to favor strong sex biases in dispersal because sex differences in potential reproductive success affect the balance between local resource competition and local mate competition. No bias is expected when local competition equally affects males and females, as happens in monogamous systems and also in polygynous or promiscuous ones as long as female fitness is limited by extrinsic factors (breeding resources). In contrast, a male-biased dispersal is predicted when local mate competition exceeds local resource competition, as happens under polygyny/promiscuity when female fitness is limited by intrinsic factors (maximal rate of processing resources rather than resources themselves). This bias is reinforced by among-sex interactions: female philopatry enhances breeding opportunities for related males, while male dispersal decreases the chances that related females will inbreed. These results meet empirical patterns in mammals: polygynous/promiscuous species usually display a male-biased dispersal, while both sexes disperse in monogamous species. A parallel is drawn with sex-ratio theory, which also predicts biases toward the sex that suffers less from local competition. Optimal sex ratios and optimal sex-specific dispersal show mutual dependence, which argues for the development of coevolution models.}, + langid = {english}, + pmid = {10657181}, + keywords = {kin selection,local mate competition,local resource competition,mating systems,potential reproductive rate} +} + +@article{petitSurveyColumnarCacti1996, + title = {Survey of {{Columnar Cacti}} and {{Carrying Capacity}} for {{Nectar-Feeding Bats}} on {{Curacao}}}, + author = {Petit, Sophie and Pors, Leon}, + year = {1996}, + journal = {Conservation Biology}, + volume = {10}, + number = {3}, + pages = {769--775}, + publisher = {{[Wiley, Society for Conservation Biology]}}, + issn = {0888-8892}, + abstract = {We estimated the population sizes of the three species of columnar cacti that grow on the island of Curacao using ground and aerial transects, and we examined the island's carrying capacity for two species of nectar-feeding bats that depend on nectar from the flowers of these cacti. We calculated carrying capacity based on the daily availability of mature flowers between January and December 1993 and the field energy requirements of bats as estimated from an equation for eutherian mammals (low estimate) and one for passerine birds (high estimate) based on body mass. Additional energy requirements of pregnancy and lactation were taken into account. We estimated that 461,172 columnar cacti were present on Curacao (38\% Subpilocereus repandus, 51\% Stenocereus griseus, and 11\% Pilosocereus lanuginosus). May through September are the critical months when bats rely most heavily on cactus for food. July 1993 was a bottleneck with the smallest number of mature flowers per day. July and August were months of greatest energy demand because females were lactating. We estimate that the carrying capacity for Glossophaga longirostris in July, when the bat (Leptonycteris curasoae) population was 900, was near 1200, an estimate that fits the observed population size of nectar-feeding bats on the island. We suggest that the extensive removal of native vegetation occurring on Curacao be strictly regulated because further destruction of the cacti will result in a decrease and potential loss of the already low populations of nectar-feeding bats.} +} + +@article{phillipsLifehistoryEvolutionRangeshifting2010a, + title = {Life-History Evolution in Range-Shifting Populations}, + author = {Phillips, Benjamin L. and Brown, Gregory P. and Shine, Richard}, + year = {2010}, + journal = {Ecology}, + volume = {91}, + number = {6}, + pages = {1617--1627}, + issn = {1939-9170}, + doi = {10.1890/09-0910.1}, + abstract = {Most evolutionary theory does not deal with populations expanding or contracting in space. Invasive species, climate change, epidemics, and the breakdown of dispersal barriers, however, all create populations in this kind of spatial disequilibrium. Importantly, spatial disequilibrium can have important ecological and evolutionary outcomes. During continuous range expansion, for example, populations on the expanding front experience novel evolutionary pressures because frontal populations are assorted by dispersal ability and have a lower density of conspecifics than do core populations. These conditions favor the evolution of traits that increase rates of dispersal and reproduction. Additionally, lowered density on the expanding front eventually frees populations on the expanding edge from specialist, coevolved enemies, permitting higher investment into traits associated with dispersal and reproduction rather than defense against pathogens. As a result, the process of range expansion drives rapid life-history evolution, and this seems to occur despite ongoing serial founder events that have complex effects on genetic diversity at the expanding front. Traits evolving on the expanding edge are smeared across the landscape as the front moves through, leaving an ephemeral signature of range expansion in the life-history traits of a species across its newly colonized range. Recent studies suggest that such nonequilibrium processes during recent population history may have contributed to many patterns usually ascribed to evolutionary forces acting in populations at spatial equilibrium.}, + langid = {english}, + keywords = {climate change,contemporary evolution,defense allocation,density dependence,dispersal rate,enemy escape,genotype “smearing”,nonequilibrium processes,range shift,rapid life-history evolution,reproductive rate}, + annotation = {\_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/09-0910.1}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\P576JEPR\\Phillips et al. - 2010 - Life-history evolution in range-shifting populatio.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\WU9FHHYS\\09-0910.html} +} + +@article{phillipsRangeShiftPromotes2012, + title = {Range Shift Promotes the Formation of Stable Range Edges}, + author = {Phillips, Ben L.}, + year = {2012}, + journal = {Journal of Biogeography}, + volume = {39}, + number = {1}, + pages = {153--161}, + issn = {1365-2699}, + doi = {10.1111/j.1365-2699.2011.02597.x}, + abstract = {Aim I investigate the counter-intuitive possibility that range shift promotes the formation of stable range edges. This might be expected because: (1) range-shifting populations typically evolve increased dispersal on the expanding range edge; (2) increased dispersal steepens the relative slope of environmental gradients (gradients appear steeper to a more dispersive population); and (3) environmental gradients that are steep relative to dispersal encourage the formation of stable range edges (when gradients appear steep, adaptation on the range edge is swamped by maladapted genes). Methods I test the idea that populations take longer to evolve across an environmental gradient when those populations have already undergone a period of spread. I do this using an individual-based coupled map lattice simulation, in which individuals carry heritable traits for dispersal probability and environment-specific fitness. Results Numerous simulations across parameter space confirm that a period of range shift almost always results in a longer time to evolve through an environmental gradient. This occurs because of both the mechanism described above and the erosion of adaptive variation resulting from the serial foundering that occurs during range advance. Main conclusions This result suggests that species may often shift their range due to intrinsic changes in the population rather than extrinsic changes in the environment. The result also suggests a new mechanism regulating the speed of invasion, and sounds a cautionary note for climate change impacts: the longer a species tracks climate change, the less able it may be to track that change into the future.}, + langid = {english}, + keywords = {Dispersal,ecological gradient,evolution,range edge,range shift,simulation modelling}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2011.02597.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\H7X4DWWC\\Phillips - 2012 - Range shift promotes the formation of stable range.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\45UCVE34\\j.1365-2699.2011.02597.html} +} + +@article{phillipsReidParadoxRevisited2008a, + title = {Reid's Paradox Revisited: The Evolution of Dispersal Kernels during Range Expansion}, + shorttitle = {Reid's Paradox Revisited}, + author = {Phillips, Benjamin L. and Brown, Gregory P. and Travis, Justin M. J. and Shine, Richard}, + year = {2008}, + month = jul, + journal = {The American Naturalist}, + volume = {172 Suppl 1}, + pages = {S34-48}, + issn = {1537-5323}, + doi = {10.1086/588255}, + abstract = {Current approaches to modeling range advance assume that the distribution describing dispersal distances in the population (the "dispersal kernel") is a static entity. We argue here that dispersal kernels are in fact highly dynamic during periods of range advance because density effects and spatial assortment by dispersal ability ("spatial selection") drive the evolution of increased dispersal on the expanding front. Using a spatially explicit individual-based model, we demonstrate this effect under a wide variety of population growth rates and dispersal costs. We then test the possibility of an evolved shift in dispersal kernels by measuring dispersal rates in individual cane toads (Bufo marinus) from invasive populations in Australia (historically, toads advanced their range at 10 km/year, but now they achieve {$>$}55 km/year in the northern part of their range). Under a common-garden design, we found a steady increase in dispersal tendency with distance from the invasion origin. Dispersal kernels on the invading front were less kurtotic and less skewed than those from origin populations. Thus, toads have increased their rate of range expansion partly through increased dispersal on the expanding front. For accurate long-range forecasts of range advance, we need to take into account the potential for dispersal kernels to be evolutionarily dynamic.}, + langid = {english}, + pmid = {18554142}, + keywords = {Animals,Australia,Biological Evolution,Bufo marinus,Ecosystem,Geography,Models; Biological,Population Dynamics,Predatory Behavior,Selection; Genetic} +} + +@article{plotnickGeneralModelSimulating2002, + title = {A General Model for Simulating the Effects of Landscape Heterogeneity and Disturbance on Community Patterns}, + author = {Plotnick, Roy E and Gardner, Robert H}, + year = {2002}, + month = jan, + journal = {Ecological Modelling}, + volume = {147}, + number = {2}, + pages = {171--197}, + issn = {0304-3800}, + doi = {10.1016/S0304-3800(01)00418-5}, + abstract = {An individual-based, spatially explicit stochastic lattice model, CAPS, was designed to examine multiple processes responsible for spatial patterns of abundance and diversity of sessile species in heterogeneous landscapes. Species simulated by CAPS differ in habitat preferences (niche width), dispersal of propagules, and relative fecundity. The spatial distribution of habitat types are represented as heterogeneous gridded landscapes. The outcome of competition and establishment processes in successive generations is determined locally via a seed lottery. A series of 200 year-long simulations was performed to investigate the effects of variation in species characteristics and competition, landscape heterogeneity, and disturbance on patterns of species abundances. The outcome of competition was most sensitive to differences in fecundity between species, the spatial distribution of suitable habitat and the initial distribution of species. Species with a narrow niche were confined to a single habitat type and remained at or near their initialization sites. Broader niches resulted in increasing niche overlap and competition but enhanced species mobility, allowing abundance levels to approach expected values determined by map resources. Even so, initial distributions still affected the spatial patterns of species distributions at year 200. Disturbance regimes were simulated by varying the frequency, extent and spatial pattern of disturbances. Disturbance events removed species from affected sites but did not otherwise alter habitat characteristics. Results showed that disturbances may lead to a reversal in competition and establishment, dependent on species-specific differences in fecundity and dispersal. Although intermediate levels of disturbance frequency and extent increased the probability of species coexistence, the spatial pattern of disturbance played an unexpectedly important role in the tradeoff between dispersal and fecundity. The ability to simulate multiple factors affecting patterns of persistence, abundance and spatial distribution of species provided by CAPS allows new insight into the temporal and spatial patterns of community development.}, + langid = {english}, + keywords = {Cellular automata,Community dynamics,Disturbance,Heterogeneity,Landscape,Lattice models,Spatial simulation}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\TH6ID3NW\\Plotnick und Gardner - 2002 - A general model for simulating the effects of land.pdf} +} + +@article{poethkeAbilityIndividualsAssess2011, + title = {The Ability of Individuals to Assess Population Density Influences the Evolution of Emigration Propensity and Dispersal Distance}, + author = {Poethke, Hans Joachim and Gros, Andreas and Hovestadt, Thomas}, + year = {2011}, + month = aug, + journal = {Journal of Theoretical Biology}, + volume = {282}, + number = {1}, + pages = {93--99}, + issn = {1095-8541}, + doi = {10.1016/j.jtbi.2011.05.012}, + abstract = {We analyze the simultaneous evolution of emigration and settlement decisions for actively dispersing species differing in their ability to assess population density. Using an individual-based model we simulate dispersal as a multi-step (patch to patch) movement in a world consisting of habitat patches surrounded by a hostile matrix. Each such step is associated with the same mortality risk. Our simulations show that individuals following an informed strategy, where emigration (and settlement) probability depends on local population density, evolve a lower (natal) emigration propensity but disperse over significantly larger distances - i.e. postpone settlement longer - than individuals performing density-independent emigration. This holds especially when variation in environmental conditions is spatially correlated. Both effects can be traced to the informed individuals' ability to better exploit existing heterogeneity in reproductive chances. Yet, already moderate distance-dependent dispersal costs prevent the evolution of multi-step (long-distance) dispersal, irrespective of the dispersal strategy.}, + langid = {english}, + pmid = {21605568}, + keywords = {Biological Evolution,Humans,Models; Theoretical,Population Density}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\7V5ILEU6\\Poethke et al. - 2011 - The ability of individuals to assess population de.pdf} +} + +@article{poethkeEvolutionDensityPatch2002, + title = {Evolution of Density\textendash and Patch\textendash Size\textendash Dependent Dispersal Rates}, + author = {Poethke, Hans Joachim and Hovestadt, Thomas}, + year = {2002}, + month = mar, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {269}, + number = {1491}, + pages = {637--645}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2001.1936}, + abstract = {Based on a marginal value approach, we derive a nonlinear expression for evolutionarily stable (ES) dispersal rates in a metapopulation with global dispersal. For the general case of density-dependent population growth, our analysis shows that individual dispersal rates should decrease with patch capacity and\textemdash beyond a certain threshold\textendash increase with population density. We performed a number of spatially explicit, individual-based simulation experiments to test these predictions and to explore further the relevance of variation in the rate of population increase, density dependence, environmental fluctuations and dispersal mortality on the evolution of dispersal rates. They confirm the predictions of our analytical approach. In addition, they show that dispersal rates in metapopulations mostly depend on dispersal mortality and inter-patch variation in population density. The latter is dominantly driven by environmental fluctuations and the rate of population increase. These conclusions are not altered by the introduction of neighbourhood dispersal. With patch capacities in the order of 100 individuals, kin competition seems to be of negligible importance for ES dispersal rates except when overall dispersal rates are low.}, + keywords = {density-dependent dispersal,dispersal rate,evolutionarily stable strategy,individual based model,metapopulation,patch size}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\WILYAUAH\\Poethke und Hovestadt - 2002 - Evolution of density–and patch–size–dependent disp.pdf} +} + +@article{poyrySpeciesTraitsExplain2009, + title = {Species Traits Explain Recent Range Shifts of {{Finnish}} Butterflies}, + author = {P{\"o}yry, Juha and Luoto, Miska and Heikkinen, Risto K. and Kuussaari, Mikko and Saarinen, Kimmo}, + year = {2009}, + journal = {Global Change Biology}, + volume = {15}, + number = {3}, + pages = {732--743}, + issn = {1365-2486}, + doi = {10.1111/j.1365-2486.2008.01789.x}, + abstract = {This study provides a novel systematic comparative analysis of the species characteristics affecting the range margin shifts in butterflies towards higher latitudes, while taking phylogenetic relatedness among species into account. We related observed changes in the northern range margins of 48 butterfly species in Finland between two time periods (1992\textendash 1996 and 2000\textendash 2004) to 11 species traits. Species with positive records in at least ten 10 km \texttimes{} 10 km grid squares (in the Finnish National Butterfly Recording Scheme, NAFI) in both periods were included in the study. When corrected for range size change, the 48 butterfly species had shifted their range margins northwards on average by 59.9 km between the study periods, with maximum shifts of over 300 km for three species. This rate of range shifts exceeds all previously reported records worldwide. Our findings may be explained by two factors: the study region is situated in higher latitudes than in most previous studies and it focuses on the period of most prominent warming during the last 10\textendash 15 years. Several species traits exhibited a significant univariate relationship with the range margin shift according to generalized estimation equations (GEE) taking into account the phylogenetic relatedness among species. Nonthreatened butterflies had on average expanded their ranges strongly northwards (84.5 km), whereas the distributions of threatened species were stationary (-2.1 km). Hierarchical partitioning (HP) analysis indicated that mobile butterflies living in forest edges and using woody plants as their larval hosts exhibited largest range shifts towards the north. Thus, habitat availability and dispersal capacity of butterfly species are likely to determine whether they will be successful in shifting their ranges in response to the warming climate.}, + langid = {english}, + keywords = {atlas data,butterflies,climate change,distribution,Finland,generalized estimation equations (GEE),hierarchical partitioning (HP),range shift,species traits}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2486.2008.01789.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Y4XNIRXF\\Pöyry et al. - 2009 - Species traits explain recent range shifts of Finn.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\FPJZ9C4C\\j.1365-2486.2008.01789.html} +} + +@article{revillaEffectsMatrixHeterogeneity2004, + title = {Effects of {{Matrix Heterogeneity}} on {{Animal Dispersal}}: {{From Individual Behavior}} to {{Metapopulation}}-{{Level Parameters}}.}, + shorttitle = {Effects of {{Matrix Heterogeneity}} on {{Animal Dispersal}}}, + author = {Revilla, Eloy and Wiegand, Thorsten and Palomares, Francisco and Ferreras, Pablo and Delibes, Miguel}, + year = {2004}, + month = nov, + journal = {The American Naturalist}, + volume = {164}, + number = {5}, + pages = {E130-E153}, + publisher = {{The University of Chicago Press}}, + issn = {0003-0147}, + doi = {10.1086/424767}, + abstract = {Mounting theoretical and empirical evidence shows that matrix heterogeneity may have contrasting effects on metapopulation dynamics by contributing to patch isolation in nontrivial ways. We analyze the movement properties during interpatch dispersal in a metapopulation of Iberian lynx (Lynx pardinus). On a daily temporal scale, lynx habitat selection defines two types of matrix habitats where individuals may move: open and dispersal habitats (avoided and used as available, respectively). There was a strong and complex impact of matrix heterogeneity on movement properties at several temporal scales (hourly and daily radiolocations and the entire dispersal event). We use the movement properties on the hourly temporal scale to build a simulation model to reconstruct individual dispersal events. The two most important parameters affecting model predictions at both the individual (daily) and metapopulation scales were related to the movement capacity (number of movement steps per day and autocorrelation in dispersal habitat) followed by the parameters representing the habitat selection in the matrix. The model adequately reproduced field estimates of population-level parameters (e.g., interpatch connectivity, maximum and final dispersal distances), and its performance was clearly improved when including the effect of matrix heterogeneity on movement properties. To assume there is a homogeneous matrix results in large errors in the estimate of interpatch connectivity, especially for close patches separated by open habitat or corridors of dispersal habitat, showing how important it is to consider matrix heterogeneity when it is present. Movement properties affect the interaction of dispersing individuals with the landscape and can be used as a mechanistic representation of dispersal at the metapopulation level. This is so when the effect of matrix heterogeneity on movement properties is evaluated under biologically meaningful spatial and temporal scales.}, + keywords = {autocorrelated random walk,individual‐based spatially explicit simulations,interpatch connectivity,Lynx pardinus,matrix fragmentation,standard of plausibility}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\DIPDQW6W\\Revilla et al. - 2004 - Effects of Matrix Heterogeneity on Animal Dispersa.pdf} +} + +@article{revillaIndividualMovementBehavior2008a, + title = {Individual Movement Behavior, Matrix Heterogeneity, and the Dynamics of Spatially Structured Populations}, + author = {Revilla, Eloy and Wiegand, Thorsten}, + year = {2008}, + month = dec, + journal = {Proceedings of the National Academy of Sciences}, + volume = {105}, + number = {49}, + pages = {19120--19125}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.0801725105}, + abstract = {The dynamics of spatially structured populations is characterized by within- and between-patch processes. The available theory describes the latter with simple distance-dependent functions that depend on landscape properties such as interpatch distance or patch size. Despite its potential role, we lack a good mechanistic understanding of how the movement of individuals between patches affects the dynamics of these populations. We used the theoretical framework provided by movement ecology to make a direct representation of the processes determining how individuals connect local populations in a spatially structured population of Iberian lynx. Interpatch processes depended on the heterogeneity of the matrix where patches are embedded and the parameters defining individual movement behavior. They were also very sensitive to the dynamic demographic variables limiting the time moving, the within-patch dynamics of available settlement sites (both spatiotemporally heterogeneous) and the response of individuals to the perceived risk while moving. These context-dependent dynamic factors are an inherent part of the movement process, producing connectivities and dispersal kernels whose variability is affected by other demographic processes. Mechanistic representations of interpatch movements, such as the one provided by the movement-ecology framework, permit the dynamic interaction of birth\textendash death processes and individual movement behavior, thus improving our understanding of stochastic spatially structured populations.}, + chapter = {Research Article}, + copyright = {\textcopyright{} 2008 by The National Academy of Sciences of the USA}, + langid = {english}, + pmid = {19060193}, + keywords = {demography,Iberian lynx,metapopulation,population dynamics,source-sink}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\H8BTU5CK\\Revilla und Wiegand - 2008 - Individual movement behavior, matrix heterogeneity.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UYMB72DH\\19120.html} +} + +@article{rickettsMatrixMattersEffective2001, + title = {The Matrix Matters: Effective Isolation in Fragmented Landscapes}, + shorttitle = {The Matrix Matters}, + author = {Ricketts, T. H.}, + year = {2001}, + month = jul, + journal = {The American Naturalist}, + volume = {158}, + number = {1}, + pages = {87--99}, + issn = {1537-5323}, + doi = {10.1086/320863}, + abstract = {Traditional approaches to the study of fragmented landscapes invoke an island-ocean model and assume that the nonhabitat matrix surrounding remnant patches is uniform. Patch isolation, a crucial parameter to the predictions of island biogeography and metapopulation theories, is measured by distance alone. To test whether the type of interpatch matrix can contribute significantly to patch isolation, I conducted a mark-recapture study on a butterfly community inhabiting meadows in a naturally patchy landscape. I used maximum likelihood to estimate the relative resistances of the two major matrix types (willow thicket and conifer forest) to butterfly movement between meadow patches. For four of the six butterfly taxa (subfamilies or tribes) studied, conifer was 3-12 times more resistant than willow. For the two remaining taxa (the most vagile and least vagile in the community), resistance estimates for willow and conifer were not significantly different, indicating that responses to matrix differ even among closely related species. These results suggest that the surrounding matrix can significantly influence the "effective isolation" of habitat patches, rendering them more or less isolated than simple distance or classic models would indicate. Modification of the matrix may provide opportunities for reducing patch isolation and thus the extinction risk of populations in fragmented landscapes.}, + langid = {english}, + pmid = {18707317} +} + +@article{ripaNoiseColourRisk1996, + title = {Noise Colour and the Risk of Population Extinctions}, + author = {Ripa, J{\"o}rgen and Lundberg, Per}, + year = {1996}, + month = dec, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {263}, + number = {1377}, + pages = {1751--1753}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.1996.0256}, + abstract = {A recurrent problem in ecology and conservation biology is to estimate the risk of population extinctions. Extinction probabilities are not only imperative for conservation and management, but may also elucidate basic mechanisms of the regulation of natural populations (Burgman et al. 1993; Pimm 1994). The usual way of modelling stochastic influence on population dynamics has been to assume that the external noise is uncorrelated. This means that each and every randomly drawn noise value is totally independent on previous ones. This is what is generally called `white' noise. However, the noise itself can be temporally autocorrelated. That is, the values of the random numbers used in the noise process will depend on previous ones. Here we show that the autocorrelation, or colour, of the external noise assumed to influence population dynamics strongly modifies estimated extinction probabilities. For positively autocorrelated (`red') noise, the risk of extinction clearly decreases the stronger the autocorrelation is, Negatively autocorrelated (`blue') noise is more ambiguously related to extinction probability. Thus, the commonly assumed white noise in population modelling will severely bias population extinction risk estimates. Moreover, the extinction probability estimates are also significantly dependent on model structure which calls for a cautious use of traditional discrete-time models.} +} + +@article{robertVariationIndividualsDemographic2003, + title = {Variation among {{Individuals}}, {{Demographic Stochasticity}}, and {{Extinction}}: {{Response}} to {{Kendall}} and {{Fox}}}, + shorttitle = {Variation among {{Individuals}}, {{Demographic Stochasticity}}, and {{Extinction}}}, + author = {Robert, Alexandre and Sarrazin, Fran{\c c}ois and Couvet, Denis}, + year = {2003}, + journal = {Conservation Biology}, + volume = {17}, + number = {4}, + pages = {1166--1169}, + publisher = {{[Wiley, Society for Conservation Biology]}}, + issn = {0888-8892} +} + +@incollection{ronceDispersalSyndromes2012, + title = {Dispersal Syndromes}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Ronce, Oph{\'e}lie and Clobert, Jean}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0010}, + abstract = {This chapter focuses on dispersal syndromes and how they describe patterns of covariation of morphological, behavioural, and/or life-history traits associated with dispersal. Covariation is a continuous measure of statistical association between traits composing a complex phenotype. There are four main reasons why this chapter is interested in covariation: firstly, syndromes may help us predict a priori, from the observation of dispersal phenotypes, the intensity, nature, and modalities of movement. Secondly, they have the potential to provide information regarding the mechanistic determinants of dispersal and the constraints associated with movement. Thirdly, they may provide information about the proximate motivations and ultimate causes of dispersal. Lastly, and most convincingly, the patterns of covariation between traits associated with dispersal will critically affect both the demographic and genetic consequences of movement.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {complex phenotype,covariation,dispersal syndromes,modalities of movement,statistical association} +} + +@article{ronceHowDoesIt2007a, + title = {How {{Does It Feel}} to {{Be Like}} a {{Rolling Stone}}? {{Ten Questions About Dispersal Evolution}}}, + shorttitle = {How {{Does It Feel}} to {{Be Like}} a {{Rolling Stone}}?}, + author = {Ronce, Oph{\'e}lie}, + year = {2007}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + volume = {38}, + number = {1}, + pages = {231--253}, + doi = {10.1146/annurev.ecolsys.38.091206.095611}, + abstract = {This review proposes ten tentative answers to frequently asked questions about dispersal evolution. I examine methodological issues, model assumptions and predictions, and their relation to empirical data. Study of dispersal evolution points to the many ecological and genetic feedbacks affecting the evolution of this complex trait, which has contributed to our better understanding of life-history evolution in spatially structured populations. Several lines of research are suggested to ameliorate the exchanges between theoretical and empirical studies of dispersal evolution.}, + annotation = {\_eprint: https://doi.org/10.1146/annurev.ecolsys.38.091206.095611}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\SXEHMND3\\Ronce - 2007 - How Does It Feel to Be Like a Rolling Stone Ten Q.pdf} +} + +@article{ronceLandscapeDynamicsEvolution2000, + title = {Landscape Dynamics and Evolution of Colonizer Syndromes: Interactions between Reproductive Effortand Dispersal in a Metapopulation}, + shorttitle = {Landscape Dynamics and Evolution of Colonizer Syndromes}, + author = {Ronce, Oph{\'e}lie and Perret, Florence and Olivieri, Isabelle}, + year = {2000}, + month = may, + journal = {Evolutionary Ecology}, + volume = {14}, + number = {3}, + pages = {233--260}, + issn = {1573-8477}, + doi = {10.1023/A:1011068005057}, + abstract = {The evolutionary consequences of changes in landscape dynamics for the evolution of life history syndromes are studied using a metapopulation model. We consider in turn the long-term effects of a change in the local disturbance rate, in the maximal local population persistence, in habitat productivity, and in habitat fragmentation. We examine the consequences of selective interactions between dispersal and reproductive effort by comparing the outcome of joint evolution to a situation where the species has lost the potential to evolve either its reproductive effort or its dispersal rate. We relax the classical assumption that any occupied site in the metapopulation reaches its carrying capacity immediately after recolonization. Our main conclusions are the following: (1) genetic diversity modifies the range of landscape parameters for which the metapopulation is viable, but it alters very little the qualitative evolutionary trends observed for each trait within this range. Although they are both part of a competition/colonization axis, reproductive effort and dispersal are not substitutable traits: their evolution reflects more directly the change in the landscape dynamics, than a selective interaction among them. (2) no general syndrome of covariation between reproductive effort and dispersal can be predicted: the pattern of association between the two traits depends on the type of change in landscape dynamics and on the saturation level. We review empirical evidence on colonizer syndromes and suggest lines for further empirical work.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\25UJK666\\Ronce et al. - 2000 - Landscape dynamics and evolution of colonizer synd.pdf} +} + +@article{roussetEvolutionDistributionDispersal2002, + title = {Evolution of the Distribution of Dispersal Distance under Distance-Dependent Cost of Dispersal}, + author = {Rousset, F. and Gandon, S.}, + year = {2002}, + journal = {Journal of Evolutionary Biology}, + volume = {15}, + number = {4}, + pages = {515--523}, + issn = {1420-9101}, + doi = {10.1046/j.1420-9101.2002.00430.x}, + abstract = {We analyse the evolution of the distribution of dispersal distances in a stable and homogeneous environment in one- and two-dimensional habitats. In this model, dispersal evolves to avoid the competition between relatives although some cost might be associated with this behaviour. The evolutionarily stable dispersal distribution is characterized by an equilibration of the fitness gains among all the different dispersal distances. This cost-benefit argument has heuristic value and facilitates the comprehension of results obtained numerically. In particular, it explains why some minimal or maximal probability of dispersal may evolve at intermediate distances when the cost of dispersal function is an increasing function of distance. We also show that kin selection may favour long range dispersal even if the survival cost of dispersal is very high, provided the survival probability does not vanish at long distances.}, + langid = {english}, + keywords = {dispersal,evolutionarily stable strategy,isolation by distance,kin selection}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1420-9101.2002.00430.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\IV89N5LY\\Rousset und Gandon - 2002 - Evolution of the distribution of dispersal distanc.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\PR6J2389\\j.1420-9101.2002.00430.html} +} + +@article{ruokolainenEcologicalEvolutionaryDynamics2009, + title = {Ecological and Evolutionary Dynamics under Coloured Environmental Variation}, + author = {Ruokolainen, Lasse and Lind{\'e}n, Andreas and Kaitala, Veijo and Fowler, Mike S.}, + year = {2009}, + month = oct, + journal = {Trends in Ecology \& Evolution}, + volume = {24}, + number = {10}, + pages = {555--563}, + issn = {0169-5347}, + doi = {10.1016/j.tree.2009.04.009}, + abstract = {Environmental variation is a ubiquitous component of individual, population and community processes in the natural world. Here, we review the consequences of spatio-temporally autocorrelated (coloured) environmental variation for ecological and evolutionary population dynamics. In single-species population models, environmental reddening increases (decreases) the amplitude of fluctuations in undercompensatory (overcompensatory) populations. This general result is also found in structurally more complex models (e.g. with space or species interactions). Environmental autocorrelation will also influence evolutionary dynamics as the changing environment is filtered through ecological dynamics. In the context of long-term environmental change, it becomes crucial to understand the potential impacts of different regimes of environmental variation at different scales of organization, from genes to species to communities.}, + langid = {english} +} + +@article{ruxtonFitnessDependentDispersal1998, + title = {Fitness-dependent Dispersal in Metapopulations and Its Consequences for Persistence and Synchrony}, + author = {Ruxton, G. D. and Rohani, P}, + year = {1998}, + journal = {Journal of Animal Ecology}, + number = {67}, + pages = {530--539} +} + +@incollection{saupeAlgorithmsRandomFractals1988, + title = {Algorithms for Random Fractals}, + booktitle = {The {{Science}} of {{Fractal Images}}}, + author = {Saupe, Dietmar}, + editor = {Barnsley, Michael F. and Devaney, Robert L. and Mandelbrot, Benoit B. and Peitgen, Heinz-Otto and Saupe, Dietmar and Voss, Richard F. and Peitgen, Heinz-Otto and Saupe, Dietmar}, + year = {1988}, + pages = {71--136}, + publisher = {{Springer}}, + address = {{New York, NY}}, + doi = {10.1007/978-1-4612-3784-6_2}, + abstract = {For about 200 years now mathematicians have developed the theory of smooth curves and surfaces in two, three or higher dimensions. These are curves and surfaces that globally may have a very complicated structure but in small neighborhoods they are just straight lines or planes. The discipline that deals with these objects is differential geometry. It is one of the most evolved and fascinating subjects in mathematics. On the other hand fractals feature just the opposite of smoothness. While the smooth objects do not yield any more detail on smaller scales a fractal possesses infinite detail at all scales no matter how small they are. The fascination that surrounds fractals has two roots: Fractals are very suitable to simulate many natural phenomena. Stunning pictures have already been produced, and it will not take very long until an uninitiated observer will no longer be able to tell whether a given scene is natural or just computer simulated. The other reason is that fractals are simple to generate on computers. In order to generate a fractal one does not have to be an expert of an involved theory such as calculus, which is necessary for differential geometry. More importantly, the complexity of a fractal, when measured in terms of the length of the shortest computer program that can generate it, is very small.}, + isbn = {978-1-4612-3784-6}, + langid = {english}, + keywords = {Brownian Motion,Fractal Cloud,Fractal Dimension,Fractional Brownian Motion,Random Function} +} + +@article{schiffersLimitedEvolutionaryRescue2013, + title = {Limited Evolutionary Rescue of Locally Adapted Populations Facing Climate Change}, + author = {Schiffers, Katja and Bourne, Elizabeth C. and Lavergne, S{\'e}bastien and Thuiller, Wilfried and Travis, Justin M. J.}, + year = {2013}, + month = jan, + journal = {Philosophical Transactions of the Royal Society B: Biological Sciences}, + volume = {368}, + number = {1610}, + pages = {20120083}, + issn = {0962-8436}, + doi = {10.1098/rstb.2012.0083}, + abstract = {Dispersal is a key determinant of a population's evolutionary potential. It facilitates the propagation of beneficial alleles throughout the distributional range of spatially outspread populations and increases the speed of adaptation. However, when habitat is heterogeneous and individuals are locally adapted, dispersal may, at the same time, reduce fitness through increasing maladaptation. Here, we use a spatially explicit, allelic simulation model to quantify how these equivocal effects of dispersal affect a population's evolutionary response to changing climate. Individuals carry a diploid set of chromosomes, with alleles coding for adaptation to non-climatic environmental conditions and climatic conditions, respectively. Our model results demonstrate that the interplay between gene flow and habitat heterogeneity may decrease effective dispersal and population size to such an extent that substantially reduces the likelihood of evolutionary rescue. Importantly, even when evolutionary rescue saves a population from extinction, its spatial range following climate change may be strongly narrowed, that is, the rescue is only partial. These findings emphasize that neglecting the impact of non-climatic, local adaptation might lead to a considerable overestimation of a population's evolvability under rapid environmental change.}, + pmcid = {PMC3538450}, + pmid = {23209165}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\3522YZAC\\Schiffers et al. - 2013 - Limited evolutionary rescue of locally adapted pop.pdf} +} + +@article{schtickzelleBehaviouralResponsesHabitat2003, + title = {Behavioural Responses to Habitat Patch Boundaries Restrict Dispersal and Generate Emigration\textendash Patch Area Relationships in Fragmented Landscapes}, + author = {Schtickzelle, Nicolas and Baguette, Michel}, + year = {2003}, + journal = {Journal of Animal Ecology}, + volume = {72}, + number = {4}, + pages = {533--545}, + issn = {1365-2656}, + doi = {10.1046/j.1365-2656.2003.00723.x}, + abstract = {We studied the consequences of behaviour at habitat patch boundaries on dispersal for the bog fritillary butterfly Proclossiana eunomia Esper in two networks of habitat differing in fragmentation and matrix quality. We tested for differences in responses to patch boundaries according to the fragmentation level of the network by analysing movement paths of adult butterflies. Butterflies systematically engaged in U-turns when they reached a boundary in the fragmented network while they crossed over boundaries in more than 40\% of boundary encounters in the continuous one. We applied the Virtual Migration model (Hanski, Alho \& Moilanen 2000) to capture\textendash mark\textendash recapture data collected in both networks. The model indicated (i) a lower dispersal rate and (ii) a lower survival during dispersal in the fragmented network. This latter difference is likely to be the key biological process leading to behavioural avoidance of patch boundary crossings. On the basis of this behavioural difference, we designed an individual-based simulation model to explore the relationship between patch area, boundary permeability and emigration rate. Predictions of the model fitted observed results of the effect of patch area on emigration rate according to fragmentation: butterflies are more likely to leave small patches than large ones in fragmented landscapes (where patch boundary permeability is low), while this relationship disappears in more continuous landscapes (where patch boundary permeability is high).}, + langid = {english}, + keywords = {boundary permeability,cost of dispersal,habitat fragmentation,metapopulation,Proclossiana eunomia}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1046/j.1365-2656.2003.00723.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VL9G8K9G\\Schtickzelle und Baguette - 2003 - Behavioural responses to habitat patch boundaries .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\C3ACNVD5\\j.1365-2656.2003.00723.html} +} + +@article{schtickzelleDispersalDepressionHabitat2006, + title = {Dispersal {{Depression}} with {{Habitat Fragmentation}} in the {{Bog Fritillary Butterfly}}}, + author = {Schtickzelle, Nicolas and Mennechez, Gw{\'e}na{\"e}lle and Baguette, Michel and Mennechez, Gw{\'e}nna{\"e}lle}, + year = {2006}, + journal = {Ecology}, + volume = {87}, + number = {4}, + pages = {1057--1065}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + abstract = {Habitat fragmentation is expected to impose strong selective pressures on dispersal rates. However, evolutionary responses of dispersal are not self-evident, since various selection pressures act in opposite directions. Here we disentangled the components of dispersal behavior in a metapopulation context using the Virtual Migration model, and we linked their variation to habitat fragmentation in the specialist butterfly Proclossiana eunomia. Our study provided a nearly unique opportunity to study how habitat fragmentation modifies dispersal at the landscape scale, as opposed to microlandscapes or simulation studies. Indeed, we studied the same species in four landscapes with various habitat fragmentation levels, in which large amounts of field data were collected and analyzed using similar methodologies. We showed the existence of quantitative variations in dispersal behavior correlated with increased fragmentation. Dispersal propensity from habitat patches (for a given patch size), and mortality during dispersal (for a given patch connectivity) were lower in more fragmented landscapes. We suggest that these were the consequences of two different evolutionary responses of dispersal behavior at the individual level: (1) when fragmentation increased, the reluctance of individuals to cross habitat patch boundaries also increased; (2) when individuals dispersed, they flew straighter in the matrix, which is the best strategy to improve dispersal success. Such evolutionary responses could generate complex nonlinear patterns of dispersal changes at the metapopulation level according to habitat fragmentation. Due to the small size and increased isolation of habitat patches in fragmented landscapes, overall emigration rate and mortality during dispersal remained high. As a consequence, successful dispersal at the metapopulation scale remained limited. Therefore, to what extent the selection of individuals with a lower dispersal propensity and a higher survival during dispersal is able to limit detrimental effects of habitat fragmentation on dispersal success is unknown, and any conclusion that metapopulations would compensate for them is flawed.} +} + +@incollection{schtickzelleTemporalVariationDispersal2012, + title = {Temporal Variation in Dispersal Kernels in a Metapopulation of the Bog Fritillary Butterfly ({{Boloria}} Eunomia)}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Schtickzelle, Nicolas and Turlure, Camille and Baguette, Michel}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0018}, + abstract = {This chapter aims to quantify the temporal variation existing in the dispersal kernel by making the kernels comparable. Variation of dispersal kernels in time has received less attention, even if temporal change in dispersal rates among local populations has been repeatedly documented in the metapopulation literature. Changes in individual mobility that generate temporal shifts in dispersal kernels would obviously be context- and phenotypic-dependent. Both environmental conditions and conspecific density are thus expected to play a central role in temporal variation of dispersal kernels. This chapter uses standardized capture-mark-recapture (CMR) data from long-term monitoring of bog fritillary butterfly, Boloria eunomia, metapopulation dynamics in a single landscape to investigate the amount of temporal variability and the amount of this temporal variability that has been explained by climatic variables and conspecific density.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {conspecific density,dispersal kernel,environmental conditions,individual mobility,metapopulation,temporal variation} +} + +@article{schultzEdgeMediatedDispersalBehavior2001, + title = {Edge-{{Mediated Dispersal Behavior}} in a {{Prairie Butterfly}}}, + author = {Schultz, Cheryl B. and Crone, Elizabeth E.}, + year = {2001}, + journal = {Ecology}, + volume = {82}, + number = {7}, + pages = {1879--1892}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + doi = {10.2307/2680054}, + abstract = {Animal responses to habitat boundaries will influence the effects of habitat fragmentation on population dynamics. Although this is an intuitive and often observed animal behavior, the influences of habitat boundaries have rarely been quantified in the field or considered in theoretical models of large scale processes. We quantified movement behavior of the Fender's blue butterfly (Icaricia icarioides fenderi) as a function of distance from host-plant patches. We measured the butterfly's tendency to move toward habitat patches (bias) and their tendency to continue to move in the direction they were already going (correlation). We found that butterflies significantly modify their behavior within 10-22 m from the habitat boundary. We used these data to predict large scale patterns of residence time as a function of patch size, using three dispersal models: homogeneous response to habitat, heterogeneous response to habitat, and heterogeneous response to habitat with edge-mediated behavior. We simulated movement for males and females in eight patch sizes (0.1-8 ha) and asked how residence time varies among the models. We found that adding edge-mediated behavior significantly increases the residence of Fender's blue butterflies in their natal patch. Only the model with edge-mediated behavior for females was consistent with independent mark-release-recapture (MRR) estimates of residence time; other models dramatically underestimated residence times, relative to MRR data.} +} + +@incollection{schurrHowRandomDispersal2012, + title = {How Random Is Dispersal? {{From}} Stochasticity to Process in the Description of Seed Movement}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Schurr, F. M.}, + editor = {Clobert, J and Baguette, M and Benton, T G and Bullock, J M}, + year = {2012}, + pages = {240--247}, + publisher = {{Oxford University Press}} +} + +@article{schurrHowUnderstandSpecies2012, + title = {How to Understand Species' Niches and Range Dynamics: A Demographic Research Agenda for Biogeography}, + shorttitle = {How to Understand Species' Niches and Range Dynamics}, + author = {Schurr, Frank M. and Pagel, J{\"o}rn and Cabral, Juliano Sarmento and Groeneveld, J{\"u}rgen and Bykova, Olga and O'Hara, Robert B. and Hartig, Florian and Kissling, W. Daniel and Linder, H. Peter and Midgley, Guy F. and Schr{\"o}der, Boris and Singer, Alexander and Zimmermann, Niklaus E.}, + year = {2012}, + journal = {Journal of Biogeography}, + volume = {39}, + number = {12}, + pages = {2146--2162}, + issn = {1365-2699}, + doi = {10.1111/j.1365-2699.2012.02737.x}, + abstract = {Range dynamics causes mismatches between a species' geographical distribution and the set of suitable environments in which population growth is positive (the Hutchinsonian niche). This is because source\textendash sink population dynamics cause species to occupy unsuitable environments, and because environmental change creates non-equilibrium situations in which species may be absent from suitable environments (due to migration limitation) or present in unsuitable environments that were previously suitable (due to time-delayed extinction). Because correlative species distribution models do not account for these processes, they are likely to produce biased niche estimates and biased forecasts of future range dynamics. Recently developed dynamic range models (DRMs) overcome this problem: they statistically estimate both range dynamics and the underlying environmental response of demographic rates from species distribution data. This process-based statistical approach qualitatively advances biogeographical analyses. Yet, the application of DRMs to a broad range of species and study systems requires substantial research efforts in statistical modelling, empirical data collection and ecological theory. Here we review current and potential contributions of these fields to a demographic understanding of niches and range dynamics. Our review serves to formulate a demographic research agenda that entails: (1) advances in incorporating process-based models of demographic responses and range dynamics into a statistical framework, (2) systematic collection of data on temporal changes in distribution and abundance and on the response of demographic rates to environmental variation, and (3) improved theoretical understanding of the scaling of demographic rates and the dynamics of spatially coupled populations. This demographic research agenda is challenging but necessary for improved comprehension and quantification of niches and range dynamics. It also forms the basis for understanding how niches and range dynamics are shaped by evolutionary dynamics and biotic interactions. Ultimately, the demographic research agenda should lead to deeper integration of biogeography with empirical and theoretical ecology.}, + langid = {english}, + keywords = {Biodiversity monitoring,climate change,ecological forecasts,ecological niche modelling,ecological theory,geographical range shifts,global environmental change,mechanistic models,migration,process-based statistics}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2012.02737.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\P5HSYZC4\\Schurr et al. - 2012 - How to understand species’ niches and range dynami.pdf} +} + +@article{schwagerDoesRedNoise2006, + title = {Does Red Noise Increase or Decrease Extinction Risk? {{Single}} Extreme Events versus Series of Unfavorable Conditions}, + shorttitle = {Does Red Noise Increase or Decrease Extinction Risk?}, + author = {Schwager, Monika and Johst, Karin and Jeltsch, Florian}, + year = {2006}, + month = jun, + journal = {The American Naturalist}, + volume = {167}, + number = {6}, + pages = {879--888}, + issn = {1537-5323}, + doi = {10.1086/503609}, + abstract = {Recent theoretical studies have shown contrasting effects of temporal correlation of environmental fluctuations (red noise) on the risk of population extinction. It is still debated whether and under which conditions red noise increases or decreases extinction risk compared with uncorrelated (white) noise. Here, we explain the opposing effects by introducing two features of red noise time series. On the one hand, positive autocorrelation increases the probability of series of poor environmental conditions, implying increasing extinction risk. On the other hand, for a given time period, the probability of at least one extremely bad year ("catastrophe") is reduced compared with white noise, implying decreasing extinction risk. Which of these two features determines extinction risk depends on the strength of environmental fluctuations and the sensitivity of population dynamics to these fluctuations. If extreme (catastrophic) events can occur (strong noise) or sensitivity is high (overcompensatory density dependence), then temporal correlation decreases extinction risk; otherwise, it increases it. Thus, our results provide a simple explanation for the contrasting previous findings and are a crucial step toward a general understanding of the effect of noise color on extinction risk.}, + langid = {english}, + pmid = {16615033}, + keywords = {Animals,Computer Simulation,Disasters,Environment,Extinction; Biological,Models; Biological} +} + +@article{schymanskiProcessCorrelationParameter2013, + title = {Process, Correlation and Parameter Fitting in Species Distribution Models: A Response to {{Kriticos}} et Al.}, + shorttitle = {Process, Correlation and Parameter Fitting in Species Distribution Models}, + author = {Schymanski, Stanislaus J. and Dormann, Carsten F. and Cabral, Juliano and Chuine, Isabelle and Graham, Catherine H. and Hartig, Florian and Kearney, Michael and Morin, Xavier and R{\"o}mermann, Christine and Schr{\"o}der, Boris and Singer, Alexander}, + year = {2013}, + journal = {Journal of Biogeography}, + volume = {40}, + number = {3}, + pages = {611--613}, + publisher = {{Wiley}}, + issn = {0305-0270}, + abstract = {In a recent article (Dormann et al., 2012, Journal of Biogeography, 39, 2119\textemdash 2131), we compared different approaches to species distribution modelling and depicted modelling approaches along an axis from purely 'correlative' to 'forward process-based' models. In their correspondence, Kriticos et al. (2013, Journal of Biogeography, doi:10.1111/j.1365-2699.2012.02791.x) challenge this view, claiming that our continuum representation neglects differences among models and does not consider the ability of fitted process-based models to combine the advantages of both process-based and correlative modelling approaches. Here we clarify that the continuum view resulted from recognition of the manifold differences between models. We also reinforce the point that the current trend towards combining different modelling approaches may lead not only to the desired combination of the advantages but also to the accumulation of the disadvantages of those approaches. This point has not been made sufficiently clear previously.} +} + +@article{sextonEvolutionEcologySpecies2009, + title = {Evolution and {{Ecology}} of {{Species Range Limits}}}, + author = {Sexton, Jason P. and McIntyre, Patrick J. and Angert, Amy L. and Rice, Kevin J.}, + year = {2009}, + journal = {Annual Review of Ecology, Evolution, and Systematics}, + volume = {40}, + number = {1}, + pages = {415--436}, + doi = {10.1146/annurev.ecolsys.110308.120317}, + abstract = {Species range limits involve many aspects of evolution and ecology, from species distribution and abundance to the evolution of niches. Theory suggests myriad processes by which range limits arise, including competitive exclusion, Allee effects, and gene swamping; however, most models remain empirically untested. Range limits are correlated with a number of abiotic and biotic factors, but further experimentation is needed to understand underlying mechanisms. Range edges are characterized by increased genetic isolation, genetic differentiation, and variability in individual and population performance, but evidence for decreased abundance and fitness is lacking. Evolution of range limits is understudied in natural systems; in particular, the role of gene flow in shaping range limits is unknown. Biological invasions and rapid distribution shifts caused by climate change represent large-scale experiments on the underlying dynamics of range limits. A better fusion of experimentation and theory will advance our understanding of the causes of range limits.}, + annotation = {\_eprint: https://doi.org/10.1146/annurev.ecolsys.110308.120317}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HD74T3Z2\\Sexton et al. - 2009 - Evolution and Ecology of Species Range Limits.pdf} +} + +@article{shreeveLandscapeScaleConservation2011, + title = {Landscape Scale Conservation: Resources, Behaviour, the Matrix and Opportunities}, + shorttitle = {Landscape Scale Conservation}, + author = {Shreeve, T. G. and Dennis, R. L. H.}, + year = {2011}, + month = apr, + journal = {Journal of Insect Conservation}, + volume = {15}, + number = {1}, + pages = {179--188}, + issn = {1572-9753}, + doi = {10.1007/s10841-010-9336-9}, + abstract = {Landscape scale conservation efforts are becoming more commonplace in conservation, with a move from single species to multi-species initiatives. These initiatives are reliant on modelling processes, largely underpinned by metapopulation models. We argue that generic models developed for individual species in particular landscapes over selected time periods may only be applicable to alternative landscapes and time periods in restricted circumstances. Variability in species responses to landscapes and environmental conditions is dependent on a range of species-specific intrinsic characteristics, dependent on their responses to resources, (including weather) and also individual states. We propose that the behavioural component of how species respond to resources needs to be taken into account in modelling species responses to landscape, and therefore how limited resources for conservation are deployed. Species behaviours are inherently complex. We argue that because of this complexity the conservation of the majority of species, especially of the least rare, may be best served if conservation effort is additionally focused on increasing landscape heterogeneity and disturbance. This may also facilitate persistence in the face of climate change. We suggest that heterogeneity should be promoted through agri-environment schemes.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6D5I6VCL\\Shreeve und Dennis - 2011 - Landscape scale conservation resources, behaviour.pdf} +} + +@article{simmonsChangesDispersalSpecies2004, + title = {Changes in Dispersal during Species' Range Expansions}, + author = {Simmons, Adam D. and Thomas, Chris D.}, + year = {2004}, + month = sep, + journal = {The American Naturalist}, + volume = {164}, + number = {3}, + pages = {378--395}, + issn = {1537-5323}, + doi = {10.1086/423430}, + abstract = {Explanations for rapid species' range expansions have typically been purely ecological, with little attention given to evolutionary processes. We tested predictions for the evolution of dispersal during range expansion using four species of wing-dimorphic bush cricket (Conocephalus discolor, Conocephalus dorsalis, Metrioptera roeselii, and Metrioptera brachyptera). We observed distinct changes in dispersal in the two species with expanding ranges. Recently colonized populations at the range margin showed increased frequencies of dispersive, long-winged (macropterous) individuals, compared with longer-established populations in the range core. This increase in dispersal appeared to be short-lived because 5-10 years after colonization populations showed similar incidences of macroptery to populations in the range core. These changes are consistent with evolutionary change; field patterns persisted when nymphs were reared under controlled environmental conditions, and range margin individuals reared in the laboratory flew farther than range core individuals in a wind tunnel. There was also a reproductive trade-off with dispersal in both females and males, which could explain the rapid reversion to lower rates of dispersal once populations become established. The effect of population density on wing morphology differed between populations from the range core (no significant effect of density) and expanding range margins (negative density dependence), which we propose is part of the mechanism of the changes in dispersal. Transient changes in dispersal are likely to be common in many species undergoing range expansion and can have major population and biogeographic consequences.}, + langid = {english}, + pmid = {15478092}, + keywords = {Animal Migration,Animals,Behavior; Animal,Biological Evolution,Body Weight,England,Female,Gryllidae,Male,Population Dynamics,Wings; Animal} +} + +@article{sinclairHowUsefulAre2010, + title = {How {{Useful Are Species Distribution Models}} for {{Managing Biodiversity}} under {{Future Climates}}?}, + author = {Sinclair, Steve J. and White, Matthew D. and Newell, Graeme R.}, + year = {2010}, + journal = {Ecology and Society}, + volume = {15}, + number = {1}, + publisher = {{Resilience Alliance Inc.}}, + issn = {1708-3087}, + abstract = {ABSTRACT. Climate change presents unprecedented challenges for biological conservation. Agencies are increasingly looking to modeled projections of species' distributions under future climates to inform management strategies. As government scientists with a responsibility to communicate the best available science to our policy colleagues, we question whether current modeling approaches and outputs are practically useful. Here, we synthesize conceptual problems with species distribution models (SDMs) associated with interspecific interactions, dispersal, ecological equilibria and time lags, evolution, and the sampling of niche space. Although projected SDMs have undoubtedly been critical in alerting us to the magnitude of climate change impacts, we conclude that until they offer insights that are more precise than what we can derive from basic ecological theory, we question their utility in deciding how to allocate scarce funds to large-scale conservation projects.} +} + +@article{singerInterspecificInteractionsAffect2013, + title = {Interspecific Interactions Affect Species and Community Responses to Climate Shifts}, + author = {Singer, Alexander and Travis, Justin M. J. and Johst, Karin}, + year = {2013}, + journal = {Oikos}, + volume = {122}, + number = {3}, + pages = {358--366}, + issn = {1600-0706}, + doi = {10.1111/j.1600-0706.2012.20465.x}, + abstract = {The response of individual species to climate change may alter the composition and dynamics of communities. Here, we show that the impacts of environmental change on communities can depend on the nature of the interspecific interactions: mutualistic communities typically respond differently than commensalistic or parasitic communities. We model and analyse the geographic range shifting of metapopulations of two interacting species \textendash{} a host and an obligate species. Different types of interspecific interactions are implemented by modifying local extinction rates according to the presence/absence of the other species. We distinguish and compare three fundamentally different community types: mutualism, commensalism and parasitism. We find that community dynamics during geographic range shifting critically depends on the type of interspecific interactions. Parasitic interactions exacerbate the negative effect of environmental change whereas mutualistic interactions only partly compensate it. Commensalistic interactions exhibit an intermediate response. Based on these model outcomes, we predict that parasitic species interactions may be more vulnerable to geographic range shifting than commensalistic or mutualistic ones. However, we observe that when climate stabilises following a period of change, the rate of community recovery is largely independent of the type of interspecific interactions. These results emphasize that communities respond delicately to environmental change, and that local interspecific interactions can affect range shifting communities at large spatial scales.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2012.20465.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\SEGSL2J7\\Singer et al. - 2013 - Interspecific interactions affect species and comm.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\LC2QTHEQ\\j.1600-0706.2012.20465.html} +} + +@article{smithStabilityPredatorPreySystems1973, + title = {The {{Stability}} of {{Predator-Prey Systems}}}, + author = {Smith, J. Maynard and Slatkin, M.}, + year = {1973}, + journal = {Ecology}, + volume = {54}, + number = {2}, + pages = {384--391}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + doi = {10.2307/1934346}, + abstract = {The interactions between a predator and prey species have been analyzed by computer simulation of a model in which there are discrete breeding seasons, separated by a winter during which the predator must be able to find prey at a certain minimum rate or starve. The model is intended to represent a warm-blooded vertebrate predator and its prey. The main conclusions are: (1) Coexistence of predator and prey is possible, but if so, the number of prey present will not be substantially below the equilibrium number in the absence of predators. Mutual regulation of predator and prey, with the latter substantially below the carrying capacity of the environment, is unstable. (2) Coexistence is more likely if there are differences in hunting ability between different individual predators--for example, between young and old predators. (3) Cover for the prey enables the prey species to survive the extinction of the predator, but does not make coexistence more likely.} +} + +@article{smouseStochasticModellingAnimal2010, + title = {Stochastic Modelling of Animal Movement}, + author = {Smouse, Peter E and Focardi, S and Moorcroft, P.R. and Kie, John G and Forester, J. D. and Morales, Juan M}, + year = {2010}, + journal = {Philosophical Transactions of the Royal Society of London. Series B, Biological Sciences}, + number = {365}, + pages = {2201--2211} +} + +@article{spearUseResistanceSurfaces2010, + title = {Use of Resistance Surfaces for Landscape Genetic Studies: Considerations for Parameterization and Analysis}, + shorttitle = {Use of Resistance Surfaces for Landscape Genetic Studies}, + author = {Spear, Stephen F. and Balkenhol, Niko and Fortin, Marie-Jos{\'e}e and McRae, Brad H. and Scribner, Kim}, + year = {2010}, + month = sep, + journal = {Molecular Ecology}, + volume = {19}, + number = {17}, + pages = {3576--3591}, + issn = {1365-294X}, + doi = {10.1111/j.1365-294X.2010.04657.x}, + abstract = {Measures of genetic structure among individuals or populations collected at different spatial locations across a landscape are commonly used as surrogate measures of functional (i.e. demographic or genetic) connectivity. In order to understand how landscape characteristics influence functional connectivity, resistance surfaces are typically created in a raster GIS environment. These resistance surfaces represent hypothesized relationships between landscape features and gene flow, and are based on underlying biological functions such as relative abundance or movement probabilities in different land cover types. The biggest challenge for calculating resistance surfaces is assignment of resistance values to different landscape features. Here, we first identify study objectives that are consistent with the use of resistance surfaces and critically review the various approaches that have been used to parameterize resistance surfaces and select optimal models in landscape genetics. We then discuss the biological assumptions and considerations that influence analyses using resistance surfaces, such as the relationship between gene flow and dispersal, how habitat suitability may influence animal movement, and how resistance surfaces can be translated into estimates of functional landscape connectivity. Finally, we outline novel approaches for creating optimal resistance surfaces using either simulation or computational methods, as well as alternatives to resistance surfaces (e.g. network and buffered paths). These approaches have the potential to improve landscape genetic analyses, but they also create new challenges. We conclude that no single way of using resistance surfaces is appropriate for every situation. We suggest that researchers carefully consider objectives, important biological assumptions and available parameterization and validation techniques when planning landscape genetic studies.}, + langid = {english}, + pmid = {20723064}, + keywords = {Algorithms,Artificial Intelligence,Computer Simulation,Ecology,Environment,Gene Flow,Genetics; Population,Geography,Models; Genetic} +} + +@article{stampsConspecificAttractionAggregation1988, + title = {Conspecific {{Attraction}} and {{Aggregation}} in {{Territorial Species}}}, + author = {Stamps, J. A.}, + year = {1988}, + journal = {The American Naturalist}, + volume = {131}, + number = {3}, + pages = {329--347}, + publisher = {{[University of Chicago Press, American Society of Naturalists]}}, + issn = {0003-0147}, + abstract = {For many years, field studies of birds have suggested that territorial individuals may be attracted to one another, forming territorial clusters independent of resource distributions. However, virtually no experiments have studied these phenomena in either the laboratory or the field. The present field study was designed to test whether prospective territory owners preferentially settle near conspecifics and form territorial aggregations when territory quality is held constant. Juvenile Anolis aeneus lizards arriving at juvenile habitats in clearings were given a choice of artificial homesites arranged around a clear-walled enclosure divided into two parts, one of which contained resident A. aeneus juveniles. Juveniles showed a clear preference for the homesites adjacent to the established territorial residents (the "experimental" homesites). In each of eight trials, the first arrivals appeared on the experimental homesites. Juveniles that first appeared on the experimental homesites were more apt to settle in the clearing, and colonists on the experimental side moved around less before choosing a final territory. During the colonization process, juveniles spent more time on the experimental sides of the enclosures; and by the end of the trials, more juveniles had eventually settled on the experimental homesites. Throughout the settlement process, new territory owners tended to cluster around the previous residents within the experimental side of the enclosures. These results indicate that A. aeneus juveniles are attracted to conspecifics while settling a territory and that this process can lead to territorial aggregations that are independent of territory quality.} +} + +@article{stampsEffectsNatalExperience2006, + title = {Effects of Natal Experience on Habitat Selection When Individuals Make Choices in Groups: {{A}} Multilevel Analysis}, + shorttitle = {Effects of Natal Experience on Habitat Selection When Individuals Make Choices in Groups}, + author = {Stamps, Judy A. and Blozis, Shelley A.}, + year = {2006}, + journal = {Animal Behaviour}, + volume = {71}, + number = {3}, + pages = {663--672}, + publisher = {{Elsevier Science}}, + address = {{Netherlands}}, + issn = {1095-8282(Electronic),0003-3472(Print)}, + doi = {10.1016/j.anbehav.2005.07.015}, + abstract = {We studied the effects of natal experience on preference for a postdispersal habitat (natal habitat preference induction, NHPI) in groups of newly eclosed female Drosophila melanogaster, using multilevel statistical models to take into account dependencies of responses from individuals making choices within the same hour. Groups consisting of flies with one of five genotypes (crosses of highly inbred female isolines) were allowed free access to a high-quality natal habitat after emergence from their pupae. The flies were then allowed to select one of two new habitats in a large 'seminatural' environment over the next 3 days. The flies showed strong positive effects of training habitat on their choice of a new habitat, after controlling for potential dependence in choices within hours and trials. The genotypes also varied with respect to the effects of conspecifics and humidity on individual choice. A second analysis using data aggregated at the trial level and a traditional statistical approach (a generalized linear model, GLM) also detected effects of training on habitat choice. However, the GLM produced other results that may have been artefacts resulting from the omission of within-trial factors with important effects on choice in this trial-level analysis. This study shows the advantages of using multilevel models rather than aggregating data to control for interactions among subjects when animals select items in groups. (PsycINFO Database Record (c) 2017 APA, all rights reserved)}, + keywords = {Animal Environments,Choice Behavior,Drosophila,Early Experience,Female Animals,Genotypes}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GW2GM63A\\2006-03109-022.html} +} + +@incollection{stampsHabitatSelectionDispersers2001, + title = {Habitat Selection by Dispersers: Integrating Proximate and Ultimate Approaches}, + shorttitle = {Habitat Selection by Dispersers}, + booktitle = {Dispersal}, + author = {Stamps, Judy}, + editor = {Clobert, J. and Danchin, Etienne and Dhondt, Andre A. and Nichols, James D.}, + year = {2001}, + month = jan, + pages = {230--242}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + abstract = {Behavioural research is shedding new light on the complex relationships between the proximate mechanisms involved in habitat selection and the selective pressures that may have contributed to the evolution of those mechanisms. Habitat selection by dispersers can be divided into three stages (search, settlement and residency); recent studies suggest that the adaptive significance of behaviour at each of these stages may differ from the assumptions of traditional habitat selection theory. For instance, dispersers may benefit from the presence of conspecifics or heterospecifics while searching for, settling in, or living in new habitats, and individuals may prefer to settle in post-dispersal habitats similar to their pre-dispersal habitats, because this behaviour reduces the costs of detecting or assessing suitable habitats (habitat cuing) or because experience in a pre-dispersal habitat improves performance if an animal settles in the same type of habitat after dispersing (habitat training). Dispersers have evolved a variety of proximate behavioural mechanisms to reduce search and settlement costs in natural environments, but if they currently rely on these processes, species living in areas modified by human activities may not exhibit 'ideal' habitat selection behaviour. Insights from recent studies of habitat selection may help solve specific problems in conservation biology, and more generally, help biologists understand the intimate relationship between dispersal and habitat selection behaviour.}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\PZNZVCJ8\\Stamps - 2001 - Habitat selection by dispersers integrating proxi.pdf} +} + +@article{stampsHowDifferentTypes2009, + title = {How {{Different Types}} of {{Natal Experience Affect Habitat Preference}}}, + author = {Stamps, Judy A. and Krishnan, V. V. and Willits, Neil H. and Ketterson, Associate Editor: Ellen D. and Shaw, Editor: Ruth G.}, + year = {2009}, + journal = {The American Naturalist}, + volume = {174}, + number = {5}, + pages = {623--630}, + publisher = {{[The University of Chicago Press, The American Society of Naturalists]}}, + issn = {0003-0147}, + doi = {10.1086/644526}, + abstract = {Abstract: In many animals, exposure to cues in a natal habitat increases disperser preferences for those cues (natal habitat preference induction [NHPI]), but the proximate and ultimate bases for this phenomenon are obscure. We developed a Bayesian model to study how different types of experience in the natal habitat and survival to the age/stage of dispersal interact to affect a disperser's estimate of the quality of new natal-type habitats. The model predicts that the types of experience a disperser had before leaving its natal habitat will affect the attractiveness of cues from new natal-type habitats and that favorable experiences will increase the level of preference for natal-type habitats more than unfavorable experiences will decrease it. An experimental study of NHPI in Drosophila melanogaster provided with ``good'' and ``bad'' experiences in their natal habitats supports these predictions while also indicating that the effects of different types of natal experience on NHPI vary across genotypes. If habitat preferences are modulated by an individual's experience before dispersal as described in this study, then NHPI may have stronger effects on sympatric speciation, metapopulation dynamics, conservation biology, and pest management than previously supposed.} +} + +@article{stampsSearchCostsHabitat2005, + title = {Search {{Costs}} and {{Habitat Selection}} by {{Dispersers}}}, + author = {Stamps, Judy A. and Krishnan, V. V. and Reid, Mary L.}, + year = {2005}, + journal = {Ecology}, + volume = {86}, + number = {2}, + pages = {510--518}, + publisher = {{Ecological Society of America}}, + issn = {0012-9658}, + abstract = {The effects of search costs on habitat selection by dispersers are largely unknown. We explore how habitat selection behavior is affected by the risk of mortality en route and by deferred search costs (i.e., costs incurred during search that reduce fitness after arrival in the new habitat), using a model designed for long-distance natal dispersers searching for scarce patches of suitable habitat embedded within a matrix of unsuitable habitat. In this situation, increases in the risk of mortality during search reduce disperser selectivity, where selectivity is reflected by the period during search when dispersers are only willing to accept a high-quality habitat. However, the effects of deferred costs on selectivity depend on other factors with pronounced effects on selectivity, including encounter rates with high-quality habitats, relative habitat quality, and total search time. Surprisingly, under some sets of conditions, increases in deferred costs lead to increases in disperser selectivity. Overall, the effects of mortality and deferred costs on selectivity are small relative to the effects of other factors on selectivity. For instance, our model suggests that selectivity is much more strongly affected by total search time than by search costs, and it predicts a positive relationship between total search time and disperser selectivity across individuals in the same population, even in the face of considerable inter-individual variation in risk of mortality or deferred search costs.} +} + +@article{starrfeltParentoffspringConflictEvolution2010, + title = {Parent-Offspring Conflict and the Evolution of Dispersal Distance}, + author = {Starrfelt, Jostein and Kokko, Hanna}, + year = {2010}, + month = jan, + journal = {The American Naturalist}, + volume = {175}, + number = {1}, + pages = {38--49}, + issn = {1537-5323}, + doi = {10.1086/648605}, + abstract = {Parent-offspring conflict emerges in many different contexts, but a rarely emphasized perspective is that of space as a resource that is allocated or acquired through dispersal. Early theoretical work has shown that there are different optima in rates of dispersal between parents and offspring. Here we examine this principle when space is explicitly modeled and dispersal is achieved through a dispersal kernel. We find a consistent pattern that selection favors longer dispersal distances under maternal control of dispersal (e.g., maternal tissue surrounding a seed) compared with scenarios where offspring themselves control dispersal (as in many animals). Intriguingly, offspring control leads to better resource utilization (higher habitat occupancy) in equilibrium scenarios than does maternal control. In contrast, in species that expand their ranges, maternal control of dispersal initially leads to faster range expansion. If there is evolutionary potential for dispersal kernels to change at the leading edge of a population, this difference vanishes quickly during an invasion because offspring-controlled dispersal evolves faster and catches up with scenarios involving maternal control. There is thus less conflict in nonequilibrium scenarios. In invasive scenarios with an evolving kernel shape, disruptive selection against intermediate distances can make the kernel not only fat-tailed but also bimodal.}, + langid = {english}, + pmid = {19911910}, + keywords = {Animal Migration,Animals,Computer Simulation,Conflict; Psychological,Female,Homing Behavior,Models; Theoretical,Population Density,Population Dynamics,Reproduction} +} + +@book{stensethAnimalDispersalSmall1992, + title = {Animal {{Dispersal}}: {{Small}} Mammals as a Model}, + shorttitle = {Animal {{Dispersal}}}, + editor = {Stenseth, N. C. and Lidicker, W. Z.}, + year = {1992}, + publisher = {{Springer Netherlands}}, + doi = {10.1007/978-94-011-2338-9}, + abstract = {4.1.1 Demographic significance Confined populations grow more rapidly than populations from which dispersal is permitted (Lidicker, 1975; Krebs, 1979; Tamarin et at., 1984), and demography in island populations where dispersal is restricted differs greatly from nearby mainland populations (Lidicker, 1973; Tamarin, 1977, 1978; Gliwicz, 1980), clearly demonstrating the demographic signi\- ficance of dispersal. The prevalence of dispersal in rapidly expanding populations is held to be the best evidence for presaturation dispersal. Because dispersal reduces the growth rate of source populations, it is generally believed that emigration is not balanced by immigration, and that mortality of emigrants occurs as a result of movement into a 'sink' of unfavourable habitat. If such dispersal is age- or sex-biased, the demo\- graphy of the population is markedly affected, as a consequence of differ\- ences in mortality in the dispersive sex or age class. Habitat heterogeneity consequently underlies this interpretation of dispersal and its demographic consequences, although the spatial variability of environments is rarely assessed in dispersal studies.}, + isbn = {978-0-412-29330-6}, + langid = {english} +} + +@article{stevensGeneFlowFunctional2006, + title = {Gene Flow and Functional Connectivity in the Natterjack Toad}, + author = {Stevens, Virginie M. and Verkenne, Catherine and Vandewoestijne, Sofie and Wesselingh, Renate A. and Baguette, Michel}, + year = {2006}, + month = aug, + journal = {Molecular Ecology}, + volume = {15}, + number = {9}, + pages = {2333--2344}, + issn = {0962-1083}, + doi = {10.1111/j.1365-294X.2006.02936.x}, + abstract = {Functional connectivity is a key factor for the persistence of many specialist species in fragmented landscapes. However, connectivity estimates have rarely been validated by the observation of dispersal movements. In this study, we estimated functional connectivity of a real landscape by modelling dispersal for the endangered natterjack toad (Bufo calamita) using cost distance. Cost distance allows the evaluation of 'effective distances', which are distances corrected for the costs involved in moving between habitat patches in spatially explicit landscapes. We parameterized cost-distance models using the results of our previous experimental investigation of natterjack's movement behaviour. These model predictions (connectivity estimates from the GIS study) were then confronted to genetic-based dispersal rates between natterjack populations in the same landscape using Mantel tests. Dispersal rates between the populations were inferred from variation at six microsatellite loci. Based on these results, we conclude that matrix structure has a strong effect on dispersal rates. Moreover, we found that cost distances generated by habitat preferences explained dispersal rates better than did the Euclidian distances, or the connectivity estimate based on patch-specific resistances (patch viscosity). This study is a clear example of how landscape genetics can validate operational functional connectivity estimates.}, + langid = {english}, + pmid = {16842409}, + keywords = {Animals,Belgium,Bufonidae,Gene Flow,Genetic Variation,Microsatellite Repeats,Population Dynamics} +} + +@incollection{stevensLandscapeEffectsSpatial2012, + title = {Landscape Effects on Spatial Dynamics: The Natterjack Toad as a Case Study}, + shorttitle = {Landscape Effects on Spatial Dynamics}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Stevens, Virginie M. and Coulon, Aur{\'e}lie}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0022}, + abstract = {This chapter discusses the two reasons that make dispersal a key process in population dynamics: first, the movement of individuals impacts population dynamics, and second, dispersal movement also has important consequences for the degree of genetic mixing expected among populations, and hence on the genetic variation found within populations. This chapter, in the attempt to address the question of what landscape changes may affect spatial dynamics, presents an example of a species with limited mobility and one which has been extensively studied in this regard \textemdash{} the natterjack toad. Firstly, empirical studies were used to measure the effects of landscape elements on movement patterns. Secondly, the results from these empirical studies were used to model the effects of landscape on movement patterns. Thirdly, the model was validated through a comparison of the movements predicted by the models with those estimated by the analysis of gene flow among populations. Finally, the model was used to predict natterjack population dynamics under different landscape management scenarios.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {dispersal movement,genetic mixing,genetic variation,natterjack toad,population dynamics,spatial dynamics} +} + +@article{stevensMetaanalysisDispersalButterflies2010, + title = {A Meta-Analysis of Dispersal in Butterflies}, + author = {Stevens, Virginie M. and Turlure, Camille and Baguette, Michel}, + year = {2010}, + journal = {Biological Reviews}, + volume = {85}, + number = {3}, + pages = {625--642}, + issn = {1469-185X}, + doi = {10.1111/j.1469-185X.2009.00119.x}, + abstract = {Dispersal has recently gained much attention because of its crucial role in the conservation and evolution of species facing major environmental changes such as habitat loss and fragmentation, climate change, and their interactions. Butterflies have long been recognized as ideal model systems for the study of dispersal and a huge amount of data on their ability to disperse has been collected under various conditions. However, no single `best' method seems to exist leading to the co-occurrence of various approaches to study butterfly mobility, and therefore a high heterogeneity among data on dispersal across this group. Accordingly, we here reviewed the knowledge accumulated on dispersal and mobility in butterflies, to detect general patterns. This meta-analysis specifically addressed two questions. Firstly, do the various methods provide a congruent picture of how dispersal ability is distributed across species? Secondly, is dispersal species-specific? Five sources of data were analysed: multisite mark-recapture experiments, genetic studies, experimental assessments, expert opinions, and transect surveys. We accounted for potential biases due to variation in genetic markers, sample sizes, spatial scales or the level of habitat fragmentation. We showed that the various dispersal estimates generally converged, and that the relative dispersal ability of species could reliably be predicted from their relative vagrancy (records of butterflies outside their normal habitat). Expert opinions gave much less reliable estimates of realized dispersal but instead reflected migration propensity of butterflies. Within-species comparisons showed that genetic estimates were relatively invariable, while other dispersal estimates were highly variable. This latter point questions dispersal as a species-specific, invariant trait.}, + langid = {english}, + keywords = {butterfly,dispersal,genetic structure,Lepidoptera,mark-release-recapture,meta-analysis,migration,mobility,vagrancy}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1469-185X.2009.00119.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\GSJ39H3B\\Stevens et al. - 2010 - A meta-analysis of dispersal in butterflies.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\5MP6UBQH\\j.1469-185X.2009.00119.html} +} + +@article{stevensQuantifyingFunctionalConnectivity2006, + title = {Quantifying Functional Connectivity: Experimental Assessment of Boundary Permeability for the Natterjack Toad ({{Bufo}} Calamita)}, + shorttitle = {Quantifying Functional Connectivity}, + author = {Stevens, Virginie M. and Lebouleng{\'e}, {\'E}ric and Wesselingh, Renate A. and Baguette, Michel}, + year = {2006}, + month = nov, + journal = {Oecologia}, + volume = {150}, + number = {1}, + pages = {161--171}, + issn = {1432-1939}, + doi = {10.1007/s00442-006-0500-6}, + abstract = {Like other pond-breeding amphibians, the natterjack toad (Bufo calamita) typically presents a patchy distribution. Because the species experiences high probabilities of local population extinction, its persistence within landscapes relies on both local and landscape-scale processes [dispersal allowing the (re)colonization of habitat patches]. However, the structure and composition of the matrix surrounding local populations can alter the dispersal rates between populations. As shown previously (Landscape Ecol 19:829\textendash 842, 2004), the locomotor performances of individuals at the dispersal stage depend on the nature of the component crossed: some landscape components offer high resistance to movement (high resistance or high viscosity components) whereas others allow high efficiency of movement (low resistance components). We now examine the ability of individuals to discriminate between landscape components and select low-resistance components. Our experimental study investigates the ways in which young natterjack toads choose from among landscape components common to southern Belgium. Toadlets (the dispersal stage) were experimentally confronted with boundaries between surrogates of sandy soils, roads, forests, agricultural fields and intensive pastures. Our results show: 1 the ability of toadlets to react to boundaries between landscape components, 2 differences in permeability among boundaries, and 3 our inability to predict correctly the permeability of the boundaries from the patch-specific resistance assessed previously. Toadlets showed a preference for bare environments and forests, whereas they avoided the use of agricultural environments. This pattern could not be explained in terms of patch-specific resistance only, and is discussed in terms of mortality risks and resource availability in the various landscape components, with particular attention to repercussions on conservation strategies.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\XFCWCPEX\\Stevens et al. - 2006 - Quantifying functional connectivity experimental .pdf} +} + +@article{thomasClimateClimateChange2010, + title = {Climate, Climate Change and Range Boundaries}, + author = {Thomas, Chris D.}, + year = {2010}, + journal = {Diversity and Distributions}, + volume = {16}, + number = {3}, + pages = {488--495}, + issn = {1472-4642}, + doi = {10.1111/j.1472-4642.2010.00642.x}, + abstract = {Aim A major issue in ecology, biogeography, conservation biology and invasion biology is the extent to which climate, and hence climate change, contributes to the positions of species' range boundaries. Thirty years of rapid climate warming provides an excellent opportunity to test the hypothesis that climate acts as a major constraint on range boundaries, treating anthropogenic climate change as a large-scale experiment. Location UK and global data, and literature. Methods This article analyses the frequencies with which species have responded to climate change by shifting their range boundaries. It does not consider abundance or other changes. Results For the majority of species, boundaries shifted in a direction that is concordant with being a response to climate change; 84\% of all species have expanded in a polewards direction as the climate has warmed (for the best data available), which represents an excess of 68\% of species after taking account of the fact that some species may shift in this direction for non-climatic reasons. Other data sets also show an excess of animal range boundaries expanding in the expected direction. Main conclusions Climate is likely to contribute to the majority of terrestrial and freshwater range boundaries. This generalization excludes species that are endemic to specific islands, lakes, rivers and geological outcrops, although these local endemics are not immune from the effects of climate change. The observed shifts associated with recent climate change are likely to have been brought about through both direct and indirect (changes to species' interactions) effects of climate; indirect effects are discussed in relation to laboratory experiments and invasive species. Recent observations of range boundary shifts are consistent with the hypothesis that climate contributes to, but is not the sole determinant of, the position of the range boundaries of the majority of terrestrial animal species.}, + langid = {english}, + keywords = {Adaptation,biological invasions,climate warming,distributions,extinction,range margins,thermal ecology}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2010.00642.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QPSUM57U\\Thomas - 2010 - Climate, climate change and range boundaries.pdf} +} + +@article{thomasExtinctionRiskClimate2004, + title = {Extinction Risk from Climate Change}, + author = {Thomas, Chris D. and Cameron, Alison and Green, Rhys E. and Bakkenes, Michel and Beaumont, Linda J. and Collingham, Yvonne C. and Erasmus, Barend F. N. and {de Siqueira}, Marinez Ferreira and Grainger, Alan and Hannah, Lee and Hughes, Lesley and Huntley, Brian and {van Jaarsveld}, Albert S. and Midgley, Guy F. and Miles, Lera and {Ortega-Huerta}, Miguel A. and Townsend Peterson, A. and Phillips, Oliver L. and Williams, Stephen E.}, + year = {2004}, + month = jan, + journal = {Nature}, + volume = {427}, + number = {6970}, + pages = {145--148}, + publisher = {{Nature Publishing Group}}, + issn = {1476-4687}, + doi = {10.1038/nature02121}, + abstract = {Climate change over the past {$\sim$}30 years has produced numerous shifts in the distributions and abundances of species1,2 and has been implicated in one species-level extinction3. Using projections of species' distributions for future climate scenarios, we assess extinction risks for sample regions that cover some 20\% of the Earth's terrestrial surface. Exploring three approaches in which the estimated probability of extinction shows a power-law relationship with geographical range size, we predict, on the basis of mid-range climate-warming scenarios for 2050, that 15\textendash 37\% of species in our sample of regions and taxa will be `committed to extinction'. When the average of the three methods and two dispersal scenarios is taken, minimal climate-warming scenarios produce lower projections of species committed to extinction ({$\sim$}18\%) than mid-range ({$\sim$}24\%) and maximum-change ({$\sim$}35\%) scenarios. These estimates show the importance of rapid implementation of technologies to decrease greenhouse gas emissions and strategies for carbon sequestration.}, + copyright = {2003 Macmillan Magazines Ltd.}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Research}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\HI7CVX3F\\Thomas et al. - 2004 - Extinction risk from climate change.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\PSWK38HT\\nature02121.html} +} + +@article{thomasTranslocationSpeciesClimate2011, + title = {Translocation of Species, Climate Change, and the End of Trying to Recreate Past Ecological Communities}, + author = {Thomas, Chris D.}, + year = {2011}, + month = may, + journal = {Trends in Ecology \& Evolution}, + volume = {26}, + number = {5}, + pages = {216--221}, + issn = {1872-8383}, + doi = {10.1016/j.tree.2011.02.006}, + abstract = {Many of the species at greatest risk of extinction from anthropogenic climate change are narrow endemics that face insurmountable dispersal barriers. In this review, I argue that the only viable option to maintain populations of these species in the wild is to translocate them to other locations where the climate is suitable. Risks of extinction to native species in destination areas are small, provided that translocations take place within the same broad geographic region and that the destinations lack local endemics. Biological communities in these areas are in the process of receiving many hundreds of other immigrant species as a result of climate change; ensuring that some of the 'new' inhabitants are climate-endangered species could reduce the net rate of extinction.}, + langid = {english}, + pmid = {21411178}, + keywords = {Biota,Climate Change,Conservation of Natural Resources,Environment,Extinction; Biological} +} + +@article{thuillerBIOMODPlatformEnsemble2009a, + title = {{{BIOMOD}} \textendash{} a Platform for Ensemble Forecasting of Species Distributions}, + author = {Thuiller, Wilfried and Lafourcade, Bruno and Engler, Robin and Ara{\'u}jo, Miguel B.}, + year = {2009}, + journal = {Ecography}, + volume = {32}, + number = {3}, + pages = {369--373}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2008.05742.x}, + abstract = {BIOMOD is a computer platform for ensemble forecasting of species distributions, enabling the treatment of a range of methodological uncertainties in models and the examination of species-environment relationships. BIOMOD includes the ability to model species distributions with several techniques, test models with a wide range of approaches, project species distributions into different environmental conditions (e.g. climate or land use change scenarios) and dispersal functions. It allows assessing species temporal turnover, plot species response curves, and test the strength of species interactions with predictor variables. BIOMOD is implemented in R and is a freeware, open source, package.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2008.05742.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\V2PLBLC9\\Thuiller et al. - 2009 - BIOMOD – a platform for ensemble forecasting of sp.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\YY2UVVUC\\j.1600-0587.2008.05742.html} +} + +@article{thuillerClimateChangeThreats2005, + title = {Climate Change Threats to Plant Diversity in {{Europe}}}, + author = {Thuiller, Wilfried and Lavorel, Sandra and Ara{\'u}jo, Miguel B. and Sykes, Martin T. and Prentice, I. Colin}, + year = {2005}, + month = jun, + journal = {Proceedings of the National Academy of Sciences}, + volume = {102}, + number = {23}, + pages = {8245--8250}, + publisher = {{National Academy of Sciences}}, + issn = {0027-8424, 1091-6490}, + doi = {10.1073/pnas.0409902102}, + abstract = {Climate change has already triggered species distribution shifts in many parts of the world. Increasing impacts are expected for the future, yet few studies have aimed for a general understanding of the regional basis for species vulnerability. We projected late 21st century distributions for 1,350 European plants species under seven climate change scenarios. Application of the International Union for Conservation of Nature and Natural Resources Red List criteria to our projections shows that many European plant species could become severely threatened. More than half of the species we studied could be vulnerable or threatened by 2080. Expected species loss and turnover per pixel proved to be highly variable across scenarios (27-42\% and 45-63\% respectively, averaged over Europe) and across regions (2.5-86\% and 17-86\%, averaged over scenarios). Modeled species loss and turnover were found to depend strongly on the degree of change in just two climate variables describing temperature and moisture conditions. Despite the coarse scale of the analysis, species from mountains could be seen to be disproportionably sensitive to climate change ({$\approx$}60\% species loss). The boreal region was projected to lose few species, although gaining many others from immigration. The greatest changes are expected in the transition between the Mediterranean and Euro-Siberian regions. We found that risks of extinction for European plants may be large, even in moderate scenarios of climate change and despite inter-model variability.}, + chapter = {Biological Sciences}, + copyright = {Copyright \textcopyright{} 2005, The National Academy of Sciences. Freely available online through the PNAS open access option.}, + langid = {english}, + pmid = {15919825}, + keywords = {Intergovernmental Panel on Climate Change storylines,niche-based model,species extinction,species turnover}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6GXYGT85\\Thuiller et al. - 2005 - Climate change threats to plant diversity in Europ.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\5WF56L7K\\8245.html} +} + +@article{thuillerPredictingGlobalChange2008, + title = {Predicting Global Change Impacts on Plant Species' Distributions: {{Future}} Challenges}, + shorttitle = {Predicting Global Change Impacts on Plant Species' Distributions}, + author = {Thuiller, Wilfried and Albert, C{\'e}cile and Ara{\'u}jo, Miguel B. and Berry, Pam M. and Cabeza, Mar and Guisan, Antoine and Hickler, Thomas and Midgley, Guy F. and Paterson, James and Schurr, Frank M. and Sykes, Martin T. and Zimmermann, Niklaus E.}, + year = {2008}, + month = mar, + journal = {Perspectives in Plant Ecology, Evolution and Systematics}, + series = {Space Matters - {{Novel}} Developments in Plant Ecology through Spatial Modelling}, + volume = {9}, + number = {3}, + pages = {137--152}, + issn = {1433-8319}, + doi = {10.1016/j.ppees.2007.09.004}, + abstract = {Given the rate of projected environmental change for the 21st century, urgent adaptation and mitigation measures are required to slow down the on-going erosion of biodiversity. Even though increasing evidence shows that recent human-induced environmental changes have already triggered species' range shifts, changes in phenology and species' extinctions, accurate projections of species' responses to future environmental changes are more difficult to ascertain. This is problematic, since there is a growing awareness of the need to adopt proactive conservation planning measures using forecasts of species' responses to future environmental changes. There is a substantial body of literature describing and assessing the impacts of various scenarios of climate and land-use change on species' distributions. Model predictions include a wide range of assumptions and limitations that are widely acknowledged but compromise their use for developing reliable adaptation and mitigation strategies for biodiversity. Indeed, amongst the most used models, few, if any, explicitly deal with migration processes, the dynamics of population at the ``trailing edge'' of shifting populations, species' interactions and the interaction between the effects of climate and land-use. In this review, we propose two main avenues to progress the understanding and prediction of the different processes occurring on the leading and trailing edge of the species' distribution in response to any global change phenomena. Deliberately focusing on plant species, we first explore the different ways to incorporate species' migration in the existing modelling approaches, given data and knowledge limitations and the dual effects of climate and land-use factors. Secondly, we explore the mechanisms and processes happening at the trailing edge of a shifting species' distribution and how to implement them into a modelling approach. We finally conclude this review with clear guidelines on how such modelling improvements will benefit conservation strategies in a changing world.}, + langid = {english}, + keywords = {Conservation planning,Global change,Habitat models,Process-based models,Species distribution modeling}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\76H4F7LQ\\S1433831907000376.html} +} + +@article{thuillerRoadMapIntegrating2013, + title = {A Road Map for Integrating Eco-Evolutionary Processes into Biodiversity Models}, + author = {Thuiller, Wilfried and M{\"u}nkem{\"u}ller, Tamara and Lavergne, S{\'e}bastien and Mouillot, David and Mouquet, Nicolas and Schiffers, Katja and Gravel, Dominique}, + year = {2013}, + journal = {Ecology Letters}, + volume = {16}, + number = {s1}, + pages = {94--105}, + issn = {1461-0248}, + doi = {10.1111/ele.12104}, + abstract = {The demand for projections of the future distribution of biodiversity has triggered an upsurge in modelling at the crossroads between ecology and evolution. Despite the enthusiasm around these so-called biodiversity models, most approaches are still criticised for not integrating key processes known to shape species ranges and community structure. Developing an integrative modelling framework for biodiversity distribution promises to improve the reliability of predictions and to give a better understanding of the eco-evolutionary dynamics of species and communities under changing environments. In this article, we briefly review some eco-evolutionary processes and interplays among them, which are essential to provide reliable projections of species distributions and community structure. We identify gaps in theory, quantitative knowledge and data availability hampering the development of an integrated modelling framework. We argue that model development relying on a strong theoretical foundation is essential to inspire new models, manage complexity and maintain tractability. We support our argument with an example of a novel integrated model for species distribution modelling, derived from metapopulation theory, which accounts for abiotic constraints, dispersal, biotic interactions and evolution under changing environmental conditions. We hope such a perspective will motivate exciting and novel research, and challenge others to improve on our proposed approach.}, + langid = {english}, + keywords = {Biotic interactions,hybrid modelling,metacommunity,rapid adaptation,species distribution}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ele.12104}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ZIYWEFA9\\Thuiller et al. - 2013 - A road map for integrating eco-evolutionary proces.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\T4IQJ2MV\\ele.html} +} + +@article{travisAcceleratingInvasionRates2009, + title = {Accelerating Invasion Rates Result from the Evolution of Density-Dependent Dispersal}, + author = {Travis, Justin M. J. and Mustin, Karen and Benton, Tim G. and Dytham, Calvin}, + year = {2009}, + month = jul, + journal = {Journal of Theoretical Biology}, + volume = {259}, + number = {1}, + pages = {151--158}, + issn = {0022-5193}, + doi = {10.1016/j.jtbi.2009.03.008}, + abstract = {Evolutionary processes play an important role in shaping the dynamics of range expansions, and selection on dispersal propensity has been demonstrated to accelerate rates of advance. Previous theory has considered only the evolution of unconditional dispersal rates, but dispersal is often more complex. For example, many species emigrate in response to crowding. Here, we use an individual-based model to investigate the evolution of density dependent dispersal into empty habitat, such as during an invasion. The landscape is represented as a lattice and dispersal between populations follows a stepping-stone pattern. Individuals carry three `genes' that determine their dispersal strategy when experiencing different population densities. For a stationary range we obtain results consistent with previous theoretical studies: few individuals emigrate from patches that are below equilibrium density. However, during the range expansion of a previously stationary population, we observe evolution towards dispersal strategies where considerable emigration occurs well below equilibrium density. This is true even for moderate costs to dispersal, and always results in accelerating rates of range expansion. Importantly, the evolution we observe at an expanding front depends upon fitness integrated over several generations and cannot be predicted by a consideration of lifetime reproductive success alone. We argue that a better understanding of the role of density dependent dispersal, and its evolution, in driving population dynamics is required especially within the context of range expansions.}, + langid = {english}, + keywords = {Climate change,Dispersal,Evolution,Exotic,Fitness,Invasion,Lifetime reproductive success,Migration,Range shifting}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\CB74RFNV\\Travis et al. - 2009 - Accelerating invasion rates result from the evolut.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\JDIHVPXQ\\S0022519309001155.html} +} + +@article{travisClimateChangeHabitat2003, + title = {Climate Change and Habitat Destruction: A Deadly Anthropogenic Cocktail}, + shorttitle = {Climate Change and Habitat Destruction}, + author = {Travis, J. M. J.}, + year = {2003}, + month = mar, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + volume = {270}, + number = {1514}, + pages = {467--473}, + publisher = {{Royal Society}}, + doi = {10.1098/rspb.2002.2246}, + abstract = {Climate change and habitat destruction are two of the greatest threats to global biodiversity. Lattice models have been used to investigate how hypothetical species with different characteristics respond to habitat loss. The main result shows that a sharp threshold in habitat availability exists below which a species rapidly becomes extinct. Here, a similar modelling approach is taken to establish what determines how species respond to climate change. A similar threshold exists for the rate of climate change as has been observed for habitat loss\textemdash patch occupancy remains high up to a critical rate of climate change, beyond which species extinction becomes likely. Habitat specialists, especially those of relatively poor colonizing ability are least able to keep pace with climate change. The interaction between climate change and habitat loss might be disastrous. During climate change, the habitat threshold occurs sooner. Similarly, species suffer more from climate change in a fragmented habitat.}, + keywords = {dispersal,extinction thresholds,metapopulation,migration,patch occupancy,spatially explicit}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\CSFELH54\\Travis - 2003 - Climate change and habitat destruction a deadly a.pdf} +} + +@article{travisColorNoiseEvolution2001, + title = {The Color of Noise and the Evolution of Dispersal}, + author = {Travis, Justin M. J.}, + year = {2001}, + month = mar, + journal = {Ecological Research}, + volume = {16}, + number = {1}, + pages = {157--163}, + issn = {1440-1703}, + doi = {10.1046/j.1440-1703.2001.00381.x}, + abstract = {The process of dispersal is vital for the long-term persistence of all species and hence is a ubiquitous characteristic of living organisms. A present challenge is to increase our understanding of the factors that govern the dispersal rate of individuals. Here I extend previous work by incorporating both spatial and temporal heterogeneity in terms of patch quality into a spatially explicit lattice model. The spatial heterogeneity is modeled as a two-dimensional fractal landscape, while temporal heterogeneity is included by using one-dimensional noise. It was found that the color of both the spatial and temporal variability influences the rate of dispersal selected as reddening of the temporal noise leads to a reduction in dispersal, while reddening of spatial variability results in an increase in the dispersal rate. These results demonstrate that the color of environmental noise should be considered in future studies looking at the evolution of life history characteristics.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\D6WTTYXA\\Travis - 2001 - The color of noise and the evolution of dispersal.pdf} +} + +@incollection{travisDispersalClimateChange2012, + title = {Dispersal and Climate Change: A Review of Theory}, + shorttitle = {Dispersal and Climate Change}, + booktitle = {Dispersal {{Ecology}} and {{Evolution}}}, + author = {Travis, Justin M. J. and Dytham, Calvin}, + year = {2012}, + publisher = {{Oxford University Press}}, + address = {{Oxford}}, + doi = {10.1093/acprof:oso/9780199608898.003.0026}, + abstract = {This chapter focuses on how models of dispersal can improve our understanding, prediction, and management of species' range shifts under environmental change. Most models of species distribution and spread represent dispersal quite crudely; this chapter begins with some thoughts on how these might be integrated with more sophisticated models of dispersal. The importance of inter-individual variability in dispersal and the role that dispersal evolution may play in range shifting is considered. An example of evolutionary entrapment that arises when species expand their ranges over fragmented landscapes is then presented. Finally, potential management strategies that may be used to promote range shifting are considered.}, + isbn = {978-0-19-960889-8}, + langid = {english}, + keywords = {environmental change,evolutionary entrapment,inter-individual variability,models of dispersal,range shifts,species distribution} +} + +@article{travisDispersalEvolutionInvasions2002, + title = {Dispersal Evolution during Invasions}, + author = {Travis, Justin M J and Dytham, Calvin}, + year = {2002}, + journal = {Evolutionary Ecology Research}, + volume = {4}, + number = {8}, + pages = {1119--1129}, + publisher = {{EVOLUTIONARY ECOLOGY LTD}}, + issn = {1522-0613}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\6RKGTXGN\\dispersal-evolution-during-invasions.html} +} + +@article{travisDispersalSpeciesResponses2014, + title = {Dispersal and Species' Responses to Climate Change}, + author = {Travis, J. M. J. and Bocedi, Greta and Baguette, Michel and Barto{\'n}, Kamil and Bonte, Dries and Boulangeat, Isabelle and Hodgson, Jenny A. and Kubisch, Alexander and Penteriani, Vincenzo and Saastamoinen, Marjo and Stevens, Virginie M. and Bullock, James M.}, + year = {2014}, + journal = {Oikos}, + volume = {122}, + number = {11}, + pages = {1532--1540}, + issn = {1600-0706}, + doi = {10.1111/j.1600-0706.2013.00399.x}, + abstract = {Dispersal is fundamental in determining biodiversity responses to rapid climate change, but recently acquired ecological and evolutionary knowledge is seldom accounted for in either predictive methods or conservation planning. We emphasise the accumulating evidence for direct and indirect impacts of climate change on dispersal. Additionally, evolutionary theory predicts increases in dispersal at expanding range margins, and this has been observed in a number of species. This multitude of ecological and evolutionary processes is likely to lead to complex responses of dispersal to climate change. As a result, improvement of models of species' range changes will require greater realism in the representation of dispersal. Placing dispersal at the heart of our thinking will facilitate development of conservation strategies that are resilient to climate change, including landscape management and assisted colonisation. Synthesis This article seeks synthesis across the fields of dispersal ecology and evolution, species distribution modelling and conservation biology. Increasing effort focuses on understanding how dispersal influences species' responses to climate change. Importantly, though perhaps not broadly widely-recognised, species' dispersal characteristics are themselves likely to alter during rapid climate change. We compile evidence for direct and indirect influences that climate change may have on dispersal, some ecological and others evolutionary. We emphasise the need for predictive modelling to account for this dispersal realism and highlight the need for conservation to make better use of our existing knowledge related to dispersal.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2013.00399.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2NKNEJ2K\\Travis et al. - 2013 - Dispersal and species’ responses to climate change.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\8Z9KM4GL\\j.1600-0706.2013.00399.html} +} + +@article{travisEvolutionDensitydependentDispersal1999, + title = {The Evolution of Density-Dependent Dispersal}, + author = {Travis, J. M. J. and Murrell, D. J. and Dytham, C.}, + year = {1999}, + month = sep, + journal = {Proceedings of the Royal Society B: Biological Sciences}, + volume = {266}, + number = {1431}, + pages = {1837}, + issn = {0962-8452}, + doi = {10.1098/rspb.1999.0854}, + abstract = {Despite a large body of empirical evidence suggesting that the dispersal rates of many species depend on population density, most metapopulation models assume a density-independent rate of dispersal. Similarly, studies investigating the evolution of dispersal have concentrated almost exclusively on density-independent rates of dispersal. We develop a model that allows density-dependent dispersal strategies to evolve. Our results demonstrate that a density-dependent dispersal strategy almost always evolves and that the form of the relationship depends on reproductive rate, type of competition, size of subpopulation equilibrium densities and cost of dispersal. We suggest that future metapopulation models should account for density-dependent dispersal}, + pmcid = {PMC1690220}, + pmid = {null}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\Q5VMNQXD\\Travis et al. - 1999 - The evolution of density-dependent dispersal.pdf} +} + +@article{travisHabitatPersistenceHabitat1999, + title = {Habitat Persistence, Habitat Availability and the Evolution of Dispersal}, + author = {Travis, J. M. J. and Dytham, C.}, + year = {1999}, + journal = {Proceedings of the Royal Society of London. Series B: Biological Sciences}, + number = {266}, + pages = {723--728}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\8JYPG8Q5\\rspb.1999.html} +} + +@article{travisImprovingPredictionManagement2011a, + title = {Improving Prediction and Management of Range Expansions by Combining Analytical and Individual-Based Modelling Approaches}, + author = {Travis, J. M. J. and Harris, Catriona M. and Park, Kirsty J. and Bullock, James M.}, + year = {2011}, + journal = {Methods in Ecology and Evolution}, + volume = {2}, + number = {5}, + pages = {477--488}, + issn = {2041-210X}, + doi = {10.1111/j.2041-210X.2011.00104.x}, + abstract = {1. Improving the understanding, prediction and management of range expansions is a key challenge for ecology. Over recent years, there has been a rapid increase in modelling effort focussed on range expansions and a shift from predominantly theoretical developments towards application. This is especially the case in the field of invasion biology and also in relation to reintroductions and species' responses to climate change. 2. While earlier models were exclusively analytical, individual-based models (IBMs) are now increasingly widely used. We argue that instead of being viewed as competing methodologies, analytical and individual-based methods can valuably be used in conjunction. 3. We use a mechanistic wind dispersal model to generate age-specific dispersal kernels for the invasive shrub, Rhododendron ponticum. To demonstrate the utility of employing both modelling approaches, this information along with demographic parameters is incorporated into an IBM and an analytical, integrodifference model. From both models, the equilibrium rate of spread is calculated. 4. Estimates of wavespeeds were similar for the two models, although slower rates of spread were consistently projected by the IBM. Further, our results demonstrate the wavespeed to be sensitive to the characterisation of age structure in the model; when few age classes are used, much higher rates of spread are projected. 5. The analytical model is extremely efficient at providing elasticity analysis of the wavespeed, which can provide helpful information for management. We gain qualitatively similar results using the IBM but obtaining the results is time-consuming and, because the model is stochastic, they are noisy and harder to interpret. We argue that analytically derived transient elasticity analyses are needed for the many cases where success of control is measured on a relatively short time horizon. 6. To demonstrate the flexibility of the IBM approach, we run it on a real landscape comprising different habitat types. The comparison of two different control scenarios is an example of the utility of this approach for more tactical applications. 7. As a general conclusion of the study, we emphasise that analytical and individual-based approaches offer different, but complementary, advantages and suggest how their joint use can facilitate the improvement in biodiversity management at a range of spatial scales.}, + langid = {english}, + keywords = {analytical model,climate change,demography,invasion,population spread,reintroduction,stochastic model}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.2041-210X.2011.00104.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\YUSBIRYM\\Travis et al. - 2011 - Improving prediction and management of range expan.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\LIJ5W48A\\j.2041-210X.2011.00104.html} +} + +@article{travisMechanisticUnderstandingDispersal2010, + title = {Towards a Mechanistic Understanding of Dispersal Evolution in Plants: Conservation Implications}, + shorttitle = {Towards a Mechanistic Understanding of Dispersal Evolution in Plants}, + author = {Travis, Justin M. J. and Smith, Hannah S. and Ranwala, Sudheera M. W.}, + year = {2010}, + month = jul, + journal = {Diversity and Distributions}, + volume = {16}, + number = {4}, + pages = {690--702}, + publisher = {{WILEY-BLACKWELL}}, + doi = {10.1111/j.1472-4642.2010.00674.x}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\BRLRUS4F\\towards-a-mechanistic-understanding-of-dispersal-evolution-in-pla.html} +} + +@article{travisMethodSimulatingPatterns2004, + title = {A {{Method}} for {{Simulating Patterns}} of {{Habitat Availability}} at {{Static}} and {{Dynamic Range Margins}}}, + author = {Travis, J. M. J. and Dytham, C.}, + year = {2004}, + journal = {Oikos}, + volume = {104}, + number = {2}, + pages = {410--416}, + publisher = {{[Nordic Society Oikos, Wiley]}}, + issn = {0030-1299}, + abstract = {The dynamics of populations inhabiting range margins are likely to be critically important in determining the response of species to climate change. Despite this, there is a lack of both empirical and theoretical work that examines the behaviour of these populations. Populations living on the edge of a species' range frequently inhabit a more patchily distributed habitat than those that live closer to the centre of the range. This difference is likely to play an important role in determining the dynamics of range margin populations, both when the range is static and when it is dynamic, for example shifting in response to climate change. Here, we present a simple method that simulates the distribution of suitable habitat sites at the edge of a range. Habitat availability is determined as a function of both latitudinal and local environmental variability, and the relative importance of the two can be adjusted. The method is readily extended to describe shifting habitat availability during a period of climate change. We suggest that there is a need for a greater effort to examine the ecology of range margin populations, and believe that the method presented here could be of considerable use in future theoretical studies.} +} + +@article{travisModellingDispersalEcoevolutionary2012a, + title = {Modelling Dispersal: An Eco-Evolutionary Framework Incorporating Emigration, Movement, Settlement Behaviour and the Multiple Costs Involved}, + shorttitle = {Modelling Dispersal}, + author = {Travis, J. M. J. and Barto{\'n}, Kamil A. and Benton, Tim G. and Clobert, Jean and Delgado, Maria M. and Dytham, Calvin and Hovestadt, Thomas and Palmer, Stephen C. F. and Dyck, Hans Van and Bonte, Dries}, + year = {2012}, + journal = {Methods in Ecology and Evolution}, + volume = {3}, + number = {4}, + pages = {628--641}, + issn = {2041-210X}, + doi = {10.1111/j.2041-210X.2012.00193.x}, + abstract = {1. Understanding the causes and consequences of dispersal remains a central topic in ecology and evolution. However, a mismatch exists between our empirical understanding of the complexity of dispersal and our representation of dispersal in models. While the empirical literature is replete with examples of condition dependence at the emigration, movement and settlement phases, models rarely incorporate realism or complexity to this degree. Nor do models often include the different costs associated with dispersal, which can themselves be linked to one or more of the three key phases. 2. Here, we propose that by explicitly accounting for emigration, movement and settlement (and the multiple costs associated with each) we can substantially improve our understanding of both the dispersal process itself and how dispersal traits trade off against other life-history characteristics. We explore some of these issues conceptually, before presenting illustrative results gained from a flexible individual-based model which incorporates considerable dispersal complexity. 3. These results emphasise the nonlinear interplay between the different dispersal stages. For example, we find that investment in movement ability (at a cost to fecundity) depends upon the propensity to emigrate (and vice versa). However, owing to selection acting at the metapopulation level as well as at the individual level, the relationship between the two is not straightforward. Importantly, the shape of the trade-off between movement ability and reproductive potential can strongly influence the joint evolution of dispersal parameters controlling the degree of investment in safer movement, the probability of emigration and the straightness of movement. 4. Our results highlight that the joint evolution of dispersal characteristics can have major implications for spatial population dynamics and we argue that, in addition to increasing our fundamental biological understanding, a new generation of dispersal modelling, which exploits recent empirical advances, can substantially improve our ability to predict and manage the response of species to environmental change.}, + langid = {english}, + keywords = {evolutionary biology,life-history,migration,modelling,population ecology,trade off,transition}, + annotation = {\_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.2041-210X.2012.00193.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\34Z5UIBP\\Travis et al. - 2012 - Modelling dispersal an eco-evolutionary framework.pdf} +} + +@article{turlureSpeciesSexspecificAdjustments2011, + title = {Species- and Sex-Specific Adjustments of Movement Behavior to Landscape Heterogeneity in Butterflies}, + author = {Turlure, Camille and Baguette, M and Stevens, Virginie M and Maes, D}, + year = {2011}, + journal = {Behavioral Ecology}, + number = {22}, + pages = {967--975} +} + +@article{turnerUsefulnessSpatiallyExplicit1995, + title = {Usefulness of {{Spatially Explicit Population Models}} in {{Land Management}}}, + author = {Turner, Monica G. and Arthaud, Greg J. and Engstrom, R. Todd and Hejl, Sallie J. and Liu, Jianguo and Loeb, Susan and McKelvey, Kevin}, + year = {1995}, + journal = {Ecological Applications}, + volume = {5}, + number = {1}, + pages = {12--16}, + issn = {1939-5582}, + doi = {10.2307/1942046}, + abstract = {Land managers need new tools, such as spatial models, to aid them in their decision-making processes because managing for biodiversity, water quality, or natural disturbance is challenging, and landscapes are complex and dynamic. Spatially explicit population models are helpful to managers because these models consider both species-habitat relationships and the arrangement of habitats in space and time. The visualizations that typically accompany spatially explicit models also permit managers to 'see' the effects of alternative management strategies on populations of interest. However, the expense entailed in developing the data bases required for spatially explicit models may limit widespread implementation. In addition, many of the models are developed for one or a few species, and dealing with multiple species in a landscape remains a significant challenge. To be most useful to land managers, spatially explicit population models should be user friendly, easily portable, operate on spatial and temporal scales appropriate to management decisions, and use input and output variables that can be measured affordably.}, + langid = {english}, + annotation = {\_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.2307/1942046}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\87Q2XHLU\\1942046.html} +} + +@article{urbanMovingForwardDispersal2013, + title = {Moving Forward: Dispersal and Species Interactions Determine Biotic Responses to Climate Change}, + shorttitle = {Moving Forward}, + author = {Urban, Mark C. and Zarnetske, Phoebe L. and Skelly, David K.}, + year = {2013}, + month = sep, + journal = {Annals of the New York Academy of Sciences}, + volume = {1297}, + pages = {44--60}, + issn = {1749-6632}, + doi = {10.1111/nyas.12184}, + abstract = {We need accurate predictions about how climate change will alter species distributions and abundances around the world. Most predictions assume simplistic dispersal scenarios and ignore biotic interactions. We argue for incorporating the complexities of dispersal and species interactions. Range expansions depend not just on mean dispersal, but also on the shape of the dispersal kernel and the population's growth rate. We show how models using species-specific dispersal can produce more accurate predictions than models applying all-or-nothing dispersal scenarios. Models that additionally include species interactions can generate distinct outcomes. For example, species interactions can slow climate tracking and produce more extinctions than models assuming no interactions. We conclude that (1) just knowing mean dispersal is insufficient to predict biotic responses to climate change, and (2) considering interspecific dispersal variation and species interactions jointly will be necessary to anticipate future changes to biological diversity. We advocate for collecting key information on interspecific dispersal differences and strong biotic interactions so that we can build the more robust predictive models that will be necessary to inform conservation efforts as climates continue to change.}, + langid = {english}, + pmid = {23819864}, + keywords = {Animal Distribution,Animals,Biodiversity,Climate,Climate Change,community ecology,dispersal kernels,Earth; Planet,Ecology,Ecosystem,landscape fragmentation,Models; Theoretical,movement,Seed Dispersal,Species Specificity,Temperature} +} + +@article{vandermeerMetapopulationDynamicsQuality2001, + title = {Metapopulation Dynamics and the Quality of the Matrix}, + author = {Vandermeer, J. and Carvajal, R.}, + year = {2001}, + month = sep, + journal = {The American Naturalist}, + volume = {158}, + number = {3}, + pages = {211--220}, + issn = {1537-5323}, + doi = {10.1086/321318}, + abstract = {In both strictly theoretical and more applied contexts it has been historically assumed that metapopulations exist within a featureless, uninhabitable matrix and that dynamics within the matrix are unimportant. In this article, we explore the range of theoretical consequences that result from relaxing this assumption. We show, with a variety of modeling techniques, that matrix quality can be extremely important in determining metapopulation dynamics. A higher-quality matrix generally buffers against extinction. However, in some situations, an increase in matrix quality can generate chaotic subpopulation dynamics, where stability had been the rule in a lower-quality matrix. Furthermore, subpopulations acting as source populations in a low-quality matrix may develop metapopulation dynamics as the quality of the matrix increases. By forcing metapopulation dynamics on a formerly heterogeneous (but stable within subpopulations) population, the probability of simultaneous extinction of all subpopulations actually increases. Thus, it cannot be automatically assumed that increasing matrix quality will lower the probability of global extinction of a population.}, + langid = {english}, + pmid = {18707319} +} + +@article{vasseurColorEnvironmentalNoise2004, + title = {The {{Color}} of {{Environmental Noise}}}, + author = {Vasseur, David A. and Yodzis, Peter}, + year = {2004}, + journal = {Ecology}, + volume = {85}, + number = {4}, + pages = {1146--1152}, + issn = {1939-9170}, + doi = {10.1890/02-3122}, + abstract = {Biological populations are strongly influenced by the random variation in their environment. The spectrum of frequencies in noise is particularly important to dynamics and persistence. Here we present an analysis of the variance spectra of a wide variety of long-term time series of environmental variables. Spectra were well approximated by the inverse power law 1/f{$\beta$} within the appropriate range of frequencies f; however, the majority of spectra were ``flattened'' at low frequencies. With some qualification we found the spectral exponents ({$\beta$}) to corroborate an earlier suggestion that terrestrial noise tends to be ``white'' ({$\beta$} {$<$} 0.5), while marine environments tend to be ``red'' ({$\beta$} {$\approx$} 1) or ``brown'' ({$\beta$} {$\approx$} 2). As well, we found a tendency for whiter noise in temperate latitudes than in either high or low latitudes. These results have wide-ranging consequences for ecosystem fragility and species conservation.}, + langid = {english}, + keywords = {environmental noise,noise color,power spectrum,time series}, + annotation = {\_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/02-3122}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\YLPUYTCC\\Vasseur und Yodzis - 2004 - The Color of Environmental Noise.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UDWZDNLR\\02-3122.html} +} + +@article{verbeylenDoesMatrixResistance2003, + title = {Does Matrix Resistance Influence Red Squirrel ({{Sciurus}} Vulgaris l. 1758) Distribution in an Urban Landscape?}, + author = {Verbeylen, Goedele and Bruyn, Luc De and Adriaensen, F. and Matthysen, E.}, + year = {2003}, + journal = {Landscape Ecology}, + volume = {18}, + number = {8}, + pages = {791--805}, + doi = {10.1023/B:LAND.0000014492.50765.05}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\QCLURXUG\\does-matrix-resistance-influence-red-squirrel-emsciurus-vulgarise.html} +} + +@article{verboomPopulationDynamicsIncreasing2010, + title = {Population Dynamics under Increasing Environmental Variability: Implications of Climate Change for Ecological Network Design Criteria}, + shorttitle = {Population Dynamics under Increasing Environmental Variability}, + author = {Verboom, J. and Schippers, P. and Cormont, A. and Sterk, M. and Vos, C. C. and Opdam, P. F. M.}, + year = {2010}, + journal = {Landscape Ecology}, + volume = {25}, + pages = {1289--1298}, + publisher = {{Springer Verlag}}, + issn = {0921-2973}, + doi = {10.1007/s10980-010-9497-7}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\ZJPCLDCV\\population-dynamics-under-increasing-environmental-variability-im.html} +} + +@article{verckenImportanceGoodNeighborhood2012, + title = {The Importance of a Good Neighborhood: Dispersal Decisions in Juvenile Common Lizards Are Based on Social Environment}, + author = {Vercken, E. and Sinervo, B. and Clobert, J}, + year = {2012}, + journal = {Behavioral Ecology}, + number = {23}, + pages = {1059--1067} +} + +@article{vittAssistedMigrationPart2009, + title = {Assisted Migration: Part of an Integrated Conservation Strategy}, + shorttitle = {Assisted Migration}, + author = {Vitt, Pati and Havens, Kayri and {Hoegh-Guldberg}, Ove}, + year = {2009}, + month = sep, + journal = {Trends in Ecology \& Evolution}, + volume = {24}, + number = {9}, + pages = {473-474; author reply 476-477}, + issn = {0169-5347}, + doi = {10.1016/j.tree.2009.05.007}, + langid = {english}, + pmid = {19595474}, + keywords = {Animal Migration,Animals,Conservation of Natural Resources,Ecosystem,Extinction; Biological,Models; Biological,Population Dynamics} +} + +@article{vuilleumierAnimalDispersalModelling2006, + title = {Animal Dispersal Modelling: {{Handling}} Landscape Features and Related Animal Choices}, + shorttitle = {Animal Dispersal Modelling}, + author = {Vuilleumier, S{\'e}verine and Metzger, Richard}, + year = {2006}, + month = jan, + journal = {Ecological Modelling}, + volume = {190}, + number = {1}, + pages = {159--170}, + issn = {0304-3800}, + doi = {10.1016/j.ecolmodel.2005.04.017}, + abstract = {Animal dispersal in a fragmented landscape depends on the complex interaction between landscape structure and animal behavior. To better understand how individuals disperse, it is important to explicitly represent the properties of organisms and the landscape in which they move. A common approach to modelling dispersal includes representing the landscape as a grid of equal sized cells and then simulating individual movement as a correlated random walk. This approach uses a priori scale of resolution, which limits the representation of all landscape features and how different dispersal abilities are modelled. We develop a vector-based landscape model coupled with an object-oriented model for animal dispersal. In this spatially explicit dispersal model, landscape features are defined based on their geographic and thematic properties and dispersal is modelled through consideration of an organism's behavior, movement rules and searching strategies (such as visual cues). We present the model's underlying concepts, its ability to adequately represent landscape features and provide simulation of dispersal according to different dispersal abilities. We demonstrate the potential of the model by simulating two virtual species in a real Swiss landscape. This illustrates the model's ability to simulate complex dispersal processes and provides information about dispersal such as colonization probability and spatial distribution of the organism's path.}, + langid = {english}, + keywords = {Animal movement,Dispersal behavior modelling,Landscape feature,Landscape model,Object-oriented design,Spatially explicit model}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\T28YE35J\\Vuilleumier und Metzger - 2006 - Animal dispersal modelling Handling landscape fea.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\Q9PKPWXL\\S030438000500222X.html} +} + +@article{vuilleumierEffectsCognitiveAbilities2006, + title = {Effects of {{Cognitive Abilities}} on {{Metapopulation Connectivity}}}, + author = {Vuilleumier, S{\'e}verine and Perrin, Nicolas and Ranta, Esa}, + year = {2006}, + journal = {Oikos}, + volume = {113}, + number = {1}, + pages = {139--147}, + publisher = {{[Nordic Society Oikos, Wiley]}}, + issn = {0030-1299}, + abstract = {Connectivity among demes in a metapopulation depends on both the landscape's and the focal organism's properties (including its mobility and cognitive abilities). Using individual-based simulations, we contrast the consequences of three different cognitive strategies on several measures of metapopulation connectivity. Model animals search suitable habitat patches while dispersing through a model landscape made of cells varying in size, shape, attractiveness and friction. In the blind strategy, the next cell is chosen randomly among the adjacent ones. In the near-sighted strategy, the choice depends on the relative attractiveness of these adjacent cells. In the far-sighted strategy, animals may additionally target suitable patches that appear within their perceptual range. Simulations show that the blind strategy provides the best overall connectivity, and results in balanced dispersal. The near-sighted strategy traps animals into corridors that reduce the number of potential targets, thereby fragmenting metapopulations in several local clusters of demes, and inducing sink-source dynamics. This sort of local trapping is somewhat prevented in the far-sighted strategy. The colonization success of strategies depends highly on initial energy reserves: blind does best when energy is high, near-sighted wins at intermediate levels, and far-sighted outcompetes its rivals at low energy reserves. We also expect strong effects in terms of metapopulation genetics: the blind strategy generates a migrant-pool mode of dispersal that should erase local structures. By contrast, near- and far-sighted strategies generate a propagule-pool mode of dispersal and source-sink behavior that should boost structures (high genetic variance among-and low variance within local clusters of demes), particularly if metapopulation dynamics is also affected by extinction-colonization processes. Our results thus point to important effects of the cognitive ability of dispersers on the connectivity, dynamics and genetics of metapopulations.} +} + +@article{wangDispersalGlanvilleFritillary2011, + title = {Dispersal in the {{Glanville}} Fritillary Butterfly in Fragmented versus Continuous Landscapes: Comparison between Three Methods}, + shorttitle = {Dispersal in the {{Glanville}} Fritillary Butterfly in Fragmented versus Continuous Landscapes}, + author = {Wang, Rongjiang and Ovaskainen, Otso and Cao, Yundong and Chen, Houqiang and Zhou, Yan and Xu, Chongren and Hanski, Ilkka}, + year = {2011}, + journal = {Ecological Entomology}, + volume = {36}, + number = {2}, + pages = {251--260}, + issn = {1365-2311}, + doi = {10.1111/j.1365-2311.2011.01267.x}, + abstract = {1. Habitat fragmentation may lead to natural selection on dispersal rate and other life-history traits. Both theoretical analyses and empirical studies suggest that habitat fragmentation may select either for increased or decreased dispersal depending on the traits of the species and the characteristics of the landscape. 2. Dispersal and movement rates in Glanville fritillary butterflies (Melitaea cinxia) originating from a continuous landscape in China and from a highly fragmented landscape in Finland were compared using three different methods. 3. The methods included replicated mark-release-recapture (MRR) experiments conducted in the natural environments in China and Finland, tracking with harmonic radar of captive-reared but free-flying butterflies in a common environment in the field, and replicated common garden experiments in a large outdoor population cage. 4. The results were largely consistent, showing that butterflies from the more continuous landscape in China had a lower movement rate than butterflies originating from the fragmented landscape in Finland. Butterflies originating from newly-established populations in Finland moved significantly longer distances than butterflies originating from old populations in Finland or from China, demonstrating significant intra-specific variation in dispersal rate in Finland. These results are consistent with model predictions for the Glanville fritillary. 5. The tracking experiment revealed a result that would have been impossible to obtain with MRR experiments: movement rate was influenced by a significant interaction between population origin (China vs. Finland) and ambient air temperature.}, + langid = {english}, + keywords = {Diffusion model,diffusion rate,habitat fragmentation,harmonic radar,mark-release-recapture study,population cage,temperature-dependent dispersal}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2311.2011.01267.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\PQ96NJ55\\Wang et al. - 2011 - Dispersal in the Glanville fritillary butterfly in.pdf} +} + +@article{warrenRapidResponsesBritish2001, + title = {Rapid Responses of {{British}} Butterflies to Opposing Forces of Climate and Habitat Change}, + author = {Warren, M. S. and Hill, J. K. and Thomas, J. A. and Asher, J. and Fox, R. and Huntley, B. and Roy, D. B. and Telfer, M. G. and Jeffcoate, S. and Harding, P. and Jeffcoate, G. and Willis, S. G. and {Greatorex-Davies}, J. N. and Moss, D. and Thomas, C. D.}, + year = {2001}, + month = nov, + journal = {Nature}, + volume = {414}, + number = {6859}, + pages = {65--69}, + publisher = {{Nature Publishing Group}}, + issn = {1476-4687}, + doi = {10.1038/35102054}, + abstract = {Habitat degradation and climate change are thought to be altering the distributions and abundances of animals and plants throughout the world, but their combined impacts have not been assessed for any species assemblage1,2,3,4. Here we evaluated changes in the distribution sizes and abundances of 46 species of butterflies that approach their northern climatic range margins in Britain\textemdash where changes in climate and habitat are opposing forces. These insects might be expected to have responded positively to climate warming over the past 30 years, yet three-quarters of them declined: negative responses to habitat loss have outweighed positive responses to climate warming. Half of the species that were mobile and habitat generalists increased their distribution sites over this period (consistent with a climate explanation), whereas the other generalists and 89\% of the habitat specialists declined in distribution size (consistent with habitat limitation). Changes in population abundances closely matched changes in distributions. The dual forces of habitat modification and climate change are likely to cause specialists to decline, leaving biological communities with reduced numbers of species and dominated by mobile and widespread habitat generalists.}, + copyright = {2001 Macmillan Magazines Ltd.}, + langid = {english}, + annotation = {Bandiera\_abtest: a Cg\_type: Nature Research Journals Primary\_atype: Research}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\WKSFZ2JB\\Warren et al. - 2001 - Rapid responses of British butterflies to opposing.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\BPTIVUI7\\35102054.html} +} + +@article{wattsTargetingEvaluatingBiodiversity2010, + title = {Targeting and Evaluating Biodiversity Conservation Action within Fragmented Landscapes: An Approach Based on Generic Focal Species and Least-Cost Networks}, + shorttitle = {Targeting and Evaluating Biodiversity Conservation Action within Fragmented Landscapes}, + author = {Watts, Kevin and Eycott, Amy E. and Handley, Phillip and Ray, Duncan and Humphrey, Jonathan W. and Quine, Christopher P.}, + year = {2010}, + month = nov, + journal = {Landscape Ecology}, + volume = {25}, + number = {9}, + pages = {1305--1318}, + issn = {1572-9761}, + doi = {10.1007/s10980-010-9507-9}, + abstract = {The focus of biodiversity conservation is shifting to larger spatial scales in response to habitat fragmentation and the need to integrate multiple landscape objectives. Conservation strategies increasingly incorporate measures to combat fragmentation such as ecological networks. These are often based on assessment of landscape structure but such approaches fail to capitalise on the potential offered by more ecologically robust assessments of landscape function and connectivity. In this paper, we describe a modelling approach to identifying functional habitat networks and demonstrate its application to a fragmented landscape where policy initiatives seek to improve conditions for woodland biodiversity including increasing woodland cover. Functional habitat networks were defined by identifying suitable habitat and by modelling connectivity using least-cost approaches to account for matrix permeability. Generic focal species (GFS) profiles were developed, in consultation with stakeholders, to represent species with high and moderate sensitivity to fragmentation. We demonstrated how this form of analysis can be used to aid the spatial targeting of conservation actions. This `targeted' action scenario was tested for effectiveness against comparable scenarios, which were based on random and clumped actions within the same landscape. We tested effectiveness using structural metrics, network-based metrics and a published functional connectivity indicator. Targeting actions within networks resulted in the highest mean woodland area and highest connectivity indicator value. Our approach provides an assessment of landscape function by recognising the importance of the landscape matrix. It provides a framework for the targeting and evaluation of alternative conservation options, offering a pragmatic, ecologically-robust solution to a current need in applied landscape ecology.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\2WBYZF8C\\Watts et al. - 2010 - Targeting and evaluating biodiversity conservation.pdf} +} + +@article{weeksAssessingBenefitsRisks2011, + title = {Assessing the Benefits and Risks of Translocations in Changing Environments: A Genetic Perspective}, + shorttitle = {Assessing the Benefits and Risks of Translocations in Changing Environments}, + author = {Weeks, Andrew R and Sgro, Carla M and Young, Andrew G and Frankham, Richard and Mitchell, Nicki J and Miller, Kim A and Byrne, Margaret and Coates, David J and Eldridge, Mark D B and Sunnucks, Paul and Breed, Martin F and James, Elizabeth A and Hoffmann, Ary A}, + year = {2011}, + month = nov, + journal = {Evolutionary Applications}, + volume = {4}, + number = {6}, + pages = {709--725}, + issn = {1752-4571}, + doi = {10.1111/j.1752-4571.2011.00192.x}, + abstract = {Translocations are being increasingly proposed as a way of conserving biodiversity, particularly in the management of threatened and keystone species, with the aims of maintaining biodiversity and ecosystem function under the combined pressures of habitat fragmentation and climate change. Evolutionary genetic considerations should be an important part of translocation strategies, but there is often confusion about concepts and goals. Here, we provide a classification of translocations based on specific genetic goals for both threatened species and ecological restoration, separating targets based on `genetic rescue' of current population fitness from those focused on maintaining adaptive potential. We then provide a framework for assessing the genetic benefits and risks associated with translocations and provide guidelines for managers focused on conserving biodiversity and evolutionary processes. Case studies are developed to illustrate the framework.}, + pmcid = {PMC3265713}, + pmid = {22287981}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\VALJUMPM\\Weeks et al. - 2011 - Assessing the benefits and risks of translocations.pdf} +} + +@article{wiegandEffectsHabitatLoss2005, + title = {Effects of {{Habitat Loss}} and {{Fragmentation}} on {{Population Dynamics}}}, + author = {Wiegand, Thorsten and Revilla, Eloy and Moloney, Kirk A.}, + year = {2005}, + journal = {Conservation Biology}, + volume = {19}, + number = {1}, + pages = {108--121}, + publisher = {{[Wiley, Society for Conservation Biology]}}, + issn = {0888-8892}, + abstract = {We used a spatially explicit population model that was generalized to produce nine ecological profiles of long-lived species with stable home ranges and natal dispersal to investigate the effects of habitat loss and fragmentation on population dynamics. We simulated population dynamics in landscapes composed of three habitat types (good-quality habitat ranging from 10-25\%, poor-quality habitat ranging from 10-70\%, and matrix). Landscape structures varied from highly fragmented to completely contiguous. The specific aims of our model were (1) to investigate under which biological circumstances the traditional approach of using two types only (habitat and matrix) failed and assess the potential impact of restoring matrix to poor-quality habitat, (2) to investigate how much of the variation in population size was explained by landscape composition alone and which key attributes of landscape structure can serve as predictors of population response, and (3) to estimate the maximum fragmentation effects expressed in equivalent pure loss of good-quality habitat. Poor-quality habitat mattered most in situations when it was generally not considered (i.e., for metapopulations or spatially structured populations when it provides dispersal habitat). Population size increased up to 3 times after restoring matrix to poor-quality habitat. Overall, habitat amount accounted for 68\%) of the variation in population size, whereas ecological profile and fragmentation accounted for approximately 13\%{$>$} each. The maximal effect of (good-quality) habitat fragmentation was equivalent to a pure loss of up to 15\%{$>$} of good-quality habitat, and the maximal loss of individuals resulting from maximal fragmentation reached 80\%. Abundant dispersal habitat and sufficiently large dispersal potential, however, resulted in functionally connected landscapes, and maximal fragmentation had no effect at all. Our findings suggest that predicting fragmentation effects requires a good understanding of the biology and habitat use of the species in question and that the uniqueness of species and the landscapes in which they live confound simple analysis.} +} + +@article{willisAssistedColonizationChanging2009, + title = {Assisted Colonization in a Changing Climate: A Test-Study Using Two {{U}}.{{K}}. Butterflies}, + shorttitle = {Assisted Colonization in a Changing Climate}, + author = {Willis, Stephen G. and Hill, Jane K. and Thomas, Chris D. and Roy, David B. and Fox, Richard and Blakeley, David S. and Huntley, Brian}, + year = {2009}, + journal = {Conservation Letters}, + volume = {2}, + number = {1}, + pages = {46--52}, + issn = {1755-263X}, + doi = {10.1111/j.1755-263X.2008.00043.x}, + abstract = {Recent climatic change in temperate regions has been rapid and there is mounting speculation that species are failing to keep track of suitable climate, perhaps necessitating assisted colonization for some species. An inability to spread into new areas may result in large reductions in species' ranges in the future, and threaten the survival of some species. Here we use ``species-climate'' models to predict suitable sites for introductions beyond current range margins, using two U.K. butterfly species. We introduced Melanargia galathea (marbled white) and Thymelicus sylvestris (small skipper) into two sites in northern England, {$\sim$}65 and {$\sim$}35 km beyond their then-range margins, respectively, to sites that were predicted to be climatically suitable and that appeared to contain suitable habitat for the species. Both introduced populations grew and expanded their range over 6 years (2001\textendash 2006; still thriving in 2008), suggesting the existence of a colonization lag and providing evidence that well-planned assisted colonization can be successful. We suggest that assisted colonization may be a feasible and cost-effective means of enabling certain species to track climatic change.}, + langid = {english}, + keywords = {assisted colonization,Climate change,distributions,introductions,range margin,range shift}, + annotation = {\_eprint: https://conbio.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1755-263X.2008.00043.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\LA26PC2P\\Willis et al. - 2009 - Assisted colonization in a changing climate a tes.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\PKJ8RAYF\\j.1755-263X.2008.00043.html} +} + +@article{willisDynamicDistributionModelling2009, + title = {Dynamic Distribution Modelling: Predicting the Present from the Past}, + shorttitle = {Dynamic Distribution Modelling}, + author = {Willis, Stephen G. and Thomas, Chris D. and Hill, Jane K. and Collingham, Yvonne C. and Telfer, Mark G. and Fox, Richard and Huntley, Brian}, + year = {2009}, + journal = {Ecography}, + volume = {32}, + number = {1}, + pages = {5--12}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2008.05711.x}, + abstract = {Confidence in projections of the future distributions of species requires demonstration that recently-observed changes could have been predicted adequately. Here we use a dynamic model framework to demonstrate that recently-observed changes at the expanding northern boundaries of three British butterfly species can be predicted with good accuracy. Previous work established that the distributions of the study species currently lag behind climate change, and so we presumed that climate is not currently a major constraint at the northern range margins of our study species. We predicted 1970\textendash 2000 distribution changes using a colonisation model, MIGRATE, superimposed on a high-resolution map of habitat availability. Thirty-year rates and patterns of distribution change could be accurately predicted for each species ({$\kappa$} goodness-of-fit of models {$>$}0.64 for all three species, corresponding to {$>$}83\% of grid cells correctly assigned), using a combination of individual species traits, species-specific habitat associations and distance-dependent dispersal. Sensitivity analyses showed that population productivity was the most important determinant of the rate of distribution expansion (variation in dispersal rate was not studied because the species are thought to be similar in dispersal capacity), and that each species' distribution prior to expansion was critical in determining the spatial pattern of the current distribution. In future, modelling approaches that combine climate suitability and spatially-explicit population models, incorporating demographic variables and habitat availability, are likely to be valuable tools in projecting species' responses to climatic change and hence in anticipating management to facilitate species' dispersal and persistence.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2008.05711.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\T757Z96L\\Willis et al. - 2009 - Dynamic distribution modelling predicting the pre.pdf} +} + +@article{wiszRoleBioticInteractions2013, + title = {The Role of Biotic Interactions in Shaping Distributions and Realised Assemblages of Species: Implications for Species Distribution Modelling}, + shorttitle = {The Role of Biotic Interactions in Shaping Distributions and Realised Assemblages of Species}, + author = {Wisz, Mary Susanne and Pottier, Julien and Kissling, W. Daniel and Pellissier, Lo{\"i}c and Lenoir, Jonathan and Damgaard, Christian F. and Dormann, Carsten F. and Forchhammer, Mads C. and Grytnes, John-Arvid and Guisan, Antoine and Heikkinen, Risto K. and H{\o}ye, Toke T. and K{\"u}hn, Ingolf and Luoto, Miska and Maiorano, Luigi and Nilsson, Marie-Charlotte and Normand, Signe and {\"O}ckinger, Erik and Schmidt, Niels M. and Termansen, Mette and Timmermann, Allan and Wardle, David A. and Aastrup, Peter and Svenning, Jens-Christian}, + year = {2013}, + month = feb, + journal = {Biological Reviews of the Cambridge Philosophical Society}, + volume = {88}, + number = {1}, + pages = {15--30}, + issn = {1469-185X}, + doi = {10.1111/j.1469-185X.2012.00235.x}, + abstract = {Predicting which species will occur together in the future, and where, remains one of the greatest challenges in ecology, and requires a sound understanding of how the abiotic and biotic environments interact with dispersal processes and history across scales. Biotic interactions and their dynamics influence species' relationships to climate, and this also has important implications for predicting future distributions of species. It is already well accepted that biotic interactions shape species' spatial distributions at local spatial extents, but the role of these interactions beyond local extents (e.g. 10 km(2) to global extents) are usually dismissed as unimportant. In this review we consolidate evidence for how biotic interactions shape species distributions beyond local extents and review methods for integrating biotic interactions into species distribution modelling tools. Drawing upon evidence from contemporary and palaeoecological studies of individual species ranges, functional groups, and species richness patterns, we show that biotic interactions have clearly left their mark on species distributions and realised assemblages of species across all spatial extents. We demonstrate this with examples from within and across trophic groups. A range of species distribution modelling tools is available to quantify species environmental relationships and predict species occurrence, such as: (i) integrating pairwise dependencies, (ii) using integrative predictors, and (iii) hybridising species distribution models (SDMs) with dynamic models. These methods have typically only been applied to interacting pairs of species at a single time, require a priori ecological knowledge about which species interact, and due to data paucity must assume that biotic interactions are constant in space and time. To better inform the future development of these models across spatial scales, we call for accelerated collection of spatially and temporally explicit species data. Ideally, these data should be sampled to reflect variation in the underlying environment across large spatial extents, and at fine spatial resolution. Simplified ecosystems where there are relatively few interacting species and sometimes a wealth of existing ecosystem monitoring data (e.g. arctic, alpine or island habitats) offer settings where the development of modelling tools that account for biotic interactions may be less difficult than elsewhere.}, + langid = {english}, + pmcid = {PMC3561684}, + pmid = {22686347}, + keywords = {Animals,Climate,Demography,Ecosystem,Models; Biological}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\PD4F99YQ\\Wisz et al. - 2013 - The role of biotic interactions in shaping distrib.pdf} +} + +@article{withApplicationNeutralLandscape1997, + title = {The {{Application}} of {{Neutral Landscape Models}} in {{Conservation Biology}}}, + author = {With, Kimberly A.}, + year = {1997}, + journal = {Conservation Biology}, + volume = {11}, + number = {5}, + pages = {1069--1080}, + publisher = {{[Wiley, Society for Conservation Biology]}}, + issn = {0888-8892}, + abstract = {Neutral landscape models, derived from percolation theory in the field of landscape ecology, are grid-based maps in which complex habitat distributions are generated by random or fractal algorithms. This grid-based representation of landscape structure is compatible with the raster-based format of geographical information systems (GIS), which facilitates comparisons between theoretical and real landscapes. Neutral landscape models permit the identification of critical thresholds in connectivity, which can be used to predict when landscapes will become fragmented. The coupling of neutral landscape models with generalized population models, such as metapopulation theory, provides a null model for generating predictions about population dynamics in fragmented landscapes. Neutral landscape models can contribute to the following applications in conservation: (1) incorporation of complex spatial patterns in (meta)population models; (2) identification of species' perceptions of landscape structure; (3) determination of landscape connectivity; (4) evaluation of the consequences of habitat fragmentation for population subdivision; (5) identification of the domain of metapopulation dynamics; (6) prediction of the occurrence of extinction thresholds; (7) determination of the genetic consequences of habitat fragmentation; and (8) reserve design and ecosystem management. This generalized, spatially explicit framework bridges the gap between spatially implicit, patch-based models and spatially realistic GIS applications which are usually parameterized for a single species in a specific landscape. Development of a generalized, spatially explicit framework is essential in conservation biology because we will not be able to develop individual models for every species of management concern.} +} + +@article{withExtinctionThresholdsSpecies1999, + title = {Extinction {{Thresholds}} for {{Species}} in {{Fractal Landscapes}}}, + author = {With, Kimberly A. and King, Anthony W.}, + year = {1999}, + journal = {Conservation Biology}, + volume = {13}, + number = {2}, + pages = {314--326}, + issn = {1523-1739}, + doi = {10.1046/j.1523-1739.1999.013002314.x}, + abstract = {Abstract: Predicting species' responses to habitat loss and fragmentation is one of the greatest challenges facing conservation biologists, particularly if extinction is a threshold phenomenon. Extinction thresholds are abrupt declines in the patch occupancy of a metapopulation across a narrow range of habitat loss. Metapopulation-type models have been used to predict extinction thresholds for endangered populations. These models often make simplifying assumptions about the distribution of habitat (random) and the search for suitable habitat sites (random dispersal). We relaxed these two assumptions in a modeling approach that combines a metapopulation model with neutral landscape models of fractal habitat distributions. Dispersal success for suitable, unoccupied sites was higher on fractal landscapes for nearest-neighbor dispersers (moving through adjacent cells of the landscape) than for dispersers searching at random (random distance and direction between steps) on random landscapes. Consequently, species either did not suffer extinction thresholds or extinction thresholds occurred later, at lower levels of habitat abundance, than predicted previously. The exception is for species with limited demographic potential, owing to low reproductive output , in which extinction thresholds occurred sooner than on random landscapes in all but the most clumped fractal landscapes . Furthermore, the threshold was more precipitous for these species. Many species of conservation concern have limited demographic potential, and these species may be at greater risk from habitat loss and fragmentation than previously suspected.}, + langid = {english}, + annotation = {\_eprint: https://conbio.onlinelibrary.wiley.com/doi/pdf/10.1046/j.1523-1739.1999.013002314.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\F6K6NTND\\With und King - 1999 - Extinction Thresholds for Species in Fractal Lands.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\EDN2NGVZ\\j.1523-1739.1999.013002314.html} +} + +@article{zhengModellingDispersalDiffusion2009a, + title = {Modelling Dispersal with Diffusion and Habitat Selection: {{Analytical}} Results for Highly Fragmented Landscapes}, + shorttitle = {Modelling Dispersal with Diffusion and Habitat Selection}, + author = {Zheng, Chaozhi and Pennanen, Juho and Ovaskainen, Otso}, + year = {2009}, + month = jun, + journal = {Ecological Modelling}, + volume = {220}, + number = {12}, + pages = {1495--1505}, + issn = {0304-3800}, + doi = {10.1016/j.ecolmodel.2009.02.024}, + abstract = {Quantifying dispersal is crucial both for understanding ecological population dynamics, and for gaining insight into factors that affect the genetic structure of populations. The role of dispersal becomes pronounced in highly fragmented landscapes inhabited by spatially structured populations. We consider a landscape consisting of a set of habitat patches surrounded by unsuitable matrix, and model dispersal by assuming that the individuals follow a random walk with parameters that may be specific to the habitat type. We allow for spatial variation in patch quality, and account for edge-mediated behavior, the latter meaning that the individuals bias their movement towards the patches when close to an edge between a patch and the matrix. We employ a diffusion approximation of the random walk model to derive analytical expressions for various characteristics of the dispersal process. For example, we derive formulae for the time that an individual is expected to spend in its current patch i, and for the time that it will spend in the matrix, both conditional on the individual hitting next a given patch j before hitting any of the other patches or dying. The analytical formulae are based on the assumptions that the landscape is infinitely large, that the patches are circularly shaped, and that the patches are small compared to interpatch distances. We evaluate the effect of these assumptions by comparing the analytical results to numerical results in a real patch network that violates all of the three assumptions. We then consider a landscape that fulfills the assumptions, and show that in this case the analytical results are in a very good agreement with the numerical results. The results obtained here allow the construction of computationally efficient dispersal models that can be used as components of metapopulation models.}, + langid = {english}, + keywords = {Conditional occupancy times,Diffusion model,Dispersal,Edge-mediate behavior,Metapopulation,Random walk}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\K4NYEMNT\\S0304380009001203.html} +} + +@article{zhengModellingSingleNucleotide2009, + title = {Modelling Single Nucleotide Effects in Phosphoglucose Isomerase on Dispersal in the {{Glanville}} Fritillary Butterfly: Coupling of Ecological and Evolutionary Dynamics}, + shorttitle = {Modelling Single Nucleotide Effects in Phosphoglucose Isomerase on Dispersal in the {{Glanville}} Fritillary Butterfly}, + author = {Zheng, Chaozhi and Ovaskainen, Otso and Hanski, Ilkka}, + year = {2009}, + month = jun, + journal = {Philosophical Transactions of the Royal Society B: Biological Sciences}, + volume = {364}, + number = {1523}, + pages = {1519--1532}, + issn = {0962-8436}, + doi = {10.1098/rstb.2009.0005}, + abstract = {Dispersal comprises a complex life-history syndrome that influences the demographic dynamics of especially those species that live in fragmented landscapes, the structure of which may in turn be expected to impose selection on dispersal. We have constructed an individual-based evolutionary sexual model of dispersal for species occurring as metapopulations in habitat patch networks. The model assumes correlated random walk dispersal with edge-mediated behaviour (habitat selection) and spatially correlated stochastic local dynamics. The model is parametrized with extensive data for the Glanville fritillary butterfly. Based on empirical results for a single nucleotide polymorphism (SNP) in the phosphoglucose isomerase (Pgi) gene, we assume that dispersal rate in the landscape matrix, fecundity and survival are affected by a locus with two alleles, A and C, individuals with the C allele being more mobile. The model was successfully tested with two independent empirical datasets on spatial variation in Pgi allele frequency. First, at the level of local populations, the frequency of the C allele is the highest in newly established isolated populations and the lowest in old isolated populations. Second, at the level of sub-networks with dissimilar numbers and connectivities of patches, the frequency of C increases with decreasing network size and hence with decreasing average metapopulation size. The frequency of C is the highest in landscapes where local extinction risk is high and where there are abundant opportunities to establish new populations. Our results indicate that the strength of the coupling of the ecological and evolutionary dynamics depends on the spatial scale and is asymmetric, demographic dynamics having a greater immediate impact on genetic dynamics than vice versa.}, + pmcid = {PMC2690501}, + pmid = {19414467}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\SBXXCXUC\\Zheng et al. - 2009 - Modelling single nucleotide effects in phosphogluc.pdf} +} + +@article{zollnerBehavioralTradeoffsWhen2005, + title = {Behavioral Tradeoffs When Dispersing across a Patchy Landscape.}, + author = {Zollner, Patrick A. and Lima, Steven L.}, + year = {2005}, + journal = {OIKOS}, + volume = {108}, + pages = {219--230}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\JXRLCA3R\\Zollner und Lima - 2005 - Behavioral tradeoffs when dispersing across a patc.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\EK9H5EZM\\12821.html} +} + +@article{zollnerLandscapelevelPerceptualAbilities1997, + title = {Landscape-Level Perceptual Abilities in White-Footed Mice : Perceptual Range and the Detection of Forested Habitat}, + shorttitle = {Landscape-Level Perceptual Abilities in White-Footed Mice}, + author = {Zollner, P. and Lima, S. L.}, + year = {1997}, + journal = {Oikos}, + volume = {80}, + number = {1}, + pages = {51--60}, + doi = {10.2307/3546515}, + abstract = {We define perceptual range as the distance from which an animal can perceive key landscape elements, such as distant patches of forested habitat. We argue that perceptual range should be a determinant of not only dispersal success in unfamiliar or hostile landscapes, but also of several landscape-level ecological processes influencing population dynamics. To redress the absence of empirical information on perceptual ranges, we simulated the dispersal of forest-dwelling white-footed mice (Peromyscus leucopus) across an agricultural landscape by releasing mice into unfamiliar, hostile agricultural habitat at various distances from fragments of forested habitat. We found that these forest mice have a remarkably low perceptual range with regard to detecting their forested (core) habitat. Mice released into bare fields failed to even orient towards forested habitat as little as 30 m distant, while mice in crop fields appeared unable to locate forest habitat as little as 10 m distant. These mice seemed to locate forested habitat by vision, despite the availability of non-visual cues. Future work will undoubtedly demonstrate vast differences in landscape-level perceptual abilities among animals, and show clearly that the ecological effects of a given landscape configuration will be influenced by the behavioral attributes of the species in question.} +} + +@article{zollnerSearchStrategiesLandscapeLevel1999, + title = {Search {{Strategies}} for {{Landscape-Level Interpatch Movements}}}, + author = {Zollner, Patrick and Lima, Steven L.}, + year = {1999}, + journal = {Ecology}, + volume = {80}, + number = {3}, + pages = {1019--1030}, + issn = {1939-9170}, + doi = {10.1890/0012-9658(1999)080[1019:SSFLLI]2.0.CO;2}, + abstract = {Ecologists need a better understanding of how animals make decisions about moving across landscapes. To this end, we developed computer simulations that contrast the effectiveness of various search strategies at finding habitat patches in idealized landscapes (uniform, random, or clumped patches), where searchers have different energy reserves and face different mortality risks. Nearly straight correlated random walks always produced better dispersal success than relatively uncorrelated random walks. However, increasing patch density decreased the degree of correlation that maximized dispersal success. Only under high mortality and low energy reserves in a uniform landscape did absolutely straight-line search perform better than any random walk. With low mortality risks and high energy reserves, exhaustive systematic search was superior to the best correlated random walk; an increase in the perceptual range of the searcher (i.e., patch detectability) also favored exhaustive search over relatively straight random walks. For all conditions examined, the ``average distance rule,'' a hybrid search rule incorporating both straight-line and systematic search, was best. Overall, however, our results suggest that a simple and effective search rule for many landscape-explicit models would involve straight or nearly straight movements.}, + langid = {english}, + keywords = {dispersal,interpatch movement,landscape configuration,landscape ecology,mortality risk,perceptual range,random walks,search strategies,systematic search}, + annotation = {\_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/0012-9658\%281999\%29080\%5B1019\%3ASSFLLI\%5D2.0.CO\%3B2}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\P5MVGMQ8\\Zollner und Lima - 1999 - Search Strategies for Landscape-Level Interpatch M.pdf;C\:\\Users\\jreeg\\Zotero\\storage\\HPFF9TKI\\0012-9658(1999)080[1019SSFLLI]2.0.html} +} + +@article{zotero-2098, + type = {Article} +} + +@article{zurellStaticSpeciesDistribution2009, + title = {Static Species Distribution Models in Dynamically Changing Systems: How Good Can Predictions Really Be?}, + shorttitle = {Static Species Distribution Models in Dynamically Changing Systems}, + author = {Zurell, Damaris and Jeltsch, Florian and Dormann, Carsten F. and Schr{\"o}der, Boris}, + year = {2009}, + journal = {Ecography}, + volume = {32}, + number = {5}, + pages = {733--744}, + issn = {1600-0587}, + doi = {10.1111/j.1600-0587.2009.05810.x}, + abstract = {It is widely acknowledged that species respond to climate change by range shifts. Robust predictions of such changes in species' distributions are pivotal for conservation planning and policy making, and are thus major challenges in ecological research. Statistical species distribution models (SDMs) have been widely applied in this context, though they remain subject to criticism as they implicitly assume equilibrium, and incorporate neither dispersal, demographic processes nor biotic interactions explicitly. In this study, the effects of transient dynamics and ecological properties and processes on the prediction accuracy of SDMs for climate change projections were tested. A spatially explicit multi-species dynamic population model was built, incorporating species-specific and interspecific ecological processes, environmental stochasticity and climate change. Species distributions were sampled in different scenarios, and SDMs were estimated by applying generalised linear models (GLMs) and boosted regression trees (BRTs). Resulting model performances were related to prevailing ecological processes and temporal dynamics. SDM performance varied for different range dynamics. Prediction accuracies decreased when abrupt range shifts occurred as species were outpaced by the rate of climate change, and increased again when a new equilibrium situation was realised. When ranges contracted, prediction accuracies increased as the absences were predicted well. Far-dispersing species were faster in tracking climate change, and were predicted more accurately by SDMs than short-dispersing species. BRTs mostly outperformed GLMs. The presence of a predator, and the inclusion of its incidence as an environmental predictor, made BRTs and GLMs perform similarly. Results are discussed in light of other studies dealing with effects of ecological traits and processes on SDM performance. Perspectives are given on further advancements of SDMs and for possible interfaces with more mechanistic approaches in order to improve predictions under environmental change.}, + langid = {english}, + annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2009.05810.x}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\4YT6HTDC\\Zurell et al. - 2009 - Static species distribution models in dynamically .pdf;C\:\\Users\\jreeg\\Zotero\\storage\\UFC34L2K\\j.1600-0587.2009.05810.html} +} + +@article{zurellUncertaintyPredictionsRange2012a, + title = {Uncertainty in Predictions of Range Dynamics: Black Grouse Climbing the {{Swiss Alps}}}, + shorttitle = {Uncertainty in Predictions of Range Dynamics}, + author = {Zurell, Damaris and Grimm, Volker and Rossmanith, Eva and Zbinden, Niklaus and Zimmermann, Niklaus E. and Schr{\"o}der, Boris}, + year = {2012}, + issn = {0906-7590}, + abstract = {Empirical species distribution models (SDMs) constitute often the tool of choice for the assessment of rapid climate change effects on species' vulnerability. Conclusions regarding extinction risks might be misleading, however, because SDMs do not explicitly incorporate dispersal or other demographic processes. Here, we supplement SDMs with a dynamic population model 1) to predict climate-induced range dynamics for black grouse in Switzerland, 2) to compare direct and indirect measures of extinction risks, and 3) to quantify uncertainty in predictions as well as the sources of that uncertainty. To this end, we linked models of habitat suitability to a spatially explicit, individual-based model. In an extensive sensitivity analysis, we quantified uncertainty in various model outputs introduced by different SDM algorithms, by different climate scenarios and by demographic model parameters. Potentially suitable habitats were predicted to shift uphill and eastwards. By the end of the 21st century, abrupt habitat losses were predicted in the western Prealps for some climate scenarios. In contrast, population size and occupied area were primarily controlled by currently negative population growth and gradually declined from the beginning of the century across all climate scenarios and SDM algorithms. However, predictions of population dynamic features were highly variable across simulations. Results indicate that inferring extinction probabilities simply from the quantity of suitable habitat may underestimate extinction risks because this may ignore important interactions between life history traits and available habitat. Also, in dynamic range predictions uncertainty in SDM algorithms and climate scenarios can become secondary to uncertainty in dynamic model components. Our study emphasises the need for principal evaluation tools like sensitivity analysis in order to assess uncertainty and robustness in dynamic range predictions. A more direct benefit of such robustness analysis is an improved mechanistic understanding of dynamic species' responses to climate change.}, + langid = {english}, + file = {C\:\\Users\\jreeg\\Zotero\\storage\\W9ILGC7X\\517524.html} +} + + diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RS_ODD.json b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RS_ODD.json new file mode 100644 index 0000000..3902114 --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RS_ODD.json @@ -0,0 +1,322 @@ +[ + {"id":"abenSimpleIndividualbasedModels2014","abstract":"Reliable estimates of dispersal rates between habitat patches (i.e. functional connectivity) are critical for predicting long-term effects of habitat fragmentation on population persistence. Connectivity measures are frequently derived from least cost path or graph-based approaches, despite the fact that these methods make biologically unrealistic assumptions. Individual-based models (IBMs) have been proposed as an alternative as they allow modelling movement behaviour in response to landscape resistance. However, IBMs typically require excessive data to be useful for management. Here, we test the extent to which an IBM requiring only an uncomplicated set of movement rules [the ‘stochastic movement simulator’ (SMS)] can predict animal movement behaviour in real-world landscapes. Movement behaviour of two forest birds, the Cabanis's greenbul Phyllastrephus cabanisi (a forest specialist) and the white-starred robin Pogonocichla stellata (a habitat generalist), across an Afrotropical matrix was simulated using SMS. Predictions from SMS were evaluated against a set of detailed movement paths collected by radiotracking homing individuals. SMS was capable of generating credible predictions of bird movement, although simulations were sensitive to the cost values and the movement rules specified. Model performance was generally highest when movement was simulated across low-contrasting cost surfaces and when virtual individuals were assigned low directional persistence and limited perceptual range. SMS better predicted movements of the habitat specialist than the habitat generalist, which highlights its potential to model functional connectivity when species movements are affected by the matrix. Synthesis and applications. Modelling the dispersal process with greater biological realism is likely to be critical for improving our predictive capability regarding functional connectivity and population persistence. For more realistic models to be widely applied, it is vital that their application is not overly complicated or data demanding. Here, we show that given relatively basic understanding of a species' dispersal ecology, the stochastic movement simulator represents a promising tool for estimating connectivity, which can help improve the design of functional ecological networks aimed at successful species conservation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Aben","given":"Job"},{"family":"Strubbe","given":"Diederik"},{"family":"Adriaensen","given":"Frank"},{"family":"Palmer","given":"Stephen C. F."},{"family":"Travis","given":"Justin M. J."},{"family":"Lens","given":"Luc"},{"family":"Matthysen","given":"Erik"}],"container-title":"Journal of Applied Ecology","DOI":"10.1111/1365-2664.12224","ISSN":"1365-2664","issue":"3","issued":{"date-parts":[[2014]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/1365-2664.12224","page":"693-702","source":"Wiley Online Library","title":"Simple individual-based models effectively represent Afrotropical forest bird movement in complex landscapes","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/1365-2664.12224","volume":"51"}, + {"id":"adriaensenApplicationLeastcostModelling2003","abstract":"The growing awareness of the adverse effects of habitat fragmentation on natural systems has resulted in a rapidly increasing number of actions to reduce current fragmentation of natural systems as well as a growing demand for tools to predict and evaluate the effect of changes in the landscape on connectivity in the natural world. Recent studies used ‘least-cost’ modelling (available as a toolbox in GIS-systems) to calculate ‘effective distance’, a measure for distance modified with the cost to move between habitat patches based on detailed geographical information on the landscape as well as behavioural aspects of the organisms studied. We applied the method to a virtual landscape and a small scaled agricultural system subject to different scenarios in a land re-allotment project. We discuss the importance of technical aspects and ecological assumption underlying this modelling method. The model is shown to be a flexible tool to model functional connectivity in the study of the relation between landscape and mobility of organisms as well as in scenario building and evaluation in wild life protection projects and applied land management projects. Since ‘effective distance’ has the same units as Euclidean distance (m), this effective distance may be a straightforward way to include landscape and behavioural aspects in other models which include distance as a measure for isolation. We show the importance of the ‘ecological’ quality of the input maps and the choice of relevant landscape features and resistance values.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Adriaensen","given":"F."},{"family":"Chardon","given":"J. P."},{"family":"De Blust","given":"G."},{"family":"Swinnen","given":"E."},{"family":"Villalba","given":"S."},{"family":"Gulinck","given":"H."},{"family":"Matthysen","given":"E."}],"container-title":"Landscape and Urban Planning","container-title-short":"Landscape and Urban Planning","DOI":"10.1016/S0169-2046(02)00242-6","ISSN":"0169-2046","issue":"4","issued":{"date-parts":[[2003,8,15]]},"language":"en","page":"233-247","source":"ScienceDirect","title":"The application of ‘least-cost’ modelling as a functional landscape model","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169204602002426","volume":"64"}, + {"id":"altweggDensitydependentDispersalSpeed2013","abstract":"Aim The speed of range expansions, be it invasive species colonizing a new area or species tracking a moving climatic niche, critically depends on dispersal. Models for species' range expansions generally assume dispersal to be independent of local population densities. However, animals often disperse in response to high population size or alternatively may avoid or leave areas of very low population sizes. We explore whether such density dependence in dispersal can safely be ignored when predicting the speed of range expansions. Location Simulation study. Methods We use simulations to examine the effect of different forms of density dependence in emigration and immigration on the speed of range expansions. For emigration, we consider linear and nonlinear forms of positive density dependence, negative density dependence at low population densities and constant emigration rates. For immigration, we consider options where individuals avoid crowded patches, are attracted to the presence of conspecifics or settle independent of local density. Results The speed of range expansion was slowest when emigration was strongly positively related to density (higher emigration at higher densities) and when individuals avoided settling in low-density patches. It tended to be fastest under negatively density-dependent emigration (higher emigration at lower densities). These results were consistent across two different life histories and different levels of carrying capacity. Main conclusions Our results suggest that considering density-dependent dispersal and the mechanisms leading to it are important for correctly predicting species' rates of spread. Organisms with a tendency to aggregate, for example, by relying on conspecific attraction in settlement and emigrating mainly in response to high local densities, are predicted to be least likely to expand their ranges and most at risk from spatial shifts in their climatic niches.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Altwegg","given":"Res"},{"family":"Collingham","given":"Yvonne C."},{"family":"Erni","given":"Birgit"},{"family":"Huntley","given":"Brian"}],"container-title":"Diversity and Distributions","DOI":"10.1111/j.1472-4642.2012.00943.x","ISSN":"1472-4642","issue":"1","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2012.00943.x","page":"60-68","source":"Wiley Online Library","title":"Density-dependent dispersal and the speed of range expansions","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1472-4642.2012.00943.x","volume":"19"}, + {"id":"andersonDynamicsRangeMargins2009","abstract":"We link spatially explicit climate change predictions to a dynamic metapopulation model. Predictions of species' responses to climate change, incorporating metapopulation dynamics and elements of dispersal, allow us to explore the range margin dynamics for two lagomorphs of conservation concern. Although the lagomorphs have very different distribution patterns, shifts at the edge of the range were more pronounced than shifts in the overall metapopulation. For Romerolagus diazi (volcano rabbit), the lower elevation range limit shifted upslope by approximately 700 m. This reduced the area occupied by the metapopulation, as the mountain peak currently lacks suitable vegetation. For Lepus timidus (European mountain hare), we modelled the British metapopulation. Increasing the dispersive estimate caused the metapopulation to shift faster on the northern range margin (leading edge). By contrast, it caused the metapopulation to respond to climate change slower, rather than faster, on the southern range margin (trailing edge). The differential responses of the leading and trailing range margins and the relative sensitivity of range limits to climate change compared with that of the metapopulation centroid have important implications for where conservation monitoring should be targeted. Our study demonstrates the importance and possibility of moving from simple bioclimatic envelope models to second-generation models that incorporate both dynamic climate change and metapopulation dynamics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Anderson","given":"B.j"},{"family":"Akçakaya","given":"H.r"},{"family":"Araújo","given":"M.b"},{"family":"Fordham","given":"D.a"},{"family":"Martinez-Meyer","given":"E"},{"family":"Thuiller","given":"W"},{"family":"Brook","given":"B.w"}],"container-title":"Proceedings of the Royal Society B: Biological Sciences","DOI":"10.1098/rspb.2008.1681","issue":"1661","issued":{"date-parts":[[2009,4,22]]},"page":"1415-1420","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Dynamics of range margins for metapopulations under climate change","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2008.1681","volume":"276"}, + {"id":"araujoClimateChangeThreatens2011","abstract":"Ecology Letters (2011) 14: 484–492 Abstract Europe has the world’s most extensive network of conservation areas. Conservation areas are selected without taking into account the effects of climate change. How effectively would such areas conserve biodiversity under climate change? We assess the effectiveness of protected areas and the Natura 2000 network in conserving a large proportion of European plant and terrestrial vertebrate species under climate change. We found that by 2080, 58 ± 2.6% of the species would lose suitable climate in protected areas, whereas losses affected 63 ± 2.1% of the species of European concern occurring in Natura 2000 areas. Protected areas are expected to retain climatic suitability for species better than unprotected areas (P < 0.001), but Natura 2000 areas retain climate suitability for species no better and sometimes less effectively than unprotected areas. The risk is high that ongoing efforts to conserve Europe’s biodiversity are jeopardized by climate change. New policies are required to avert this risk.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Araújo","given":"Miguel B."},{"family":"Alagador","given":"Diogo"},{"family":"Cabeza","given":"Mar"},{"family":"Nogués-Bravo","given":"David"},{"family":"Thuiller","given":"Wilfried"}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2011.01610.x","ISSN":"1461-0248","issue":"5","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2011.01610.x","page":"484-492","source":"Wiley Online Library","title":"Climate change threatens European conservation areas","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2011.01610.x","volume":"14"}, + {"id":"araujoReducingUncertaintyProjections2005","abstract":"Aim Concern over the implications of climate change for biodiversity has led to the use of species–climate ‘envelope’ models to forecast risks of species extinctions under climate change scenarios. Recent studies have demonstrated significant variability in model projections and there remains a need to test the accuracy of models and to reduce uncertainties. Testing of models has been limited by a lack of data against which projections of future ranges can be tested. Here we provide a first test of the predictive accuracy of such models using observed species’ range shifts and climate change in two periods of the recent past. Location Britain. Methods Observed range shifts for 116 breeding bird species in Britain between 1967 and 1972 (t1) and 1987–91 (t2) are used. We project range shifts between t1 and t2 for each species based on observed climate using 16 alternative models (4 methods × 2 data parameterizations × 2 rules to transform probabilities of occurrence into presence and absence records). Results Modelling results were extremely variable, with projected range shifts varying both in magnitude and in direction from observed changes and from each other. However, using approaches that explore the central tendency (consensus) of model projections, we were able to improve agreement between projected and observed shifts significantly. Conclusions Our results provide the first empirical evidence of the value of species–climate ‘envelope’ models under climate change and demonstrate reduction in uncertainty and improvement in accuracy through selection of the most consensual projections.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Araújo","given":"Miguel B."},{"family":"Whittaker","given":"Robert J."},{"family":"Ladle","given":"Richard J."},{"family":"Erhard","given":"Markus"}],"container-title":"Global Ecology and Biogeography","DOI":"10.1111/j.1466-822X.2005.00182.x","ISSN":"1466-8238","issue":"6","issued":{"date-parts":[[2005]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-822X.2005.00182.x","page":"529-538","source":"Wiley Online Library","title":"Reducing uncertainty in projections of extinction risk from climate change","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1466-822X.2005.00182.x","volume":"14"}, + {"id":"armsworthConditionalDispersalClines2008","abstract":"Conditional dispersal, in which an individual’s decision over whether to disperse is a response to environmental conditions, features prominently in studies of dispersal evolution. Using models of clines, I examine how one widely discussed cost of dispersal, namely, that dispersal impedes local adaptation, changes with conditional dispersal and what this implies for dispersal evolution. I examine the consequences for dispersal evolution of the responsiveness of dispersal to the environment, the accuracy of any proximal cues that individuals rely upon to assess habitat quality, and whether dispersal responds to fitness itself or only to some fitness components (juvenile survivorship). All of the conditional dispersal behaviors that I consider weaken the indirect cost of dispersal inhibiting local adaptation. However, if individuals rely on imprecise cues to assess habitat quality and base dispersal decisions on juvenile survivorship, then conditional dispersal can incur additional costs by exacerbating overcrowding. Conditional dispersal initially leads to steeper clines in traits under direct selection, but when dispersiveness can itself evolve, conditional dispersal allows sigmoidal clines to persist long after those obtained with unconditional movement would become stepped.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Armsworth","given":"Paul R."}],"container-title":"Theoretical Ecology","container-title-short":"Theor Ecol","DOI":"10.1007/s12080-008-0032-2","ISSN":"1874-1746","issue":"2","issued":{"date-parts":[[2008]]},"language":"en","page":"105-117","source":"Springer Link","title":"Conditional dispersal, clines, and the evolution of dispersiveness","type":"article-journal","URL":"https://doi.org/10.1007/s12080-008-0032-2","volume":"2"}, + {"id":"armsworthStructureClinesFitness2008","abstract":"Spatial models commonly assume that dispersal does not depend on environmental conditions or phenotype. For example, these assumptions underpin explanations for clines on the basis of a trade‐off between dispersal and local adaptation. We reexamine clines when an individual’s decisions over whether and where to disperse depend on its fitness. We compare fitness‐dependent dispersal with cases where dispersal responds to juvenile survivorship only. Clines are steeper the more responsive dispersal is to environmental conditions for all dispersal behaviors that we consider. Clines eventually become stepped as the responsiveness of dispersal to environmental conditions is increased for half of the dispersal behaviors we consider, but smooth clines are maintained for the remaining cases. Smooth clines are maintained by the biased movement of individuals out of the hybrid zone when individuals move directionally in response to gradients in juvenile survivorship, which is a different mechanism to that maintaining smooth clines in classic cline theory.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Armsworth","given":"Paul R."},{"family":"Roughgarden","given":"Joan E."}],"container-title":"The American Naturalist","DOI":"10.1086/591685","ISSN":"0003-0147","issue":"5","issued":{"date-parts":[[2008,11,1]]},"page":"648-657","publisher":"The University of Chicago Press","source":"journals.uchicago.edu (Atypon)","title":"The Structure of Clines with Fitness‐Dependent Dispersal.","type":"article-journal","URL":"https://www.journals.uchicago.edu/doi/full/10.1086/591685","volume":"172"}, + {"id":"atkinsLocalAdaptationEvolution2010","abstract":"The potential impact of climate change on biodiversity is well documented. A well developed range of statistical methods currently exists that projects the possible future habitat of a species directly from the current climate and a species distribution. However, studies incorporating ecological and evolutionary processes remain limited. Here, we focus on the potential role that local adaptation to climate may play in driving the range dynamics of sessile organisms. Incorporating environmental adaptation into a stochastic simulation yields several new insights. Counter-intuitively, our simulation results suggest that species with broader ranges are not necessarily more robust to climate change. Instead, species with broader ranges can be more susceptible to extinction as locally adapted genotypes are often blocked from range shifting by the presence of cooler adapted genotypes that persist even when their optimum climate has left them behind. Interestingly, our results also suggest that it will not always be the cold-adapted phenotypes that drive polewards range expansion. Instead, range shifts may be driven by phenotypes conferring adaptation to conditions prevalent towards the centre of a species’ equilibrium distribution. This may have important consequences for the conservation method termed predictive provenancing. These initial results highlight the potential importance of local adaptation in determining how species will respond to climate change and we argue that this is an area requiring urgent theoretical and empirical attention.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Atkins","given":"K. E."},{"family":"Travis","given":"J. M. J."}],"container-title":"Journal of Theoretical Biology","container-title-short":"Journal of Theoretical Biology","DOI":"10.1016/j.jtbi.2010.07.014","ISSN":"0022-5193","issue":"3","issued":{"date-parts":[[2010,10,7]]},"language":"en","page":"449-457","source":"ScienceDirect","title":"Local adaptation and the evolution of species’ ranges under climate change","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0022519310003632","volume":"266"}, + {"id":"bachEvolutionConditionalDispersal2007","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bach","given":"Lars"},{"family":"Ripa","given":"Jörgen"},{"family":"Lundberg","given":"Per"}],"container-title":"Evolutionary Ecology","container-title-short":"(Evolutionary ecology","ISSN":"1573-8477","issue":"4","issued":{"date-parts":[[2007]]},"language":"English","page":"663-673","publisher":"Springer","source":"portal.research.lu.se","title":"On the evolution of conditional dispersal under environmental and demographic stochasticity","type":"article-journal","URL":"https://portal.research.lu.se/portal/en/publications/on-the-evolution-of-conditional-dispersal-under-environmental-and-demographic-stochasticity(f23f9fc6-0c1d-460e-b1d6-4c96baa25102).html","volume":"9"}, + {"id":"baguetteIndividualDispersalLandscape2013","abstract":"Connectivity is classically considered an emergent property of landscapes encapsulating individuals' flows across space. However, its operational use requires a precise understanding of why and how organisms disperse. Such movements, and hence landscape connectivity, will obviously vary according to both organism properties and landscape features. We review whether landscape connectivity estimates could gain in both precision and generality by incorporating three fundamental outcomes of dispersal theory. Firstly, dispersal is a multi-causal process; its restriction to an ‘escape reaction’ to environmental unsuitability is an oversimplification, as dispersing individuals can leave excellent quality habitat patches or stay in poor-quality habitats according to the relative costs and benefits of dispersal and philopatry. Secondly, species, populations and individuals do not always react similarly to those cues that trigger dispersal, which sometimes results in contrasting dispersal strategies. Finally, dispersal is a major component of fitness and is thus under strong selective pressures, which could generate rapid adaptations of dispersal strategies. Such evolutionary responses will entail spatiotemporal variation in landscape connectivity. We thus strongly recommend the use of genetic tools to: (i) assess gene flow intensity and direction among populations in a given landscape; and (ii) accurately estimate landscape features impacting gene flow, and hence landscape connectivity. Such approaches will provide the basic data for planning corridors or stepping stones aiming at (re)connecting local populations of a given species in a given landscape. This strategy is clearly species- and landscape-specific. But we suggest that the ecological network in a given landscape could be designed by stacking up such linkages designed for several species living in different ecosystems. This procedure relies on the use of umbrella species that are representative of other species living in the same ecosystem.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Baguette","given":"Michel"},{"family":"Blanchet","given":"Simon"},{"family":"Legrand","given":"Delphine"},{"family":"Stevens","given":"Virginie M."},{"family":"Turlure","given":"Camille"}],"container-title":"Biological Reviews","DOI":"10.1111/brv.12000","ISSN":"1469-185X","issue":"2","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/brv.12000","page":"310-326","source":"Wiley Online Library","title":"Individual dispersal, landscape connectivity and ecological networks","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/brv.12000","volume":"88"}, + {"id":"baguetteLandscapeConnectivityAnimal2007","abstract":"Landscape connectivity can be viewed from two perspectives that could be considered as extremes of a gradient: functional connectivity (refers to how the behavior of a dispersing organism is affected by landscape structure and elements) and structural connectivity (depends on the spatial configuration of habitat patches in the landscape like vicinity or presence of barriers). Here we argue that dispersal behavior changes with landscape configuration stressing the evolutionary dimension that has often been ignored in landscape ecology. Our working hypothesis is that the functional grain of resource patches in the landscape is a crucial factor shaping individual movements, and therefore influencing landscape connectivity. Such changes are likely to occur on the short-term (some generations). We review empirical studies comparing dispersal behavior in landscapes differing in their fragmentation level, i.e., with variable resource grain. We show that behavioral variation affecting each of the three stages of the dispersal process (emigration, displacement or transfer in the matrix, and immigration) is indeed likely to occur according to selective pressures resulting from changes in the grain of the landscape (mortality or deferred costs). Accordingly, landscape connectivity results from the interaction between the dispersal behavior of individuals and the grain of each particular landscape. The existence of this interaction requires that connectivity estimates (being based on individual-based models, least cost distance algorithms, and structural connectivity metrics or even Euclidian distance) should be carefully evaluated for their applicability with respect to the required level of precision in species-specific and landscape information.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Baguette","given":"Michel"},{"family":"Van Dyck","given":"Hans"}],"container-title":"Landscape Ecology","container-title-short":"Landscape Ecol","DOI":"10.1007/s10980-007-9108-4","ISSN":"1572-9761","issue":"8","issued":{"date-parts":[[2007,10,1]]},"language":"en","page":"1117-1129","source":"Springer Link","title":"Landscape connectivity and animal behavior: functional grain as a key determinant for dispersal","title-short":"Landscape connectivity and animal behavior","type":"article-journal","URL":"https://doi.org/10.1007/s10980-007-9108-4","volume":"22"}, + {"id":"baguetteLongDistanceDispersal2003","abstract":"Movements between habitat patches in a patchy population of the butterfly Boloria aquilonaris were monitored using capture-mark-recapture methods during three successive generations. For each data set, the inverse cumulative proportion of individuals moving 100 m distance classes was fitted to the negative exponential function and the inverse power function. In each case, the negative exponential function provided a better fit than the inverse power function. Two dispersal kernels were generated using both negative exponential and inverse power functions. These dispersal kernels were used to predict movements between 14 suitable sites in a landscape of $220\\ {\\rm km}^{2}$. The negative exponential function generated a dispersal kernel predicting extremely low probabilities for movements exceeding 1 km. The inverse power function generated probabilities predicting that between site movements were possible, according to metapopulation size. CMR studies in the landscape revealed that long distance movements occurred at each generation, corresponding to predictions of the inverse power function dispersal kernel. A total of 26 movements between sites (up to 13 km) were detected, together with recolonisation of empty sites. The spatial scale of the metapopulation dynamics is larger than ever reported on butterflies and long distance movements clearly matter to the persistence of this species in a highly fragmented landscape.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Baguette","given":"Michel"}],"container-title":"Ecography","ISSN":"0906-7590","issue":"2","issued":{"date-parts":[[2003]]},"page":"153-160","publisher":"[Nordic Society Oikos, Wiley]","source":"JSTOR","title":"Long Distance Dispersal and Landscape Occupancy in a Metapopulation of the Cranberry Fritillary Butterfly","type":"article-journal","URL":"https://www.jstor.org/stable/3683430","volume":"26"}, + {"id":"bakerIncrementalCostsBenefits2004","abstract":"Incremental (distance-dependent) costs and benefits of dispersal have received less attention than those that are qualitative. We present a dynamic programming model of settling behavior using parameters estimated from a field study of dispersal in desert isopods, Hemilepistus reaumuri, which walk up to thousands of meters before settling in new or already-established burrows each spring. The model shows that incremental costs of dispersal lead to right-skewed population dispersal patterns, in contrast to cost-free systems or those with unitary costs (i.e., a one time cost of leaving a group or patch). In the model, continuous variation in habitat quality, as opposed to discrete suitable vs. unsuitable sites, allows for trade-offs with dispersal costs that lead to shifts in the likelihood of settling in a patch of a given quality. Thus, measurement of quantitative costs and benefits of movement are needed to understand population dispersal distributions. These costs or benefits may be observable during or after movement, and we examined both pre- and postsettling incremental consequences of dispersal. The daily mortality rate of traveling isopods was 4.2% during the dispersal season, higher than that of settled individuals. Successful settlers traveled more slowly, but burrows started in midseason were most likely to succeed. More distant burrows failed more often, suggesting either an additional cost of movement or a difference in the quality of individuals traveling different distances. The predicted mean dispersal duration from the simulations matched observed values closely, but was based on an unrealistic assumption of perfect knowledge of habitat quality, suggesting some other factor favors longer times before settling. Reproductive success was much higher in re-used burrows than in new burrows, making them a possible incentive for long-distance movements.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Baker","given":"Mitchell B."},{"family":"Rao","given":"Steven"}],"container-title":"Ecology","ISSN":"0012-9658","issue":"4","issued":{"date-parts":[[2004]]},"page":"1039-1051","publisher":"Ecological Society of America","source":"JSTOR","title":"Incremental Costs and Benefits Shape Natal Dispersal: Theory and Example with Hemilepistus reaumuri","title-short":"Incremental Costs and Benefits Shape Natal Dispersal","type":"article-journal","URL":"https://www.jstor.org/stable/3450319","volume":"85"}, + {"id":"balciauskasEstimationCarryingCapacity2009","abstract":"The purpose of this paper is to estimate ecological carrying capacity (K) and growth rate (r) of Lithuanian wolf based on the estimated population sizes and number of harvests from 1966 to 2007. We used the modified Schaefer model where population dynamics is described by the logistic-equation-type growth function with time lag operator (τ) and harvest. We statistically selected the best model whose τ value was 4 and estimated value of K and r were 626 heads for the total Lithuanian territory and 0.776/ year, respectively. Then we examined the appropriateness of the values from the ecological point of view and concluded that ecological carrying capacity is supported by the prey base of wild animals, mainly cervids, and also by depredation on domestic animals. In 1994–1998, the population was near ecological carrying capacity or exceeding it, what we explain by high ecological plasticity of the species and increased use of domestic animals.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Balčiauskas","given":"Linas"},{"family":"Kawata","given":"Yukichika"}],"container-title":"Acta Zoologica Lituanica","DOI":"10.2478/v10043-009-0018-3","ISSN":"1392-1657","issue":"2","issued":{"date-parts":[[2009,1,1]]},"note":"_eprint: https://doi.org/10.2478/v10043-009-0018-3","page":"79-84","publisher":"Taylor & Francis","source":"Taylor and Francis+NEJM","title":"Estimation of Carrying Capacity and Growth Rate of Wolf in Lithuania","type":"article-journal","URL":"https://doi.org/10.2478/v10043-009-0018-3","volume":"19"}, + {"id":"bartonEvolutionIntelligentDispersal2009","abstract":"Theoretical work exploring dispersal evolution focuses on the emigration rate of individuals and typically assumes that movement occurs either at random to any other patch or to one of the nearest-neighbour patches. There is a lack of work exploring the process by which individuals move between patches, and how this process evolves. This is of concern because any organism that can exert control over dispersal direction can potentially evolve efficiencies in locating patches, and the process by which individuals find new patches will potentially have major effects on metapopulation dynamics and gene flow. Here, we take an initial step towards filling this knowledge gap. To do this we constructed a continuous space population model, in which individuals each carry heritable trait values that specify the characteristics of the biased correlated random walk they use to disperse from their natal patch. We explore how the evolution of the random walk depends upon the cost of dispersal, the density of patches in the landscape, and the emigration rate. The clearest result is that highly correlated walks always evolved (individuals tended to disperse in relatively straight lines from their natal patch), reflecting the efficiency of straight-line movement. In our models, more costly dispersal resulted in walks with higher correlation between successive steps. However, the exact walk that evolved also depended upon the density of suitable habitat patches, with low density habitat evolving more biased walks (individuals which orient towards suitable habitat at quite large distances from that habitat). Thus, low density habitat will tend to develop individuals which disperse efficiently between adjacent habitat patches but which only rarely disperse to more distant patches; a result that has clear implications for metapopulation theory. Hence, an understanding of the movement behaviour of dispersing individuals is critical for robust long-term predictions of population dynamics in fragmented landscapes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bartoń","given":"Kamil A."},{"family":"Phillips","given":"Ben L."},{"family":"Morales","given":"Juan M."},{"family":"Travis","given":"Justin M. J."}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2008.16936.x","ISSN":"1600-0706","issue":"2","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2008.16936.x","page":"309-319","source":"Wiley Online Library","title":"The evolution of an ‘intelligent’ dispersal strategy: biased, correlated random walks in patchy landscapes","title-short":"The evolution of an ‘intelligent’ dispersal strategy","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0706.2008.16936.x","volume":"118"}, + {"id":"bartonRiskyMovementIncreases2012","abstract":"The movement rules used by an individual determine both its survival and dispersal success. Here, we develop a simple model that links inter-patch movement behaviour with population dynamics in order to explore how individual dispersal behaviour influences not only its dispersal and survival, but also the population's rate of range expansion. Whereas dispersers are most likely to survive when they follow nearly straight lines and rapidly orient movement towards a non-natal patch, the most rapid rates of range expansion are obtained for trajectories in which individuals delay biasing their movement towards a non-natal patch. This result is robust to the spatial structure of the landscape. Importantly, in a set of evolutionary simulations, we also demonstrate that the movement strategy that evolves at an expanding front is much closer to that maximizing the rate of range expansion than that which maximizes the survival of dispersers. Our results suggest that if one of our conservation goals is the facilitation of range-shifting, then current indices of connectivity need to be complemented by the development and utilization of new indices providing a measure of the ease with which a species spreads across a landscape.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bartoń","given":"K. A."},{"family":"Hovestadt","given":"T."},{"family":"Phillips","given":"B. L."},{"family":"Travis","given":"J. M. J."}],"container-title":"Proceedings of the Royal Society B: Biological Sciences","DOI":"10.1098/rspb.2011.1254","issue":"1731","issued":{"date-parts":[[2012,3,22]]},"page":"1194-1202","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Risky movement increases the rate of range expansion","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2011.1254","volume":"279"}, + {"id":"beaumontApproximateBayesianComputation2010","abstract":"In the past 10years a statistical technique, approximate Bayesian computation (ABC), has been developed that can be used to infer parameters and choose between models in the complicated scenarios that are often considered in the environmental sciences. For example, based on gene sequence and microsatellite data, the method has been used to choose between competing models of human demographic history as well as to infer growth rates, times of divergence, and other parameters. The method fits naturally in the Bayesian inferential framework, and a brief overview is given of the key concepts. Three main approaches to ABC have been developed, and these are described and compared. Although the method arose in population genetics, ABC is increasingly used in other fields, including epidemiology, systems biology, ecology, and agent-based modeling, and many of these applications are briefly described.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Beaumont","given":"Mark A."}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","DOI":"10.1146/annurev-ecolsys-102209-144621","issue":"1","issued":{"date-parts":[[2010]]},"note":"_eprint: https://doi.org/10.1146/annurev-ecolsys-102209-144621","page":"379-406","source":"Annual Reviews","title":"Approximate Bayesian Computation in Evolution and Ecology","type":"article-journal","URL":"https://doi.org/10.1146/annurev-ecolsys-102209-144621","volume":"41"}, + {"id":"bellardImpactsClimateChange2012","abstract":"Many studies in recent years have investigated the effects of climate change on the future of biodiversity. In this review, we first examine the different possible effects of climate change that can operate at individual, population, species, community, ecosystem and biome scales, notably showing that species can respond to climate change challenges by shifting their climatic niche along three non-exclusive axes: time (e.g. phenology), space (e.g. range) and self (e.g. physiology). Then, we present the principal specificities and caveats of the most common approaches used to estimate future biodiversity at global and sub-continental scales and we synthesise their results. Finally, we highlight several challenges for future research both in theoretical and applied realms. Overall, our review shows that current estimates are very variable, depending on the method, taxonomic group, biodiversity loss metrics, spatial scales and time periods considered. Yet, the majority of models indicate alarming consequences for biodiversity, with the worst-case scenarios leading to extinction rates that would qualify as the sixth mass extinction in the history of the earth.","author":[{"family":"Bellard","given":"Céline"},{"family":"Bertelsmeier","given":"Cleo"},{"family":"Leadley","given":"Paul"},{"family":"Thuiller","given":"Wilfried"},{"family":"Courchamp","given":"Franck"}],"container-title":"Ecology Letters","container-title-short":"Ecol Lett","DOI":"10.1111/j.1461-0248.2011.01736.x","ISSN":"1461-0248","issue":"4","issued":{"date-parts":[[2012,4]]},"language":"eng","page":"365-377","PMCID":"PMC3880584","PMID":"22257223","source":"PubMed","title":"Impacts of climate change on the future of biodiversity","type":"article-journal","volume":"15"}, + {"id":"bentonDispersalInvertebratesInfluences2012","abstract":"This chapter briefly lists some of the generic factors that differentiate dispersal in invertebrates from vertebrates. Invertebrates can have considerable flexibility in their life histories and can often develop specific machinery or life-history stages for movement or a combination of life-history stage and behaviour. This makes the overall context of the life history crucial in determining the scope for dispersal, which is often constrained developmentally into a short period. There has been an increasing recognition that variability between individuals is both ubiquitous and important in ecology. The purpose of this chapter is to focus on the proximal factors that influence an individual's decisions, using examples from invertebrates. Environmental factors are first addressed, followed by the role of an individual's age, stage, sex, and condition on dispersal decisions.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Benton","given":"Tim G."},{"family":"Bowler","given":"Diana E."}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0004","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Dispersal in invertebrates: influences on individual decisions","title-short":"Dispersal in invertebrates","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-4"}, + {"id":"bentonMicrocosmExperimentsCan2007","abstract":"Global-scale environmental problems are rarely regarded as amenable to traditional scientific experiment. We argue here that small-scale experiments using ‘model organisms’ in microcosms or mesocosms can be a useful approach for apparently intractable global problems, such as ecosystem responses to climate change or managing biodiversity through the design of nature reserves. An experimental, small-scale research programme can easily be coupled with the development of theory and act as a stimulus to further research, thereby hastening both understanding of the issues and development of practical solutions. This process – from microcosm experiment to the development of practical application – has previously been influential but also has a long time lag. We suggest short-cuts in an attempt to stimulate the use of small-scale experiments to address globally urgent issues with meaningful policy implications.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Benton","given":"Tim G."},{"family":"Solan","given":"Martin"},{"family":"Travis","given":"Justin M. J."},{"family":"Sait","given":"Steven M."}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/j.tree.2007.08.003","ISSN":"0169-5347","issue":"10","issued":{"date-parts":[[2007,10,1]]},"language":"en","page":"516-521","source":"ScienceDirect","title":"Microcosm experiments can inform global ecological problems","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169534707002315","volume":"22"}, + {"id":"bessa-gomesDiscreteTwosexModels2010","abstract":"Although sexual reproduction has long been a central subject of theoretical ecology, until recently its consequences for population dynamics were largely overlooked. This is now changing, and many studies have addressed this issue, showing that when the mating system is taken into account, the population dynamics depends on the relative abundance of males and females, and is non-linear. Moreover, sexual reproduction increases the extinction risk, namely due to the Allee effect. Nevertheless, different studies have identified diverse potential consequences, depending on the choice of mating function. In this study, we investigate the consequences of three alternative mating functions that are frequently used in discrete population models: the minimum; the harmonic mean; and the modified harmonic mean. We consider their consequences at three levels: on the probability that females will breed; on the presence and intensity of the Allee effect; and on the extinction risk. When we consider the harmonic mean, the number of times the individuals of the least abundant sex mate exceeds their mating potential, which implies that with variable sex-ratios the potential reproductive rate is no longer under the modeller's control. Consequently, the female breeding probability exceeds 1 whenever the sex-ratio is male-biased, which constitutes an obvious problem. The use of the harmonic mean is thus only justified if we think that this parameter should be re-defined in order to represent the females' breeding rate and the fact that females may reproduce more than once per breeding season. This phenomenon buffers the Allee effect, and reduces the extinction risk. However, when we consider birth-pulse populations, such a phenomenon is implausible because the number of times females can reproduce per birth season is limited. In general, the minimum or modified harmonic mean mating functions seem to be more suitable for assessing the impact of mating systems on population dynamics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bessa-Gomes","given":"Carmen"},{"family":"Legendre","given":"Stéphane"},{"family":"Clobert","given":"Jean"}],"container-title":"Acta Oecologica","DOI":"10.1016/j.actao.2010.02.010","ISSN":"1146-609X","issued":{"date-parts":[[2010,9,1]]},"page":"439-445","source":"NASA ADS","title":"Discrete two-sex models of population dynamics: On modelling the mating function","title-short":"Discrete two-sex models of population dynamics","type":"article-journal","URL":"https://ui.adsabs.harvard.edu/abs/2010AcO....36..439B","volume":"36"}, + {"id":"bestWhichSpeciesWill2007","abstract":"Understanding the ability of species to shift their geographic range is of considerable importance given the current period of rapid climate change. Furthermore, a greater understanding of the spatial population dynamics underlying range shifting is required to complement the advances made in climate niche modelling. A simulation model is developed which incorporates three key features that have been largely overlooked in studies of range shifting dynamics: the form of intraspecific competition, density dependent dispersal and the transient dynamics of habitat patches. The results show that the exact shape of the response depends critically on both local and patch dynamics. Species whose intraspecific competition is contest based are more vulnerable than those whose competition is scramble based. Contesters are especially sensitive when combined with density dependent dispersal. Species living in patches whose carrying capacity grows slowly are also susceptible to rapid shifts of environmental conditions. A complementary analytic approach further highlights the importance of intraspecific competition.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Best","given":"A. S."},{"family":"Johst","given":"K."},{"family":"Münkemüller","given":"T."},{"family":"Travis","given":"J. M. J."}],"container-title":"Oikos","DOI":"10.1111/j.0030-1299.2007.16047.x","ISSN":"1600-0706","issue":"9","issued":{"date-parts":[[2007]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.0030-1299.2007.16047.x","page":"1531-1539","source":"Wiley Online Library","title":"Which species will succesfully track climate change? The influence of intraspecific competition and density dependent dispersal on range shifting dynamics","title-short":"Which species will succesfully track climate change?","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.0030-1299.2007.16047.x","volume":"116"}, + {"id":"bianRepresentationEnvironmentContext2003","abstract":"Individual-based modeling includes the explicit representation of the environment, to which individual organisms interact. From the perspective of spatial representation, spatially extended environment is different from discrete individual organisms, thus the success of object-orientation in the representation of individual organisms may not be applicable to the representation of the environment. Over the past few years, the attempt to adopt object-orientation in the representation of the environment has stimulated interesting discussions over what space is and how it may be represented in ecological modeling. The objective of this paper is to evaluate the merit of two traditional approaches used to represent the environment, i.e., the grid model and the patch model, and, in particular, the object-oriented versions of the two approaches in the representation of the environment. Two case studies are provided in support of the discussions of how the environment may be represented. One case study concerns individual fish growth and movement in an aquatic environment and the other concerns the movement of calving elk in a short-grass prairie. The discussion stresses the importance of two issues in the context of individual-based modeling: (1) the distinction between object-orientation used as a programming technique and as a representation means, and (2) the conceptual compatibility between a perceived phenomenon and the approach used to represent the phenomenon. It is suggested that caution be exercised in the practice of treating cells as objects. The paper concludes that two approaches may be appropriate for individual-based modeling. One is a hybrid approach that incorporates the traditional grid model of the environment and an object-oriented model of individual organisms. The other is the all-object approach that combines the object-oriented patches of the environment and the object-oriented individual organisms.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bian","given":"Ling"}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/S0304-3800(02)00298-3","ISSN":"0304-3800","issue":"2","issued":{"date-parts":[[2003,1,15]]},"language":"en","page":"279-296","source":"ScienceDirect","title":"The representation of the environment in the context of individual-based modeling","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0304380002002983","volume":"159"}, + {"id":"bitumeDensityGeneticRelatedness2013","abstract":"Although dispersal distance plays a major role in determining whether organisms will reach new habitats, empirical data on the environmental factors that affect dispersal distance are lacking. Population density and kin competition are two factors theorised to increase dispersal distance. Using the two-spotted spider mite as a model species, we altered these two environmental conditions and measured the mean dispersal distance of individuals, as well as other attributes of the dispersal kernel. We find that both density and relatedness in the release patch increase dispersal distance. Relatedness, but not density, changes the shape of the dispersal kernel towards a more skewed and leptokurtic shape including a longer ‘fat-tail’. This is the first experimental demonstration that kin competition can shape the whole distribution of dispersal distances in a population, and thus affect the geographical spread of dispersal phenotypes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bitume","given":"E. V."},{"family":"Bonte","given":"D."},{"family":"Ronce","given":"O."},{"family":"Bach","given":"F."},{"family":"Flaven","given":"E."},{"family":"Olivieri","given":"I."},{"family":"Nieberding","given":"C. M."}],"container-title":"Ecology Letters","DOI":"10.1111/ele.12057","ISSN":"1461-0248","issue":"4","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ele.12057","page":"430-437","source":"Wiley Online Library","title":"Density and genetic relatedness increase dispersal distance in a subsocial organism","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/ele.12057","volume":"16"}, + {"id":"bocediEffectsLocalAdaptation2013","abstract":"Local adaptation and species interactions have been shown to affect geographic ranges; therefore, we need models of climate impact that include both factors. To identify possible dynamics of species when including these factors, we ran simulations of two competing species using an individual-based, coupled map-lattice model using a linear climatic gradient that varies across latitude and is warmed over time. Reproductive success is governed by an individual's adaptation to local climate as well as its location relative to global constraints. In exploratory experiments varying the strength of adaptation and competition, competition reduces genetic diversity and slows range change, although the two species can coexist in the absence of climate change and shift in the absence of competitors. We also found that one species can drive the other to extinction, sometimes long after climate change ends. Weak selection on local adaptation and poor dispersal ability also caused surfing of cooler-adapted phenotypes from the expanding margin backwards, causing loss of warmer-adapted phenotypes. Finally, geographic ranges can become disjointed, losing centrally-adapted genotypes. These initial results suggest that the interplay between local adaptation and interspecific competition can significantly influence species' responses to climate change, in a way that demands future research.","author":[{"family":"Bocedi","given":"Greta"},{"family":"Atkins","given":"Katherine E."},{"family":"Liao","given":"Jishan"},{"family":"Henry","given":"Roslyn C."},{"family":"Travis","given":"Justin M. J."},{"family":"Hellmann","given":"Jessica J."}],"container-title":"Annals of the New York Academy of Sciences","container-title-short":"Ann N Y Acad Sci","DOI":"10.1111/nyas.12211","ISSN":"1749-6632","issued":{"date-parts":[[2013,9]]},"language":"eng","page":"83-97","PMID":"23905876","source":"PubMed","title":"Effects of local adaptation and interspecific competition on species' responses to climate change","type":"article-journal","volume":"1297"}, + {"id":"bocediProjectingSpeciesRange2012a","abstract":"1. Dynamic simulation models are a promising tool for assessing how species respond to habitat fragmentation and climate change. However, sensitivity of their outputs to impacts of spatial resolution is insufficiently known.\n2. Using an individual-based dynamic model for species’ range expansion, we demonstrate an inherent risk of substantial biases resulting from choices relating to the resolution at which key patterns and processes are modelled.\n3. Increasing cell size leads to overestimating dispersal distances, the extent of the range shift and population size. Overestimation accelerates with cell size for species with short dispersal capacity and is particularly severe in highly fragmented landscapes.\n4. The overestimation results from three main interacting sources: homogenisation of spatial information, alteration of dispersal kernels and stabilisation/aggregation of population dynamics.\n5. We urge for caution in selecting the spatial resolution used in dynamic simulations and other predictive models and highlight the urgent need to develop upscaling methods that maintain important patterns and processes at fine scales.","author":[{"family":"Bocedi","given":"Greta"},{"family":"Pe'er","given":"Guy"},{"family":"Heikkinen","given":"Risto"},{"family":"Matsinos","given":"Yiannis"},{"family":"Travis","given":"Justin"}],"container-title":"Methods in Ecology and Evolution","container-title-short":"Methods in Ecology and Evolution","DOI":"10.1111/j.2041-210X.2012.00235.x","issued":{"date-parts":[[2012,12,1]]},"page":"1008-1018","source":"ResearchGate","title":"Projecting species' range expansion dynamics: Sources of systematic biases when scaling up patterns and processes","title-short":"Projecting species' range expansion dynamics","type":"article-journal","volume":"3"}, + {"id":"bocediRangeShifterPlatformModelling2014","abstract":"Rapid environmental changes are threatening biodiversity and exposing species to novel ecological and evolutionary pressures. The scientific community increasingly recognizes the need for dynamic models integrating sufficient complexity both to improve our understanding of species' responses to environmental changes and to inform effective management strategies. Using three illustrative examples, we introduce a novel modelling platform, RangeShifter, which integrates complex population dynamics and dispersal behaviour, includes plastic and evolutionary processes and simulates scenarios on spatially explicit landscapes. The software provides functionality for a wide variety of modelling applications ranging from applied questions, where it can be parameterized for real landscapes and species to compare alternative potential management interventions, to purely theoretical studies of species' eco-evolutionary dynamics and responses to different environmental pressures. RangeShifter provides an important tool for facilitating the advancement of ecological theory on species' spatial dynamics in response to environmental changes, and linking it directly to application in biodiversity conservation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bocedi","given":"Greta"},{"family":"Palmer","given":"Stephen C. F."},{"family":"Pe'er","given":"Guy"},{"family":"Heikkinen","given":"Risto K."},{"family":"Matsinos","given":"Yiannis G."},{"family":"Watts","given":"Kevin"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Methods in Ecology and Evolution","DOI":"10.1111/2041-210X.12162","ISSN":"2041-210X","issue":"4","issued":{"date-parts":[[2014]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/2041-210X.12162","page":"388-396","source":"Wiley Online Library","title":"RangeShifter: a platform for modelling spatial eco-evolutionary dynamics and species' responses to environmental changes","title-short":"RangeShifter","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.12162","volume":"5"}, + {"id":"bocediUncertaintyRoleInformation2012","abstract":"There is increasing empirical evidence that individuals utilize social and environmental cues in making decisions as to whether or not to disperse. However, we lack theory exploring the influence of information acquisition and use on the evolution of dispersal strategies and metapopulation dynamics. We used an individual-based, spatially explicit simulation model to explore the evolution of emigration strategies under varying precision of information about the natal patch, cost of information acquisition, and environmental predictability. Our findings show an interesting interplay between information use and the evolved emigration propensity. Lack of information led to higher emigration probabilities in more unpredictable environments but to lower emigration probabilities in constant or highly predictable scenarios. Somewhat-informed dispersal strategies were selected for in most cases, even when the acquisition of information was associated with a moderate reproductive cost. Notably, selection rarely favored investment in acquisition of high-precision information, and the tendency to invest in information acquisition was greatest in predictable environments when the associated cost was low. Our results highlight that information use can affect dispersal in a complex manner and also emphasize that information-acquisition behaviors can themselves come under strong selection, resulting in evolutionary dynamics that are tightly coupled to those of context-dependent behaviors.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bocedi","given":"Greta"},{"family":"Heinonen","given":"Johannes"},{"family":"Travis","given":"Justin M. J."}],"container-title":"The American Naturalist","DOI":"10.1086/665004","ISSN":"0003-0147","issue":"5","issued":{"date-parts":[[2012,5,1]]},"page":"606-620","publisher":"The University of Chicago Press","source":"journals.uchicago.edu (Atypon)","title":"Uncertainty and the Role of Information Acquisition in the Evolution of Context-Dependent Emigration.","type":"article-journal","URL":"https://www.journals.uchicago.edu/doi/full/10.1086/665004","volume":"179"}, + {"id":"boeyeMoreRapidClimate2013","abstract":"Species can either adapt to new conditions induced by climate change or shift their range in an attempt to track optimal environmental conditions. During current range shifts, species are simultaneously confronted with a second major anthropogenic disturbance, landscape fragmentation. Using individual-based models with a shifting climate window, we examine the effect of different rates of climate change on the evolution of dispersal distances through changes in the genetically determined dispersal kernel. Our results demonstrate that the rate of climate change is positively correlated to the evolved dispersal distances although too fast climate change causes the population to crash. When faced with realistic rates of climate change, greater dispersal distances evolve than those required for the population to keep track of the climate, thereby maximizing population size. Importantly, the greater dispersal distances that evolve when climate change is more rapid, induce evolutionary rescue by facilitating the population in crossing large gaps in the landscape. This could ensure population persistence in case of range shifting in fragmented landscapes. Furthermore, we highlight problems in using invasion speed as a proxy for potential range shifting abilities under climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Boeye","given":"Jeroen"},{"family":"Travis","given":"Justin M J"},{"family":"Stoks","given":"Robby"},{"family":"Bonte","given":"Dries"}],"container-title":"Evolutionary Applications","container-title-short":"Evol Appl","DOI":"10.1111/eva.12004","ISSN":"1752-4571","issue":"2","issued":{"date-parts":[[2013,2]]},"page":"353-364","PMCID":"PMC3586623","PMID":"23467649","source":"PubMed Central","title":"More rapid climate change promotes evolutionary rescue through selection for increased dispersal distance","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3586623/","volume":"6"}, + {"id":"bonenfantChapterEmpiricalEvidence2009","abstract":"Density‐dependence is a key concept in population dynamics. Here, we review how body mass and demographic parameters vary with population density in large herbivores. The demographic parameters we consider are age‐ and sex‐specific reproduction, survival and dispersal. As population density increases, the body mass of large herbivores typically declines, affecting individual performance traits such as age of first reproduction and juvenile survival. We documented density‐dependent variations in reproductive rates for many species from the Arctic to subtropical zones, both with and without predation. At high density, a trade‐off between growth and reproduction delays the age of primiparity and often increases the costs of reproduction, decreasing both survival and future reproductive success of adult females. Density‐dependent preweaning juvenile survival occurs more often in polytocous than monotocous species, while the effects of density on post‐weaning juvenile survival are independent of litter size. Responses of adult survival to density are much less marked than for juvenile survival, and may be exaggerated by density‐dependent changes in age structure. The role of density‐dependent dispersal in population dynamics remains uncertain, because very few studies have examined it. For sexually dimorphic species, we found little support for higher sensitivity to increasing density in the life history traits of males compared to females, except for young age classes. It remains unclear whether males of dimorphic species are sensitive to male density, female density or a combination of both. Eberhardt's model predicting a sequential effect of density on demographic parameters (from juvenile survival to adult survival) was supported by 9 of 10 case studies. In addition, population density at birth can also lead to cohort effects, including a direct effect on juvenile survival and long‐term effects on average cohort performance as adults. Density effects typically interact with weather, increasing in strength in years of harsh weather. For some species, the synchronization between plant phenology and reproductive cycle is a key process in population dynamics. The timing of late gestation as a function of plant phenology determines whether density‐dependence influences juvenile survival or adult female reproduction. The detection of density‐dependence can be made difficult by nonlinear relationships with density, high sampling variability, lagged responses to density changes, changes in population age structure, and temporal variation in the main factors limiting population growth. The negative feedbacks of population size on individual performance, and hence on life history traits, are thus only expected in particular ecological contexts and are most often restricted to certain age‐specific demographic traits.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bonenfant","given":"Christophe"},{"family":"Gaillard","given":"Jean‐Michel"},{"family":"Coulson","given":"Tim"},{"family":"Festa‐Bianchet","given":"Marco"},{"family":"Loison","given":"Anne"},{"family":"Garel","given":"Mathieu"},{"family":"Loe","given":"Leif Egil"},{"family":"Blanchard","given":"Pierrick"},{"family":"Pettorelli","given":"Nathalie"},{"family":"Owen‐Smith","given":"Norman"},{"family":"Du Toit","given":"Johan"},{"family":"Duncan","given":"Patrick"}],"container-title":"Advances in Ecological Research","DOI":"10.1016/S0065-2504(09)00405-X","issued":{"date-parts":[[2009,1,1]]},"language":"en","page":"313-357","publisher":"Academic Press","source":"ScienceDirect","title":"Chapter 5 Empirical Evidence of Density‐Dependence in Populations of Large Herbivores","type":"chapter","URL":"https://www.sciencedirect.com/science/article/pii/S006525040900405X","volume":"41"}, + {"id":"bonteCostsDispersal2012a","abstract":"Dispersal costs can be classified into energetic, time, risk and opportunity costs and may be levied directly or deferred during departure, transfer and settlement. They may equally be incurred during life stages before the actual dispersal event through investments in special morphologies. Because costs will eventually determine the performance of dispersing individuals and the evolution of dispersal, we here provide an extensive review on the different cost types that occur during dispersal in a wide array of organisms, ranging from micro-organisms to plants, invertebrates and vertebrates. In general, costs of transfer have been more widely documented in actively dispersing organisms, in contrast to a greater focus on costs during departure and settlement in plants and animals with a passive transfer phase. Costs related to the development of specific dispersal attributes appear to be much more prominent than previously accepted. Because costs induce trade-offs, they give rise to covariation between dispersal and other life-history traits at different scales of organismal organisation. The consequences of (i) the presence and magnitude of different costs during different phases of the dispersal process, and (ii) their internal organisation through covariation with other life-history traits, are synthesised with respect to potential consequences for species conservation and the need for development of a new generation of spatial simulation models.","author":[{"family":"Bonte","given":"D."},{"family":"Bullock","given":"James M."},{"family":"Coulon","given":"Aurélie"},{"family":"Delgado","given":"Maria"},{"family":"Gibbs","given":"Melanie"},{"family":"Lehouck","given":"Valerie"},{"family":"Matthysen","given":"Erik"},{"family":"Mustin","given":"Karin"},{"family":"Saastamoinen","given":"Marjo"},{"family":"Schtickzelle","given":"Nicolas"},{"family":"Stevens","given":"Virginie M."},{"family":"Vandewoestijne","given":"Sofie"},{"family":"Baguette","given":"Michel"},{"family":"Barton","given":"Kamil"},{"family":"Benton","given":"Tim G."},{"family":"Chaput-Bardy","given":"Audrey"},{"family":"Clobert","given":"Jean"},{"family":"Dytham","given":"Calvin"},{"family":"Hovestadt","given":"Thomas"},{"family":"Meier","given":"Christoph M."},{"family":"Palmer","given":"Steve C. F."},{"family":"Turlure","given":"Camille"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Biological Reviews of the Cambridge Philosophical Society","container-title-short":"Biol Rev Camb Philos Soc","DOI":"10.1111/j.1469-185X.2011.00201.x","ISSN":"1469-185X","issue":"2","issued":{"date-parts":[[2012,5]]},"language":"eng","page":"290-312","PMID":"21929715","source":"PubMed","title":"Costs of dispersal","type":"article-journal","volume":"87"}, + {"id":"bonteEvolutionDispersalPolymorphism2010","abstract":"Many organisms show polymorphism in dispersal distance strategies. This variation is particularly ecological relevant if it encompasses a functional separation of short- (SDD) and long-distance dispersal (LDD). It remains, however, an open question whether both parts of the dispersal kernel are similarly affected by landscape related selection pressures. We implemented an individual-based model to analyze the evolution of dispersal traits in fractal landscapes that vary in the proportion of habitat and its spatial configuration. Individuals are parthenogenetic with dispersal distance determined by two alleles on each individual's genome: one allele coding for the probability of global dispersal and one allele coding for the variance σ of a Gaussian local dispersal with mean value zero. Simulations show that mean distances of local dispersal and the probability of global dispersal, increase with increasing habitat availability, but that changes in the habitat's spatial autocorrelation impose opposing selective pressure: local dispersal distances decrease and global dispersal probabilities increase with decreasing spatial autocorrelation of the available habitat. Local adaptation of local dispersal distance emerges in landscapes with less than 70% of clumped habitat. These results demonstrate that long and short distance dispersal evolve separately according to different properties of the landscape. The landscape structure may consequently largely affect the evolution of dispersal distance strategies and the level of dispersal polymorphism.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bonte","given":"Dries"},{"family":"Hovestadt","given":"Thomas"},{"family":"Poethke","given":"Hans-Joachim"}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2009.17943.x","ISSN":"1600-0706","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2009.17943.x","page":"560-566","source":"Wiley Online Library","title":"Evolution of dispersal polymorphism and local adaptation of dispersal distance in spatially structured landscapes","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0706.2009.17943.x","volume":"119"}, + {"id":"bonteGeographicalVariationWolf2006","abstract":"Theoretical studies suggest that mechanisms underlying habitat and population structure are important for shaping inter- and intraspecific variation in dispersal behaviour. Empirical evidence, especially in organisms living in spatially structured populations, however, is scarce. We investigated the relation between habitat configuration (patch size, connectivity) and dispersal by studying variation in tiptoe behaviour in the dune wolf spider, Pardosa monticola, under standardized laboratory conditions. Tiptoe behaviour prepares spiderlings for ballooning and can hence be considered as a precursor of aerial dispersal. The proportion of individuals that displayed tiptoe behaviour was highest in offspring from grasslands in a large dune landscape where habitat was continuously available, intermediate in offspring originating from a fragmented landscape, and lowest in offspring originating from a small and extremely isolated grassland patch. At the level of the fragmented landscape, variation was related to size and connectivity of four subpopulations. Both between and within landscapes, maternal condition had no effect on offspring dispersal. These results indicate that changes in habitat configuration from a large, connected landscape towards a small, fragmented one may lead to a decrease in dispersal rates, even at small spatial scales. Hence, behavioural traits narrowly linked to dispersal evolve towards less mobile phenotypes in small, isolated habitats, indicating high dispersal costs and low efficacy for gene flow in a spider species restricted to fragmented habitats.","author":[{"family":"Bonte","given":"D."},{"family":"Borre","given":"J. V."},{"family":"Lens","given":"L."},{"family":"Maelfait","given":"J."}],"container-title":"Animal Behaviour","DOI":"10.1016/j.anbehav.2005.11.026","issued":{"date-parts":[[2006]]},"source":"Semantic Scholar","title":"Geographical variation in wolf spider dispersal behaviour is related to landscape structure","type":"article-journal"}, + {"id":"bonteSexspecificDispersalEvolutionary2009","abstract":"Background: Male killing endosymbionts manipulate their arthropod host reproduction by only allowing female embryos to develop into infected females and killing all male offspring. Because the resulting change in sex ratio is expected to affect the evolution of sex-specific dispersal, we investigated under which environmental conditions strong sex-biased dispersal would emerge, and how this would affect host and endosymbiont metapopulation persistence. Results: We simulated host-endosymbiont metapopulation dynamics in an individual-based model, in which dispersal rates are allowed to evolve independently for the two sexes. Prominent male-biased dispersal emerges under conditions of low environmental stochasticity and high dispersal mortality. By applying a reshuffling algorithm, we show that kin-competition is a major driver of this evolutionary pattern because of the high within-population relatedness of males compared to those of females. Moreover, the evolution of sex-specific dispersal rescues metapopulations from extinction by (i) reducing endosymbiont fixation rates and (ii) by enhancing the extinction of endosymbionts within metapopulations that are characterized by low environmental stochasticity. Conclusion: Male killing endosymbionts induce the evolution of sex-specific dispersal, with prominent male-biased dispersal under conditions of low environmental stochasticity and high dispersal mortality. This male-biased dispersal emerges from stronger kin-competition in males compared to females and induces an evolutionary rescue mechanism.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bonte","given":"Dries"},{"family":"Hovestadt","given":"Thomas"},{"family":"Poethke","given":"Hans Joachim"}],"issued":{"date-parts":[[2009]]},"language":"eng","source":"opus.bibliothek.uni-wuerzburg.de","title":"Sex-specific dispersal and evolutionary rescue in metapopulations infected by male killing endosymbionts","type":"article-journal","URL":"https://opus.bibliothek.uni-wuerzburg.de/frontdoor/index/index/docId/3999"}, + {"id":"boulangeatAccountingDispersalBiotic2012","abstract":"Ecology Letters (2012) Abstract Although abiotic factors, together with dispersal and biotic interactions, are often suggested to explain the distribution of species and their abundances, species distribution models usually focus on abiotic factors only. We propose an integrative framework linking ecological theory, empirical data and statistical models to understand the distribution of species and their abundances together with the underlying community assembly dynamics. We illustrate our approach with 21 plant species in the French Alps. We show that a spatially nested modelling framework significantly improves the model’s performance and that the spatial variations of species presence–absence and abundances are predominantly explained by different factors. We also show that incorporating abiotic, dispersal and biotic factors into the same model bring new insights to our understanding of community assembly. This approach, at the crossroads between community ecology and biogeography, is a promising avenue for a better understanding of species co-existence and biodiversity distribution.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Boulangeat","given":"Isabelle"},{"family":"Gravel","given":"Dominique"},{"family":"Thuiller","given":"Wilfried"}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2012.01772.x","ISSN":"1461-0248","issue":"6","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2012.01772.x","page":"584-593","source":"Wiley Online Library","title":"Accounting for dispersal and biotic interactions to disentangle the drivers of species distributions and their abundances","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2012.01772.x","volume":"15"}, + {"id":"bowlerCausesConsequencesAnimal2005a","abstract":"Knowledge of the ecological and evolutionary causes of dispersal can be crucial in understanding the behaviour of spatially structured populations, and predicting how species respond to environmental change. Despite the focus of much theoretical research, simplistic assumptions regarding the dispersal process are still made. Dispersal is usually regarded as an unconditional process although in many cases fitness gains of dispersal are dependent on environmental factors and individual state. Condition-dependent dispersal strategies will often be superior to unconditional, fixed strategies. In addition, dispersal is often collapsed into a single parameter, despite it being a process composed of three interdependent stages: emigration, inter-patch movement and immigration, each of which may display different condition dependencies. Empirical studies have investigated correlates of these stages, emigration in particular, providing evidence for the prevalence of conditional dispersal strategies. Ill-defined use of the term 'dispersal', for movement across many different spatial scales, further hinders making general conclusions and relating movement correlates to consequences at the population level. Logistical difficulties preclude a detailed study of dispersal for many species, however incorporating unrealistic dispersal assumptions in spatial population models may yield inaccurate and costly predictions. Further studies are necessary to explore the importance of incorporating specific condition-dependent dispersal strategies for evolutionary and population dynamic predictions.","author":[{"family":"Bowler","given":"Diana E."},{"family":"Benton","given":"Tim G."}],"container-title":"Biological Reviews of the Cambridge Philosophical Society","container-title-short":"Biol Rev Camb Philos Soc","DOI":"10.1017/s1464793104006645","ISSN":"1464-7931","issue":"2","issued":{"date-parts":[[2005,5]]},"language":"eng","page":"205-225","PMID":"15921049","source":"PubMed","title":"Causes and consequences of animal dispersal strategies: relating individual behaviour to spatial dynamics","title-short":"Causes and consequences of animal dispersal strategies","type":"article-journal","volume":"80"}, + {"id":"bridleLimitsEvolutionRange2007","abstract":"What stops populations expanding into new territory beyond the edge of a range margin? Recent models addressing this problem have brought together population genetics and population ecology, and some have included interactions among species at range edges. Here, we review these models of adaptation at environmental or parapatric margins, and discuss the contrasting effects of migration in either swamping local adaptation, or supplying the genetic variation that is necessary for adaptation to continue. We illustrate how studying adaptation at range margins (both with and without hybridization) can provide insight into the genetic and ecological factors that limit evolution more generally, especially in response to current rates of environmental change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bridle","given":"Jon R"},{"family":"Vines","given":"Timothy H"}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/j.tree.2006.11.002","ISSN":"0169-5347","issue":"3","issued":{"date-parts":[[2007,3,1]]},"language":"en","page":"140-147","source":"ScienceDirect","title":"Limits to evolution at range margins: when and why does adaptation fail?","title-short":"Limits to evolution at range margins","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169534706003636","volume":"22"}, + {"id":"brookerModellingSpeciesRange2007","abstract":"There is an urgent need for accurate prediction of climate change impacts on species ranges. Current reliance on bioclimatic envelope approaches ignores important biological processes such as interactions and dispersal. Although much debated, it is unclear how such processes might influence range shifting. Using individual-based modelling we show that interspecific interactions and dispersal ability interact with the rate of climate change to determine range-shifting dynamics in a simulated community with two growth forms--mutualists and competitors. Interactions determine spatial arrangements of species prior to the onset of rapid climate change. These lead to space-occupancy effects that limit the rate of expansion of the fast-growing competitors but which can be overcome by increased long-distance dispersal. As the rate of climate change increases, lower levels of long-distance dispersal can drive the mutualists to extinction, demonstrating the potential for subtle process balances, non-linear dynamics and abrupt changes from species coexistence to species loss during climate change.","author":[{"family":"Brooker","given":"Rob W."},{"family":"Travis","given":"Justin M. J."},{"family":"Clark","given":"Ewen J."},{"family":"Dytham","given":"Calvin"}],"container-title":"Journal of Theoretical Biology","container-title-short":"J Theor Biol","DOI":"10.1016/j.jtbi.2006.09.033","ISSN":"0022-5193","issue":"1","issued":{"date-parts":[[2007,3,7]]},"language":"eng","page":"59-65","PMID":"17087974","source":"PubMed","title":"Modelling species' range shifts in a changing climate: the impacts of biotic interactions, dispersal distance and the rate of climate change","title-short":"Modelling species' range shifts in a changing climate","type":"article-journal","volume":"245"}, + {"id":"broquetMolecularEstimationDispersal2009","abstract":"The dispersal process, by which individuals or other dispersing agents such as gametes or seeds move from birthplace to a new settlement locality, has important consequences for the dynamics of genes, individuals, and species. Many of the questions addressed by ecology and evolutionary biology require a good understanding of species’ dispersal patterns. Much effort has thus been devoted to overcoming the difficulties associated with dispersal measurement. In this context, genetic tools have long been the focus of intensive research, providing a great variety of potential solutions to measuring dispersal. This methodological diversity is reviewed here to help (molecular) ecologists find their way toward dispersal inference and interpretation and to stimulate further developments.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Broquet","given":"Thomas"},{"family":"Petit","given":"Eric J."}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","DOI":"10.1146/annurev.ecolsys.110308.120324","issue":"1","issued":{"date-parts":[[2009]]},"note":"_eprint: https://doi.org/10.1146/annurev.ecolsys.110308.120324","page":"193-216","source":"Annual Reviews","title":"Molecular Estimation of Dispersal for Ecology and Population Genetics","type":"article-journal","URL":"https://doi.org/10.1146/annurev.ecolsys.110308.120324","volume":"40"}, + {"id":"bullockLongDistanceSeed2000","abstract":"The size and shape of the tail of the seed dispersal curve is important in determining the spatial dynamics of plants, but is difficult to quantify. We devised an experimental protocol to measure long-distance dispersal which involved measuring dispersal by wind from isolated individuals at a range of distances from the source, but maintaining a large and constant sampling intensity at each distance. Seeds were trapped up to 80 m from the plants, the furthest a dispersal curve for an individual plant has been measured for a non-tree species. Standard empirical negative exponential and inverse power models were fitted using likelihood methods. The latter always had a better fit than the former, but in most cases neither described the data well, and strongly under-estimated the tail of the dispersal curve. An alternative model formulation with two kernel components had a much better fit in most cases and described the tail data more accurately. Mechanistic models provide an alternative to direct measurement of dispersal. However, while a previous mechanistic model accurately predicted the modal dispersal distance, it always under-predicted the measured tail. Long-distance dispersal may be caused by rare extremes in horizontal wind speed or turbulence. Therefore, under-estimation of the tail by standard empirical models and mechanistic models may indicate a lack of flexibility to take account of such extremes. Future studies should examine carefully whether the widely used exponential and power models are, in fact, valid, and investigate alternative models.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Bullock","given":"J. M."},{"family":"Clarke","given":"R. T."}],"container-title":"Oecologia","container-title-short":"Oecologia","DOI":"10.1007/PL00008876","ISSN":"1432-1939","issue":"4","issued":{"date-parts":[[2000,9,1]]},"language":"en","page":"506-521","source":"Springer Link","title":"Long distance seed dispersal by wind: measuring and modelling the tail of the curve","title-short":"Long distance seed dispersal by wind","type":"article-journal","URL":"https://doi.org/10.1007/PL00008876","volume":"124"}, + {"id":"cagnacciAnimalEcologyMeets2010","abstract":"Global positioning system (GPS) telemetry technology allows us to monitor and to map the details of animal movement, securing vast quantities of such data even for highly cryptic organisms. We envision an exciting synergy between animal ecology and GPS-based radiotelemetry, as for other examples of new technologies stimulating rapid conceptual advances, where research opportunities have been paralleled by technical and analytical challenges. Animal positions provide the elemental unit of movement paths and show where individuals interact with the ecosystems around them. We discuss how knowing where animals go can help scientists in their search for a mechanistic understanding of key concepts of animal ecology, including resource use, home range and dispersal, and population dynamics. It is probable that in the not-so-distant future, intense sampling of movements coupled with detailed information on habitat features at a variety of scales will allow us to represent an animal's cognitive map of its environment, and the intimate relationship between behaviour and fitness. An extended use of these data over long periods of time and over large spatial scales can provide robust inferences for complex, multi-factorial phenomena, such as meta-analyses of the effects of climate change on animal behaviour and distribution.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Cagnacci","given":"Francesca"},{"family":"Boitani","given":"Luigi"},{"family":"Powell","given":"Roger A."},{"family":"Boyce","given":"Mark S."}],"container-title":"Philosophical Transactions of the Royal Society B: Biological Sciences","DOI":"10.1098/rstb.2010.0107","issue":"1550","issued":{"date-parts":[[2010,7,27]]},"page":"2157-2162","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Animal ecology meets GPS-based radiotelemetry: a perfect storm of opportunities and challenges","title-short":"Animal ecology meets GPS-based radiotelemetry","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rstb.2010.0107","volume":"365"}, + {"id":"caswellMatrixPopulationModels2001a","abstract":"Published by Sinauer Associates, an imprint of Oxford University Press. Matrix Population Models, Second Edition, is a comprehensive treatment of matrix population models and their applications in ecology and demography. It begins with simple cases, presented in detail so that beginning students can learn how to use these powerful models. It goes on to cover advanced topics in stochastic and nonlinear models. Analytical methods and theoretical issues are illustrated with empirical examples throughout. The decade since the publication of the First Edition of this book has seen enormous progress in the theory and application of matrix population models. The new edition includes greatly expanded treatment of stochastic and density-dependent models, sensitivity analysis, and statistical inference, and new chapters on parameter estimation, structured population models, demographic stochasticity, and applications of matrix models in conservation biology. Matrix Population Models, Second Edition, is an indispensable reference for graduate students and researchers in ecology, population biology, conservation biology, and human demography","author":[{"family":"Caswell","given":"Hal"}],"edition":"Second Edition, Matrix Population Models, Second Edition, is a comprehensive treatment of matrix population models and their applications in ecology and ...","event-place":"Oxford, New York","ISBN":"978-0-87893-121-7","issued":{"date-parts":[[2001]]},"number-of-pages":"722","publisher":"Oxford University Press","publisher-place":"Oxford, New York","source":"Oxford University Press","title":"Matrix Population Models: Construction, Analysis, and Interpretation","title-short":"Matrix Population Models","type":"book"}, + {"id":"caswellSensitivityAnalysisEquilibrium2004","abstract":"We consider the effects of parameter perturbations on a density-dependent population at equilibrium. Such perturbations change the dominant eigenvalue λ of the projection matrix evaluated at the equilibrium as well as the equilibrium itself. We show that, regardless of the functional form of density dependence, the sensitivity of λ is equal to the sensitivity of an effective equilibrium density , which is a weighted combination of the equilibrium stage densities. The weights measure the contributions of each stage to density dependence and their effects on demography. Thus, is in general more relevant than total density, which simply adds all stages regardless of their ecological properties. As log λ is the invasion exponent, our results show that successful invasion will increase , and that an evolutionary stable strategy will maximize . Our results imply that eigenvalue sensitivity analysis of a population projection matrix that is evaluated near equilibrium can give useful information about the sensitivity of the equilibrium population, even if no data on density dependence are available.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Caswell","given":"Hal"},{"family":"Takada","given":"Takenori"},{"family":"Hunter","given":"Christine M."}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2004.00595.x","ISSN":"1461-0248","issue":"5","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2004.00595.x","page":"380-387","source":"Wiley Online Library","title":"Sensitivity analysis of equilibrium in density-dependent matrix population models","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2004.00595.x","volume":"7"}, + {"id":"caswellTwoSexModelsChaos1986","abstract":"Most demographic models consider only one sex, usually the female. The widespread occurrence of sexual dimorphism in life history traits and the occurrence of skewed and fluctuating sex ratios suggest that one-sex models or those dominated by one sex may often be less appropriate than two-sex models. Reproduction in two-sex models is a frequency-dependent nonlinear function (the birth or marriage function) of the relative abundance of males and females. In this paper, we examine the population dynamics resulting from three different two-sex, discrete-time, population-projection models. For a large class of birth functions, models without inter-stage mate competition are shown to converge to a locally stable adult sex ratio. Formulas for the stable population structure, stable sex ratio, and reproductive value at equilibrium are derived. When individuals of different stages compete for mates, the equilibrium population structure may become unstable. A sequence of bifurcations then occurs, leading to periodic oscillations, quasi-periodic fluctuations, and chaos as the intensity of competition increases. Finally, when per capita fecundity is a sigmoid function of the relative abundance of the other sex, perturbations of the sex ratio may lead to extinction.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Caswell","given":"Hal"},{"family":"Weeks","given":"Daniel E."}],"container-title":"The American Naturalist","ISSN":"0003-0147","issue":"5","issued":{"date-parts":[[1986]]},"page":"707-735","publisher":"[University of Chicago Press, American Society of Naturalists]","source":"JSTOR","title":"Two-Sex Models: Chaos, Extinction, and Other Dynamic Consequences of Sex","title-short":"Two-Sex Models","type":"article-journal","URL":"https://www.jstor.org/stable/2461952","volume":"128"}, + {"id":"chaineCoevolutionMultiplyinformedDispersal2013","abstract":"Dispersal plays a key role in natural systems by shaping spatial population and evolutionary dynamics. Dispersal has been largely treated as a population process with little attention to individual decisions and the influence of information use on the fitness benefits of dispersal despite clear empirical evidence that dispersal behavior varies among individuals. While information on local density is common, more controversial is the notion that indirect information use can easily evolve. We used an individual-based model to ask under what conditions indirect information use in dispersal will evolve. We modeled indirect information provided by immigrant arrival into a population which should be linked to overall metapopulation density. We also modeled direct information use of density which directly impacts fitness. We show that immigrant-dependent dispersal evolves and does so even when density dependent information is available. Use of two sources of information also provides benefits at the metapopulation level by reducing extinction risk and prolonging the persistence of populations. Our results suggest that use of indirect information in dispersal can evolve under conservative conditions and thus could be widespread.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Chaine","given":"Alexis S."},{"family":"Legendre","given":"Stéphane"},{"family":"Clobert","given":"Jean"}],"container-title":"PeerJ","container-title-short":"PeerJ","DOI":"10.7717/peerj.44","ISSN":"2167-8359","issued":{"date-parts":[[2013,2,26]]},"language":"en","page":"e44","publisher":"PeerJ Inc.","source":"peerj.com","title":"The co-evolution of multiply-informed dispersal: information transfer across landscapes from neighbors and immigrants","title-short":"The co-evolution of multiply-informed dispersal","type":"article-journal","URL":"https://peerj.com/articles/44","volume":"1"}, + {"id":"chaput-bardyConditionPhenotypeDependentDispersal2010","abstract":"Individual dispersal decisions may be affected by the internal state of the individual and the external information of its current environment. Here we estimated the influence of dispersal on survival and investigated if individual phenotype (sex and wing length) and environmental condition (conspecific density and sex-ratio) affected dispersal decisions in the banded damselfly, Calopteryx splendens. As suspected from the literature, we showed that the proportion of dispersing individuals was higher in females than in males. We also found negative-density dependent dispersal in both sexes and influence of sex-ratio on dispersal. Individuals moved less when sex-ratio was male biased. These results are consistent with a lek mating system where males aggregate in a place and hold mating territories. Contrary to our expectations, neither dispersal nor survival was affected by wing length. Nevertheless, mean adult survival was about 8% lower in dispersing individuals than in residents. This might reflect a mortality cost due to dispersal.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Chaput-Bardy","given":"Audrey"},{"family":"Grégoire","given":"Arnaud"},{"family":"Baguette","given":"Michel"},{"family":"Pagano","given":"Alain"},{"family":"Secondi","given":"Jean"}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0010694","ISSN":"1932-6203","issue":"5","issued":{"date-parts":[[2010,5,18]]},"language":"en","page":"e10694","publisher":"Public Library of Science","source":"PLoS Journals","title":"Condition and Phenotype-Dependent Dispersal in a Damselfly, Calopteryx splendens","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0010694","volume":"5"}, + {"id":"chardonIncorporatingLandscapeElements2003","abstract":"In spatial studies of populations, Euclidean distance is commonly used to measure the structural connectivity between habitat patches. The role of the matrix on patch connectivity is thereby ignored. However, the importance of the matrix for (dispersal) movement is increasingly being acknowledged. Our study compared the cost-distance measure with the Euclidean distance. The cost-distance is a simple GIS-calculated connectivity measure that incorporates the resistance of the landscape matrix to movement behaviour. We used presence-absence data from a field study on the Speckled wood butterfly in two Belgian landscapes. Logistic regression revealed that the cost-distance measure had a significantly better predictive power than the Euclidean distance. This result was consistent for all the six sets of different matrix resistance values. In our study the cost-distance proves to be a better connectivity measure than the Euclidean distance.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Chardon","given":"J. Paul"},{"family":"Adriaensen","given":"Frank"},{"family":"Matthysen","given":"Erik"}],"container-title":"Landscape Ecology","container-title-short":"Landscape Ecology","DOI":"10.1023/A:1026062530600","ISSN":"1572-9761","issue":"6","issued":{"date-parts":[[2003,9,1]]},"language":"en","page":"561-573","source":"Springer Link","title":"Incorporating landscape elements into a connectivity measure: a case study for the Speckled wood butterfly (Pararge aegeria L.)","title-short":"Incorporating landscape elements into a connectivity measure","type":"article-journal","URL":"https://doi.org/10.1023/A:1026062530600","volume":"18"}, + {"id":"chenRapidRangeShifts2011","abstract":"The distributions of many terrestrial organisms are currently shifting in latitude or elevation in response to changing climate. Using a meta-analysis, we estimated that the distributions of species have recently shifted to higher elevations at a median rate of 11.0 meters per decade, and to higher latitudes at a median rate of 16.9 kilometers per decade. These rates are approximately two and three times faster than previously reported. The distances moved by species are greatest in studies showing the highest levels of warming, with average latitudinal shifts being generally sufficient to track temperature changes. However, individual species vary greatly in their rates of change, suggesting that the range shift of each species depends on multiple internal species traits and external drivers of change. Rapid average shifts derive from a wide diversity of responses by individual species.\nA meta-analysis shows that species are shifting their distributions in response to climate change at an accelerating rate.\nA meta-analysis shows that species are shifting their distributions in response to climate change at an accelerating rate.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Chen","given":"I.-Ching"},{"family":"Hill","given":"Jane K."},{"family":"Ohlemüller","given":"Ralf"},{"family":"Roy","given":"David B."},{"family":"Thomas","given":"Chris D."}],"container-title":"Science","DOI":"10.1126/science.1206432","ISSN":"0036-8075, 1095-9203","issue":"6045","issued":{"date-parts":[[2011,8,19]]},"language":"en","page":"1024-1026","PMID":"21852500","publisher":"American Association for the Advancement of Science","section":"Report","source":"science.sciencemag.org","title":"Rapid Range Shifts of Species Associated with High Levels of Climate Warming","type":"article-journal","URL":"https://science.sciencemag.org/content/333/6045/1024","volume":"333"}, + {"id":"chipperfieldUpdatedAlgorithmGeneration2011","abstract":"Background Patterns that arise from an ecological process can be driven as much from the landscape over which the process is run as it is by some intrinsic properties of the process itself. The disentanglement of these effects is aided if it possible to run models of the process over artificial landscapes with controllable spatial properties. A number of different methods for the generation of so-called ‘neutral landscapes’ have been developed to provide just such a tool. Of these methods, a particular class that simulate fractional Brownian motion have shown particular promise. The existing methods of simulating fractional Brownian motion suffer from a number of problems however: they are often not easily generalisable to an arbitrary number of dimensions and produce outputs that can exhibit some undesirable artefacts. Methodology We describe here an updated algorithm for the generation of neutral landscapes by fractional Brownian motion that do not display such undesirable properties. Using Monte Carlo simulation we assess the anisotropic properties of landscapes generated using the new algorithm described in this paper and compare it against a popular benchmark algorithm. Conclusion/Significance The results show that the existing algorithm creates landscapes with values strongly correlated in the diagonal direction and that the new algorithm presented here corrects this artefact. A number of extensions of the algorithm described here are also highlighted: we describe how the algorithm can be employed to generate landscapes that display different properties in different dimensions and how they can be combined with an environmental gradient to produce landscapes that combine environmental variation at the local and macro scales.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Chipperfield","given":"Joseph D."},{"family":"Dytham","given":"Calvin"},{"family":"Hovestadt","given":"Thomas"}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0017040","ISSN":"1932-6203","issue":"2","issued":{"date-parts":[[2011,2,15]]},"language":"en","page":"e17040","publisher":"Public Library of Science","source":"PLoS Journals","title":"An Updated Algorithm for the Generation of Neutral Landscapes by Spectral Synthesis","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0017040","volume":"6"}, + {"id":"clarkInvasionExtremesPopulation2001","abstract":"For populations having dispersal described by fat-tailed kernels (kernels with tails that are not exponentially bounded), asymptotic population spread rates cannot be estimated by traditional models because these models predict continually accelerating (asymptotically infinite) invasion. The impossible predictions come from the fact that the fat-tailed kernels fitted to dispersal data have a quality (nondiscrete individuals and, thus, no moment-generating function) that never applies to data. Real organisms produce finite (and random) numbers of offspring; thus, an empirical moment-generating function can always be determined. Using an alternative method to estimate spread rates in terms of extreme dispersal events, we show that finite estimates can be derived for fat-tailed kernels, and we demonstrate how variable reproduction modifies these rates. Whereas the traditional models define spread rate as the speed of an advancing front describing the expected density of individuals, our alternative definition for spread rate is the expected velocity for the location of the furthest-forward individual in the population. The asymptotic wave speed for a constant net reproductive rate R0 is approximated as (1/T)(piuR)/2)(1/2) m yr(-1), where T is generation time, and u is a distance parameter (m2) of Clark et al.'s 2Dt model having shape parameter p = 1. From fitted dispersal kernels with fat tails and infinite variance, we derive finite rates of spread and a simple method for numerical estimation. Fitted kernels, with infinite variance, yield distributions of rates of spread that are asymptotically normal and, thus, have finite moments. Variable reproduction can profoundly affect rates of spread. By incorporating the variance in reproduction that results from variable life span, we estimate much lower rates than predicted by the standard approach, which assumes a constant net reproductive rate. Using basic life-history data for trees, we show these estimated rates to be lower than expected from previous analytical models and as interpreted from paleorecords of forest spread at the end of the Pleistocene. Our results suggest reexamination of past rates of spread and the potential for future response to climate change.","author":[{"family":"Clark","given":"J. S."},{"family":"Lewis","given":"M."},{"family":"Horvath","given":"L."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/319934","ISSN":"1537-5323","issue":"5","issued":{"date-parts":[[2001,5]]},"language":"eng","page":"537-554","PMID":"18707261","source":"PubMed","title":"Invasion by extremes: population spread with variation in dispersal and reproduction","title-short":"Invasion by extremes","type":"article-journal","volume":"157"}, + {"id":"clarkReidParadoxRapid1998","abstract":"The oak, to gain its present most northerly position in North Britain after being driven out by the cold probably had to travel fully six hundred miles, and this without external aid would take something like a million years. (Reid 1899)","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Clark","given":"James S."},{"family":"Fastie","given":"Chris"},{"family":"Hurtt","given":"George"},{"family":"Jackson","given":"Stephen T."},{"family":"Johnson","given":"Carter"},{"family":"King","given":"George A."},{"family":"Lewis","given":"Mark"},{"family":"Lynch","given":"Jason"},{"family":"Pacala","given":"Stephen"},{"family":"Prentice","given":"Colin"},{"family":"Schupp","given":"Eugene W."},{"family":"Webb","given":"Thompson","suffix":"III"},{"family":"Wyckoff","given":"Peter"}],"container-title":"BioScience","container-title-short":"BioScience","DOI":"10.2307/1313224","ISSN":"0006-3568","issue":"1","issued":{"date-parts":[[1998,1,1]]},"page":"13-24","source":"Silverchair","title":"Reid's Paradox of Rapid Plant Migration: Dispersal theory and interpretation of paleoecological records","title-short":"Reid's Paradox of Rapid Plant Migration","type":"article-journal","URL":"https://doi.org/10.2307/1313224","volume":"48"}, + {"id":"clobertDispersal2001","abstract":"The ability of species to migrate that has interested ecologists for many years. Now that so many species and ecosystems face major environmental change, the ability of species to adapt to these changes by dispersing, migrating, or moving between different patches of habitat can be crucial to ensuring their survivial. This book provides a timely and wide-ranging overview of the study of dispersal and incorporates much of the latest research. The causes, mechanisms, and consequences of dispersal at the individual, population, species and community levels are considered. The potential of new techniques and models for studying dispersal, drawn from molecular biology and demography, is also explored. Perspectives and insights are offered from the fields of evolution, conservation biology and genetics. Throughout the book, theoretical approaches are combined with empirical data, and care has been taken to include examples from as wide a range of species as possible.","editor":[{"family":"Clobert","given":"Jean"},{"family":"Danchin","given":"Etienne"},{"family":"Dhondt","given":"Andre A."},{"family":"Nichols","given":"James D."}],"event-place":"Oxford, New York","ISBN":"978-0-19-850659-1","issued":{"date-parts":[[2001,2,22]]},"number-of-pages":"480","publisher":"Oxford University Press","publisher-place":"Oxford, New York","source":"Oxford University Press","title":"Dispersal","type":"book"}, + {"id":"clobertDispersalEcologyEvolution2012a","abstract":"Now that so many ecosystems face rapid and major environmental change, the ability of species to respond to these changes by dispersing or moving between different patches of habitat can be crucial to ensuring their survival. Understanding dispersal has become key to understanding how populations may persist. This book provides an overview of the fast expanding field of dispersal ecology, incorporating the very latest research. The causes, mechanisms, and consequences of dispersal at the individual, population, species, and community levels are considered. Perspectives and insights are offered from the fields of evolution, behavioural ecology, conservation biology, and genetics. Throughout the book theoretical approaches are combined with empirical data, and care has been taken to include examples from as wide a range of species as possible — both plant and animal.","accessed":{"date-parts":[[2021,8,9]]},"DOI":"10.1093/acprof:oso/9780199608898.001.0001","editor":[{"family":"Clobert","given":"Jean"},{"family":"Baguette","given":"Michel"},{"family":"Benton","given":"Tim G."},{"family":"Bullock","given":"James M."}],"event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","number-of-pages":"496","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Dispersal Ecology and Evolution","type":"book","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898"}, + {"id":"clobertInformedDispersalHeterogeneity2009","abstract":"There is accumulating evidence that individuals leave their natal area and select a breeding habitat non-randomly by relying upon information about their natal and future breeding environments. This variation in dispersal is not only based on external information (condition dependence) but also depends upon the internal state of individuals (phenotype dependence). As a consequence, not all dispersers are of the same quality or search for the same habitats. In addition, the individual's state is characterized by morphological, physiological or behavioural attributes that might themselves serve as a cue altering the habitat choice of conspecifics. These combined effects of internal and external information have the potential to generate complex movement patterns and could influence population dynamics and colonization processes. Here, we highlight three particular processes that link condition-dependent dispersal, phenotype-dependent dispersal and habitat choice strategies: (1) the relationship between the cause of departure and the dispersers' phenotype; (2) the relationship between the cause of departure and the settlement behaviour and (3) the concept of informed dispersal, where individuals gather and transfer information before and during their movements through the landscape. We review the empirical evidence for these processes with a special emphasis on vertebrate and arthropod model systems, and present case studies that have quantified the impacts of these processes on spatially structured population dynamics. We also discuss recent literature providing strong evidence that individual variation in dispersal has an important impact on both reinforcement and colonization success and therefore must be taken into account when predicting ecological responses to global warming and habitat fragmentation.","author":[{"family":"Clobert","given":"Jean"},{"family":"Le Galliard","given":"Jean-François"},{"family":"Cote","given":"Julien"},{"family":"Meylan","given":"Sandrine"},{"family":"Massot","given":"Manuel"}],"container-title":"Ecology Letters","container-title-short":"Ecol Lett","DOI":"10.1111/j.1461-0248.2008.01267.x","ISSN":"1461-0248","issue":"3","issued":{"date-parts":[[2009,3]]},"language":"eng","page":"197-209","PMID":"19170731","source":"PubMed","title":"Informed dispersal, heterogeneity in animal dispersal syndromes and the dynamics of spatially structured populations","type":"article-journal","volume":"12"}, + {"id":"clotucheSettlementDecisionsTwospotted2013","abstract":"In silk-spinning arthropods, silk can be used for web building, protection, and communication. Silk is an informative material about the presence of conspecifics. It can therefore inform on habitat suitability and hence assist in habitat choice. In this context, we investigated the influence of silk on microhabitat choice by the two-spotted spider mite, Tetranychus urticae. Three factors that could potentially influence habitat choice were manipulated: the strain, number, and the stage of mites. Our study showed that these factors all influence the choice of microhabitat. The tendency of whether to settle on a silk-covered area was influenced by the origin of mites (strain effect). Adult females showed a higher tendency to settle on an area covered with the silk laid by numerous congeners (number effect). Moreover, larvae seemed to be more responsive to the presence of silk than adults (stage effect). This suggests that individuals use silk as a social cue in selecting their microhabitat and that the spatial organization and group behaviour seem to be shaped by the individuals’ response to social cues, such as the amount of silk already present.\nRésumé\nChez les arthropodes tisseurs, la soie peut être utilisée pour la construction, la protection et la communication. La soie peut également informer de la présence de congénères. Elle peut renseigner sur la qualité d’un habitat et donc aider les individus lors du choix d’établissement. Dans ce contexte, nous avons étudié l’influence de la soie lors de la sélection d’un micro-habitat chez l’acarien tisserand, Tetranychus urticae. Trois facteurs ont été manipulés : la souche, le nombre et le stade des acariens. Notre étude montre que ces facteurs influencent le choix du micro-habitat. La tendance à s’installer sur une zone couverte de soie diffère en fonction de l’origine des acariens. Les femelles adultes montrent une plus forte tendance à s’installer sur une zone couverte de soie tissée par de nombreux congénères. Les larves semblent plus sensibles que les adultes à la présence de soie. La soie est utilisée comme indice social pour choisir le micro-habitat et, dès lors, l’organisation spatiale et l’agrégation de cet acarien semblent être façonnées par la réponse des individus à des signaux sociaux tels que la quantité de soie.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Clotuche","given":"Gwendoline"},{"family":"Mailleux","given":"Anne-Catherine"},{"family":"Yano","given":"Shuichi"},{"family":"Detrain","given":"Claire"},{"family":"Deneubourg","given":"Jean-Louis"},{"family":"Hance","given":"Thierry"}],"container-title":"Comptes Rendus Biologies","container-title-short":"Comptes Rendus Biologies","DOI":"10.1016/j.crvi.2013.02.006","ISSN":"1631-0691","issue":"2","issued":{"date-parts":[[2013,2,1]]},"language":"en","page":"93-101","source":"ScienceDirect","title":"Settlement decisions by the two-spotted spider mite Tetranychus urticae","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S1631069113000139","volume":"336"}, + {"id":"codlingRandomWalkModels2008","abstract":"Mathematical modelling of the movement of animals, micro-organisms and cells is of great relevance in the fields of biology, ecology and medicine. Movement models can take many different forms, but the most widely used are based on the extensions of simple random walk processes. In this review paper, our aim is twofold: to introduce the mathematics behind random walks in a straightforward manner and to explain how such models can be used to aid our understanding of biological processes. We introduce the mathematical theory behind the simple random walk and explain how this relates to Brownian motion and diffusive processes in general. We demonstrate how these simple models can be extended to include drift and waiting times or be used to calculate first passage times. We discuss biased random walks and show how hyperbolic models can be used to generate correlated random walks. We cover two main applications of the random walk model. Firstly, we review models and results relating to the movement, dispersal and population redistribution of animals and micro-organisms. This includes direct calculation of mean squared displacement, mean dispersal distance, tortuosity measures, as well as possible limitations of these model approaches. Secondly, oriented movement and chemotaxis models are reviewed. General hyperbolic models based on the linear transport equation are introduced and we show how a reinforced random walk can be used to model movement where the individual changes its environment. We discuss the applications of these models in the context of cell migration leading to blood vessel growth (angiogenesis). Finally, we discuss how the various random walk models and approaches are related and the connections that underpin many of the key processes involved.","author":[{"family":"Codling","given":"Edward A."},{"family":"Plank","given":"Michael J."},{"family":"Benhamou","given":"Simon"}],"container-title":"Journal of the Royal Society, Interface","container-title-short":"J R Soc Interface","DOI":"10.1098/rsif.2008.0014","ISSN":"1742-5689","issue":"25","issued":{"date-parts":[[2008,8,6]]},"language":"eng","page":"813-834","PMCID":"PMC2504494","PMID":"18426776","source":"PubMed","title":"Random walk models in biology","type":"article-journal","volume":"5"}, + {"id":"cominsEvolutionarilyStableDispersal1980","abstract":"Using the idea that life-history parameters are subject to natural selection and should approach values that are stable optima, with the population immune to invasion by mutant individuals, we derive an analytic expression for the evolutionarily stable dispersal rate in a stochastic island model with random site extinction. The results provide interesting contrasts between three different optimization criteria: species survival, individual fitness and gene fitness. We also consider the effects of sexual reproduction, and of localized migration (stepping-stone structure).","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Comins","given":"Hugh N."},{"family":"Hamilton","given":"William D."},{"family":"May","given":"Robert M."}],"container-title":"Journal of Theoretical Biology","container-title-short":"Journal of Theoretical Biology","DOI":"10.1016/0022-5193(80)90099-5","ISSN":"0022-5193","issue":"2","issued":{"date-parts":[[1980,1,21]]},"language":"en","page":"205-230","source":"ScienceDirect","title":"Evolutionarily stable dispersal strategies","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/0022519380900995","volume":"82"}, + {"id":"conliskUncertaintyAssessingImpacts2013","abstract":"Concern over rapid global changes and the potential for interactions among multiple threats are prompting scientists to combine multiple modelling approaches to understand impacts on biodiversity. A relatively recent development is the combination of species distribution models, land-use change predictions, and dynamic population models to predict the relative and combined impacts of climate change, land-use change, and altered disturbance regimes on species' extinction risk. Each modelling component introduces its own source of uncertainty through different parameters and assumptions, which, when combined, can result in compounded uncertainty that can have major implications for management. Although some uncertainty analyses have been conducted separately on various model components - such as climate predictions, species distribution models, land-use change predictions, and population models - a unified sensitivity analysis comparing various sources of uncertainty in combined modelling approaches is needed to identify the most influential and problematic assumptions. We estimated the sensitivities of long-run population predictions to different ecological assumptions and parameter settings for a rare and endangered annual plant species (Acanthomintha ilicifolia, or San Diego thornmint). Uncertainty about habitat suitability predictions, due to the choice of species distribution model, contributed most to variation in predictions about long-run populations.","author":[{"family":"Conlisk","given":"Erin"},{"family":"Syphard","given":"Alexandra D."},{"family":"Franklin","given":"Janet"},{"family":"Flint","given":"Lorraine"},{"family":"Flint","given":"Alan"},{"family":"Regan","given":"Helen"}],"container-title":"Global Change Biology","container-title-short":"Glob Chang Biol","DOI":"10.1111/gcb.12090","ISSN":"1354-1013","issue":"3","issued":{"date-parts":[[2013,3]]},"language":"eng","page":"858-869","PMID":"23504842","source":"PubMed","title":"Uncertainty in assessing the impacts of global change with coupled dynamic species distribution and population models","type":"article-journal","volume":"19"}, + {"id":"coteSocialInformationEmigration2007","abstract":"'Should I stay or should I go?' is a fundamental question facing any candidate for emigration, as emigrating without outside information has major costs. Most studies on this topic have concentrated on risk-reducing strategies (e.g. exploration) developed after leaving the natal habitat. The idea that information might be acquired before leaving has not been investigated. Immigrants carrying information about their origins could provide such information to potential emigrants in their initial habitat. We manipulated the density of common lizard (Lacerta vivipara) populations, to investigate whether immigrants originating from these populations transmitted such information to the population they joined. Emigration of the residents of this new population clearly depended on the origin of the immigrant. Immigrants are therefore a source of information, in this case about surrounding population densities, and may have a major effect on dispersal and species persistence in a fragmented habitat.","author":[{"family":"Cote","given":"J."},{"family":"Clobert","given":"J."}],"container-title":"Ecology Letters","container-title-short":"Ecol Lett","DOI":"10.1111/j.1461-0248.2007.01032.x","ISSN":"1461-0248","issue":"5","issued":{"date-parts":[[2007,5]]},"language":"eng","page":"411-417","PMID":"17498140","source":"PubMed","title":"Social information and emigration: lessons from immigrants","title-short":"Social information and emigration","type":"article-journal","volume":"10"}, + {"id":"cottoNemoageSpatiallyExplicit2020","abstract":"Anticipating and preparing for the effect of environmental changes on biodiversity requires to understand and predict both the ecological and evolutionary responses of populations. Tools and methods to efficiently integrate these complex processes are lacking. We present the genetically and spatially explicit individual-based simulation software Nemo-age combining ecological and evolutionary processes. Nemo-age has a strong emphasis on modelling complex life histories. We here provide a methodology to predict changes in species distribution for given climate projections using Nemo-age. Modelling complex life histories, spatial distribution and evolutionary processes unravel possible eco-evolutionary mechanisms that have been previously overlooked when populations endure rapid environmental changes. The interface of Nemo-age is designed to integrate species' data from different fields, from demography to genetic architecture and spatial distributions, thus representing a versatile tool to model a variety of applied and theoretical scenarios.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Cotto","given":"Olivier"},{"family":"Schmid","given":"Max"},{"family":"Guillaume","given":"Frédéric"}],"container-title":"Methods in Ecology and Evolution","DOI":"10.1111/2041-210X.13460","ISSN":"2041-210X","issue":"10","issued":{"date-parts":[[2020]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/2041-210X.13460","page":"1227-1236","source":"Wiley Online Library","title":"Nemo-age: Spatially explicit simulations of eco-evolutionary dynamics in stage-structured populations under changing environments","title-short":"Nemo-age","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.13460","volume":"11"}, + {"id":"coulsonEstimatingFunctionalForm2008","abstract":"Two contrasting approaches to the analysis of population dynamics are currently popular: demographic approaches where the associations between demographic rates and statistics summarizing the population dynamics are identified; and time series approaches where the associations between population dynamics, population density, and environmental covariates are investigated. In this paper, we develop an approach to combine these methods and apply it to detailed data from Soay sheep (Ovis aries). We examine how density dependence and climate contribute to fluctuations in population size via age- and sex-specific demographic rates, and how fluctuations in demographic structure influence population dynamics. Density dependence contributes most, followed by climatic variation, age structure fluctuations and interactions between density and climate. We then simplify the density-dependent, stochastic, age-structured demographic model and derive a new phenomenological time series which captures the dynamics better than previously selected functions. The simple method we develop has potential to provide substantial insight into the relative contributions of population and individual-level processes to the dynamics of populations in stochastic environments.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Coulson","given":"T."},{"family":"Ezard","given":"T. H. G."},{"family":"Pelletier","given":"F."},{"family":"Tavecchia","given":"G."},{"family":"Stenseth","given":"N. C."},{"family":"Childs","given":"D. Z."},{"family":"Pilkington","given":"J. G."},{"family":"Pemberton","given":"J. M."},{"family":"Kruuk","given":"L. E. B."},{"family":"Clutton-Brock","given":"T. H."},{"family":"Crawley","given":"M. J."}],"container-title":"Ecology","ISSN":"0012-9658","issue":"6","issued":{"date-parts":[[2008]]},"page":"1661-1674","publisher":"Ecological Society of America","source":"JSTOR","title":"Estimating the Functional Form for the Density Dependence from Life History Data","type":"article-journal","URL":"https://www.jstor.org/stable/27650672","volume":"89"}, + {"id":"coumouDecadeWeatherExtremes2012","abstract":"The ostensibly large number of recent extreme weather events has triggered intensive discussions, both in- and outside the scientific community, on whether they are related to global warming. Here, we review the evidence and argue that for some types of extreme — notably heatwaves, but also precipitation extremes — there is now strong evidence linking specific events or an increase in their numbers to the human influence on climate. For other types of extreme, such as storms, the available evidence is less conclusive, but based on observed trends and basic physical concepts it is nevertheless plausible to expect an increase.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Coumou","given":"Dim"},{"family":"Rahmstorf","given":"Stefan"}],"container-title":"Nature Climate Change","container-title-short":"Nature Clim Change","DOI":"10.1038/nclimate1452","ISSN":"1758-6798","issue":"7","issued":{"date-parts":[[2012,7]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Reviews\nSubject_term: Climate change;Climate-change impacts\nSubject_term_id: climate-change;climate-change-impacts","number":"7","page":"491-496","publisher":"Nature Publishing Group","source":"www.nature.com","title":"A decade of weather extremes","type":"article-journal","URL":"https://www.nature.com/articles/nclimate1452","volume":"2"}, + {"id":"davisRangeShiftsAdaptive2001","abstract":"Tree taxa shifted latitude or elevation range in response to changes in Quaternary climate. Because many modern trees display adaptive differentiation in relation to latitude or elevation, it is likely that ancient trees were also so differentiated, with environmental sensitivities of populations throughout the range evolving in conjunction with migrations. Rapid climate changes challenge this process by imposing stronger selection and by distancing populations from environments to which they are adapted. The unprecedented rates of climate changes anticipated to occur in the future, coupled with land use changes that impede gene flow, can be expected to disrupt the interplay of adaptation and migration, likely affecting productivity and threatening the persistence of many species.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Davis","given":"Margaret B."},{"family":"Shaw","given":"Ruth G."}],"container-title":"Science","DOI":"10.1126/science.292.5517.673","ISSN":"0036-8075, 1095-9203","issue":"5517","issued":{"date-parts":[[2001,4,27]]},"language":"en","page":"673-679","PMID":"11326089","publisher":"American Association for the Advancement of Science","section":"Special Reviews","source":"science.sciencemag.org","title":"Range Shifts and Adaptive Responses to Quaternary Climate Change","type":"article-journal","URL":"https://science.sciencemag.org/content/292/5517/673","volume":"292"}, + {"id":"dawsonPredictionsBiodiversityConservation2011","abstract":"Climate change is predicted to become a major threat to biodiversity in the 21st century, but accurate predictions and effective solutions have proved difficult to formulate. Alarming predictions have come from a rather narrow methodological base, but a new, integrated science of climate-change biodiversity assessment is emerging, based on multiple sources and approaches. Drawing on evidence from paleoecological observations, recent phenological and microevolutionary responses, experiments, and computational models, we review the insights that different approaches bring to anticipating and managing the biodiversity consequences of climate change, including the extent of species’ natural resilience. We introduce a framework that uses information from different sources to identify vulnerability and to support the design of conservation responses. Although much of the information reviewed is on species, our framework and conclusions are also applicable to ecosystems, habitats, ecological communities, and genetic diversity, whether terrestrial, marine, or fresh water.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dawson","given":"Terence P."},{"family":"Jackson","given":"Stephen T."},{"family":"House","given":"Joanna I."},{"family":"Prentice","given":"Iain Colin"},{"family":"Mace","given":"Georgina M."}],"container-title":"Science","DOI":"10.1126/science.1200303","ISSN":"0036-8075, 1095-9203","issue":"6025","issued":{"date-parts":[[2011,4,1]]},"language":"en","page":"53-58","PMID":"21454781","publisher":"American Association for the Advancement of Science","section":"Review","source":"science.sciencemag.org","title":"Beyond Predictions: Biodiversity Conservation in a Changing Climate","title-short":"Beyond Predictions","type":"article-journal","URL":"https://science.sciencemag.org/content/332/6025/53","volume":"332"}, + {"id":"deblockLocalGeneticAdaptation2013","abstract":"Temperature effects on predator-prey interactions are fundamental to better understand the effects of global warming. Previous studies never considered local adaptation of both predators and prey at different latitudes, and ignored the novel population combinations of the same predator-prey species system that may arise because of northward dispersal. We set up a common garden warming experiment to study predator-prey interactions between Ischnura elegans damselfly predators and Daphnia magna zooplankton prey from three source latitudes spanning >1500 km. Damselfly foraging rates showed thermal plasticity and strong latitudinal differences consistent with adaptation to local time constraints. Relative survival was higher at 24 °C than at 20 °C in southern Daphnia and higher at 20 °C than at 24 °C, in northern Daphnia indicating local thermal adaptation of the Daphnia prey. Yet, this thermal advantage disappeared when they were confronted with the damselfly predators of the same latitude, reflecting also a signal of local thermal adaptation in the damselfly predators. Our results further suggest the invasion success of northward moving predators as well as prey to be latitude-specific. We advocate the novel common garden experimental approach using predators and prey obtained from natural temperature gradients spanning the predicted temperature increase in the northern populations as a powerful approach to gain mechanistic insights into how community modules will be affected by global warming. It can be used as a space-for-time substitution to inform how predator-prey interaction may gradually evolve to long-term warming.","author":[{"family":"De Block","given":"Marjan"},{"family":"Pauwels","given":"Kevin"},{"family":"Van Den Broeck","given":"Maarten"},{"family":"De Meester","given":"Luc"},{"family":"Stoks","given":"Robby"}],"container-title":"Global Change Biology","container-title-short":"Glob Chang Biol","DOI":"10.1111/gcb.12089","ISSN":"1354-1013","issue":"3","issued":{"date-parts":[[2013,3]]},"language":"eng","page":"689-696","PMID":"23504827","source":"PubMed","title":"Local genetic adaptation generates latitude-specific effects of warming on predator-prey interactions","type":"article-journal","volume":"19"}, + {"id":"delattreDispersalMoodRevealed2010","abstract":"A comprehensive mechanistic approach to dispersal requires the translation of the whole mobility register of the target organism into movement rules that could subsequently be used to model its displacements. According to the optimality paradigm, this procedure implies a cost – benefi t analysis of mobility patterns taking into account not only movements, but also their external context and the internal state of the moving individuals. Using this framework, we detected a ‘dispersal mood' in some individuals of the meadow brown butterfly Maniola jurtina. These adopted a direct flight strategy, which was topologically different from the previously documented foray search strategy. Those individuals that used the direct flight strategy moved straighter as soon as they left the habitat and avoided heading back to their patch of origin, which is the best inter-patch search strategy when dispersal risks and costs are high. The direct flight strategy was conditional to sex: females used it twice as much as males. We suggest that this sex bias was due to female investment in off spring, which is maximized by male avoidance and spatial bet hedging. Inter-patch dispersal of gravid females is crucial for the persistence of M. jurtina populations in spatially and temporally unpredictable environments.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Delattre","given":"Thomas"},{"family":"Burel","given":"Francoise"},{"family":"Humeau","given":"Antoine"},{"family":"Stevens","given":"Virginie Marie"},{"family":"Vernon","given":"Philippe"},{"family":"Baguette","given":"Michel"}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2010.18615.x","issue":"12","issued":{"date-parts":[[2010]]},"page":"1900-1908","publisher":"Nordic Ecological Society","source":"HAL Archives Ouvertes","title":"Dispersal mood revealed by shifts from routine to direct flights in the meadow brown butterfly Maniola jurtina.","type":"article-journal","URL":"https://hal.archives-ouvertes.fr/hal-00557623","volume":"119"}, + {"id":"delgadoEffectPhenotypicTraits2010","abstract":"1. Natal dispersal has the potential to affect most ecological and evolutionary processes. However, despite its importance, this complex ecological process still represents a significant gap in our understanding of animal ecology due to both the lack of empirical data and the intrinsic complexity of dispersal dynamics. 2. By studying natal dispersal of 74 radiotagged juvenile eagle owls Bubo bubo (Linnaeus), in both the wandering and the settlement phases, we empirically addressed the complex interactions by which individual phenotypic traits and external cues jointly shape individual heterogeneity through the different phases of dispersal, both at nightly and weekly temporal scales. 3. Owls in poorer physical conditions travelled shorter total distances during the wandering phase, describing straighter paths and moving slower, especially when crossing heterogeneous habitats. In general, the owls in worse condition started dispersal later and took longer times to find further settlement areas. Net distances were also sex biased, with females settling at further distances. Dispersing individuals did not seem to explore wandering and settlement areas by using a search image of their natal surroundings. Eagle owls showed a heterogeneous pattern of patch occupancy, where few patches were highly visited by different owls whereas the majority were visited by just one individual. During dispersal, the routes followed by owls were an intermediate solution between optimized and randomized ones. Finally, dispersal direction had a marked directionality, largely influenced by dominant winds. These results suggest an asymmetric and anisotropic dispersal pattern, where not only the number of patches but also their functions can affect population viability. 4. The combination of the information coming from the relationships among a large set of factors acting and integrating at different spatial and temporal scales, under the perspective of heterogeneous life histories, are a fruitful ground for future understanding of natal dispersal.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Delgado","given":"María del Mar"},{"family":"Penteriani","given":"Vincenzo"},{"family":"Revilla","given":"Eloy"},{"family":"Nams","given":"Vilis O."}],"container-title":"Journal of Animal Ecology","DOI":"10.1111/j.1365-2656.2009.01655.x","ISSN":"1365-2656","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2656.2009.01655.x","page":"620-632","source":"Wiley Online Library","title":"The effect of phenotypic traits and external cues on natal dispersal movements","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2656.2009.01655.x","volume":"79"}, + {"id":"demeesterInformationUseDensitydependent2010","abstract":"Density of conspecifics is considered as one of the main conditions affecting dispersal behavior and leading to a stabilization of population dynamics. Density-dependent dispersal can be induced by local competition at different phases during development and/or by density-related sources of social information. Here, we assessed the importance of population density on emigration rates and the degree to which the presence of silk threads at dispersal takeoff locations affects immediate dispersal decision making in the spider Erigone atra. By quantifying behaviors in wind tunnels under standardized laboratory conditions, silk-assisted long- and short-distance dispersal is quantified before the actual onset of the dispersal event.Increased densities during juvenile development only affected short-distance dispersal behavior. In females, short-distance dispersal increased with the female density experienced during development, whereas responses in males increased under combined high male/low female-experienced densities. Elevated densities at the onset of dispersal led to a general increase of predispersal behaviors. The presence of silk threads at takeoff platforms similarly induced an increase of dispersal displays, with specifically an increase in long-distance dispersal in both sexes.Our results demonstrate that the spider E. atra uses information related to density during development, most probably to avoid competition by performing short-distance dispersal. In contrast, density-related cues at the time of dispersal (i.e., increased densities and the presence of silk threads) increase general dispersal activities and long-distance ballooning events. Short- and long-distance dispersal strategies are consequently guided by differential density-related information use.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"De Meester","given":"Nele"},{"family":"Bonte","given":"Dries"}],"container-title":"Behavioral Ecology","container-title-short":"Behavioral Ecology","DOI":"10.1093/beheco/arq088","ISSN":"1045-2249","issue":"5","issued":{"date-parts":[[2010,9,1]]},"page":"992-998","source":"Silverchair","title":"Information use and density-dependent emigration in an agrobiont spider","type":"article-journal","URL":"https://doi.org/10.1093/beheco/arq088","volume":"21"}, + {"id":"dennoHabitatPersistenceUnderlies1996","abstract":"Dispersal is considered a vital life history characteristic for insects exploiting temporary habitats, and life history theorists have often hypothesized an inverse relationship between dispersal capability and habitat persistence. Most often, this hypothesis has been tested using interspecific comparisons of dispersal capability and qualitative estimates of habitat persistence. Consequently, most assessments have failed to control for possible phylogenetic nonindependence and they also lack quantitative rigor. We capitalized on existing intraspecific variation in the dispersal capability of Prokelisia planthoppers to examine the relationship between habitat persistence and dispersal, thereby minimizing possible phylogenetic effects. Two congeneric species (Prokelisia marginata and P. dolus) occur in the intertidal marshes of North America, where they feed exclusively on cordgrasses (Spartina). Because these planthoppers exhibit wing dimorphism, flight-capable adults (macropters with fully developed wings) are easily differentiated from flightless adults (brachypters with reduced wings). Thus, dispersal capability can be readily estimated by the percentage of macropters in a population. At a regional spatial scale, we found a highly significant negative relationship between dispersal capability (percent macroptery) and habitat persistence. In this system, habitat persistence is influenced by a combination of marsh elevation, winter severity, and tidal range, which interact to determine the ability of planthoppers to endure through winter in their primary habitat for development. P. marginata develops primarily in low-marsh habitats during summer, habitats that can be subjected to pronounced winter disturbance due to ice scouring and/or extensive tidal inundation. Levels of winter disturbance of the low marsh are extreme along the Atlantic coast, intermediate along the Pacific, and low along the Gulf. Both the failure of P. marginata populations to remain through winter in this habitat, and the dispersal ability of these populations (92%, 29%, and 17% macroptery, respectively), are correlated with levels of disturbance. Thus, in regions where winter disturbance is high, levels of dispersal are correspondingly high to allow for recolonization of extirpated habitats from overwintering sites on the high marsh. Unlike P. marginata, P. dolus develops primarily in high-marsh habitats, which are much less disturbed on all coasts during winter. Consequently, this species remains year-round in its primary habitat for development, and most populations exhibit relatively low levels of macroptery (<10%). When raised under common garden conditions, many more macropters of both species were produced from Atlantic compared to Gulf populations. Thus the proportion of macropters produced from the populations used in this experiment paralleled the incidence of macroptery measured in the field, providing evidence that the geographic variation in dispersal capability in both species has in part a genetic basis. The results of this study provide strong intraspecific evidence for an inverse relationship between the dispersal capability of insects and the persistence of their habitats.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Denno","given":"Robert F."},{"family":"Roderick","given":"George K."},{"family":"Peterson","given":"Merrill A."},{"family":"Huberty","given":"Andrea F."},{"family":"Dobel","given":"Hartmut G."},{"family":"Eubanks","given":"Micky D."},{"family":"Losey","given":"John E."},{"family":"Langellotto","given":"Gail A."}],"container-title":"Ecological Monographs","DOI":"10.2307/2963487","ISSN":"0012-9615","issue":"4","issued":{"date-parts":[[1996]]},"page":"389-408","publisher":"Ecological Society of America","source":"JSTOR","title":"Habitat Persistence Underlies Intraspecific Variation in the Dispersal Strategies of Planthoppers","type":"article-journal","URL":"https://www.jstor.org/stable/2963487","volume":"66"}, + {"id":"doerrConnectivityDispersalBehaviour2011a","abstract":"1. Hodgson et al. [Journal of Applied Ecology46 (2009) 964] argue that connectivity is complex and uncertain, that it can be improved incidentally by increasing habitat extent, and that connectivity conservation is unlikely to be effective under climate change. 2. We believe that they have overlooked recent research on dispersal behaviour and structural connectivity, which has improved our understanding of functional connectivity and revealed that it will not necessarily increase with habitat extent. 3. New modelling techniques including least-cost path models incorporate this more detailed understanding of connectivity into conservation planning, facilitating the true aim of connectivity conservation – to ensure appropriate interactions between habitat extent, quality and connectivity. 4. Synthesis and applications. Advances in behavioural research and modelling techniques allow us to manage structural connectivity with as much certainty as we manage extent and quality of habitat. Successful landscape conservation to address both current threats and future climate change must manage these three elements in concert.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Doerr","given":"Veronica A. J."},{"family":"Barrett","given":"Tom"},{"family":"Doerr","given":"Erik D."}],"container-title":"Journal of Applied Ecology","DOI":"10.1111/j.1365-2664.2010.01899.x","ISSN":"1365-2664","issue":"1","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2664.2010.01899.x","page":"143-147","source":"Wiley Online Library","title":"Connectivity, dispersal behaviour and conservation under climate change: a response to Hodgson et al.","title-short":"Connectivity, dispersal behaviour and conservation under climate change","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2664.2010.01899.x","volume":"48"}, + {"id":"doligezAvailabilityUsePublic2004","abstract":"1. Public information, i.e. local reproductive performance of conspecifics, is expected to be a highly valuable cue for breeding habitat selection. However, the access to this cue may be spatially and temporally constrained. When public information is unavailable, individuals may use other integrative cues, such as the local density of breeders. 2. Departure decisions of collared flycatchers (Ficedula albicollis) were shown previously to be related to both public information and breeding density, in a long-term correlative study of a fragmented population. Here, we tested whether flycatchers also use public information (number and condition of fledglings produced locally) and breeding density to make individual settlement decisions in the following year. 3. Immigration rates were computed to measure the degree of attractiveness of patches to new breeders. We investigated the relative influence of public information and breeding density on immigration rates of yearlings and older adults separately. The access to public information for settlement decisions may indeed be more limited for yearlings. 4. Immigration rate in a patch increased with mean fledgling number in the previous year for older adults but not for yearlings. Yearling immigration rate was correlated positively to mean fledgling condition when patch breeding density in the previous year was low, but negatively when density was high. 5. Immigration rates of both yearlings and older adults increased with breeding density in the previous year. Breeding density explained a larger part of the variance in immigration rate than patch reproductive success. 6. The proportion of yearlings among breeders decreased with increasing patch reproductive success and breeding density in the previous year, suggesting that local competition was high in attractive patches. 7. Our results thus suggest that public information is also used for immigration decisions. However, decisions of yearlings are more complex than those of older adults, due to their more limited access to public information and the higher impact of intraspecific competition. Conversely, all individuals seemed to cue on breeding density in a similar way. Density is correlated to patch reproductive success, and may be a more easily accessible cue. We discuss the potential advantages of using conspecific density over conspecific reproductive performance for future immigration decisions.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Doligez","given":"Blandine"},{"family":"Pärt","given":"Tomas"},{"family":"Danchin","given":"Etienne"},{"family":"Clobert","given":"Jean"},{"family":"Gustafsson","given":"Lars"}],"container-title":"Journal of Animal Ecology","ISSN":"0021-8790","issue":"1","issued":{"date-parts":[[2004]]},"page":"75-87","publisher":"[Wiley, British Ecological Society]","source":"JSTOR","title":"Availability and Use of Public Information and Conspecific Density for Settlement Decisions in the Collared Flycatcher","type":"article-journal","URL":"https://www.jstor.org/stable/3505318","volume":"73"}, + {"id":"dormannCorrelationProcessSpecies2012","abstract":"Within the field of species distribution modelling an apparent dichotomy exists between process-based and correlative approaches, where the processes are explicit in the former and implicit in the latter. However, these intuitive distinctions can become blurred when comparing species distribution modelling approaches in more detail. In this review article, we contrast the extremes of the correlative–process spectrum of species distribution models with respect to core assumptions, model building and selection strategies, validation, uncertainties, common errors and the questions they are most suited to answer. The extremes of such approaches differ clearly in many aspects, such as model building approaches, parameter estimation strategies and transferability. However, they also share strengths and weaknesses. We show that claims of one approach being intrinsically superior to the other are misguided and that they ignore the process–correlation continuum as well as the domains of questions that each approach is addressing. Nonetheless, the application of process-based approaches to species distribution modelling lags far behind more correlative (process-implicit) methods and more research is required to explore their potential benefits. Critical issues for the employment of species distribution modelling approaches are given, together with a guideline for appropriate usage. We close with challenges for future development of process-explicit species distribution models and how they may complement current approaches to study species distributions.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dormann","given":"Carsten F."},{"family":"Schymanski","given":"Stanislaus J."},{"family":"Cabral","given":"Juliano"},{"family":"Chuine","given":"Isabelle"},{"family":"Graham","given":"Catherine"},{"family":"Hartig","given":"Florian"},{"family":"Kearney","given":"Michael"},{"family":"Morin","given":"Xavier"},{"family":"Römermann","given":"Christine"},{"family":"Schröder","given":"Boris"},{"family":"Singer","given":"Alexander"}],"container-title":"Journal of Biogeography","DOI":"10.1111/j.1365-2699.2011.02659.x","ISSN":"1365-2699","issue":"12","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2011.02659.x","page":"2119-2131","source":"Wiley Online Library","title":"Correlation and process in species distribution models: bridging a dichotomy","title-short":"Correlation and process in species distribution models","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2699.2011.02659.x","volume":"39"}, + {"id":"dormannEffectsIncorporatingSpatial2007","abstract":"Aim Spatial autocorrelation (SAC) in data, i.e. the higher similarity of closer samples, is a common phenomenon in ecology. SAC is starting to be considered in the analysis of species distribution data, and over the last 10 years several studies have incorporated SAC into statistical models (here termed ‘spatial models’). Here, I address the question of whether incorporating SAC affects estimates of model coefficients and inference from statistical models. Methods I review ecological studies that compare spatial and non-spatial models. Results In all cases coefficient estimates for environmental correlates of species distributions were affected by SAC, leading to a mis-estimation of on average c. 25%. Model fit was also improved by incorporating SAC. Main conclusions These biased estimates and incorrect model specifications have implications for predicting species occurrences under changing environmental conditions. Spatial models are therefore required to estimate correctly the effects of environmental drivers on species present distributions, for a statistically unbiased identification of the drivers of distribution, and hence for more accurate forecasts of future distributions.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dormann","given":"Carsten F."}],"container-title":"Global Ecology and Biogeography","DOI":"10.1111/j.1466-8238.2006.00279.x","ISSN":"1466-8238","issue":"2","issued":{"date-parts":[[2007]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-8238.2006.00279.x","page":"129-138","source":"Wiley Online Library","title":"Effects of incorporating spatial autocorrelation into the analysis of species distribution data","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1466-8238.2006.00279.x","volume":"16"}, + {"id":"doverInfluencesLandscapeStructure2009","abstract":"We review the literature on the influence of landscape structure on butterfly distribution and movement. We start by examining the definition of landscape commonly used in spatial ecology. Landscape-level processes are reviewed before focusing on the impact of the geometry and spatial arrangement of habitat patches on butterflies e.g. the nature of the matrix, patch size and shape, minimum area requirements, immigration and emigration, and temporal habitat dynamics. The role of landscape elements is reviewed in terms of corridors (and stepping-stones), barriers, nodes, environmental buffers, and prominent landmark features.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dover","given":"John"},{"family":"Settele","given":"Josef"}],"container-title":"Journal of Insect Conservation","container-title-short":"J Insect Conserv","DOI":"10.1007/s10841-008-9135-8","ISSN":"1572-9753","issue":"1","issued":{"date-parts":[[2009,2,1]]},"language":"en","page":"3-27","source":"Springer Link","title":"The influences of landscape structure on butterfly distribution and movement: a review","title-short":"The influences of landscape structure on butterfly distribution and movement","type":"article-journal","URL":"https://doi.org/10.1007/s10841-008-9135-8","volume":"13"}, + {"id":"driezenEvaluatingLeastcostModel2007","abstract":"Habitat fragmentation and habitat loss are widely recognized as major threats to biodiversity on a regional as well as on a global scale. To restrict its effects, ecological networks such as the trans-European network NATURA2000 are being developed based on the assumption that structural connections between habitat fragments lead to increased exchange through dispersal and a higher viability of (meta)populations. However, there is a great need for techniques that translate these networks and/or structural characteristics of landscapes into functional connectivity for specific organisms. Least-cost analysis has the capacities to fulfill these needs, but has never been validated against actual observations of dispersal paths. Here we present a method to validate the results of a least-cost analysis by comparing realized movement paths of hedgehogs in unfamiliar areas, obtained by radiotracking, with statistics on landscape-wide distribution of cost values. The degree of correspondence between empirical dispersal paths and the output of a least-cost analysis can be visualized and quantified, and least-cost scenarios can be statistically compared. We show that hedgehogs moved along paths with significantly lower cost values than the average landscape, implying that they took better than random routes, but performance was relatively poor. We attribute this to the relatively generalistic habitat use of the model species and the rather homogeneous landscapes. We conclude that this approach can be useful for further validation of the least-cost model and allows a direct comparison of model performance among different taxa and/or landscapes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Driezen","given":"Kassandra"},{"family":"Adriaensen","given":"Frank"},{"family":"Rondinini","given":"Carlo"},{"family":"Doncaster","given":"C. Patrick"},{"family":"Matthysen","given":"Erik"}],"container-title":"Ecological Modelling","issue":"2","issued":{"date-parts":[[2007]]},"language":"en","page":"314-322","publisher":"Elsevier","source":"ideas.repec.org","title":"Evaluating least-cost model predictions with empirical dispersal data: A case-study using radiotracking data of hedgehogs (Erinaceus europaeus)","title-short":"Evaluating least-cost model predictions with empirical dispersal data","type":"article-journal","URL":"https://ideas.repec.org/a/eee/ecomod/v209y2007i2p314-322.html","volume":"209"}, + {"id":"duckworthAdaptiveDispersalStrategies2008","abstract":"In species undergoing range expansion, newly established populations are often more dispersive than older populations. Because dispersal phenotypes are complex and often costly, it is unclear how highly dispersive phenotypes are maintained in a species to enable their rapid expression during periods of range expansion. Here I test the idea that metapopulation dynamics of local extinction and recolonization maintain distinct dispersal strategies outside the context of range expansion. Western bluebirds display distinct dispersal phenotypes where aggressive males are more dispersive than nonaggressive males, resulting in highly aggressive populations at the edge of their expanding range. I experimentally created new habitat interior to the range edge to show that, as on the range front, it was colonized solely by aggressive males. Moreover, fitness consequences of aggression depended on population age: aggressive males had high fitness when colonizing new populations, while nonaggressive males performed best in an older population. These results suggest that distinct dispersal strategies were maintained before range expansion as an adaptation for the continual recolonization of new habitat. These results emphasize similarities between range expansion and metapopulation dynamics and suggest that preexisting adaptive dispersal strategies may explain rapid changes in dispersal phenotypes during range expansion.","author":[{"family":"Duckworth","given":"Renée A."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/588289","ISSN":"1537-5323","issued":{"date-parts":[[2008,7]]},"language":"eng","page":"S4-17","PMID":"18554143","source":"PubMed","title":"Adaptive dispersal strategies and the dynamics of a range expansion","type":"article-journal","volume":"172 Suppl 1"}, + {"id":"dyckHabitatFragmentationInsect1999","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dyck","given":"Hans Van"},{"family":"Matthysen","given":"Erik"}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/S0169-5347(99)01610-9","ISSN":"0169-5347","issue":"5","issued":{"date-parts":[[1999,5,1]]},"language":"English","page":"172-174","PMID":"10322528","publisher":"Elsevier","source":"www.cell.com","title":"Habitat fragmentation and insect flight: a changing ‘design’ in a changing landscape?","title-short":"Habitat fragmentation and insect flight","type":"article-journal","URL":"https://www.cell.com/trends/ecology-evolution/abstract/S0169-5347(99)01610-9","volume":"14"}, + {"id":"dythamEvolvedDispersalStrategies2009","abstract":"Dispersal is a key component of a species's ecology and will be under different selection pressures in different parts of the range. For example, a long-distance dispersal strategy suitable for continuous habitat at the range core might not be favoured at the margin, where the habitat is sparse. Using a spatially explicit, individual-based, evolutionary simulation model, the dispersal strategies of an organism that has only one dispersal event in its lifetime, such as a plant or sessile animal, are considered. Within the model, removing habitat, increasing habitat turnover, increasing the cost of dispersal, reducing habitat quality or altering vital rates imposes range limits. In most cases, there is a clear change in the dispersal strategies across the range, although increasing death rate towards the margin has little impact on evolved dispersal strategy across the range. Habitat turnover, reduced birth rate and reduced habitat quality all increase evolved dispersal distances at the margin, while increased cost of dispersal and reduced habitat density lead to lower evolved dispersal distances at the margins. As climate change shifts suitable habitat poleward, species ranges will also start to shift, and it will be the dispersal capabilities of marginal populations, rather than core populations, that will influence the rate of range shifting.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dytham","given":"Calvin"}],"container-title":"Proceedings of the Royal Society B: Biological Sciences","container-title-short":"Proc Biol Sci","DOI":"10.1098/rspb.2008.1535","ISSN":"0962-8452","issue":"1661","issued":{"date-parts":[[2009,4,22]]},"page":"1407-1413","PMCID":"PMC2677228","PMID":"19324810","source":"PubMed Central","title":"Evolved dispersal strategies at range margins","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2677228/","volume":"276"}, + {"id":"dythamEvolvingDispersalAge2006","abstract":"Traditional, and often competing, theories on ageing agree that a programmed age at death must have arisen as a side effect of natural selection, and that it can have no adaptive value of its own. However, theoretical models suggest that ageing and programmed death can be adaptive. Travis J. M. J. suggested that if fecundity declines with age, a programmed age of death evolves through kin selection and that the nature of dispersal is crucial as it determines the degree of spatial structure and hence the strength of kin selection. Here, using a similar model, we consider the interplay between dispersal and age of death. We incorporate more realistic dispersal kernels and allow both dispersal and age of death to evolve. Our results show each trait can evolve in response to the other: earlier age of death evolves when individuals disperse less and greater dispersal distances evolve when individuals are programmed to die later. When we allow dispersal and age of death to evolve at the same time we typically find that dispersal evolves more rapidly, and that ageing then evolves in response to the new dispersal regime. The cost of dispersal is crucial in determining the evolution of both traits. We argue both that ageing is an overlooked ecological process, and that the field of gerontology could learn a lot from evolutionary ecology. We suggest that it is time to develop the field of ecological gerontology and we highlight a few areas where future work might be particularly rewarding.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Dytham","given":"Calvin"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Oikos","ISSN":"0030-1299","issue":"3","issued":{"date-parts":[[2006]]},"page":"530-538","publisher":"[Nordic Society Oikos, Wiley]","source":"JSTOR","title":"Evolving Dispersal and Age at Death","type":"article-journal","URL":"https://www.jstor.org/stable/40234835","volume":"113"}, + {"id":"easterlingClimateExtremesObservations2000","abstract":"One of the major concerns with a potential change in climate is that an increase in extreme events will occur. Results of observational studies suggest that in many areas that have been analyzed, changes in total precipitation are amplified at the tails, and changes in some temperature extremes have been observed. Model output has been analyzed that shows changes in extreme events for future climates, such as increases in extreme high temperatures, decreases in extreme low temperatures, and increases in intense precipitation events. In addition, the societal infrastructure is becoming more sensitive to weather and climate extremes, which would be exacerbated by climate change. In wild plants and animals, climate-induced extinctions, distributional and phenological changes, and species' range shifts are being documented at an increasing rate. Several apparently gradual biological changes are linked to responses to extreme weather and climate events.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Easterling","given":"David R."},{"family":"Meehl","given":"Gerald A."},{"family":"Parmesan","given":"Camille"},{"family":"Changnon","given":"Stanley A."},{"family":"Karl","given":"Thomas R."},{"family":"Mearns","given":"Linda O."}],"container-title":"Science","DOI":"10.1126/science.289.5487.2068","ISSN":"0036-8075, 1095-9203","issue":"5487","issued":{"date-parts":[[2000,9,22]]},"language":"en","page":"2068-2074","PMID":"11000103","publisher":"American Association for the Advancement of Science","section":"Review","source":"science.sciencemag.org","title":"Climate Extremes: Observations, Modeling, and Impacts","title-short":"Climate Extremes","type":"article-journal","URL":"https://science.sciencemag.org/content/289/5487/2068","volume":"289"}, + {"id":"edelaarMatchingHabitatChoice2008","abstract":"Gene flow among populations is typically thought to be antagonistic to population differentiation and local adaptation. However, this assumes that dispersing individuals disperse randomly with respect to their ability to use the environment. Yet dispersing individuals often sample and compare environments and settle in those environments that best match their phenotype, causing directed gene flow, which can in fact promote population differentiation and adaptation. We refer to this process as “matching habitat choice.” Although this process has been acknowledged by several researchers, no synthesis or perspective on its potentially widespread importance exists. Here we synthesize empirical and theoretical studies, and offer a new perspective that matching habitat choice can have significant effects on important and controversial topics. We discuss the potential implications of matching habitat choice for the degree and rate of local adaptation, the evolution of niche width, adaptive peak shifts, speciation in the presence of gene flow, and on our view and interpretation of measures of natural selection. Because of its potential importance for such a wide range of topics, we call for heightened empirical and theoretical attention for this neglected dimension in evolutionary and ecological studies.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Edelaar","given":"Pim"},{"family":"Siepielski","given":"Adam M."},{"family":"Clobert","given":"Jean"}],"container-title":"Evolution","DOI":"10.1111/j.1558-5646.2008.00459.x","ISSN":"1558-5646","issue":"10","issued":{"date-parts":[[2008]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1558-5646.2008.00459.x","page":"2462-2472","source":"Wiley Online Library","title":"Matching Habitat Choice Causes Directed Gene Flow: A Neglected Dimension in Evolution and Ecology","title-short":"Matching Habitat Choice Causes Directed Gene Flow","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1558-5646.2008.00459.x","volume":"62"}, + {"id":"elithSpeciesDistributionModels","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Elith","given":"J"},{"family":"Leathwick","given":"J. R."}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","issue":"40","page":"677-697","title":"Species Distribution Models: Ecological Explanation and Prediction Across Space and Time","type":"article-journal","URL":"https://www.annualreviews.org/doi/full/10.1146/annurev.ecolsys.110308.120159"}, + {"id":"enfjallEvolutionDispersalImportance2009","abstract":"The evolution of mobility patterns and dispersal strategies depend on different population, habitat and life history characteristics. The ability to perceive and make use of information about the surrounding environment for dispersal decisions will also differ between organisms. To investigate the evolutionary consequences of such differences, we have used a simulation model with nearest-neighbour dispersal in a metapopulation to study how variation in the ability to obtain and make use of information about habitat quality and conspecific density affects the evolution of dispersal strategies. We found a rather strong influence of variation in information on the overall rate of dispersal in a metapopulation. The highest emigration rate evolved in organisms with no information about either density or habitat quality and the lowest rate was found in organisms with information about both the natal and the neighbouring patches. For organisms that can make use of information about conspecific density, positively density-dependent dispersal evolved in the majority of cases, with the strongest density dependence occurring when an individual only has information about density in the natal patch. However, we also identified situations, involving strong local population fluctuations and frequent local extinctions, where negatively density-dependent dispersal evolved.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Enfjäll","given":"Karin"},{"family":"Leimar","given":"Olof"}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2008.16863.x","ISSN":"1600-0706","issue":"2","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2008.16863.x","page":"291-299","source":"Wiley Online Library","title":"The evolution of dispersal – the importance of information about population density and habitat characteristics","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0706.2008.16863.x","volume":"118"}, + {"id":"englerMigClimPredictingPlant2009","abstract":"Aim Many studies have forecasted the possible impact of climate change on plant distributions using models based on ecological niche theory, but most of them have ignored dispersal-limitations, assuming dispersal to be either unlimited or null. Depending on the rate of climatic change, the landscape fragmentation and the dispersal capabilities of individual species, these assumptions are likely to prove inaccurate, leading to under- or overestimation of future species distributions and yielding large uncertainty between these two extremes. As a result, the concepts of ‘potentially suitable’ and ‘potentially colonizable’ habitat are expected to differ significantly. To quantify to what extent these two concepts can differ, we developed MigClim, a model simulating plant dispersal under climate change and landscape fragmentation scenarios. MigClim implements various parameters, such as dispersal distance, increase in reproductive potential over time, landscape fragmentation or long-distance dispersal. Location Western Swiss Alps. Methods Using our MigClim model, several simulations were run for two virtual species by varying dispersal distance and other parameters. Each simulation covered the 100-year period 2001–2100 and three different IPCC-based temperature warming scenarios were considered. Results of dispersal-limited projections were compared with unlimited and no-dispersal projections. Results Our simulations indicate that: (1) using realistic parameter values, the future potential distributions generated using MigClim can differ significantly (up to more than 95% difference in colonized surface) from those that ignore dispersal; (2) this divergence increases under more extreme climate warming scenarios and over longer time periods; and (3) the uncertainty associated with the warming scenario can be as large as the one related to dispersal parameters. Main conclusions Accounting for dispersal, even roughly, can importantly reduce uncertainty in projections of species distribution under climate change scenarios.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Engler","given":"Robin"},{"family":"Guisan","given":"Antoine"}],"container-title":"Diversity and Distributions","DOI":"10.1111/j.1472-4642.2009.00566.x","ISSN":"1472-4642","issue":"4","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2009.00566.x","page":"590-601","source":"Wiley Online Library","title":"MigClim: Predicting plant distribution and dispersal in a changing climate","title-short":"MigClim","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1472-4642.2009.00566.x","volume":"15"}, + {"id":"eppersonUtilityComputerSimulations2010","abstract":"Population genetics theory is primarily based on mathematical models in which spatial complexity and temporal variability are largely ignored. In contrast, the field of landscape genetics expressly focuses on how population genetic processes are affected by complex spatial and temporal environmental heterogeneity. It is spatially explicit and relates patterns to processes by combining complex and realistic life histories, behaviours, landscape features and genetic data. Central to landscape genetics is the connection of spatial patterns of genetic variation to the usually highly stochastic space–time processes that create them over both historical and contemporary time periods. The field should benefit from a shift to computer simulation approaches, which enable incorporation of demographic and environmental stochasticity. A key role of simulations is to show how demographic processes such as dispersal or reproduction interact with landscape features to affect probability of site occupancy, population size, and gene flow, which in turn determine spatial genetic structure. Simulations could also be used to compare various statistical methods and determine which have correct type I error or the highest statistical power to correctly identify spatio-temporal and environmental effects. Simulations may also help in evaluating how specific spatial metrics may be used to project future genetic trends. This article summarizes some of the fundamental aspects of spatial–temporal population genetic processes. It discusses the potential use of simulations to determine how various spatial metrics can be rigorously employed to identify features of interest, including contrasting locus-specific spatial patterns due to micro-scale environmental selection.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Epperson","given":"Bryan K."},{"family":"Mcrae","given":"Brad H."},{"family":"Scribner","given":"Kim"},{"family":"Cushman","given":"Samuel A."},{"family":"Rosenberg","given":"Michael S."},{"family":"Fortin","given":"Marie-Josée"},{"family":"James","given":"Patrick M. A."},{"family":"Murphy","given":"Melanie"},{"family":"Manel","given":"Stéphanie"},{"family":"Legendre","given":"Pierre"},{"family":"Dale","given":"Mark R. T."}],"container-title":"Molecular Ecology","DOI":"10.1111/j.1365-294X.2010.04678.x","ISSN":"1365-294X","issue":"17","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-294X.2010.04678.x","page":"3549-3564","source":"Wiley Online Library","title":"Utility of computer simulations in landscape genetics","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-294X.2010.04678.x","volume":"19"}, + {"id":"excoffierGeneticConsequencesRange2009","abstract":"Although range expansions have occurred recurrently in the history of most species, their genetic consequences have been little investigated. Theoretical studies show that range expansions are quite different from pure demographic expansions and that the extent of recent gene flow conditions expected patterns of molecular diversity within and between populations. Spatially explicit simulation studies have led to unexpected and fascinating results about genetic patterns emerging after a range expansion. For instance, spatial expansions can generate allele frequency gradients, promote the surfing of rare variants into newly occupied territories, induce the structuring of newly colonized areas into distinct sectors of low genetic diversity, or lead to massive introgression of local genes into the genome of an invading species. Interestingly, most of these patterns had been previously attributed to distinct selective processes, showing that taking into account the dynamic nature of a species range can lead to a paradigm shift in our perception of evolutionary processes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Excoffier","given":"Laurent"},{"family":"Foll","given":"Matthieu"},{"family":"Petit","given":"Rémy J."}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","DOI":"10.1146/annurev.ecolsys.39.110707.173414","issue":"1","issued":{"date-parts":[[2009]]},"note":"_eprint: https://doi.org/10.1146/annurev.ecolsys.39.110707.173414","page":"481-501","source":"Annual Reviews","title":"Genetic Consequences of Range Expansions","type":"article-journal","URL":"https://doi.org/10.1146/annurev.ecolsys.39.110707.173414","volume":"40"}, + {"id":"fahrigEffectsHabitatFragmentation2003a","abstract":"The literature on effects of habitat fragmentation on biodiversity is huge. It is also very diverse, with different authors measuring fragmentation in different ways and, as a consequence, drawing different conclusions regarding both the magnitude and direction of its effects. Habitat fragmentation is usually defined as a landscape-scale process involving both habitat loss and the breaking apart of habitat. Results of empirical studies of habitat fragmentation are often difficult to interpret because (a) many researchers measure fragmentation at the patch scale, not the landscape scale and (b) most researchers measure fragmentation in ways that do not distinguish between habitat loss and habitat fragmentation per se, i.e., the breaking apart of habitat after controlling for habitat loss. Empirical studies to date suggest that habitat loss has large, consistently negative effects on biodiversity. Habitat fragmentation per se has much weaker effects on biodiversity that are at least as likely to be positive as negative. Therefore, to correctly interpret the influence of habitat fragmentation on biodiversity, the effects of these two components of fragmentation must be measured independently. More studies of the independent effects of habitat loss and fragmentation per se are needed to determine the factors that lead to positive versus negative effects of fragmentation per se. I suggest that the term “fragmentation” should be reserved for the breaking apart of habitat, independent of habitat loss.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fahrig","given":"Lenore"}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","DOI":"10.1146/annurev.ecolsys.34.011802.132419","issue":"1","issued":{"date-parts":[[2003]]},"note":"_eprint: https://doi.org/10.1146/annurev.ecolsys.34.011802.132419","page":"487-515","source":"Annual Reviews","title":"Effects of Habitat Fragmentation on Biodiversity","type":"article-journal","URL":"https://doi.org/10.1146/annurev.ecolsys.34.011802.132419","volume":"34"}, + {"id":"fahrigNonoptimalAnimalMovement2007a","abstract":"1 I synthesize the understanding of the relationship between landscape structure and animal movement in human-modified landscapes. 2 The variety of landscape structures is first classified into four categories: continuous habitat, patchy habitat with high-quality matrix, patchy habitat with low-quality matrix, and patchy, ephemeral habitat. Using this simplification I group the range of evolved movement parameters into four categories or movement types. I then discuss how these movement types interact with current human-caused landscape changes, and how this often results in non-optimal movement. 3 From this synthesis I develop a hypothesis that predicts the relative importance of the different population-level consequences of these non-optimal movements, for the four movement types. 4 Populations of species that have inhabited landscapes with high habitat cover or patchy landscapes with low-risk matrix should have evolved low boundary responses and moderate to high movement probabilities. These species are predicted to be highly susceptible to increased movement mortality resulting from habitat loss and reduced matrix quality. 5 In contrast, populations of species that evolved in patchy landscapes with high-risk matrix or dynamic patchy landscapes are predicted to be highly susceptible to decreased immigration and colonization success, due to the increasing patch isolation that results from habitat loss. 6 Finally, I discuss three implications of this synthesis: (i) ‘least cost path’ analysis should not be used for land management decisions without data on actual movement paths and movement risks in the landscape; (ii) ‘dispersal ability’ is not simply an attribute of a species, but varies strongly with landscape structure such that the relative rankings of species’ dispersal abilities can change following landscape alteration; and (iii) the assumption that more mobile species are more resilient to human-caused landscape change is not generally true, but depends on the structure of the landscape where the species evolved.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fahrig","given":"Lenore"}],"container-title":"Functional Ecology","DOI":"10.1111/j.1365-2435.2007.01326.x","ISSN":"1365-2435","issue":"6","issued":{"date-parts":[[2007]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2435.2007.01326.x","page":"1003-1015","source":"Wiley Online Library","title":"Non-optimal animal movement in human-altered landscapes","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2435.2007.01326.x","volume":"21"}, + {"id":"fellousQuorumSensingDensityDependent2012","abstract":"Many organisms use cues to decide whether to disperse or not, especially those related to the composition of their environment. Dispersal hence sometimes depends on population density, which can be important for the dynamics and evolution of sub-divided populations. But very little is known about the factors that organisms use to inform their dispersal decision. We investigated the cues underlying density-dependent dispersal in inter-connected microcosms of the freshwater protozoan Paramecium caudatum. In two experiments, we manipulated (i) the number of cells per microcosm and (ii) the origin of their culture medium (supernatant from high- or low-density populations). We found a negative relationship between population density and rates of dispersal, suggesting the use of physical cues. There was no significant effect of culture medium origin on dispersal and thus no support for chemical cues usage. These results suggest that the perception of density – and as a result, the decision to disperse – in this organism can be based on physical factors. This type of quorum sensing may be an adaptation optimizing small scale monitoring of the environment and swarm formation in open water.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fellous","given":"Simon"},{"family":"Duncan","given":"Alison"},{"family":"Coulon","given":"Aurélie"},{"family":"Kaltz","given":"Oliver"}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0048436","ISSN":"1932-6203","issue":"11","issued":{"date-parts":[[2012,11,7]]},"language":"en","page":"e48436","publisher":"Public Library of Science","source":"PLoS Journals","title":"Quorum Sensing and Density-Dependent Dispersal in an Aquatic Model System","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0048436","volume":"7"}, + {"id":"fischerLandscapeModificationHabitat2007","abstract":"Landscape modification and habitat fragmentation are key drivers of global species loss. Their effects may be understood by focusing on: (1) individual species and the processes threatening them, and (2) human-perceived landscape patterns and their correlation with species and assemblages. Individual species may decline as a result of interacting exogenous and endogenous threats, including habitat loss, habitat degradation, habitat isolation, changes in the biology, behaviour, and interactions of species, as well as additional, stochastic threats. Human-perceived landscape patterns that are frequently correlated with species assemblages include the amount and structure of native vegetation, the prevalence of anthropogenic edges, the degree of landscape connectivity, and the structure and heterogeneity of modified areas. Extinction cascades are particularly likely to occur in landscapes with low native vegetation cover, low landscape connectivity, degraded native vegetation and intensive land use in modified areas, especially if keystone species or entire functional groups of species are lost. This review (1) demonstrates that species-oriented and pattern-oriented approaches to understanding the ecology of modified landscapes are highly complementary, (2) clarifies the links between a wide range of interconnected themes, and (3) provides clear and consistent terminology. Tangible research and management priorities are outlined that are likely to benefit the conservation of native species in modified landscapes around the world.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fischer","given":"Joern"},{"family":"Lindenmayer","given":"David B."}],"container-title":"Global Ecology and Biogeography","DOI":"10.1111/j.1466-8238.2007.00287.x","ISSN":"1466-8238","issue":"3","issued":{"date-parts":[[2007]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-8238.2007.00287.x","page":"265-280","source":"Wiley Online Library","title":"Landscape modification and habitat fragmentation: a synthesis","title-short":"Landscape modification and habitat fragmentation","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1466-8238.2007.00287.x","volume":"16"}, + {"id":"fletcherjr.EmergentPropertiesConspecific2006","abstract":"Abstract: Attraction to conspecifics may have wide‐ranging implications for habitat selection and metapopulation theory, yet little is known about the process of attraction and its effects relative to other habitat selection strategies. Using individual‐based simulations, I investigated the emergent properties of conspecific attraction during habitat selection on survival, fecundity, short‐term fitness (sur \\documentclass{aastex} \\usepackage{amsbsy} \\usepackage{amsfonts} \\usepackage{amssymb} \\usepackage{bm} \\usepackage{mathrsfs} \\usepackage{pifont} \\usepackage{stmaryrd} \\usepackage{textcomp} \\usepackage{portland,xspace} \\usepackage{amsmath,amsxtra} \\usepackage[OT2,OT1]{fontenc} \\newcommand\\cyr{ \\renewcommand\\rmdefault{wncyr} \\renewcommand\\sfdefault{wncyss} \\renewcommand\\encodingdefault{OT2} \\normalfont \\selectfont} \\DeclareTextFontCommand{\\textcyr}{\\cyr} \\pagestyle{empty} \\DeclareMathSizes{10}{9}{7}{6} \\begin{document} \\landscape $\\mathrm{vival}\\,\\times \\mathrm{fecundity}\\,$ \\end{document} ), and distributions in fragmented landscapes. I simulated conspecific attraction during searching and settlement decisions and compared attraction with random, habitat‐based (searching for the presence of habitat), and habitat quality sampling strategies (searching for and settling in high‐quality habitat). Conspecific attraction during searching or settlement decisions had different consequences for animals: attraction while searching increased survival by decreasing time spent in nonsuitable habitat, whereas attraction during settlement increased fecundity by aggregating animals in high‐quality habitats. Habitat‐based sampling did not improve fitness over attraction, but directly sampling habitat quality resulted in the highest short‐term fitness among strategies. These results suggest that attraction can improve fitness when animals cannot directly assess habitat quality. Interestingly, conspecific attraction influenced distributions by generating patch size effects and weak edge effects, highlighting that attraction is one potential, yet previously unappreciated, mechanism to explain the widespread patterns of animal sensitivity to habitat fragmentation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fletcher Jr.","given":"Robert J."},{"family":"Grimm","given":"Associate Editor: Volker"},{"family":"DeAngelis","given":"Editor: Donald L."}],"container-title":"The American Naturalist","DOI":"10.1086/505764","ISSN":"0003-0147","issue":"2","issued":{"date-parts":[[2006]]},"page":"207-219","publisher":"[The University of Chicago Press, The American Society of Naturalists]","source":"JSTOR","title":"Emergent Properties of Conspecific Attraction in Fragmented Landscapes","type":"article-journal","URL":"https://www.jstor.org/stable/10.1086/505764","volume":"168"}, + {"id":"fletcherSpeciesInteractionsPopulation2007","abstract":"1. The perspective that populations and communities are structured by antagonistic interactions among individuals has dominated much of ecology. Yet how animals use social information to guide decisions, such as habitat selection, may be influenced by both positive and negative interactions among individuals. Recent theory also suggests that the way animals use social information may be substantially influenced by population density, which alters the potential costs and benefits of such behaviours. 2. I manipulated cues of two competitors, the dominant least flycatcher Empidonax minimus (Baird & Baird) and the subordinate American redstart Setophaga ruticilla (Linnaeus), to assess the use of conspecific and heterospecific cues during habitat selection, and if population density influences these strategies. The experiment consisted of surveying birds during a pre-treatment year, which allows for the control and testing the effect of baseline densities, and a treatment year, in which treatments were applied just prior to settlement. Treatments included broadcasting songs of flycatchers and redstarts, and were compared with controls. 3. When controlling for pre-treatment densities, bird densities, and to a lesser extent arrival dates, during the treatment year suggested that flycatchers were attracted to both conspecific and heterospecific cues during settlement. Furthermore, attraction was strongest for flycatchers in plots with moderate pre-treatment densities. American redstarts were rare in the study area but showed apparent attraction to conspecifics and avoidance of heterospecifics. 4. These results provide experimental evidence for the use of multiple social cues in habitat selection and suggest that heterospecific attraction may operate under broader contexts than originally envisioned. In such instances, nontarget effects can potentially occur when manipulating social cues to elicit settlement in conservation strategies. The impact of population density on the use of social cues shown here can also influence our understanding of metapopulation dynamics by causing complex threshold effects on the likelihood of rescue, which may influence metapopulation stability and the likelihood of local extinction.","author":[{"family":"Fletcher","given":"Robert J."}],"container-title":"The Journal of Animal Ecology","container-title-short":"J Anim Ecol","DOI":"10.1111/j.1365-2656.2007.01230.x","ISSN":"0021-8790","issue":"3","issued":{"date-parts":[[2007,5]]},"language":"eng","page":"598-606","PMID":"17439476","source":"PubMed","title":"Species interactions and population density mediate the use of social cues for habitat selection","type":"article-journal","volume":"76"}, + {"id":"fowlerConfoundingEnvironmentalColour2013","abstract":"The colour of environmental variability influences the size of population fluctuations when filtered through density dependent dynamics, driving extinction risk through dynamical resonance. Slow fluctuations (low frequencies) dominate in red environments, rapid fluctuations (high frequencies) in blue environments and white environments are purely random (no frequencies dominate). Two methods are commonly employed to generate the coloured spatial and/or temporal stochastic (environmental) series used in combination with population (dynamical feedback) models: autoregressive [AR(1)] and sinusoidal (1/f) models. We show that changing environmental colour from white to red with 1/f models, and from white to red or blue with AR(1) models, generates coloured environmental series that are not normally distributed at finite time-scales, potentially confounding comparison with normally distributed white noise models. Increasing variability of sample Skewness and Kurtosis and decreasing mean Kurtosis of these series alter the frequency distribution shape of the realised values of the coloured stochastic processes. These changes in distribution shape alter patterns in the probability of single and series of extreme conditions. We show that the reduced extinction risk for undercompensating (slow growing) populations in red environments previously predicted with traditional 1/f methods is an artefact of changes in the distribution shapes of the environmental series. This is demonstrated by comparison with coloured series controlled to be normally distributed using spectral mimicry. Changes in the distribution shape that arise using traditional methods lead to underestimation of extinction risk in normally distributed, red 1/f environments. AR(1) methods also underestimate extinction risks in traditionally generated red environments. This work synthesises previous results and provides further insight into the processes driving extinction risk in model populations. We must let the characteristics of known natural environmental covariates (e.g., colour and distribution shape) guide us in our choice of how to best model the impact of coloured environmental variation on population dynamics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fowler","given":"Mike S."},{"family":"Ruokolainen","given":"Lasse"}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0055855","ISSN":"1932-6203","issue":"2","issued":{"date-parts":[[2013,2,11]]},"language":"en","page":"e55855","publisher":"Public Library of Science","source":"PLoS Journals","title":"Confounding Environmental Colour and Distribution Shape Leads to Underestimation of Population Extinction Risk","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0055855","volume":"8"}, + {"id":"frankhamWhereAreWe2010","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Frankham","given":"Richard"}],"container-title":"Conservation Genetics","container-title-short":"Conserv Genet","DOI":"10.1007/s10592-009-0010-2","ISSN":"1572-9737","issue":"2","issued":{"date-parts":[[2010,4,1]]},"language":"en","page":"661-663","source":"Springer Link","title":"Where are we in conservation genetics and where do we need to go?","type":"article-journal","URL":"https://doi.org/10.1007/s10592-009-0010-2","volume":"11"}, + {"id":"franklinMovingStaticSpecies2010","abstract":"Aim To demonstrate that multi-modelling methods have effectively been used to combine static species distribution models (SDM), predicting the geographical pattern of suitable habitat, with dynamic landscape and population models to forecast the impacts of environmental change on species’ status, an important goal of conservation biogeography. Methods Three approaches were considered: (1) incorporating models of species migration to understand the ability of a species to occupy suitable habitat in new locations; (2) linking models of landscape disturbance and succession to models of habitat suitability; and (3) fully linking models of habitat suitability, habitat dynamics and spatially explicit population dynamics. Results Linking species–environment relationships, landscape dynamics and population dynamics in a multi-modelling framework allows the combined impacts of climate change (affecting species distribution and vital rates) and land cover dynamics (land use change, altered disturbance regimes) on species to be predicted. This approach is only feasible if the life history parameters and habitat requirements of the species are well understood. Main conclusions Forecasts of the impacts of global change on species may be improved by considering multiple causes. A range of methods are available to address the interactions of changing habitat suitability, habitat dynamics and population response that vary in their complexity, realism and data requirements.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Franklin","given":"Janet"}],"container-title":"Diversity and Distributions","DOI":"10.1111/j.1472-4642.2010.00641.x","ISSN":"1472-4642","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2010.00641.x","page":"321-330","source":"Wiley Online Library","title":"Moving beyond static species distribution models in support of conservation biogeography","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1472-4642.2010.00641.x","volume":"16"}, + {"id":"franksGeneticsClimateChange2012","abstract":"The rapid rate of current global climate change is having strong effects on many species and, at least in some cases, is driving evolution, particularly when changes in conditions alter patterns of selection. Climate change thus provides an opportunity for the study of the genetic basis of adaptation. Such studies include a variety of observational and experimental approaches, such as sampling across clines, artificial evolution experiments, and resurrection studies. These approaches can be combined with a number of techniques in genetics and genomics, including association and mapping analyses, genome scans, and transcription profiling. Recent research has revealed a number of candidate genes potentially involved in climate change adaptation and has also illustrated that genetic regulatory networks and epigenetic effects may be particularly relevant for evolution driven by climate change. Although genetic and genomic data are rapidly accumulating, we still have much to learn about the genetic architecture of climate change adaptation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Franks","given":"Steven J."},{"family":"Hoffmann","given":"Ary A."}],"container-title":"Annual Review of Genetics","container-title-short":"Annu. Rev. Genet.","DOI":"10.1146/annurev-genet-110711-155511","ISSN":"0066-4197","issue":"1","issued":{"date-parts":[[2012,12,15]]},"page":"185-208","publisher":"Annual Reviews","source":"annualreviews.org (Atypon)","title":"Genetics of Climate Change Adaptation","type":"article-journal","URL":"https://www.annualreviews.org/doi/10.1146/annurev-genet-110711-155511","volume":"46"}, + {"id":"fraserRangeExpansionInvasive2015","abstract":"Aim The impact of invasive species is one of the main causes of biodiversity loss world-wide, and as a result, there is much interest in understanding the pattern and rate of expansion of species outside their native range. We aimed to characterize the range expansion of the American mink (Neovison vison) invading from multiple introduction points through a varied landscape bounded by coastline to better understand and manage its spread. Location Scotland, UK. Method We collated and used records of mink presence to calculate the historical range and rate of range expansion at successive time intervals. We used a presence-only model to predict habitat suitability and a newly developed individual-based modelling platform, RangeShifter, to simulate range expansion. Results Records showed that mink were distributed throughout Scotland, except in the far north. We found that the rate of spread varied both spatially and temporally and was related to landscape heterogeneity. Habitat suitable for mink in west Scotland is restricted to the coast. Main conclusions We concluded that temporal and spatial variation in range expansion is attributable to heterogeneity within the landscape and also demonstrated that the potential for long-distance dispersal does not necessarily facilitate range expansion when availability of suitable habitat occurs in narrow strips and/or is fragmented. We have highlighted methodological gaps in calculating rates of expansion in invasive species but have demonstrated alternative methods that successfully utilize presence-only data. Our study reaffirms that invasive species will colonize less favourable habitats and highlights the need to remain vigilant of their potential for expansion even when distribution appears to be static for a time.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fraser","given":"Elaine J."},{"family":"Lambin","given":"Xavier"},{"family":"Travis","given":"Justin M. J."},{"family":"Harrington","given":"Lauren A."},{"family":"Palmer","given":"Stephen C. F."},{"family":"Bocedi","given":"Greta"},{"family":"Macdonald","given":"David W."}],"container-title":"Diversity and Distributions","DOI":"10.1111/ddi.12303","ISSN":"1472-4642","issue":"8","issued":{"date-parts":[[2015]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ddi.12303","page":"888-900","source":"Wiley Online Library","title":"Range expansion of an invasive species through a heterogeneous landscape – the case of American mink in Scotland","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/ddi.12303","volume":"21"}, + {"id":"friedenbergExperimentalEvolutionDispersal2003","abstract":"The world is an uncertain place. Individuals’ fates vary from place to place and from time to time. Natural selection in unpredictable environments should favour individuals that hedge their bets by dispersing offspring. I confirm this basic prediction using Caenorhabditis elegans in experimental microcosms. My results agree with evolutionary models and correlations found previously between habitat stability and individual dispersal propensity in nature. However, I also find that environmental variation that triggers conditional dispersal behaviour may not impose selection on baseline dispersal rates. These findings imply that an increased rate of disturbance in natural systems has the potential to cause an evolutionary response in the life history of impacted organisms.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Friedenberg","given":"Nicholas A."}],"container-title":"Ecology Letters","DOI":"10.1046/j.1461-0248.2003.00524.x","ISSN":"1461-0248","issue":"10","issued":{"date-parts":[[2003]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1461-0248.2003.00524.x","page":"953-959","source":"Wiley Online Library","title":"Experimental evolution of dispersal in spatiotemporally variable microcosms","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1046/j.1461-0248.2003.00524.x","volume":"6"}, + {"id":"fronhoferPickyHitchhikersVector2013a","abstract":"Dispersal is a central life-history trait for most animals and plants: it allows to colonize new habitats, escape from competition or avoid inbreeding. Yet, not all species are mobile enough to perform sufficient dispersal. Such passive dispersers may use more mobile animals as dispersal vectors. If multiple potential vectors are available, an active choice can allow to optimize the dispersal process and to determine the distribution of dispersal distances, i.e. an optimal dispersal kernel. We explore dispersal and vector choice in the neotropical flower mite Spadiseius calyptrogynae using a dual approach which combines experiments with an individual-based simulation model. Spadiseius calyptrogynae is found in lowland rainforests in Costa Rica. It inhabits inflorescences of the understorey palm Calyptrogyne ghiesbreghtiana and is phoretic on a number of flower visitors including bats, beetles and stingless bees. We hypothesised that the mites should optimise their dispersal kernel by actively choosing a specific mix of potential phoretic vectors. In a simple olfactometer setup we showed that the flower mites do indeed discriminate between potential vectors. Subsequently we used an individual-based model to analyse the evolutionary forces responsible for the observed patterns of vector choice. The mites combine vectors exhibiting long-distance dispersal with those allowing for more localized dispersal. This results in a fat-tailed dispersal kernel that guarantees the occasional colonization of new host plant patches (long distance) while optimizing the exploitation of clumped resources (local dispersal). Additionally, kin competition results in a preference for small vectors that transport only few individuals at a time. At the same time, these vectors lead to directed dispersal towards suitable habitat, which increases the stability of this very specialized interaction. Our findings can be applied to other phoretic systems but also to vector-based seed dispersal, for example.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fronhofer","given":"Emanuel A."},{"family":"Sperr","given":"Ellen B."},{"family":"Kreis","given":"Anna"},{"family":"Ayasse","given":"Manfred"},{"family":"Poethke","given":"Hans Joachim"},{"family":"Tschapka","given":"Marco"}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2013.00503.x","ISSN":"1600-0706","issue":"8","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2013.00503.x","page":"1254-1264","source":"Wiley Online Library","title":"Picky hitch-hikers: vector choice leads to directed dispersal and fat-tailed kernels in a passively dispersing mite","title-short":"Picky hitch-hikers","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0706.2013.00503.x","volume":"122"}, + {"id":"fryxellMultipleMovementModes2008","abstract":"Recent theory suggests that animals should switch facultatively among canonical movement modes as a complex function of internal state, landscape characteristics, motion capacity, and navigational capacity. We tested the generality of this paradigm for free-ranging elk (Cervus elaphus) over 5 orders of magnitude in time (minutes to years) and space (meters to 100 km). At the coarsest spatiotemporal scale, elk shifted from a dispersive to a home-ranging phase over the course of 1–3 years after introduction into a novel environment. At intermediate spatiotemporal scales, elk continued to alternate between movement modes. During the dispersive phase, elk alternated between encamped and exploratory modes, possibly linked to changes in motivational goals from foraging to social bonding. During the home-ranging phase, elk movements were characterized by a complex interplay between attraction to preferred habitat types and memory of previous movements across the home-range. At the finest temporal and spatial scale, elk used area-restricted search while browsing, interspersed with less sinuous paths when not browsing. Encountering a patch of high-quality food plants triggered the switch from one mode to the next, creating biphasic movement dynamics that were reinforced by local resource heterogeneity. These patterns suggest that multiphasic structure is fundamental to the movement patterns of elk at all temporal and spatial scales tested.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Fryxell","given":"John M."},{"family":"Hazell","given":"Megan"},{"family":"Börger","given":"Luca"},{"family":"Dalziel","given":"Ben D."},{"family":"Haydon","given":"Daniel T."},{"family":"Morales","given":"Juan M."},{"family":"McIntosh","given":"Therese"},{"family":"Rosatte","given":"Rick C."}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.0801737105","ISSN":"0027-8424, 1091-6490","issue":"49","issued":{"date-parts":[[2008,12,9]]},"language":"en","page":"19114-19119","PMID":"19060190","publisher":"National Academy of Sciences","section":"Research Article","source":"www.pnas.org","title":"Multiple movement modes by large herbivores at multiple spatiotemporal scales","type":"article-journal","URL":"https://www.pnas.org/content/105/49/19114","volume":"105"}, + {"id":"gallienPredictingPotentialDistributions2010","abstract":"Aim There has been considerable recent interest in modelling the potential distributions of invasive species. However, research has developed in two opposite directions: the first, focusing on screening, utilizes phenomenological models; the second, focusing on predictions of invasion dynamics, utilizes mechanistic models. Here, we present hybrid modelling as an approach to bridge the gap and to integrate the advantages of both research directions. Location Global. Methods First, we briefly summarize the characteristics and limitations of both approaches (screening vs. understanding). Then, we review the recent developments of hybrid models, discuss their current problems and offer suggestions to improve them. Results Generally, hybrid models are able to combine the advantages of currently used phenomenological and mechanistic approaches. Main challenges in building hybrid models are the choices of the appropriate degree of detail and efficiency and the decision on how to connect the different sub-models. Given these challenges, we discuss the links between the phenomenological and the mechanistic model parameters, the underlying concepts of fundamental and realized niches and the problem of feedback loops between population dynamics and environmental factors. Main conclusions Once the above challenges have been addressed and the necessary framework has been developed, hybrid models will provide outstanding tools for overcoming past limitations and will provide the means to make reliable and robust predictions of the potential distribution of invasive species, their population dynamics and the potential outcomes of the overall invasion process.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Gallien","given":"Laure"},{"family":"Münkemüller","given":"Tamara"},{"family":"Albert","given":"Cécile H."},{"family":"Boulangeat","given":"Isabelle"},{"family":"Thuiller","given":"Wilfried"}],"container-title":"Diversity and Distributions","DOI":"10.1111/j.1472-4642.2010.00652.x","ISSN":"1472-4642","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2010.00652.x","page":"331-342","source":"Wiley Online Library","title":"Predicting potential distributions of invasive species: where to go from here?","title-short":"Predicting potential distributions of invasive species","type":"article-journal","URL":"https://www.onlinelibrary.wiley.com/doi/abs/10.1111/j.1472-4642.2010.00652.x","volume":"16"}, + {"id":"gardnerSimulatingDispersalReintroduced2004b","abstract":"This paper describes the development and application of a spatially explicit, individual based model of animal dispersal (J-walk) to determine the relative effects of landscape heterogeneity, prey availability, predation risk, and the energy requirements and behavior of dispersing organisms on dispersal success. Significant unknowns exist for the simulation of complex movement behavior within heterogeneous landscapes. Therefore, initial simulations with J-walk examined the relative effect of landscape patterns and species-specific characteristics on dispersal success. Differences in landscape pattern were simulated by random generation of fractal maps with average available energy (i.e. prey) and predation risk expressed as a function of habitat type. Variation in species-specific patterns were then simulated by a series of scenarios that varied the response of dispersing individuals to habitat heterogeneity, including: habitat selection to maximize energy intake, habitat selection to minimize predation risk, or habitat selection contingent on energy reserves. Results showed that significant shifts in dispersal could be related to (1) the unique spatial arrangement of habitat within each map, (2) changes in relative prey abundance, and (3) variation in the relationship between energy availability and predation risk. Hypothetical management scenarios were used to identify critical data needed to assure the persistence of reintroduced populations of American martens (Martes americana).","accessed":{"date-parts":[[2021,8,10]]},"author":[{"family":"Gardner","given":"Robert H."},{"family":"Gustafson","given":"Eric J."}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/j.ecolmodel.2003.08.008","ISSN":"0304-3800","issue":"4","issued":{"date-parts":[[2004,2,1]]},"language":"en","page":"339-358","source":"ScienceDirect","title":"Simulating dispersal of reintroduced species within heterogeneous landscapes","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0304380003003387","volume":"171"}, + {"id":"gastonGeographicRangeLimits2009","abstract":"Understanding of the determinants of species' geographic range limits remains poorly integrated. In part, this is because of the diversity of perspectives on the issue, and because empirical studies have lagged substantially behind developments in theory. Here, I provide a broad overview, drawing together many of the disparate threads, considering, in turn, how influences on the terms of a simple single-population equation can determine range limits. There is theoretical and empirical evidence for systematic changes towards range limits under some circumstances in each of the demographic parameters. However, under other circumstances, no such changes may take place in particular parameters, or they may occur in a different direction, with limitation still occurring. This suggests that (i) little about range limitation can categorically be inferred from many empirical studies, which document change in only one demographic parameter, (ii) there is a need for studies that document variation in all of the parameters, and (iii) in agreement with theoretical evidence that range limits can be formed in the presence or absence of hard boundaries, environmental gradients or biotic interactions, there may be few general patterns as to the determinants of these limits, with most claimed generalities at least having many exceptions.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Gaston","given":"Kevin J"}],"container-title":"Proceedings of the Royal Society B: Biological Sciences","DOI":"10.1098/rspb.2008.1480","issue":"1661","issued":{"date-parts":[[2009,4,22]]},"page":"1395-1406","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Geographic range limits: achieving synthesis","title-short":"Geographic range limits","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2008.1480","volume":"276"}, + {"id":"gilmanFrameworkCommunityInteractions2010a","abstract":"Predicting the impacts of climate change on species is one of the biggest challenges that ecologists face. Predictions routinely focus on the direct effects of climate change on individual species, yet interactions between species can strongly influence how climate change affects organisms at every scale by altering their individual fitness, geographic ranges and the structure and dynamics of their community. Failure to incorporate these interactions limits the ability to predict responses of species to climate change. We propose a framework based on ideas from global-change biology, community ecology, and invasion biology that uses community modules to assess how species interactions shape responses to climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Gilman","given":"Sarah E."},{"family":"Urban","given":"Mark C."},{"family":"Tewksbury","given":"Joshua"},{"family":"Gilchrist","given":"George W."},{"family":"Holt","given":"Robert D."}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/j.tree.2010.03.002","ISSN":"0169-5347","issue":"6","issued":{"date-parts":[[2010,6,1]]},"language":"en","page":"325-331","source":"ScienceDirect","title":"A framework for community interactions under climate change","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169534710000613","volume":"25"}, + {"id":"gilroyMateFindingOverlookedCritical2012","abstract":"Dispersal is a critically important process in ecology, but robust predictive models of animal dispersal remain elusive. We identify a potentially ubiquitous component of variation in animal dispersal that has been largely overlooked until now: the influence of mate encounters on settlement probability. We use an individual-based model to simulate dispersal in sexually-reproducing organisms that follow a simple set of movement rules based on conspecific encounters, within an environment lacking spatial habitat heterogeneity. We show that dispersal distances vary dramatically with fluctuations in population density in such a model, even in the absence of variation in dispersive traits between individuals. In a simple random-walk model with promiscuous mating, dispersal distributions become increasingly ‘fat-tailed’ at low population densities due to the increasing scarcity of mates. Similar variation arises in models incorporating territoriality. In a model with polygynous mating, we show that patterns of sex-biased dispersal can even be reversed across a gradient of population density, despite underlying dispersal mechanisms remaining unchanged. We show that some widespread dispersal patterns found in nature (e.g. fat tailed distributions) can arise as a result of demographic variability in the absence of heterogeneity in dispersive traits across the population. This implies that models in which individual dispersal distances are considered to be fixed traits might be unrealistic, as dispersal distances vary widely under a single dispersal mechanism when settlement is influenced by mate encounters. Mechanistic models offer a promising means of advancing our understanding of dispersal in sexually-reproducing organisms.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Gilroy","given":"James J."},{"family":"Lockwood","given":"Julie L."}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0038091","ISSN":"1932-6203","issue":"5","issued":{"date-parts":[[2012,5,25]]},"language":"en","page":"e38091","publisher":"Public Library of Science","source":"PLoS Journals","title":"Mate-Finding as an Overlooked Critical Determinant of Dispersal Variation in Sexually-Reproducing Animals","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0038091","volume":"7"}, + {"id":"greenmanImpactEnvironmentalFluctuations2005","abstract":"External forcing of a discrete time ecological system does not just add variation to existing dynamics but can change the dynamics. We study the mechanisms that can bring this about, focusing on the key concepts of excitation and suppression which emerge when analysing the power spectra of the system in linear approximation. Excitation, through resonance between the system dynamics and the external forcing, is the greater the closer the system is to the boundary of the stability region. This amplification means that the extinction of populations becomes possible sooner than expected and, conversely, invasion can be significantly delayed. Suppression and the consequent redistribution of power within the spectrum proves to be a function both of the connectivity of the network graph of the system and the way that external forcing is applied to the system. It is also established that colour in stochastic forcing can have a major impact, by enhancing resonance and by greater redistribution of power. This can mean a higher risk of extinction through larger fluctuations in population numbers and a higher degree of synchrony between populations. The implications of external forcing for stage-structured species, for populations in competition and for trophic web systems are studied using the tools and concepts developed in the paper.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Greenman","given":"J. V."},{"family":"Benton","given":"T. G."}],"container-title":"Theoretical Population Biology","container-title-short":"Theoretical Population Biology","DOI":"10.1016/j.tpb.2005.06.007","ISSN":"0040-5809","issue":"4","issued":{"date-parts":[[2005,12,1]]},"language":"en","page":"217-235","source":"ScienceDirect","title":"The impact of environmental fluctuations on structured discrete time population models: Resonance, synchrony and threshold behaviour","title-short":"The impact of environmental fluctuations on structured discrete time population models","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0040580905000936","volume":"68"}, + {"id":"greenwoodMatingSystemsPhilopatry1980","abstract":"Many species of birds and mammals are faithful to their natal and breeding site or group. In most of them one sex is more philopatric than the other. In birds it is usually females which disperse more than males; in mammals it is usually males which disperse more than females. Reproductive enhancement through increased access to mates or resources and the avoidance of inbreeding are important in promoting sex differences in dispersal. It is argued that the direction of the sex bias is a consequence of the type of mating system. Philopatry will favour the evolution of cooperative traits between members of the sedentary sex. Disruptive acts will be a feature of dispersers.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Greenwood","given":"Paul J."}],"container-title":"Animal Behaviour","container-title-short":"Animal Behaviour","DOI":"10.1016/S0003-3472(80)80103-5","ISSN":"0003-3472","issue":"4","issued":{"date-parts":[[1980,11,1]]},"language":"en","page":"1140-1162","source":"ScienceDirect","title":"Mating systems, philopatry and dispersal in birds and mammals","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0003347280801035","volume":"28"}, + {"id":"grimmIndividualbasedModelingEcology2005","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Grimm","given":"Volker"},{"family":"Railsback","given":"Steven F."}],"ISBN":"978-0-691-09666-7","issued":{"date-parts":[[2005]]},"language":"en","publisher":"Princeton University Press","source":"press.princeton.edu","title":"Individual-based Modeling and Ecology","type":"book","URL":"https://press.princeton.edu/books/paperback/9780691096667/individual-based-modeling-and-ecology"}, + {"id":"grosEvolutionSexbiasedDispersal2008","abstract":"Abstract: Inbreeding avoidance and asymmetric competition over resources have both been identified as factors favoring the evolution of sex-biased dispersal. It has also been recognized that sex-specific costs of dispersal would select for sex-biased dispersal, but there is little quantitative information on this aspect. In this paper we explore (i) the quantitative relationship between cost-asymmetry and a bias in dispersal, (ii) the influence of demographic stochasticity on this effect, and (iii) how inbreeding and cost-asymmetry interact in their effect on sex-specific dispersal. We adjust an existing analytical model to account for sex-specific costs of dispersal. Based on numerical calculations we predict a severe bias in dispersal already for small differences in dispersal costs. We corroborate these predictions in individual-based simulations, but show that demographic stochasticity generally leads to more balanced dispersal. In combination with inbreeding, cost asymmetries will usually determine which of the two sexes becomes the more dispersive.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Gros","given":"Andreas"},{"family":"Hovestadt","given":"Thomas"},{"family":"Poethke","given":"Hans Joachim"}],"issued":{"date-parts":[[2008]]},"language":"eng","source":"opus.bibliothek.uni-wuerzburg.de","title":"Evolution of sex-biased dispersal : the role of sex-specific dispersal costs, demographic stochasticity, and inbreeding","title-short":"Evolution of sex-biased dispersal","type":"article-journal","URL":"https://opus.bibliothek.uni-wuerzburg.de/frontdoor/index/index/docId/4031"}, + {"id":"grosSexspecificSpatiotemporalVariability2009","abstract":"Inbreeding depression, asymmetries in costs or benefits of dispersal, and the mating system have been identified as potential factors underlying the evolution of sex-biased dispersal. We use individual-based simulations to explore how the mating system and demographic stochasticity influence the evolution of sex-specific dispersal in a metapopulation with females competing over breeding sites, and males over mating opportunities. Comparison of simulation results for random mating with those for a harem system (locally, a single male sires all offspring) reveal that even extreme variance in local male reproductive success (extreme male competition) does not induce male-biased dispersal. The latter evolves if the between-patch variance in reproductive success is larger for males than females. This can emerge due to demographic stochasticity if the habitat patches are small. More generally, members of a group of individuals experiencing higher spatio-temporal variance in fitness expectations may evolve to disperse with greater probability than others.","author":[{"family":"Gros","given":"Andreas"},{"family":"Poethke","given":"Hans Joachim"},{"family":"Hovestadt","given":"Thomas"}],"container-title":"Theoretical Population Biology","container-title-short":"Theor Popul Biol","DOI":"10.1016/j.tpb.2009.03.002","ISSN":"1096-0325","issue":"1","issued":{"date-parts":[[2009,8]]},"language":"eng","page":"13-18","PMID":"19303892","source":"PubMed","title":"Sex-specific spatio-temporal variability in reproductive success promotes the evolution of sex-biased dispersal","type":"article-journal","volume":"76"}, + {"id":"guillaumeInbreedingLoadBet2009","abstract":"Inbreeding load affects not only the average fecundity of philopatric individuals but also its variance. From bet‐hedging theory, this should add further dispersal pressures to those stemming from the mere avoidance of inbreeding. Pressures on both sexes are identical under monogamy or promiscuity. Under polygyny, by contrast, the variance in reproductive output decreases with dispersal rate in females but increases in males, which should induce a female‐biased dispersal. To test this prediction, we performed individual‐based simulations. From our results, a female‐biased dispersal indeed emerges as both polygyny and inbreeding load increase. We conclude that sex‐biased dispersal may be selected for as a bet‐hedging strategy.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Guillaume","given":"Frédéric"},{"family":"Perrin","given":"Nicolas"}],"container-title":"The American Naturalist","DOI":"10.1086/597218","ISSN":"0003-0147","issue":"4","issued":{"date-parts":[[2009,4,1]]},"page":"536-541","publisher":"The University of Chicago Press","source":"journals.uchicago.edu (Atypon)","title":"Inbreeding Load, Bet Hedging, and the Evolution of Sex‐Biased Dispersal.","type":"article-journal","URL":"https://www.journals.uchicago.edu/doi/full/10.1086/597218","volume":"173"}, + {"id":"guillaumeNEMOEvolutionaryPopulation2006","abstract":"Unlabelled: \nNemo is an individual-based, genetically explicit and stochastic population computer program for the simulation of population genetics and life-history trait evolution in a metapopulation context. It comes as both a C++ programming framework and an executable program file. Its object-oriented programming design gives it the flexibility and extensibility needed to implement a large variety of forward-time evolutionary models. It provides developers with abstract models allowing them to implement their own life-history traits and life-cycle events. Nemo offers a large panel of population models, from the Island model to lattice models with demographic or environmental stochasticity and a variety of already implemented traits (deleterious mutations, neutral markers and more), life-cycle events (mating, dispersal, aging, selection, etc.) and output operators for saving data and statistics. It runs on all major computer platforms including parallel computing environments.\n\nAvailability:\nThe source code, binaries and documentation are available under the GNU General Public License at http://nemo2.sourceforge.net.","author":[{"family":"Guillaume","given":"Frédéric"},{"family":"Rougemont","given":"Jacques"}],"container-title":"Bioinformatics (Oxford, England)","container-title-short":"Bioinformatics (Oxford, England)","DOI":"10.1093/bioinformatics/btl415","issued":{"date-parts":[[2006,11,1]]},"page":"2556-7","source":"ResearchGate","title":"NEMO: an evolutionary and population genetics programming framework","title-short":"NEMO","type":"article-journal","volume":"22"}, + {"id":"guisanPredictingSpeciesDistribution2005a","abstract":"In the last two decades, interest in species distribution models (SDMs) of plants and animals has grown dramatically. Recent advances in SDMs allow us to potentially forecast anthropogenic effects on patterns of biodiversity at different spatial scales. However, some limitations still preclude the use of SDMs in many theoretical and practical applications. Here, we provide an overview of recent advances in this field, discuss the ecological principles and assumptions underpinning SDMs, and highlight critical limitations and decisions inherent in the construction and evaluation of SDMs. Particular emphasis is given to the use of SDMs for the assessment of climate change impacts and conservation management issues. We suggest new avenues for incorporating species migration, population dynamics, biotic interactions and community ecology into SDMs at multiple spatial scales. Addressing all these issues requires a better integration of SDMs with ecological theory.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Guisan","given":"Antoine"},{"family":"Thuiller","given":"Wilfried"}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2005.00792.x","ISSN":"1461-0248","issue":"9","issued":{"date-parts":[[2005]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2005.00792.x","page":"993-1009","source":"Wiley Online Library","title":"Predicting species distribution: offering more than simple habitat models","title-short":"Predicting species distribution","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2005.00792.x","volume":"8"}, + {"id":"hallerSLiMForwardGenetic","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Haller","given":"Benjamin C."},{"family":"Messer","given":"Phillip W."}],"container-title":"Molecular Biology and Evolution","issue":"36","page":"632-637","title":"SLiM 3: Forward Genetic Simulations Beyond the Wright–Fisher Model | Molecular Biology and Evolution | Oxford Academic","type":"article-journal","URL":"https://academic.oup.com/mbe/article/36/3/632/5229931"}, + {"id":"hansenPerceptionClimateChange2012","abstract":"“Climate dice,” describing the chance of unusually warm or cool seasons, have become more and more “loaded” in the past 30 y, coincident with rapid global warming. The distribution of seasonal mean temperature anomalies has shifted toward higher temperatures and the range of anomalies has increased. An important change is the emergence of a category of summertime extremely hot outliers, more than three standard deviations (3σ) warmer than the climatology of the 1951–1980 base period. This hot extreme, which covered much less than 1% of Earth’s surface during the base period, now typically covers about 10% of the land area. It follows that we can state, with a high degree of confidence, that extreme anomalies such as those in Texas and Oklahoma in 2011 and Moscow in 2010 were a consequence of global warming because their likelihood in the absence of global warming was exceedingly small. We discuss practical implications of this substantial, growing, climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hansen","given":"James"},{"family":"Sato","given":"Makiko"},{"family":"Ruedy","given":"Reto"}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.1205276109","ISSN":"0027-8424, 1091-6490","issue":"37","issued":{"date-parts":[[2012,9,11]]},"language":"en","page":"E2415-E2423","PMID":"22869707","publisher":"National Academy of Sciences","section":"PNAS Plus","source":"www.pnas.org","title":"Perception of climate change","type":"article-journal","URL":"https://www.pnas.org/content/109/37/E2415","volume":"109"}, + {"id":"hanskiEcoevolutionaryDynamicsDispersal2011a","abstract":"Evolutionary changes in natural populations are often so fast that the evolutionary dynamics may influence ecological population dynamics and vice versa. Here we construct an eco-evolutionary model for dispersal by combining a stochastic patch occupancy metapopulation model with a model for changes in the frequency of fast-dispersing individuals in local populations. We test the model using data on allelic variation in the gene phosphoglucose isomerase (Pgi), which is strongly associated with dispersal rate in the Glanville fritillary butterfly. Population-specific measures of immigration and extinction rates and the frequency of fast-dispersing individuals among the immigrants explained 40% of spatial variation in Pgi allele frequency among 97 local populations. The model clarifies the roles of founder events and gene flow in dispersal evolution and resolves a controversy in the literature about the consequences of habitat loss and fragmentation on the evolution of dispersal.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hanski","given":"Ilkka"},{"family":"Mononen","given":"Tommi"}],"container-title":"Ecology Letters","container-title-short":"Ecol Lett","DOI":"10.1111/j.1461-0248.2011.01671.x","ISSN":"1461-023X","issue":"10","issued":{"date-parts":[[2011,10]]},"page":"1025-1034","PMCID":"PMC3187866","PMID":"21794053","source":"PubMed Central","title":"Eco-evolutionary dynamics of dispersal in spatially heterogeneous environments","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3187866/","volume":"14"}, + {"id":"hanskiVariationMigrationPropensity2004","abstract":"Metapopulation dynamics lead to predictable patterns of habitat occupancy, population density and trophic structure in relation to landscape features such as habitat patch size and isolation. Comparable patterns may occur in behavioural, physiological and life-history traits but remain little studied. In the Glanville fritillary butterfly, females in newly established populations were more mobile than females in old populations. Among females from new populations, mobility decreased with increasing connectivity (decreasing isolation), but in females from old populations mobility increased with connectivity. The [ATP]/[ADP] ratio of flight muscles following controlled activity showed the same pattern as mobility in relation to population age and connectivity, suggesting that physiological differences in flight metabolic performance contribute to the observed variation in mobility. We demonstrate with an evolutionary metapopulation model parameterised for the Glanville fritillary that increasing spatial variation in landscape structure increases variance in mobility among individuals in a metapopulation, supporting the general notion that complex landscape structure maintains life-history variation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hanski","given":"Ilkka"},{"family":"Erälahti","given":"Claudia"},{"family":"Kankare","given":"Maaria"},{"family":"Ovaskainen","given":"Otso"},{"family":"Sirén","given":"Heli"}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2004.00654.x","ISSN":"1461-0248","issue":"10","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2004.00654.x","page":"958-966","source":"Wiley Online Library","title":"Variation in migration propensity among individuals maintained by landscape structure","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2004.00654.x","volume":"7"}, + {"id":"hartigConnectingDynamicVegetation2012","abstract":"Dynamic vegetation models provide process-based explanations of the dynamics and the distribution of plant ecosystems. They offer significant advantages over static, correlative modelling approaches, particularly for ecosystems that are outside their equilibrium due to global change or climate change. A persistent problem, however, is their parameterization. Parameters and processes of dynamic vegetation models (DVMs) are traditionally determined independently of the model, while model outputs are compared to empirical data for validation and informal model comparison only. But field data for such independent estimates of parameters and processes are often difficult to obtain, and the desire to include better descriptions of processes such as biotic interactions, dispersal, phenotypic plasticity and evolution in future vegetation models aggravates limitations related to the current parameterization paradigm. In this paper, we discuss the use of Bayesian methods to bridge this gap. We explain how Bayesian methods allow direct estimates of parameters and processes, encoded in prior distributions, to be combined with inverse estimates, encoded in likelihood functions. The combination of direct and inverse estimation of parameters and processes allows a much wider range of vegetation data to be used simultaneously, including vegetation inventories, species traits, species distributions, remote sensing, eddy flux measurements and palaeorecords. The possible reduction of uncertainty regarding structure, parameters and predictions of DVMs may not only foster scientific progress, but will also increase the relevance of these models for policy advice.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hartig","given":"Florian"},{"family":"Dyke","given":"James"},{"family":"Hickler","given":"Thomas"},{"family":"Higgins","given":"Steven I."},{"family":"O’Hara","given":"Robert B."},{"family":"Scheiter","given":"Simon"},{"family":"Huth","given":"Andreas"}],"container-title":"Journal of Biogeography","DOI":"10.1111/j.1365-2699.2012.02745.x","ISSN":"1365-2699","issue":"12","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2012.02745.x","page":"2240-2252","source":"Wiley Online Library","title":"Connecting dynamic vegetation models to data – an inverse perspective","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2699.2012.02745.x","volume":"39"}, + {"id":"hartigStatisticalInferenceStochastic2011","abstract":"Ecology Letters (2011) 14: 816–827 Abstract Statistical models are the traditional choice to test scientific theories when observations, processes or boundary conditions are subject to stochasticity. Many important systems in ecology and biology, however, are difficult to capture with statistical models. Stochastic simulation models offer an alternative, but they were hitherto associated with a major disadvantage: their likelihood functions can usually not be calculated explicitly, and thus it is difficult to couple them to well-established statistical theory such as maximum likelihood and Bayesian statistics. A number of new methods, among them Approximate Bayesian Computing and Pattern-Oriented Modelling, bypass this limitation. These methods share three main principles: aggregation of simulated and observed data via summary statistics, likelihood approximation based on the summary statistics, and efficient sampling. We discuss principles as well as advantages and caveats of these methods, and demonstrate their potential for integrating stochastic simulation models into a unified framework for statistical modelling.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hartig","given":"Florian"},{"family":"Calabrese","given":"Justin M."},{"family":"Reineking","given":"Björn"},{"family":"Wiegand","given":"Thorsten"},{"family":"Huth","given":"Andreas"}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2011.01640.x","ISSN":"1461-0248","issue":"8","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2011.01640.x","page":"816-827","source":"Wiley Online Library","title":"Statistical inference for stochastic simulation models – theory and application","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2011.01640.x","volume":"14"}, + {"id":"hastingsSpatialSpreadInvasions2005","abstract":"We review and synthesize recent developments in the study of the spread of invasive species, emphasizing both empirical and theoretical approaches. Recent theoretical work has shown that invasive species spread is a much more complex process than the classical models suggested, as long range dispersal events can have a large influence on the rate of range expansion through time. Empirical work goes even further, emphasizing the role of spatial heterogeneity, temporal variability, other species, and evolution. As in some of the classic work on spread, the study of range expansion of invasive species provides unique opportunities to use differences between theory and data to determine the important underlying processes that control spread rates.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hastings","given":"Alan"},{"family":"Cuddington","given":"Kim"},{"family":"Davies","given":"Kendi F."},{"family":"Dugaw","given":"Christopher J."},{"family":"Elmendorf","given":"Sarah"},{"family":"Freestone","given":"Amy"},{"family":"Harrison","given":"Susan"},{"family":"Holland","given":"Matthew"},{"family":"Lambrinos","given":"John"},{"family":"Malvadkar","given":"Urmila"},{"family":"Melbourne","given":"Brett A."},{"family":"Moore","given":"Kara"},{"family":"Taylor","given":"Caz"},{"family":"Thomson","given":"Diane"}],"container-title":"Ecology Letters","DOI":"10.1111/j.1461-0248.2004.00687.x","ISSN":"1461-0248","issue":"1","issued":{"date-parts":[[2005]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1461-0248.2004.00687.x","page":"91-101","source":"Wiley Online Library","title":"The spatial spread of invasions: new developments in theory and evidence","title-short":"The spatial spread of invasions","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1461-0248.2004.00687.x","volume":"8"}, + {"id":"haughlandExplorationCorrelatesSettlement2004","abstract":"1 Dispersers in heterogeneous habitat theoretically should target the habitat(s) where reproduction and survival (i.e. fitness) will be highest. However, the cues that dispersing animals respond to are not well understood: differences in habitat quality ultimately may be important, but whether animals respond to these differences may be influenced by their own familiarity with different habitats. 2 To determine if dispersers reacted to differences in habitat, we documented the exploratory movements, dispersal, and settlement patterns of juvenile North American red squirrels (Tamiasciurus hudsonicus) originating in adjacent patches of different habitats. 3 Dispersers originating in mature, closed-canopy forest (linked to higher female reproductive success and smaller territories) did not explore contrasting open forest with lower tree densities, and the magnitude of the dispersers’ explorations was relatively similar. In contrast, dispersers from the open forest habitat made explorations that carried them into contrasting, mature forest habitat, and their explorations were more variable across individuals. 4 When settlement occurred, it was strongly philopatric in all groups of dispersers, although the distances and directions favoured during the exploratory phase of dispersal remained strong predictors of where settlement occurred. Overall, processes favouring philopatry (i.e. maternal influences, competitive advantages, etc.) appeared to dominate the dispersal of our study animals, even those that were exposed to higher quality habitat during their explorations. 5 Secondarily, annual stochasticity (or some correlate) affected the scale of exploration and timing of settlement more than the relative quality of habitat in which dispersers were born. 6 Studies such as this that seek to understand the relative importance of individual experience, habitat familiarity, and habitat quality are important to ultimately understanding how individual animals and populations react to habitat heterogeneity.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Haughland","given":"Diane L."},{"family":"Larsen","given":"Karl W."}],"container-title":"Journal of Animal Ecology","DOI":"10.1111/j.0021-8790.2004.00884.x","ISSN":"1365-2656","issue":"6","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.0021-8790.2004.00884.x","page":"1024-1034","source":"Wiley Online Library","title":"Exploration correlates with settlement: red squirrel dispersal in contrasting habitats","title-short":"Exploration correlates with settlement","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.0021-8790.2004.00884.x","volume":"73"}, + {"id":"hauserDispersalClobertDanchin2001","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hauser","given":"Lorenz"}],"container-title":"Heredity","DOI":"10.1046/j.1365-2540.2001.0963a.x","ISSN":"1365-2540","issue":"4","issued":{"date-parts":[[2001]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1365-2540.2001.0963a.x","page":"508-508","source":"Wiley Online Library","title":"Dispersal. J. Clobert, E. Danchin, A. A. Dhondt and J. D. Nichols (eds). Oxford University Press, New York. 2001. pp. 452. Price £24.95, paperback. ISBN: 0-19-850659-7.","title-short":"Dispersal. J. Clobert, E. Danchin, A. A. Dhondt and J. D. Nichols (eds). Oxford University Press, New York. 2001. pp. 452. Price £24.95, paperback. ISBN","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1046/j.1365-2540.2001.0963a.x","volume":"87"}, + {"id":"hawkesLinkingMovementBehaviour2009","abstract":"1 Movement behaviour has become increasingly important in dispersal ecology and dispersal is central to the development of spatially explicit population ecology. The ways in which the elements have been brought together are reviewed with particular emphasis on dispersal distance distributions and the value of mechanistic models. 2 There is a continuous range of movement behaviours and in some species, dispersal is a clearly delineated event but not in others. The biological complexities restrict conclusions to high-level generalizations but there may be principles that are common to dispersal and other movements. 3 Random walk and diffusion models when appropriately elaborated can provide an understanding of dispersal distance relationships on spatial and temporal scales relevant to dispersal. Leptokurtosis in the relationships may be the result of a combination of factors including population heterogeneity, correlation, landscape features, time integration and density dependence. The inclusion in diffusion models of individual variation appears to be a useful elaboration. The limitations of the negative exponential and other phenomenological models are discussed. 4 The dynamics of metapopulation models are sensitive to what appears to be small differences in the assumptions about dispersal. In order to represent dispersal realistically in population models, it is suggested that phenomenological models should be replaced by those based on movement behaviour incorporating individual variation. 5 The conclusions are presented as a set of candidate principles for evaluation. The main features of the principles are that uncorrelated or correlated random walk, not linear movement, is expected where the directions of habitat patches are unpredictable and more complex behaviour when organisms have the ability to orientate or navigate. Individuals within populations vary in their movement behaviour and dispersal; part of this variation is a product of random elements in movement behaviour and some of it is heritable. Local and metapopulation dynamics are influenced by population heterogeneity in dispersal characteristics and heritable changes in dispersal propensity occur on time-scales short enough to impact population dynamics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hawkes","given":"Colin"}],"container-title":"Journal of Animal Ecology","DOI":"10.1111/j.1365-2656.2009.01534.x","ISSN":"1365-2656","issue":"5","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2656.2009.01534.x","page":"894-906","source":"Wiley Online Library","title":"Linking movement behaviour, dispersal and population processes: is individual variation a key?","title-short":"Linking movement behaviour, dispersal and population processes","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2656.2009.01534.x","volume":"78"}, + {"id":"heikkinenMethodsUncertaintiesBioclimatic2006","abstract":"Potential impacts of projected climate change on biodiversity are often assessed using single-species bioclimatic ‘envelope’models. Such models are a special case of species distribution models in which the current geographical distribution of species is related to climatic variables so to enable projections of distributions under future climate change scenarios. This work reviews a number of critical methodological issues that may lead to uncertainty in predictions from bioclimatic modelling. Particular attention is paid to recent developments of bioclimatic modelling that address some of these issues as well as to the topics where more progress needs to be made. Developing and applying bioclimatic models in a informative way requires good understanding of a wide range of methodologies, including the choice of modelling technique, model validation, collinearity, autocorrelation, biased sampling of explanatory variables, scaling and impacts of non-climatic factors. A key challenge for future research is integrating factors such as land cover, direct CO2 effects, biotic interactions and dispersal mechanisms into species-climate models. We conclude that, although bioclimatic envelope models have a number of important advantages, they need to be applied only when users of models have a thorough understanding of their limitations and uncertainties.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Heikkinen","given":"Risto K."},{"family":"Luoto","given":"Miska"},{"family":"Araújo","given":"Miguel B."},{"family":"Virkkala","given":"Raimo"},{"family":"Thuiller","given":"Wilfried"},{"family":"Sykes","given":"Martin T."}],"container-title":"Progress in Physical Geography: Earth and Environment","container-title-short":"Progress in Physical Geography: Earth and Environment","DOI":"10.1177/0309133306071957","ISSN":"0309-1333","issue":"6","issued":{"date-parts":[[2006,12,1]]},"language":"en","page":"751-777","publisher":"SAGE Publications Ltd","source":"SAGE Journals","title":"Methods and uncertainties in bioclimatic envelope modelling under climate change","type":"article-journal","URL":"https://doi.org/10.1177/0309133306071957","volume":"30"}, + {"id":"heinoEvolutionMigrationRate2001","abstract":"We use an individual-based, spatially realistic metapopulation model to study the evolution of migration rate. We first explore the consequences of habitat change in hypothetical patch networks on a regular lattice. If the primary consequence of habitat change is an increase in local extinction risk as a result of decreased local population sizes, migration rate increases. A nonmonotonic response, with migration rate decreasing at high extinction rate, was obtained only by assuming very frequent catastrophes. If the quality of the matrix habitat deteriorates, leading to increased mortality during migration, the evolutionary response is more complex. As long as habitat patch occupancy does not decrease markedly with increased migration mortality, reduced migration rate evolves. However, once mortality becomes so high that empty patches remain uncolonized for a long time, evolution tends to increase migration rate, which may lead to an \"evolutionary rescue\" in a fragmented landscape. Kin competition has a quantitative effect on the evolution of migration rate in our model, but these patterns in the evolution of migration rate appear to be primarily caused by spatiotemporal variation in fitness and mortality during migration. We apply the model to real habitat patch networks occupied by two checkerspot butterfly (Melitaea) species, for which sufficient data are available to estimate rigorously most of the model parameters. The model-predicted migration rate is not significantly different from the empirically observed one. Regional variation in patch areas and connectivities leads to regional variation in the optimal migration rate, predictions that can be tested empirically.","author":[{"family":"Heino","given":"M."},{"family":"Hanski","given":"I."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/319927","ISSN":"1537-5323","issue":"5","issued":{"date-parts":[[2001,5]]},"language":"eng","page":"495-511","PMID":"18707258","source":"PubMed","title":"Evolution of migration rate in a spatially realistic metapopulation model","type":"article-journal","volume":"157"}, + {"id":"heinoExtinctionRiskColoured2000","abstract":"Positively autocorrelated red environmental noise is characterized by a strong dependence of expected sample variance on sample length. This dependence has to be taken into account when assessing extinction risk under red and white uncorrelated environmental noise. To facilitate a comparison between red and white noise, their expected variances can be scaled to be equal, but only at a chosen time scale. We show with a simple one-dimensional population dynamics model that the different but equally reasonable choices of the time scale yield qualitatively different results on the dependence of extinction risk on the colour of environmental noise: extinction risk might increase as well as decrease when the temporal correlation of noise increases.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Heino","given":"Mikko"},{"family":"Ripa","given":"Jörgen"},{"family":"Kaitala","given":"Veijo"}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2000.tb00273.x","ISSN":"1600-0587","issue":"2","issued":{"date-parts":[[2000]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2000.tb00273.x","page":"177-184","source":"Wiley Online Library","title":"Extinction risk under coloured environmental noise","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2000.tb00273.x","volume":"23"}, + {"id":"heinoExtinctionRiskColoured2000a","abstract":"Positively autocorrelated red environmental noise is characterized by a strong dependence of expected sample variance on sample length. This dependence has to be taken into account when assessing extinction risk under red and white uncorrelated environmental noise. To facilitate a comparison between red and white noise, their expected variances can be scaled to be equal, but only at a chosen time scale. We show with a simple one-dimensional population dynamics model that the different but equally reasonable choices of the time scale yield qualitatively different results on the dependence of extinction risk on the colour of environmental noise: extinction risk might increase as well as decrease when the temporal correlation of noise increases.","accessed":{"date-parts":[[2021,8,10]]},"author":[{"family":"Heino","given":"Mikko"},{"family":"Ripa","given":"Jörgen"},{"family":"Kaitala","given":"Veijo"}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2000.tb00273.x","ISSN":"1600-0587","issue":"2","issued":{"date-parts":[[2000]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2000.tb00273.x","page":"177-184","source":"Wiley Online Library","title":"Extinction risk under coloured environmental noise","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2000.tb00273.x","volume":"23"}, + {"id":"heinzAdaptivePatchSearching2006","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Heinz","given":"S. K."},{"family":"Strand","given":"E."}],"container-title":"Evolutionary Ecology","issue":"20","issued":{"date-parts":[[2006]]},"page":"113-130","title":"Adaptive Patch Searching Strategies in Fragmented Landscapes","type":"article-journal","URL":"https://www.researchgate.net/publication/225577761_Adaptive_Patch_Searching_Strategies_in_Fragmented_Landscapes"}, + {"id":"hellmannInfluenceSpeciesInteractions2012","abstract":"The fossil record tells us that many species shifted their geographic distributions during historic climate changes, but this record does not portray the complete picture of future range change in response to climate change. In particular, it does not provide information on how species interactions will affect range shifts. Therefore, we also need modern research to generate understanding of range change. This paper focuses on the role that species interactions play in promoting or preventing geographic ranges shifts under current and future climate change, and we illustrate key points using empirical case studies from an integrated study system. Case studies can have limited generalizability, but they are critical to defining possible outcomes under climate change. Our case studies emphasize host limitation that could reduce range shifts and enemy release that could facilitate range expansion. We also need improvements in modeling that explicitly consider species interactions, and this modeling can be informed by empirical research. Finally, we discuss how species interactions have implications for range management by people.","author":[{"family":"Hellmann","given":"Jessica J."},{"family":"Prior","given":"Kirsten M."},{"family":"Pelini","given":"Shannon L."}],"container-title":"Annals of the New York Academy of Sciences","container-title-short":"Ann N Y Acad Sci","DOI":"10.1111/j.1749-6632.2011.06410.x","ISSN":"1749-6632","issued":{"date-parts":[[2012,2]]},"language":"eng","page":"18-28","PMID":"22329888","source":"PubMed","title":"The influence of species interactions on geographic range change under climate change","type":"article-journal","volume":"1249"}, + {"id":"henryEcoevolutionaryDynamicsRange2012","author":[{"family":"Henry","given":"Roslyn"},{"family":"Bocedi","given":"Greta"},{"family":"Travis","given":"Justin"}],"container-title":"Journal of theoretical biology","container-title-short":"Journal of theoretical biology","DOI":"10.1016/j.jtbi.2012.12.004","issued":{"date-parts":[[2012,12,11]]},"source":"ResearchGate","title":"Eco-evolutionary dynamics of range shifts: Elastic margins and critical thresholds","title-short":"Eco-evolutionary dynamics of range shifts","type":"article-journal","volume":"321"}, + {"id":"herefordQuantitativeSurveyLocal2009","abstract":"The long history of reciprocal transplant studies testing the hypothesis of local adaptation has shown that populations are often adapted to their local environments. Yet many studies have not demonstrated local adaptation, suggesting that sometimes native populations are no better adapted than are genotypes from foreign environments. Local adaptation may also lead to trade-offs, in which adaptation to one environment comes at a cost of adaptation to another environment. I conducted a survey of published studies of local adaptation to quantify its frequency and magnitude and the costs associated with local adaptation. I also quantified the relationship between local adaptation and environmental differences and the relationship between local adaptation and phenotypic divergence. The overall frequency of local adaptation was 0.71, and the magnitude of the native population advantage in relative fitness was 45%. Divergence between home site environments was positively associated with the magnitude of local adaptation, but phenotypic divergence was not. I found a small negative correlation between a population's relative fitness in its native environment and its fitness in a foreign environment, indicating weak trade-offs associated with local adaptation. These results suggest that populations are often locally adapted but stochastic processes such as genetic drift may limit the efficacy of divergent selection.","author":[{"family":"Hereford","given":"Joe"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/597611","ISSN":"1537-5323","issue":"5","issued":{"date-parts":[[2009,5]]},"language":"eng","page":"579-588","PMID":"19272016","source":"PubMed","title":"A quantitative survey of local adaptation and fitness trade-offs","type":"article-journal","volume":"173"}, + {"id":"higginsNicheBiologySpecies2012","abstract":"Why species are found where they are is a central question in biogeography. The most widely used tool for understanding the controls on distribution is species distribution modelling. Species distribution modelling is now a well-established method in both the theoretical and applied ecological literature. In this special issue we examine the current state of the art in species distribution modelling and explore avenues for including more biological processes in such models. In particular we focus on physiological, demographic, dispersal, competitive and ecological-modulation processes. This overview highlights opportunities for new species distribution model concepts and developments, as well as a statistical agenda for implementing such models.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Higgins","given":"Steven I."},{"family":"O'Hara","given":"Robert B."},{"family":"Römermann","given":"Christine"}],"container-title":"Journal of Biogeography","DOI":"10.1111/jbi.12029","ISSN":"1365-2699","issue":"12","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/jbi.12029","page":"2091-2095","source":"Wiley Online Library","title":"A niche for biology in species distribution models","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/jbi.12029","volume":"39"}, + {"id":"hobanComputerSimulationsTools2012","abstract":"Computer simulations are excellent tools for understanding the evolutionary and genetic consequences of complex processes whose interactions cannot be analytically predicted. Simulations have traditionally been used in population genetics by a fairly small community with programming expertise, but the recent availability of dozens of sophisticated, customizable software packages for simulation now makes simulation an accessible option for researchers in many fields. The in silico genetic data produced by simulations, along with greater availability of population-genomics data, are transforming genetic epidemiology, anthropology, evolutionary and population genetics and conservation. In this Review of the state-of-the-art of simulation software, we identify applications of simulations, evaluate simulator capabilities, provide a guide for their use and summarize future directions.","author":[{"family":"Hoban","given":"Sean"},{"family":"Bertorelle","given":"Giorgio"},{"family":"Gaggiotti","given":"Oscar E."}],"container-title":"Nature Reviews. Genetics","container-title-short":"Nat Rev Genet","DOI":"10.1038/nrg3130","ISSN":"1471-0064","issue":"2","issued":{"date-parts":[[2012,1,10]]},"language":"eng","page":"110-122","PMID":"22230817","source":"PubMed","title":"Computer simulations: tools for population and evolutionary genetics","title-short":"Computer simulations","type":"article-journal","volume":"13"}, + {"id":"hobbsEstimatesHabitatCarrying1985","abstract":"Presentation d'un algorithme pour estimer la densite supportable d'herbivores consommant des ressources alimentaires a des degres divers de qualite nutritive. Influence des brulis. On prend pour exemple Odocoileus hemionus et Ovis canadensis","author":[{"family":"Hobbs","given":"N."}],"DOI":"10.2307/3801716","issued":{"date-parts":[[1985]]},"source":"Semantic Scholar","title":"Estimates of habitat carrying capacity incorporating explicit nutritional constraints","type":"article-journal"}, + {"id":"hodgsonClimateChangeConnectivity2009a","abstract":"1. The challenge of climate change forces us to re-examine the assumptions underlying conservation planning. 2. Increasing ‘connectivity’ has emerged as the most favoured option for conservation in the face of climate change. 3. We argue that the importance of connectivity is being overemphasized: quantifying the benefits of connectivity per se is plagued with uncertainty, and connectivity can be co-incidentally improved by targeting more concrete metrics: habitat area and habitat quality. 4. Synthesis and applications. Before investing in connectivity projects, conservation practitioners should analyse the benefits expected to arise from increasing connectivity and compare them with alternative investments, to ensure as much biodiversity conservation and resilience to climate change as possible within their budget. Strategies that we expect to remain robust in the face of climate change include maintaining and increasing the area of high quality habitats, prioritizing areas that have high environmental heterogeneity and controlling other anthropogenic threatening processes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hodgson","given":"Jenny A."},{"family":"Thomas","given":"Chris D."},{"family":"Wintle","given":"Brendan A."},{"family":"Moilanen","given":"Atte"}],"container-title":"Journal of Applied Ecology","DOI":"10.1111/j.1365-2664.2009.01695.x","ISSN":"1365-2664","issue":"5","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2664.2009.01695.x","page":"964-969","source":"Wiley Online Library","title":"Climate change, connectivity and conservation decision making: back to basics","title-short":"Climate change, connectivity and conservation decision making","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2664.2009.01695.x","volume":"46"}, + {"id":"hodgsonHabitatAreaQuality2011a","abstract":"1. Population viability can depend on habitat area, habitat quality, the spatial arrangement of habitats (aggregations and connections) and the properties of the intervening non-breeding (matrix) land. Hodgson et al. [Journal of Applied Ecology46 (2009) 964] and Doerr, Barrett & Doerr (Journal of Applied Ecology, 2011) disagree on the relative importance of these landscape attributes in enabling species to persist and change their distributions in response to climate change. 2. A brief review of published evidence suggests that variations in habitat area and quality have bigger effects than variations in spatial arrangement of habitats or properties of the intervening land. Even if structural features in the matrix have a measurable effect on dispersal rates, this does not necessarily lead to significant increases in population viability. 3. Large and high-quality habitats provide source populations and locations for colonisation, so they are the main determinants of the capacity of species to shift their distributions in response to climate change because populations must be established successively in each new region. 4. Synthesis and applications. Retaining as much high quality natural and semi-natural habitat as possible should remain the key focus for conservation, especially during a period of climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hodgson","given":"Jenny A."},{"family":"Moilanen","given":"Atte"},{"family":"Wintle","given":"Brendan A."},{"family":"Thomas","given":"Chris D."}],"container-title":"Journal of Applied Ecology","DOI":"10.1111/j.1365-2664.2010.01919.x","ISSN":"1365-2664","issue":"1","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2664.2010.01919.x","page":"148-152","source":"Wiley Online Library","title":"Habitat area, quality and connectivity: striking the balance for efficient conservation","title-short":"Habitat area, quality and connectivity","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2664.2010.01919.x","volume":"48"}, + {"id":"hodgsonSpeedRangeShifts2012","abstract":"Species may be driven extinct by climate change, unless their populations are able to shift fast enough to track regions of suitable climate. Shifting will be faster as the proportion of suitable habitat in the landscape increases. However, it is not known how the spatial arrangement of habitat will affect the speed of range advance, especially when habitat is scarce, as is the case for many specialist species. We develop methods for calculating the speed of advance that are appropriate for highly fragmented, stochastic systems. We reveal that spatial aggregation of habitat tends to reduce the speed of advance throughout a wide range of species parameters: different dispersal distances and dispersal kernel shapes, and high and low extinction probabilities. In contrast, aggregation increases the steady-state proportion of habitat that is occupied (without climate change). Nonetheless, we find that it is possible to achieve both rapid advance and relatively high patch occupancy when the habitat has a “channeled” pattern, resembling corridors or chains of stepping stones. We adapt techniques from electrical circuit theory to predict the rate of advance efficiently for complex, realistic landscape patterns, whereas the rate cannot be predicted by any simple statistic of aggregation or fragmentation. Conservationists are already advocating corridors and stepping stones as important conservation tools under climate change, but they are vaguely defined and have so far lacked a convincing basis in fundamental population biology. Our work shows how to discriminate properties of a landscape's spatial pattern that affect the speed of colonization (including, but not limited to, patterns like corridors and chains of stepping stones), and properties that affect a species' probability of persistence once established. We can therefore point the way to better land use planning approaches, which will provide functional habitat linkages and also maintain local population viability.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hodgson","given":"Jenny A."},{"family":"Thomas","given":"Chris D."},{"family":"Dytham","given":"Calvin"},{"family":"Travis","given":"Justin M. J."},{"family":"Cornell","given":"Stephen J."}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0047141","ISSN":"1932-6203","issue":"10","issued":{"date-parts":[[2012,10,17]]},"language":"en","page":"e47141","publisher":"Public Library of Science","source":"PLoS Journals","title":"The Speed of Range Shifts in Fragmented Landscapes","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0047141","volume":"7"}, + {"id":"hodgsonSpeedRangeShifts2012a","abstract":"Species may be driven extinct by climate change, unless their populations are able to shift fast enough to track regions of suitable climate. Shifting will be faster as the proportion of suitable habitat in the landscape increases. However, it is not known how the spatial arrangement of habitat will affect the speed of range advance, especially when habitat is scarce, as is the case for many specialist species. We develop methods for calculating the speed of advance that are appropriate for highly fragmented, stochastic systems. We reveal that spatial aggregation of habitat tends to reduce the speed of advance throughout a wide range of species parameters: different dispersal distances and dispersal kernel shapes, and high and low extinction probabilities. In contrast, aggregation increases the steady-state proportion of habitat that is occupied (without climate change). Nonetheless, we find that it is possible to achieve both rapid advance and relatively high patch occupancy when the habitat has a “channeled” pattern, resembling corridors or chains of stepping stones. We adapt techniques from electrical circuit theory to predict the rate of advance efficiently for complex, realistic landscape patterns, whereas the rate cannot be predicted by any simple statistic of aggregation or fragmentation. Conservationists are already advocating corridors and stepping stones as important conservation tools under climate change, but they are vaguely defined and have so far lacked a convincing basis in fundamental population biology. Our work shows how to discriminate properties of a landscape's spatial pattern that affect the speed of colonization (including, but not limited to, patterns like corridors and chains of stepping stones), and properties that affect a species' probability of persistence once established. We can therefore point the way to better land use planning approaches, which will provide functional habitat linkages and also maintain local population viability.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hodgson","given":"Jenny A."},{"family":"Thomas","given":"Chris D."},{"family":"Dytham","given":"Calvin"},{"family":"Travis","given":"Justin M. J."},{"family":"Cornell","given":"Stephen J."}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0047141","ISSN":"1932-6203","issue":"10","issued":{"date-parts":[[2012,10,17]]},"language":"en","page":"e47141","publisher":"Public Library of Science","source":"PLoS Journals","title":"The Speed of Range Shifts in Fragmented Landscapes","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0047141","volume":"7"}, + {"id":"hoegh-guldbergAssistedColonizationRapid2008","abstract":"Moving species outside their historic ranges may mitigate loss of biodiversity in the face of global climate change.\nMoving species outside their historic ranges may mitigate loss of biodiversity in the face of global climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hoegh-Guldberg","given":"O."},{"family":"Hughes","given":"L."},{"family":"McIntyre","given":"S."},{"family":"Lindenmayer","given":"D. B."},{"family":"Parmesan","given":"C."},{"family":"Possingham","given":"H. P."},{"family":"Thomas","given":"C. D."}],"container-title":"Science","DOI":"10.1126/science.1157897","ISSN":"0036-8075, 1095-9203","issue":"5887","issued":{"date-parts":[[2008,7,18]]},"language":"en","page":"345-346","PMID":"18635780","publisher":"American Association for the Advancement of Science","section":"Policy Forum","source":"science.sciencemag.org","title":"Assisted Colonization and Rapid Climate Change","type":"article-journal","URL":"https://science.sciencemag.org/content/321/5887/345","volume":"321"}, + {"id":"hoffmannClimateChangeEvolutionary2011","abstract":"Natural populations are responding to global climate change by shifting their geographical distribution and the timing of their growth and reproduction, but for many species, such responses are likely to be inadequate to counter the speed and magnitude of climate change. Can evolutionary change help their cause? Ary Hoffmann and Carla Sgrò review the evidence for evolutionary adaptation in response to recent climate change and consider the implications for population and ecosystem management.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hoffmann","given":"Ary A."},{"family":"Sgrò","given":"Carla M."}],"container-title":"Nature","DOI":"10.1038/nature09670","ISSN":"1476-4687","issue":"7335","issued":{"date-parts":[[2011,2]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Reviews\nSubject_term: Climate-change adaptation;Genetic variation\nSubject_term_id: climate-change-adaptation;genetic-variation","number":"7335","page":"479-485","publisher":"Nature Publishing Group","source":"www.nature.com","title":"Climate change and evolutionary adaptation","type":"article-journal","URL":"https://www.nature.com/articles/nature09670","volume":"470"}, + {"id":"holtEvolutionaryEcologySpecies2003","abstract":"A species' range limits may shift in space either because of changes in ecological factors (e.g. climate, the abundances of interacting species) or because the traits which influence range limits (e.g. dispersal, niche characteristics) evolve by natural selection. In Geographical Ecology, Robert MacArthur (1972) provided a synthesis of the evolutionary factors that may drive range dynamics. In this paper, I revisit this theme in the light of recent theoretical studies of evolution in heterogeneous environments. These studies suggest that a rich range of evolutionary patterns in species' ranges may occur, including expansions or contractions, leading to dynamism in ranges even in epochs without strong directional environmental change.","author":[{"family":"Holt","given":"R."}],"container-title":"Evolutionary Ecology Research","container-title-short":"Evolutionary Ecology Research","issued":{"date-parts":[[2003,2,1]]},"page":"159-178","source":"ResearchGate","title":"On the evolutionary ecology of species' ranges","type":"article-journal","volume":"5"}, + {"id":"holtTheoreticalModelsSpecies2005","abstract":"The range of potential mechanisms limiting species' distributions in space is nearly as varied and complex as the diversity of life itself. Yet viewed abstractly, a species' border is a geographic manifestation of a species' demographic responses to a spatially and temporally varying world. Population dynamic models provide insight into the different routes by which range limits can arise owing to gradients in demographic rates. In a metapopulation context, for example, range limits may be caused by gradients in extinction rates, colonization rates or habitat availability. We have consider invasion models in uniform and heterogeneous environments as a framework for understanding non-equilibrium range limits, and explore conditions under which invasions may cease to spread leaving behind a stationary range limit. We conclude that non-equilibrial range dynamics need further theoretical and empirical attention.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Holt","given":"Robert D."},{"family":"Keitt","given":"Timothy H."},{"family":"Lewis","given":"Mark A."},{"family":"Maurer","given":"Brian A."},{"family":"Taper","given":"Mark L."}],"container-title":"Oikos","DOI":"10.1111/j.0030-1299.2005.13147.x","ISSN":"1600-0706","issue":"1","issued":{"date-parts":[[2005]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.0030-1299.2005.13147.x","page":"18-27","source":"Wiley Online Library","title":"Theoretical models of species’ borders: single species approaches","title-short":"Theoretical models of species’ borders","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.0030-1299.2005.13147.x","volume":"108"}, + {"id":"holyoakTrendsMissingParts2008","abstract":"Movement is important to all organisms, and accordingly it is addressed in a huge number of papers in the literature. Of nearly 26,000 papers referring to movement, an estimated 34% focused on movement by measuring it or testing hypotheses about it. This enormous amount of information is difficult to review and highlights the need to assess the collective completeness of movement studies and identify gaps. We surveyed 1,000 randomly selected papers from 496 journals and compared the facets of movement studied with a suggested framework for movement ecology, consisting of internal state (motivation, physiology), motion and navigation capacities, and external factors (both the physical environment and living organisms), and links among these components. Most studies simply measured and described the movement of organisms without reference to ecological or internal factors, and the most frequently studied part of the framework was the link between external factors and motion capacity. Few studies looked at the effects on movement of navigation capacity, or internal state, and those were mainly from vertebrates. For invertebrates and plants most studies were at the population level, whereas more vertebrate studies were conducted at the individual level. Consideration of only population-level averages promulgates neglect of between-individual variation in movement, potentially hindering the study of factors controlling movement. Terminology was found to be inconsistent among taxa and subdisciplines. The gaps identified in coverage of movement studies highlight research areas that should be addressed to fully understand the ecology of movement.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Holyoak","given":"Marcel"},{"family":"Casagrandi","given":"Renato"},{"family":"Nathan","given":"Ran"},{"family":"Revilla","given":"Eloy"},{"family":"Spiegel","given":"Orr"}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.0800483105","ISSN":"0027-8424, 1091-6490","issue":"49","issued":{"date-parts":[[2008,12,9]]},"language":"en","page":"19060-19065","PMID":"19060194","publisher":"National Academy of Sciences","section":"Review","source":"www.pnas.org","title":"Trends and missing parts in the study of movement ecology","type":"article-journal","URL":"https://www.pnas.org/content/105/49/19060","volume":"105"}, + {"id":"hovestadtAllInterpatchMovements2011","abstract":"1. In times of ongoing habitat fragmentation, the persistence of many species is determined by their dispersal abilities. Consequently, understanding the rules underlying movement between habitat patches is a key issue in conservation ecology. 2. We have analysed mark-release-recapture (MRR) data on inter-patches movements of the Dusky Large Blue butterfly Maculinea nausithous in a fragmented landscape in northern Bavaria, Germany. The aim of the analysis was to quantify distance dependence of dispersal as well as to evaluate the effect of target patch area on immigration probability. For statistical evaluation, we apply a 'reduced version' of the virtual migration model (VM), only fitting parameters for dispersal distance and immigration. In contrast to other analyses, we fit a mixed dispersal kernel to the MRR data. 3. A large fraction of recaptures happened in other habitat patches than those where individuals were initially caught. Further, we found significant evidence for the presence of a mixed dispersal kernel. The results indicate that individuals follow different strategies in their movements. Most movements are performed over small distances, nonetheless involving travelling between nearby habitat patches (median distance c. 480 m). A small fraction (c. 0·025) of the population has a tendency to move over larger distances (median distance c. 3800 m). Further, immigration was positively affected by patch area (I∼A(ζ) ), with the scaling parameter ζ = 0·5. 4. Our findings should help to resolve the long-lasting dispute over the suitability of the negative exponential function vs. inverse-power one for modelling dispersal. Previous studies on various organisms found that the former typically gives better overall fit to empirical distance distributions, but that the latter better represents long-distance movement probabilities. As long-distance movements are more important for landscape-level effects and thus, e.g. for conservation-oriented analyses like PVAs, fitting inverse-power kernels has often been preferred. 5. We conclude that the above discrepancy may simply stem from the fact that recorded inter-patch movements are an outcome of two different processes: daily routine movements and genuine dispersal. Consequently, applying mixed dispersal kernels to disentangle the two processes is recommended.","author":[{"family":"Hovestadt","given":"Thomas"},{"family":"Binzenhöfer","given":"Birgit"},{"family":"Nowicki","given":"Piotr"},{"family":"Settele","given":"Josef"}],"container-title":"The Journal of Animal Ecology","container-title-short":"J Anim Ecol","DOI":"10.1111/j.1365-2656.2011.01848.x","ISSN":"1365-2656","issue":"5","issued":{"date-parts":[[2011,9]]},"language":"eng","page":"1070-1077","PMID":"21585369","source":"PubMed","title":"Do all inter-patch movements represent dispersal? A mixed kernel study of butterfly mobility in fragmented landscapes","title-short":"Do all inter-patch movements represent dispersal?","type":"article-journal","volume":"80"}, + {"id":"hovestadtEvolutionEmergenceDispersal2012","abstract":"This chapter discusses hypothetical kernels for single individuals since this kernel defines the long-term average success of a dispersal strategy, and is the ultimate target of selection; consequently, it is the appropriate definition in the context of models of dispersal. It is vital to have a detailed knowledge of dispersal kernels when predicting the expansion of invasive species, for example, or the recolonisation of sites in fragmented landscapes. The chapter starts with a definition of the term ‘dispersal kernel’, as its definition is not consistent throughout the literature. There is ambiguity in certain respects. Firstly, it has been used to describe the density probability density function. Secondly, it has been used as the summary description of dispersal events for a whole population or of a single individual. Finally, it has also been used as the statistical description of real dispersal data or of a ‘hypothetical’ kernel from which a single dispersal event is drawn as a random realization.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hovestadt","given":"Thomas"},{"family":"Bonte","given":"Dries"},{"family":"Dytham","given":"Calvin"},{"family":"Poethke","given":"Hans Joachim"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0016","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Evolution and emergence of dispersal kernels—a brief theoretical evaluation","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-16"}, + {"id":"hovestadtEvolutionReducedDispersal2001","abstract":"Models describing the evolution of dispersal strategies have mostly focused on the evolution of dispersal rates. Taking trees as a model for organisms with undirected, passive dispersal, we have developed an individual-based, spatially explicit simulation tool to investigate the evolution of the dispersal kernel, P(r), and its resulting cumulative seed-density distribution, D(r). Simulations were run on a variety of fractal landscapes differing in the fraction of suitable habitat and the spatial autocorrelation. Starting from a uniform D(r), evolution led to an increase in the fraction of seeds staying in the home cell, a reduction of the dispersal mortality (arrival in unsuitable habitat), and the evolution of 'fat-tailed' D(r) in autocorrelated landscapes and approximately uniform D(r) in random landscapes. The evolutionary process was characterized by long periods of stasis with a few bouts of rapid change in the dispersal rate.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hovestadt","given":"T."},{"family":"Messner","given":"S."},{"family":"Poethke","given":"H. J."}],"container-title":"Proceedings of the Royal Society B: Biological Sciences","container-title-short":"Proc Biol Sci","DOI":"10.1098/rspb.2000.1379","ISSN":"0962-8452","issue":"1465","issued":{"date-parts":[[2001,2,22]]},"page":"385-391","PMCID":"PMC1088618","PMID":"11270435","source":"PubMed Central","title":"Evolution of reduced dispersal mortality and 'fat-tailed' dispersal kernels in autocorrelated landscapes.","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1088618/","volume":"268"}, + {"id":"hovestadtInformationProcessingModels2010","abstract":"Density-dependent emigration has been recognized as a fitness enhancing strategy. Yet, especially in the modelling literature there is no consensus about how density-dependent emigration should quantitatively be incorporated into metapopulation models. In this paper we compare the performance of five different dispersal strategies (defined by the functional link between density and emigration probability). Four of these strategies are based on published functional relationships between local population density and emigration probability, one assumes density-independent dispersal. We use individual-based simulations of time-discrete metapopulation dynamics and conduct evolution experiments for a broad range of values for dispersal mortality and environmental stochasticity. For each set of these conditions we analyze the evolution of emigration rates in ‘monoculture experiments’ (with only one type of dispersal strategy used by all individuals in the metapopulation) as well as in selection experiments that allow a pair-wise comparison of the performance of each functional type. We find that a single-parameter ‘asymptotic threshold’ strategy – derived from the marginal value theorem – with a decelerating increase of emigration rate with increasing population density, out-competes any other strategy, i.e. density-independent emigration, a ‘linear threshold’ strategy and a flexible three-parameter strategy. Only when environmental conditions select for extremely high emigration probabilities (close to one), strategies may perform approximately equally. A simple threshold strategy derived for the case of continuous population growth performs even worse than the density-independent strategy. As the functional type of the dispersal function implemented in metapopulation models may severely affect predictions concerning the survival of populations, range expansion, or community changes we clearly recommend to carefully select adequate functions to model density-dependent dispersal.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hovestadt","given":"Thomas"},{"family":"Kubisch","given":"Alexander"},{"family":"Poethke","given":"Hans-Joachim"}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/j.ecolmodel.2009.11.005","ISSN":"0304-3800","issue":"3","issued":{"date-parts":[[2010,2,10]]},"language":"en","page":"405-410","source":"ScienceDirect","title":"Information processing in models for density-dependent emigration: A comparison","title-short":"Information processing in models for density-dependent emigration","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0304380009007510","volume":"221"}, + {"id":"hughesEvolutionaryTradeoffsReproduction2003","abstract":"During recent climate warming, some species have expanded their ranges northwards to keep track of climate changes. Evolutionary changes in dispersal have been demonstrated in these expanding populations and here we show that increased dispersal is associated with reduced investment in reproduction in populations of the speckled wood butterfly, Pararge aegeria. Evolutionary changes in flight versus reproduction will affect the pattern and rate of expansion at range boundaries in the future, and understanding these responses will be crucial for predicting the distribution of species in the future as climates continue to warm.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hughes","given":"Clare L."},{"family":"Hill","given":"Jane K."},{"family":"Dytham","given":"Calvin"}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rsbl.2003.0049","issue":"suppl_2","issued":{"date-parts":[[2003,11,7]]},"page":"S147-S150","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Evolutionary trade-offs between reproduction and dispersal in populations at expanding range boundaries","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rsbl.2003.0049","volume":"270"}, + {"id":"hughesModellingAnalysingEvolution2007","abstract":"1. Species would be expected to shift northwards in response to current climate warming, but many are failing to do so because of fragmentation of breeding habitats. Dispersal is important for colonisation and an individual-based spatially explicit model was developed to investigate impacts of habitat availability on the evolution of dispersal in expanding populations. Model output was compared with field data from the speckled wood butterfly Pararge aegeria, which currently is expanding its range in Britain. 2. During range expansion, models simulated positive linear relationships between dispersal and distance from the seed location. This pattern was observed regardless of quantity (100% to 10% habitat availability) or distribution (random vs. gradient distribution) of habitat, although higher dispersal evolved at expanding range margins in landscapes with greater quantity of habitat and in gradient landscapes. Increased dispersal was no longer evident in any landscape once populations had reached equilibrium; dispersal values returned to those of seed populations. However, in landscapes with the least quantity of habitat, reduced dispersal (below that of seed populations) was observed at equilibrium. 3. Evolutionary changes in adult flight morphology were examined in six populations of P. aegeria along a transect from the distribution core to an expanding range margin in England (spanning a latitudinal distance of >200 km). Empirical data were in agreement with model output and showed increased dispersal ability (larger and broader thoraxes, smaller abdomens, higher wing aspect ratios) with increasing distance from the distribution core. Increased dispersal ability was evident in populations from areas colonised >30 years previously, although dispersal changes were generally evident only in females. 4. Evolutionary increases in dispersal ability in expanding populations may help species track future climate changes and counteract impacts of habitat fragmentation by promoting colonisation. However, at the highest levels of habitat loss, increased dispersal was less evident during expansion and reduced dispersal was observed at equilibrium indicating that, for many species, continued habitat fragmentation is likely to outweigh any benefits from dispersal.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Hughes","given":"Clare L."},{"family":"Dytham","given":"Calvin"},{"family":"Hill","given":"Jane K."}],"container-title":"Ecological Entomology","DOI":"10.1111/j.1365-2311.2007.00890.x","ISSN":"1365-2311","issue":"5","issued":{"date-parts":[[2007]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2311.2007.00890.x","page":"437-445","source":"Wiley Online Library","title":"Modelling and analysing evolution of dispersal in populations at expanding range boundaries","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2311.2007.00890.x","volume":"32"}, + {"id":"huntleyBioclimaticEnvelopesDynamic2010","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Huntley","given":"Brian"},{"family":"Barnard","given":"Phoebe"},{"family":"Altwegg","given":"Res"},{"family":"Chambers","given":"Lynda"},{"family":"Coetzee","given":"Bernard W. T."},{"family":"Gibson","given":"Lesley"},{"family":"Hockey","given":"Philip A. R."},{"family":"Hole","given":"David G."},{"family":"Midgley","given":"Guy F."},{"family":"Underhill","given":"Les G."},{"family":"Willis","given":"Stephen G."}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2009.06023.x","ISSN":"1600-0587","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2009.06023.x","page":"621-626","source":"Wiley Online Library","title":"Beyond bioclimatic envelopes: dynamic species' range and abundance modelling in the context of climatic change","title-short":"Beyond bioclimatic envelopes","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2009.06023.x","volume":"33"}, + {"id":"jeltschIntegratingMovementEcology2013a","abstract":"Movement of organisms is one of the key mechanisms shaping biodiversity, e.g. the distribution of genes, individuals and species in space and time. Recent technological and conceptual advances have improved our ability to assess the causes and consequences of individual movement, and led to the emergence of the new field of ‘movement ecology’. Here, we outline how movement ecology can contribute to the broad field of biodiversity research, i.e. the study of processes and patterns of life among and across different scales, from genes to ecosystems, and we propose a conceptual framework linking these hitherto largely separated fields of research. Our framework builds on the concept of movement ecology for individuals, and demonstrates its importance for linking individual organismal movement with biodiversity. First, organismal movements can provide ‘mobile links’ between habitats or ecosystems, thereby connecting resources, genes, and processes among otherwise separate locations. Understanding these mobile links and their impact on biodiversity will be facilitated by movement ecology, because mobile links can be created by different modes of movement (i.e., foraging, dispersal, migration) that relate to different spatiotemporal scales and have differential effects on biodiversity. Second, organismal movements can also mediate coexistence in communities, through ‘equalizing’ and ‘stabilizing’ mechanisms. This novel integrated framework provides a conceptual starting point for a better understanding of biodiversity dynamics in light of individual movement and space-use behavior across spatiotemporal scales. By illustrating this framework with examples, we argue that the integration of movement ecology and biodiversity research will also enhance our ability to conserve diversity at the genetic, species, and ecosystem levels.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Jeltsch","given":"Florian"},{"family":"Bonte","given":"Dries"},{"family":"Pe'er","given":"Guy"},{"family":"Reineking","given":"Björn"},{"family":"Leimgruber","given":"Peter"},{"family":"Balkenhol","given":"Niko"},{"family":"Schröder","given":"Boris"},{"family":"Buchmann","given":"Carsten M."},{"family":"Mueller","given":"Thomas"},{"family":"Blaum","given":"Niels"},{"family":"Zurell","given":"Damaris"},{"family":"Böhning-Gaese","given":"Katrin"},{"family":"Wiegand","given":"Thorsten"},{"family":"Eccard","given":"Jana A."},{"family":"Hofer","given":"Heribert"},{"family":"Reeg","given":"Jette"},{"family":"Eggers","given":"Ute"},{"family":"Bauer","given":"Silke"}],"container-title":"Movement Ecology","container-title-short":"Movement Ecology","DOI":"10.1186/2051-3933-1-6","ISSN":"2051-3933","issue":"1","issued":{"date-parts":[[2013,8,5]]},"page":"6","source":"BioMed Central","title":"Integrating movement ecology with biodiversity research - exploring new avenues to address spatiotemporal biodiversity dynamics","type":"article-journal","URL":"https://doi.org/10.1186/2051-3933-1-6","volume":"1"}, + {"id":"johstExtinctionRiskTemporally1997","abstract":"Usually extinction risk due to environmental stochasticity is estimated under the assumption of white environmental noise. This holds for a sufficiently short correlation time tauc of the fluctuations compared to the internal time scale of population growth r-1 (tauc/r-1<<1). Using a time-discrete simulation model we investigate when the white noise approximation is misleading. Environmental fluctuations are related to fluctuations of the birth and death rates of the species and the temporal correlation of these fluctuations (coloured noise) is described by a first-order autoregressive process. We found that extinction risk increases rapidly with correlation time tauc if the strength of noise is large. In this case the white noise approximation underestimates extinction risk essentially unless temporal correlation is very small (tauc/r-1<<0.1). Extinction risk increases only slowly with correlation time if the strength of noise is small. Then the white noise approximation may be used even for stronger temporal correlations (tauc/r-1>/=0.1). Thus, the estimation of extinction risk on the basis of white or coloured noise must be justified by time scale and strength of the fluctuations. Especially for species that are sensitive to environmental fluctuations the applicability of the white noise approximation should be carefully checked.","author":[{"family":"Johst","given":"K."},{"family":"Wissel","given":"C."}],"container-title":"Theoretical Population Biology","container-title-short":"Theor Popul Biol","DOI":"10.1006/tpbi.1997.1322","ISSN":"0040-5809","issue":"2","issued":{"date-parts":[[1997,10]]},"language":"eng","page":"91-100","PMID":"9356326","source":"PubMed","title":"Extinction risk in a temporally correlated fluctuating environment","type":"article-journal","volume":"52"}, + {"id":"johstMetapopulationPersistenceDynamic2002","abstract":"Species associated with transient habitats need efficient dispersal strategies to ensure their regional survival. Using a spatially explicit metapopulation model, we studied the effect of the dispersal range on the persistence of a metapopulation as a function of the local population and landscape dynamics (including habitat patch destruction and subsequent regeneration). Our results show that the impact of the dispersal range depends on both the local population and patch growth. This is due to interactions between dispersal and the dynamics of patches and populations via the number of potential dispersers. In general, long-range dispersal had a positive effect on persistence in a dynamic landscape compared to short-range dispersal. Long-range dispersal increases the number of couplings between the patches and thus the colonisation of regenerated patches. However, long-range dispersal lost its advantage for long-term persistence when the number of potential dispersers was low due to small population growth rates and/or small patch growth rates. Its advantage also disappeared with complex local population dynamics and in a landscape with clumped patch distribution.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Johst","given":"Karin"},{"family":"Brandl","given":"Roland"},{"family":"Eber","given":"Sabine"}],"container-title":"Oikos","DOI":"10.1034/j.1600-0706.2002.980208.x","ISSN":"1600-0706","issue":"2","issued":{"date-parts":[[2002]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1034/j.1600-0706.2002.980208.x","page":"263-270","source":"Wiley Online Library","title":"Metapopulation persistence in dynamic landscapes: the role of dispersal distance","title-short":"Metapopulation persistence in dynamic landscapes","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1034/j.1600-0706.2002.980208.x","volume":"98"}, + {"id":"jongejansDispersalDemographySpatial2008","abstract":"Spatial population dynamics can seldom be ignored in management aimed at conserving or controlling plant species in a spatial context. Therefore, spatial population models, that bring together knowledge about a species’ local demography and dispersal behavior, are of growing applied importance. Here, we survey increasingly complex analytical and simulation models that are being developed to describe both demography and dispersal in applied studies. Local population dynamics can be modeled in an unstructured way, by specifying age- or stage-structure or by modeling each individual. Dispersal is often summarized in population-spread models with descriptive and simple statistical models. Mechanistic models that incorporate the physical or behavioral dynamics of dispersal vectors, however, provide more insight and can more readily be applied to novel situations. Importantly, mechanistic models provide a tool for linking variation in species traits and environments to dispersal and population spread. Spatial population models span a wide range: from diffusion models, metapopulation models, integrodifference equation models, and Neubert–Caswell models, to spatially explicit individual-based models. The complexity (and biological realism) of such models often trades off with tractability: for instance, individual-based simulation models allow for unlimited incorporation of biological detail, but rarely for analytical exploration of the model dynamics. We discuss the advantages and disadvantages of these various spatial population models; the choice of the most appropriate model will depend on the management objective, the biological complexity, available data and the principle of parsimony. We present five case studies of endangered and invasive species for which spatial population models have been developed to inform management, for instance to decrease the spread rate of invasive species or to improve the regional persistence of endangered species. We also anticipate exciting new developments in both spatial analytical and spatial simulation models with increasing demographic, dispersal and spatial sophistication.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Jongejans","given":"Eelke"},{"family":"Skarpaas","given":"Olav"},{"family":"Shea","given":"Katriona"}],"collection-title":"Space matters - Novel developments in plant ecology through spatial modelling","container-title":"Perspectives in Plant Ecology, Evolution and Systematics","container-title-short":"Perspectives in Plant Ecology, Evolution and Systematics","DOI":"10.1016/j.ppees.2007.09.005","ISSN":"1433-8319","issue":"3","issued":{"date-parts":[[2008,3,6]]},"language":"en","page":"153-170","source":"ScienceDirect","title":"Dispersal, demography and spatial population models for conservation and control management","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S1433831907000467","volume":"9"}, + {"id":"keithPredictingExtinctionRisks2008","abstract":"Species responses to climate change may be influenced by changes in available habitat, as well as population processes, species interactions and interactions between demographic and landscape dynamics. Current methods for assessing these responses fail to provide an integrated view of these influences because they deal with habitat change or population dynamics, but rarely both. In this study, we linked a time series of habitat suitability models with spatially explicit stochastic population models to explore factors that influence the viability of plant species populations under stable and changing climate scenarios in South African fynbos, a global biodiversity hot spot. Results indicate that complex interactions between life history, disturbance regime and distribution pattern mediate species extinction risks under climate change. Our novel mechanistic approach allows more complete and direct appraisal of future biotic responses than do static bioclimatic habitat modelling approaches, and will ultimately support development of more effective conservation strategies to mitigate biodiversity losses due to climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Keith","given":"David A"},{"family":"Akçakaya","given":"H. Resit"},{"family":"Thuiller","given":"Wilfried"},{"family":"Midgley","given":"Guy F"},{"family":"Pearson","given":"Richard G"},{"family":"Phillips","given":"Steven J"},{"family":"Regan","given":"Helen M"},{"family":"Araújo","given":"Miguel B"},{"family":"Rebelo","given":"Tony G"}],"container-title":"Biology Letters","DOI":"10.1098/rsbl.2008.0049","issue":"5","issued":{"date-parts":[[2008,10,23]]},"page":"560-563","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Predicting extinction risks under climate change: coupling stochastic population models with dynamic bioclimatic habitat models","title-short":"Predicting extinction risks under climate change","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/abs/10.1098/rsbl.2008.0049","volume":"4"}, + {"id":"kendallUnstructuredIndividualVariation2003","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Kendall","given":"Bruce E."},{"family":"Fox","given":"Gordon A."}],"container-title":"Conservation Biology","ISSN":"0888-8892","issue":"4","issued":{"date-parts":[[2003]]},"page":"1170-1172","publisher":"[Wiley, Society for Conservation Biology]","source":"JSTOR","title":"Unstructured Individual Variation and Demographic Stochasticity","type":"article-journal","URL":"https://www.jstor.org/stable/3588875","volume":"17"}, + {"id":"knowltonUsingBehavioralLandscape2010","abstract":"Climate change and habitat destruction are widely recognized as major threats to species’ survival. As a result of these anthropogenic impacts, species are often forced into novel landscapes where their persistence is difficult to predict. Knowledge of how individuals move or disperse through the landscape, choose habitat in which to settle, and produce offspring which survive to repeat the process can greatly improve our ability to predict species’ persistence. The field of behavioral landscape ecology uses a strong theoretical base to explore, often experimentally, how the behavior of a particular species is affected by heterogeneous and rapidly changing landscapes and can offer valuable insight for managing species in the face of human-induced environmental changes. When interpreted by modelers, results of landscape-level behavioral experiments can be quantified for use in predictive models. To this end, we summarize the methods and results of research using direct experimental manipulation techniques broken into the following categories: translocations, playback experiments, food resource manipulations, manipulations of reproductive success, direct manipulations of the landscape, and manipulations of predation risk. We review and place in a theoretical framework the results from this emerging body of research regarding how organisms move in and respond to different types of landscapes, both natural and human-altered. We go onto highlight the potential of each experimental method to quantify different processes, which may be useful when interpreted by modelers attempting to parameterize predictive models. Finally, we suggest future directions for experimental research that will allow for greater integration of behavioral landscape ecology and predictive modeling.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Knowlton","given":"Jessie L."},{"family":"Graham","given":"Catherine H."}],"container-title":"Biological Conservation","container-title-short":"Biological Conservation","DOI":"10.1016/j.biocon.2010.03.011","ISSN":"0006-3207","issue":"6","issued":{"date-parts":[[2010,6,1]]},"language":"en","page":"1342-1354","source":"ScienceDirect","title":"Using behavioral landscape ecology to predict species’ responses to land-use and climate change","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S000632071000100X","volume":"143"}, + {"id":"kokkoIndividualDispersalSpecies2006","abstract":"Dispersal is often risky to the individual, yet the long-term survival of populations depends on having a sufficient number of individuals that move, find each other, and locate suitable breeding habitats. This tension has consequences that rarely meet our conservation or management goals. This is particularly true in changing environments, which makes the study of dispersal urgently topical in a world plagued with habitat loss, climate change, and species introductions. Despite the difficulty of tracking mobile individuals over potentially vast ranges, recent research has revealed a multitude of ways in which dispersal evolution can either constrain, or accelerate, species' responses to environmental changes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Kokko","given":"Hanna"},{"family":"López-Sepulcre","given":"Andrés"}],"container-title":"Science","DOI":"10.1126/science.1128566","ISSN":"0036-8075, 1095-9203","issue":"5788","issued":{"date-parts":[[2006,8,11]]},"language":"en","page":"789-791","PMID":"16902127","publisher":"American Association for the Advancement of Science","section":"Special Perspectives","source":"science.sciencemag.org","title":"From Individual Dispersal to Species Ranges: Perspectives for a Changing World","title-short":"From Individual Dispersal to Species Ranges","type":"article-journal","URL":"https://science.sciencemag.org/content/313/5788/789","volume":"313"}, + {"id":"kramer-schadtFragmentedLandscapesRoad2004","abstract":"1 Although many reintroduction schemes for the Eurasian lynx Lynx lynx in Germany have been discussed, the implications of connectivity between suitable patches have not been assessed. 2 We introduce an individual-based, spatially explicit dispersal model to assess the probability of a dispersing animal reaching another suitable patch in the complex heterogeneous German landscape, with its dense transport system. The dispersal model was calibrated using telemetric data from the Swiss Jura and based on a map of potential lynx dispersal habitat. 3 Most suitable patches could be interconnected by movements of dispersing lynx within 10 years of reintroduction. However, when realistic levels of mortality risks on roads were applied, most patches become isolated except along the German–Czech border. Consequently, patch connectivity is limited not so much by the distribution of dispersal habitat but by the high mortality of dispersing lynx. Accordingly, rather than solely investing in habitat restoration, management efforts should try to reduce road mortality. 4 Synthesis and applications. Our approach illustrates how spatially explicit dispersal models can guide conservation efforts and reintroduction programmes even where data are scarce. Clear limits imposed by substantial road mortality will affect dispersing lynx as well as other large carnivores, unless offset by careful road-crossing management or by the careful selection of release points in reintroduction programmes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Kramer-Schadt","given":"Stephanie"},{"family":"Revilla","given":"Eloy"},{"family":"Wiegand","given":"Thorsten"},{"family":"Breitenmoser","given":"Urs"}],"container-title":"Journal of Applied Ecology","DOI":"10.1111/j.0021-8901.2004.00933.x","ISSN":"1365-2664","issue":"4","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.0021-8901.2004.00933.x","page":"711-723","source":"Wiley Online Library","title":"Fragmented landscapes, road mortality and patch connectivity: modelling influences on the dispersal of Eurasian lynx","title-short":"Fragmented landscapes, road mortality and patch connectivity","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.0021-8901.2004.00933.x","volume":"41"}, + {"id":"krosbyEcologicalConnectivityChanging2010a","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"KROSBY","given":"MEADE"},{"family":"TEWKSBURY","given":"JOSHUA"},{"family":"HADDAD","given":"NICK M."},{"family":"HOEKSTRA","given":"JONATHAN"}],"container-title":"Conservation Biology","ISSN":"0888-8892","issue":"6","issued":{"date-parts":[[2010]]},"page":"1686-1689","publisher":"[Wiley, Society for Conservation Biology]","source":"JSTOR","title":"Ecological Connectivity for a Changing Climate","type":"article-journal","URL":"https://www.jstor.org/stable/40925337","volume":"24"}, + {"id":"kubischDensitydependentDispersalFormation2011","abstract":"Knowledge about the mechanisms of range formation is crucial for scientifically based species conservation strategies in the face of ongoing global climate change. In recent years an increasing amount of studies have focused on the influences of density-dependent dispersal on demographic and biogeographical patterns. However, it still remains unclear, to what extent and in what ways this strategy would affect the range formation of species. In order to fill this gap, we present a study using individual-based simulations of a species with discrete generations living along a dispersal mortality gradient. We compare the evolution of range sizes for species following density-dependent and density-independent emigration. Furthermore we assess the influence of environmental stochasticity and Allee effects on range formation, as both processes are known to play an important role for dispersal evolution. We find that density-dependent dispersal always results in much wider ranges than unconditional dispersal. Increasing environmental stochasticity, a predicted consequence of climate change, can remarkably expand the ranges of species living in such connectivity gradients if dispersal decisions are based on local population density. A strong Allee effect causes range contraction for both strategies, but the effect is considerably less dramatic under density-dependent compared to density-independent emigration. We strongly recommend accounting for these findings in future attempts to model species' range shifts due to climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Kubisch","given":"Alexander"},{"family":"Poethke","given":"Hans-Joachim"},{"family":"Hovestadt","given":"Thomas"}],"container-title":"Ecography","ISSN":"0906-7590","issue":"6","issued":{"date-parts":[[2011]]},"page":"1002-1008","publisher":"Wiley","source":"JSTOR","title":"Density-dependent dispersal and the formation of range borders","type":"article-journal","URL":"https://www.jstor.org/stable/41315778","volume":"34"}, + {"id":"kubischElasticityRangeLimits2010","abstract":"Dispersal is known to play a crucial role in the formation of species' ranges. Recent studies demonstrate that dispersiveness increases rapidly during the range expansion of species due to a fitness increase for dispersers at the expanding front. R. D. Holt concluded, however, that emigration should decline after the period of invasion and hence predicted some range contraction following the initial expansion phase. In this study, we evaluate this hypothesis using a spatially explicit individual-based model of populations distributed along environmental gradients. In our experiments we allow the species to spread along a gradient of declining conditions. Results show that range contraction did emerge in a gradient of dispersal mortality, caused by the rapid increase in emigration probability during invasion and selection disfavoring dispersal, once a stable range is formed. However, gradients in growth rate, local extinction rate, and patch capacity did not lead to a noticeable contraction of the range. We conclude, that the phenomenon of range contraction may emerge, but only under conditions that select for a reduction in dispersal at the range edge in comparison to the core region once the expansion period is over.","author":[{"family":"Kubisch","given":"Alexander"},{"family":"Hovestadt","given":"Thomas"},{"family":"Poethke","given":"Hans-Joachim"}],"container-title":"Ecology","container-title-short":"Ecology","DOI":"10.1890/09-2022.1","ISSN":"0012-9658","issue":"10","issued":{"date-parts":[[2010,10]]},"language":"eng","page":"3094-3099","PMID":"21058568","source":"PubMed","title":"On the elasticity of range limits during periods of expansion","type":"article-journal","volume":"91"}, + {"id":"kubischPredictingRangeShifts2013","abstract":"Bioclimate envelope models (BEMs) have often been criticized as being too simplistic due to e.g. not incorporating effects of biotic interactions or evolutionary adaptation. However, BEMs are widely applied and have proven to be often useful. Here we investigate, under which conditions evolution of dispersal, local adaptation or interspecific competition may be of minor importance for forecasting future range shifts. Therefore we use individual-based simulations of metapopulations under climate change living in spatial temperature gradients. Scenarios incorporate single-species systems or systems with competing species, respectively. Dispersal rate is evolving and adaptation to local conditions may also evolve in some scenarios. Results show that in single-species scenarios excluding evolutionary adaptation, species either follow optimal habitat conditions or go extinct if habitat connectivity is too low. These simulations are in close accordance to predictions from BEMs. Including evolutionary adaptation qualitatively changes these results. In the absence of competing species the species either completely invades the world or goes extinct. With competitors, results strongly depend on habitat fragmentation. For highly connected habitats the range border may shift as predicted by BEMs, for intermediate connectivity it will lag behind, while species will go extinct if fragmentation is too high. Our results indicate that (simple) BEMs may work well if habitats are well connected and species will not encounter many difficulties in dispersing to new sites. Selection in this case may promote evolution of even higher dispersal activities. We thus show that the presence of biotic interactions may be ignored for predictions of range shifts when high dispersal can be expected.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Kubisch","given":"Alexander"},{"family":"Degen","given":"Tobias"},{"family":"Hovestadt","given":"Thomas"},{"family":"Poethke","given":"Hans Joachim"}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2012.00062.x","ISSN":"1600-0587","issue":"8","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2012.00062.x","page":"873-882","source":"Wiley Online Library","title":"Predicting range shifts under global change: the balance between local adaptation and dispersal","title-short":"Predicting range shifts under global change","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2012.00062.x","volume":"36"}, + {"id":"kubischRangeBorderFormation2011","abstract":"Questions: How will a change in climatic conditions characterized by an increase in the variance of environmental conditions affect the distribution of species along spatial environmental gradients? How does the specific type of gradient influence their response? Features of the model: Spatially explicit individual-based simulation of a metapopulation. Logistic population growth and density-dependent emigration. Spatial gradients in habitat isolation, quality, and size. Ranges of the key variables: Environmental stochasticity was modelled as a variation of net reproductive rate (lambda). For a mean reproductive rate of lambda = 2, the standard deviation (sigma) was varied in the range of 0 to 3. Conclusions: When the range margin was predominantly determined by a lack of colonizers, ranges initially expanded with increasing environmental fluctuations, but contracted again when these fluctuations became too strong (sigma textgreater 1). When extinction risk was more important for range formation, the initial expansion was damped or completely absent. When the climate changed too fast to allow for local adaptation of dispersal behaviour, the described patterns were less pronounced.","author":[{"family":"Kubisch","given":"Alexander"},{"family":"Poethke","given":"Hans"}],"container-title":"Evolutionary Ecology Research","container-title-short":"Evolutionary Ecology Research","issued":{"date-parts":[[2011,2,1]]},"page":"159–169","source":"ResearchGate","title":"Range border formation in a world with increasing climatic variance","type":"article-journal","volume":"13"}, + {"id":"kunEvolutionDensityDependentDispersal2006","abstract":"It is well-known that dispersal is advantageous in many different ecological situations, e.g. to survive local catastrophes where populations live in spatially and temporally heterogeneous habitats. However, the key question, what kind of dispersal strategy is optimal in a particular situation, has remained unanswered. We studied the evolution of density-dependent dispersal in a coupled map lattice model, where the population dynamics are perturbed by external environmental noise. We used a very flexible dispersal function to enable evolution to select from practically all possible types of monotonous density-dependent dispersal functions. We treated the parameters of the dispersal function as continuously changing phenotypic traits. The evolutionary stable dispersal strategies were investigated by numerical simulations. We pointed out that irrespective of the cost of dispersal and the strength of environmental noise, this strategy leads to a very weak dispersal below a threshold density, and dispersal rate increases in an accelerating manner above this threshold. Decreasing the cost of dispersal increases the skewness of the population density distribution, while increasing the environmental noise causes more pronounced bimodality in this distribution. In case of positive temporal autocorrelation of the environmental noise, there is no dispersal below the threshold, and only low dispersal below it, on the other hand with negative autocorrelation practically all individual disperses above the threshold. We found our results to be in good concordance with empirical observations.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Kun","given":"Ádám"},{"family":"Scheuring","given":"István"}],"container-title":"Oikos","ISSN":"0030-1299","issue":"2","issued":{"date-parts":[[2006]]},"page":"308-320","publisher":"[Nordic Society Oikos, Wiley]","source":"JSTOR","title":"The Evolution of Density-Dependent Dispersal in a Noisy Spatial Population Model","type":"article-journal","URL":"https://www.jstor.org/stable/40235281","volume":"115"}, + {"id":"lambinHighConnectivityHigh2012","abstract":"This chapter reviews published and unpublished studies on dispersal by water voles inhabiting fragmented habitats and organized as metapopulations. Studies of dispersal that have checked the consistency of pattern emerging at behavioural, individual, and population scale are rare or altogether lacking. This chapter describes how inferences have been drawn from exceptionally large-scale, but largely descriptive, studies of dispersal through the use of molecular markers, combined with small-scale individual-level experiments. These studies reveal a high degree of connectivity through dispersal between geographically isolated water vole colonies. Experiments with ‘enforced dispersers’ show how water vole behaviour during the transience phase of dispersal might bring this about, if dispersal takes place over a long time through multiple stepping-stone movements.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Lambin","given":"Xavier"},{"family":"Bouille","given":"Diane Le"},{"family":"Oliver","given":"Matthew K"},{"family":"Sutherland","given":"Chris"},{"family":"Tedesco","given":"Edoardo"},{"family":"Douglas","given":"Alex"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0032","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"High connectivity despite high fragmentation: iterated dispersal in a vertebrate metapopulation","title-short":"High connectivity despite high fragmentation","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-32"}, + {"id":"landeEstimatingDensityDependence2006","abstract":"Abstract: Population fluctuations are caused by demographic and environmental stochasticity, time lags due to life history, and density dependence. We model a general life history allowing density dependence within and among age or stage classes in a population undergoing small or moderate fluctuations around a stable equilibrium. We develop a method for estimating the overall strength of density dependence measured by the rate of return toward equilibrium, and we also consider a simplified population description and forecasting using the density‐dependent reproductive value. This generality comes at the cost of requiring a time series of the population age or stage structure instead of a univariate time series of adult or total population size. The method is illustrated by analyzing the dynamics of a fully censused population of red deer (Cervus elaphus) based on annual fluctuations of age structure through 21 years.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Lande","given":"Russell"},{"family":"Engen","given":"Steinar"},{"family":"Sæther","given":"Bernt‐Erik"},{"family":"Coulson","given":"Tim"},{"family":"Solow","given":"Associate Editor: Andrew R."},{"family":"DeAngelis","given":"Editor: Donald L."}],"container-title":"The American Naturalist","DOI":"10.1086/504851","ISSN":"0003-0147","issue":"1","issued":{"date-parts":[[2006]]},"page":"76-87","publisher":"[The University of Chicago Press, The American Society of Naturalists]","source":"JSTOR","title":"Estimating Density Dependence from Time Series of Population Age Structure","type":"article-journal","URL":"https://www.jstor.org/stable/10.1086/504851","volume":"168"}, + {"id":"lawsonhandleyAdvancesOurUnderstanding2007","abstract":"Sex-biased dispersal is an almost ubiquitous feature of mammalian life history, but the evolutionary causes behind these patterns still require much clarification. A quarter of a century since the publication of seminal papers describing general patterns of sex-biased dispersal in both mammals and birds, we review the advances in our theoretical understanding of the evolutionary causes of sex-biased dispersal, and those in statistical genetics that enable us to test hypotheses and measure dispersal in natural populations. We use mammalian examples to illustrate patterns and proximate causes of sex-biased dispersal, because by far the most data are available and because they exhibit an enormous diversity in terms of dispersal strategy, mating and social systems. Recent studies using molecular markers have helped to confirm that sex-biased dispersal is widespread among mammals and varies widely in direction and intensity, but there is a great need to bridge the gap between genetic information, observational data and theory. A review of mammalian data indicates that the relationship between direction of sex-bias and mating system is not a simple one. The role of social systems emerges as a key factor in determining intensity and direction of dispersal bias, but there is still need for a theoretical framework that can account for the complex interactions between inbreeding avoidance, kin competition and cooperation to explain the impressive diversity of patterns.","author":[{"family":"Lawson Handley","given":"L. J."},{"family":"Perrin","given":"N."}],"container-title":"Molecular Ecology","container-title-short":"Mol Ecol","DOI":"10.1111/j.1365-294X.2006.03152.x","ISSN":"0962-1083","issue":"8","issued":{"date-parts":[[2007,4]]},"language":"eng","page":"1559-1578","PMID":"17402974","source":"PubMed","title":"Advances in our understanding of mammalian sex-biased dispersal","type":"article-journal","volume":"16"}, + {"id":"legalliardDispersalRangeDynamics2012","abstract":"This chapter presents an attempt to summarize existing results and methods in the development of predictive models of ecological responses to climate change, with the aim of highlighting existing patterns and trends in the current data, the most important knowledge gaps, and some fruitful avenues for future research. It highlights the urgent need for a good understanding of the effects of climate change on dispersal. Global climate changes, in fact, have been responsible for the growing awareness and recent surge of interest in studies of dispersal aimed at understanding and predicting the ecological effects of climate change. One of the most common ecological responses to climate change involves range or habitat shifts due to spatial expansions at the cool range margins and spatial retractions at the warm range margins.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Le Galliard","given":"Jean François Le"},{"family":"Massot","given":"Manuel"},{"family":"Clobert","given":"Jean"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0025","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Dispersal and range dynamics in changing climates: a review","title-short":"Dispersal and range dynamics in changing climates","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-25"}, + {"id":"legalliardPatternsProcessesDispersal2012","abstract":"A good understanding of mammalian societies requires measuring patterns and comprehending processes of dispersal in each sex. We investigated dispersal behaviour in arvicoline rodents, a subfamily of mammals widespread in northern temperate environments and characterized by a multivoltine life cycle. In arvicoline rodents, variation in life history strategies occurs along a continuum from precocial to delayed maturation that reflects seasonal and ecological fluctuations. We compared dispersal across and within species focusing on the effects of external (condition-dependent) and internal (phenotype-dependent) factors. Our data revealed substantial, unexplained variation between species for dispersal distances and a strong variation within species for both dispersal distance and fraction. Some methodological aspects explained variation across studies, which cautions against comparisons that do not control for them. Overall, the species under consideration display frequent short-distance dispersal events and extremely flexible dispersal strategies, but they also have hitherto unexpected capacity to disperse long distances. Female arvicolines are predominantly philopatric relative to males, but we found no clear association between the mating system and the degree of sex bias in dispersal across species. Dispersal is a response to both various proximate and ultimate factors, including competition, inbreeding avoidance, mate searching and habitat quality. In particular, our review suggests that costs and benefits experienced during transience and settlement are prime determinants of condition dependence. Patterns of phenotype-dependent dispersal are idiosyncratic, except for a widespread association between an exploration/activity syndrome and natal dispersal. Consequences for population dynamics and genetic structures are discussed.","author":[{"family":"Le Galliard","given":"Jean-François"},{"family":"Rémy","given":"Alice"},{"family":"Ims","given":"Rolf A."},{"family":"Lambin","given":"Xavier"}],"container-title":"Molecular Ecology","container-title-short":"Mol Ecol","DOI":"10.1111/j.1365-294X.2011.05410.x","ISSN":"1365-294X","issue":"3","issued":{"date-parts":[[2012,2]]},"language":"eng","page":"505-523","PMID":"22211403","source":"PubMed","title":"Patterns and processes of dispersal behaviour in arvicoline rodents","type":"article-journal","volume":"21"}, + {"id":"legendreAgeStructureMating2004","abstract":"IntroductionThe fate of populations depends on the life-history traits of the species and possible adaptive changes in these traits in response to selective pressure. In unstructured population models, life-history traits are compounded into few parameters, like the intrinsic growth rate r and the carrying capacity K (see Chapter 2). Structured population models, based on life-cycle graphs, allow the effects of specific life-history traits (survival rates, fecundities, generation time, age at maturity) on population dynamics to be investigated. For example, sensitivities of the growth rate to changes in life-cycle transitions can be computed. Individual life-history traits are important determinants of a population's extinction risk, and are also both factors in and targets of a population's adaptive response to environmental change.When population size is small – always a concern in conservation biology – both individual life-history traits and the structure of interactions between individuals and the genetic system are expected to influence viability. The mating system, for example, may be conducive to an Allee effect (see Chapter 2), and inbreeding depression is a potentially important factor of the extinction process of small populations. In this chapter, we study the interplay between population structure, in terms of age and sex, and population persistence. Two-sex structured models that incorporate specific features of the social mating system and possible differences in male and female life cycles are analyzed. Also, attempts to merge genetic factors and demography into integrated models are presented.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Legendre","given":"Stéphane"}],"collection-title":"Cambridge Studies in Adaptive Dynamics","container-title":"Evolutionary Conservation Biology","DOI":"10.1017/CBO9780511542022.005","editor":[{"family":"Couvet","given":"Denis"},{"family":"Ferrière","given":"Régis"},{"family":"Dieckmann","given":"Ulf"}],"event-place":"Cambridge","ISBN":"978-0-521-82700-3","issued":{"date-parts":[[2004]]},"page":"41-58","publisher":"Cambridge University Press","publisher-place":"Cambridge","source":"Cambridge University Press","title":"Age Structure, Mating System, and Population Viability","type":"chapter","URL":"https://www.cambridge.org/core/books/evolutionary-conservation-biology/age-structure-mating-system-and-population-viability/D1CC2D39E906307B2189468AA0FA716C"}, + {"id":"lenoirSignificantUpwardShift2008","abstract":"Spatial fingerprints of climate change on biotic communities are usually associated with changes in the distribution of species at their latitudinal or altitudinal extremes. By comparing the altitudinal distribution of 171 forest plant species between 1905 and 1985 and 1986 and 2005 along the entire elevation range (0 to 2600 meters above sea level) in west Europe, we show that climate warming has resulted in a significant upward shift in species optimum elevation averaging 29 meters per decade. The shift is larger for species restricted to mountain habitats and for grassy species, which are characterized by faster population turnover. Our study shows that climate change affects the spatial core of the distributional range of plant species, in addition to their distributional margins, as previously reported.\nA 100-year survey shows that the optimal elevations for growth of plant species in European temperate forests have shifted upward by about 30 meters per decade.\nA 100-year survey shows that the optimal elevations for growth of plant species in European temperate forests have shifted upward by about 30 meters per decade.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Lenoir","given":"J."},{"family":"Gégout","given":"J. C."},{"family":"Marquet","given":"P. A."},{"family":"Ruffray","given":"P.","dropping-particle":"de"},{"family":"Brisse","given":"H."}],"container-title":"Science","DOI":"10.1126/science.1156831","ISSN":"0036-8075, 1095-9203","issue":"5884","issued":{"date-parts":[[2008,6,27]]},"language":"en","page":"1768-1771","PMID":"18583610","publisher":"American Association for the Advancement of Science","section":"Report","source":"science.sciencemag.org","title":"A Significant Upward Shift in Plant Species Optimum Elevation During the 20th Century","type":"article-journal","URL":"https://science.sciencemag.org/content/320/5884/1768","volume":"320"}, + {"id":"lesserContributionsLongdistanceDispersal2013","abstract":"Long-distance dispersal is an integral part of plant species migration and population development. We aged and genotyped 1125 individuals in four disjunct populations of Pinus ponderosa that were initially established by long-distance dispersal in the 16th and 17th centuries. Parentage analysis was used to determine if individuals were the product of local reproductive events (two parents present), long-distance pollen dispersal (one parent present) or long-distance seed dispersal (no parents present). All individuals established in the first century at each site were the result of long-distance dispersal. Individuals reproduced at younger ages with increasing age of the overall population. These results suggest Allee effects, where populations were initially unable to expand on their own, and were dependent on long-distance dispersal to overcome a minimum-size threshold. Our results demonstrate that long-distance dispersal was not only necessary for initial colonisation but also to sustain subsequent population growth during early phases of expansion.","author":[{"family":"Lesser","given":"Mark R."},{"family":"Jackson","given":"Stephen T."}],"container-title":"Ecology Letters","container-title-short":"Ecol Lett","DOI":"10.1111/ele.12053","ISSN":"1461-0248","issue":"3","issued":{"date-parts":[[2013,3]]},"language":"eng","page":"380-389","PMID":"23279647","source":"PubMed","title":"Contributions of long-distance dispersal to population growth in colonising Pinus ponderosa populations","type":"article-journal","volume":"16"}, + {"id":"limaBehavioralEcologyEcological1996","abstract":"Recent developments in landscape-level ecological modeling rest upon poorly understood behavioral phenomena. Surprisingly, these phenomena include animal movement and habitat selection, two areas with a long history of study in behavioral ecology. A major problem in applying traditional behavioral ecology to landscape-level ecological problems is that ecologists and behaviorists work at very different spatial scales. Thus a behavioral ecology of ecological landscapes would strive to overcome this inopportune differential in spatial scales. Such a landscape-conscious behavioral undertaking would not only establish more firmly the link between behavior and ecological systems, but also catalyze the study of basic biological phenomena of Interest to behaviorists and ecologists alike.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Lima","given":"Steven L."},{"family":"Zollner","given":"Patrick A."}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/0169-5347(96)81094-9","ISSN":"0169-5347","issue":"3","issued":{"date-parts":[[1996,3,1]]},"language":"en","page":"131-135","source":"ScienceDirect","title":"Towards a behavioral ecology of ecological landscapes","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/0169534796810949","volume":"11"}, + {"id":"lindstromSexualReproductionPopulation1998","abstract":"Most models of population dynamics do not take sexual reproduction into account (i.e. they do not consider the role of males). However, assumptions behind this practice—that no demographic sex differences exist and males are always abundant enough to fertilize all the females—are usually not justified in natural populations. On the contrary, demographic sex differences are common, especially in polygynous species. Previous models that consider sexual reproduction report a stabilizing effect through mixing of different genotypes, thus suggesting a decrease in the propensity for complex dynamics in sexually reproducing populations. Here we show that considering the direct role of males in reproduction and density dependence leads to the conclusion that a two–sex model is not necessarily more stable compared with the corresponding one–sex model. Although solutions exist where sexual reproduction has a stabilizing effect even when no genotypic variability is included (primarily when associated with monogamy), factors like polygyny, sex differences in survival or density dependence, and possible alterations of the primary sex ratio (the Trivers–Willard mechanism), may enlarge the parametric region of complex dynamics. Sexual reproduction therefore does not necessarily increase the stability of population dynamics and can have destabilizing effects, at least in species with complicated mating systems and sexual dimorphism.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Lindström","given":"Jan"},{"family":"Kokko","given":"Hanna"}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rspb.1998.0320","issue":"1395","issued":{"date-parts":[[1998,3,22]]},"page":"483-488","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Sexual reproduction and population dynamics: the role of polygyny and demographic sex differences","title-short":"Sexual reproduction and population dynamics","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.1998.0320","volume":"265"}, + {"id":"loarieVelocityClimateChange2009","abstract":"In the event of climate change, species have to move if they are to remain in an area with the same average temperature: their chances of survival therefore depend on the ability to keep pace with a moving climate as well as on the extent of change in temperature and other climate factors. To put this pressure on species into context, a novel index designed to quantify climate change in the coming century has been developed. Its value gives the local velocity along the Earth's surface needed to maintain constant temperatures, and is derived from temperature gradients scaled by distance (°C per km) and time (°C per year). The index provides a quantitative view of the role of topography in buffering climate change as it would affect plants and animals: on the IPCC's A1B emission scenario the index has a global mean of 0.42 km per year, compared to extremes of 0.08 and 1.26 km per year for mountains forest biomes and flooded grasslands, respectively. Climate change velocity, it turns out, is large relative to species migration speeds and the sizes of protected habitats. The data suggest that, in some ecosystems, helping species to relocate more rapidly via habitat corridors or new reserves could be an important contribution to conservation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Loarie","given":"Scott R."},{"family":"Duffy","given":"Philip B."},{"family":"Hamilton","given":"Healy"},{"family":"Asner","given":"Gregory P."},{"family":"Field","given":"Christopher B."},{"family":"Ackerly","given":"David D."}],"container-title":"Nature","DOI":"10.1038/nature08649","ISSN":"1476-4687","issue":"7276","issued":{"date-parts":[[2009,12]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Research","number":"7276","page":"1052-1055","publisher":"Nature Publishing Group","source":"www.nature.com","title":"The velocity of climate change","type":"article-journal","URL":"https://www.nature.com/articles/nature08649","volume":"462"}, + {"id":"lossAssistedColonizationIntegrating2011","abstract":"Global climate change poses an immense challenge for conservation biologists seeking to mitigate impacts to species and ecosystems. Species persistence will depend on geographic range shifts or adaptation in response to warming patterns as novel climates and community assemblages arise. Assisted colonization has been proposed as a method for addressing these challenges. This technique, which consists of transporting species to a new range that is predicted to be favorable for persistence under future climate scenarios, has become the subject of controversy and discussion in the conservation community due to its highly manipulative nature, questions about widespread feasibility, and uncertainty associated with the likelihood of translocated species becoming invasive. We reviewed the discussion and criticism associated with assisted colonization and sought to identify other conservation techniques that also display potential to promote the colonization and adaptation of species in response to climate change. We propose an integrated conservation strategy that includes management for habitat connectivity, conservation genetics, and when necessary, assisted colonization of species that are still unable to shift their ranges even given implementation of the above standard conservation approaches. We argue that this integrated approach will facilitate persistence for a larger proportion of species than is possible by solely using assisted colonization. Furthermore, a multi-faceted approach will likely reduce the uncertainty of conservation outcomes and will become increasingly necessary for conservation of biodiversity in a changing climate.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Loss","given":"Scott R."},{"family":"Terwilliger","given":"Lauren A."},{"family":"Peterson","given":"Anna C."}],"container-title":"Biological Conservation","container-title-short":"Biological Conservation","DOI":"10.1016/j.biocon.2010.11.016","ISSN":"0006-3207","issue":"1","issued":{"date-parts":[[2011,1,1]]},"language":"en","page":"92-100","source":"ScienceDirect","title":"Assisted colonization: Integrating conservation strategies in the face of climate change","title-short":"Assisted colonization","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0006320710004866","volume":"144"}, + {"id":"manelLandscapeGeneticsCombining2003a","abstract":"Understanding the processes and patterns of gene flow and local adaptation requires a detailed knowledge of how landscape characteristics structure populations. This understanding is crucial, not only for improving ecological knowledge, but also for managing properly the genetic diversity of threatened and endangered populations. For nearly 80 years, population geneticists have investigated how physiognomy and other landscape features have influenced genetic variation within and between populations. They have relied on sampling populations that have been identified beforehand because most population genetics methods have required discrete populations. However, a new approach has emerged for analyzing spatial genetic data without requiring that discrete populations be identified in advance. This approach, landscape genetics, promises to facilitate our understanding of how geographical and environmental features structure genetic variation at both the population and individual levels, and has implications for ecology, evolution and conservation biology. It differs from other genetic approaches, such as phylogeography, in that it tends to focus on processes at finer spatial and temporal scales. Here, we discuss, from a population genetic perspective, the current tools available for conducting studies of landscape genetics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Manel","given":"Stéphanie"},{"family":"Schwartz","given":"Michael K."},{"family":"Luikart","given":"Gordon"},{"family":"Taberlet","given":"Pierre"}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/S0169-5347(03)00008-9","ISSN":"0169-5347","issue":"4","issued":{"date-parts":[[2003,4,1]]},"language":"en","page":"189-197","source":"ScienceDirect","title":"Landscape genetics: combining landscape ecology and population genetics","title-short":"Landscape genetics","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169534703000089","volume":"18"}, + {"id":"mathiasDivergentEvolutionDispersal2001","abstract":"The evolution of dispersal is investigated in a landscape of many patches with fluctuating carrying capacities and spatial heterogeneity in temporal fluctuations. Although asynchronous temporal fluctuations select for dispersal, spatial heterogeneity in the distribution of fluctuating environmental variables selects against it. We find evolutionary branching in dispersal rate leading to the evolutionarily stable coexistence of a high- and a low-dispersal phenotype. We study how the opposing forces of selection for and against dispersal change with the relative size and the environmental qualities of the source and sink habitats. Our results suggest that the evolution of dispersal dimorphism could be a first step towards speciation and local adaptation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Mathias","given":"Andrea"},{"family":"Kisdi","given":"Eva"},{"family":"Olivieri","given":"Isabelle"}],"container-title":"Evolution","ISSN":"0014-3820","issue":"2","issued":{"date-parts":[[2001]]},"page":"246-259","publisher":"[Society for the Study of Evolution, Wiley]","source":"JSTOR","title":"Divergent Evolution of Dispersal in a Heterogeneous Landscape","type":"article-journal","URL":"https://www.jstor.org/stable/2640747","volume":"55"}, + {"id":"matthysenDensitydependentDispersalBirds2005","abstract":"Density-dependent dispersal can be caused by various mechanisms, from competition inducing individuals to emigrate (positive density-dependence) to social crowding effects impeding free movement (negative density-dependence). Various spatial population models have incorporated positively density-dependent dispersal algorithms, and recent theoretical models have explored the conditions for density-dependent dispersal (DD) to evolve. However, while the existence of DD is well documented in some taxa such as insects, there is no clear picture on its generality in vertebrates. Here I review the available empirical data on DD in birds and mammals, focusing mainly on variation in dispersal between years and on experimental density manipulations. Surprisingly few studies have explicitly focused on DD, and interpretation of the available data is often hampered by differences in approach, small sample sizes and/or statistical shortcomings. Positive DD was reported in 50 and 33% of the selected mammal and bird studies, respectively, while two studies on mammals (out of eight) reported negative DD. Among bird studies, DD was more often reported for emigration rates or long-distance recoveries than for average distances within finite study areas. Experimental studies manipulating densities (mainly on mammals) have consistently generated positive DD, typically showing reduced emigration in response to partial population removal. Studies that examined dispersal in relation to seasonal changes in density (small mammals only) have more often reported negative DD. Studies that compared dispersal between sites differing in density, also show a mixture of positive and negative DD. This suggests that dispersal changes in a more complex way with seasonal and spatial density variation than with annual densities, and/or that these results are confounded by other factors differing between seasons and sites, such as habitat quality. I conclude that both correlational and experimental studies support the existence of positive, rather than negative, density-dependent dispersal in birds and mammals.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Matthysen","given":"Erik"}],"container-title":"Ecography","DOI":"10.1111/j.0906-7590.2005.04073.x","ISSN":"1600-0587","issue":"3","issued":{"date-parts":[[2005]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.0906-7590.2005.04073.x","page":"403-416","source":"Wiley Online Library","title":"Density-dependent dispersal in birds and mammals","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.0906-7590.2005.04073.x","volume":"28"}, + {"id":"matthysenMulticausalityDispersalReview2012","abstract":"This chapter reviews the main causes leading to dispersal, and emphasises its proximate factors. Dispersal is the main mechanism leading to gene flow within and between populations, and is defined as the movement of an individual from site of birth to site of reproduction or its movement between successive sites of reproduction. Causality in dispersal here is considered as any factor that explains variation among individuals in any component of dispersal. Following a general introduction, the different types of causal factors that may explain dispersal patterns are reviewed. The chapter begins with a discussion of the concept of dispersal. This is followed by a brief discussion of its ultimate explications. Lastly, an overview of its different possible mechanisms.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Matthysen","given":"Erik"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0001","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Multicausality of dispersal: a review","title-short":"Multicausality of dispersal","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-1"}, + {"id":"mclaughlinClimateChangeHastens2002","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"McLaughlin","given":"John F."},{"family":"Hellmann","given":"Jessica J."},{"family":"Boggs","given":"Carol L."},{"family":"Ehrlich","given":"Paul R."}],"container-title":"Proceedings of the National Academy of Sciences of the United States of America","container-title-short":"PROC. NAT. ACAD. OF SCI. (U.S.A.)","DOI":"10.1073/pnas.052131199","ISSN":"0027-8424","issue":"9","issued":{"date-parts":[[2002,4,30]]},"language":"English (US)","page":"6070-6074","PMID":"11972020","publisher":"National Academy of Sciences","source":"experts.umn.edu","title":"Climate change hastens population extinctions","type":"article-journal","URL":"https://experts.umn.edu/en/publications/climate-change-hastens-population-extinctions","volume":"99"}, + {"id":"mcpeekEvolutionDispersalSpatially1992","abstract":"Using a simple two-patch model, we examine how patterns of spatial and temporal variation in carrying capacities affect natural selection on dispersal. The size of the population in each patch is regulated separately, according to a discrete-generation logistic equation, and individuals disperse from each patch at propensities determined by their genotype. We consider genotypes that express the same dispersal propensities in both patches and genotypes that express patch-specific disperal propensities. Contrary to previous analyses, our results show that some level of dispersal is favored by selection under almost all regimes of habitat variability, including a spatially varying and temporally constant environment. Furthermore, two very different polymorphisms are favored under different conditions. When carrying capacities vary spatially but not temporally, any number of genotypes with patch-specific dispersal propensities in ratios inversely proportional to the ratio of the carrying capacities can coexist. This result extends previous analyses to show that dispersal is favored in such an environment if individuals can alter dispersal propensities in response to environmental cues. In contrast, when carrying capacities vary both spatially and temporally but differ in mean or variance, a polymorphism of only two genotypes (a high-dispersal and a no-dispersal genotype) is favored when the only genotypes possible are ones expressing the same dispersal propensity in both patches. However, this dimorphism can be invaded and replaced by one genotype with a particular combination of patch-specific dispersal propensities in a ratio also inversely proportional to the ratio of the average population sizes. We discuss a number of testable predictions this model suggests about the amounts of phenotypic and genetic variation in dispersal characters that are expected both within and between populations, and the degree to which the expression of phenotypic characters affecting dispersal propensity should be sensitive to environmental conditions. The model also suggests novel mechanisms for coexistence between competing species in varying environments.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"McPeek","given":"Mark A."},{"family":"Holt","given":"Robert D."}],"container-title":"The American Naturalist","ISSN":"0003-0147","issue":"6","issued":{"date-parts":[[1992]]},"page":"1010-1027","publisher":"[University of Chicago Press, American Society of Naturalists]","source":"JSTOR","title":"The Evolution of Dispersal in Spatially and Temporally Varying Environments","type":"article-journal","URL":"https://www.jstor.org/stable/2462931","volume":"140"}, + {"id":"merckxEvolutionMovementsBehaviour2003","abstract":"As landscapes change, mobility patterns of species may alter. Different mechanistic scenarios may, however, lead to particular patterns. Here, we tested conflicting predictions from two hypotheses on butterfly movements in relation to habitat fragmentation. According to the resource distribution hypothesis, butterflies in more fragmented landscapes would have higher levels of mobility as resources are more scattered. However, these butterflies could have lower levels of mobility as they experience ‘hard’ habitat boundaries more frequently (i.e. higher crossing costs) compared with butterflies in landscapes with continuous habitat; i.e. the behaviour–at–boundaries hypothesis. We studied movements, habitat boundary crossing and habitat preference of laboratory–reared individuals of Pararge aegeria that originated from woodland and agricultural landscapes, by using an experimental landscape as a common environment (outdoor cages) to test the predictions, taking into account sexual differences and weather. Woodland butterflies covered longer distances, were more prone to cross open–shade boundaries, travelled more frequently between woodland parts of the cages and were more at flight than agricultural butterflies. Our results support the behaviour–at–boundaries hypothesis, with ‘softer’ boundaries for woodland landscapes. Because the butterflies were reared in a common environment, the observed behavioural differences rely on heritable variation between populations from woodland and agricultural landscapes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Merckx","given":"Thomas"},{"family":"Dyck","given":"Hans Van"},{"family":"Karlsson","given":"Bengt"},{"family":"Leimar","given":"Olof"}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rspb.2003.2459","issue":"1526","issued":{"date-parts":[[2003,9,7]]},"page":"1815-1821","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"The evolution of movements and behaviour at boundaries in different landscapes: a common arena experiment with butterflies","title-short":"The evolution of movements and behaviour at boundaries in different landscapes","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2003.2459","volume":"270"}, + {"id":"merckxLandscapeStructurePhenotypic2006","abstract":"In evolutionary time, varying environments may lead to different morphs as a result of genetic adaptation and divergence or phenotypic plasticity. Landscapes that differ in the extent of habitat fragmentation may provide different selection regimes for dispersal, but also for other ecological functions. Several studies on flying insects have shown differences in flight morphology between landscapes, but whether such differences result from plastic responses have rarely been tested. We did a reciprocal transplant experiment with offspring of speckled wood butterfly females (Parargeaegeria) from three types of landscape differing in fragmentation: woodland landscape, landscape with woodland fragments and agricultural landscape with only hedgerows. Young caterpillars were allowed to grow individually on potted host grasses in small enclosures under the three landscape conditions (split-brood design). Mortality in caterpillars was much higher in agricultural landscape compared to the other landscapes. Additive to the effect of landscape of development, landscape of origin also affected mortality rate in a similar way. Flight morphology of the adults resulting from the experiment differed significantly with landscape. Independent of the landscape of origin, males and females that developed in agricultural landscape were the heaviest and had the greatest wing loadings. Females that developed in agricultural landscape had higher relative thorax mass (i.e. greater flight muscle allocation) in line with adaptive predictions on altered dispersal behaviour with type of landscape. In males, relative thorax mass did not respond significantly relative to landscape of development, but males originating from landscape with woodland fragments allocated more into their thorax compared to males from the other types. We found significant G×E interactions for total dry mass and wing loading. Our results suggest the existence of phenotypic plasticity in butterfly flight morphology associated with landscape structure.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Merckx","given":"Thomas"},{"family":"Dyck","given":"Hans Van"}],"container-title":"Oikos","DOI":"10.1111/j.2006.0030-1299.14501.x","ISSN":"1600-0706","issue":"2","issued":{"date-parts":[[2006]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.2006.0030-1299.14501.x","page":"226-232","source":"Wiley Online Library","title":"Landscape structure and phenotypic plasticity in flight morphology in the butterfly Pararge aegeria","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.2006.0030-1299.14501.x","volume":"113"}, + {"id":"metzHowShouldWe2001","abstract":"We define a fitness concept applicable to structured metapopulations consisting of infinitely many equally coupled patches. In addition, we introduce a more easily calculated quantity Rm that relates to fitness in the same manner as R0 relates to fitness in ordinary population dynamics: the Rm of a mutant is only defined when the resident population dynamics converges to a point equilibrium and Rm is larger (smaller) than 1 if and only if mutant fitness is positive (negative). Rm corresponds to the average number of newborn dispersers resulting from the (on average less than one) local colony founded by a newborn disperser. Efficient algorithms for calculating its numerical value are provided. As an example of the usefulness of these concepts we calculate the evolutionarily stable conditional dispersal strategy for individuals that can account for the local population density in their dispersal decisions. Below a threshold density ã, at which staying and leaving are equality profitable, everybody should stay and above ã everybody should leave, where profitability is measured as the mean number of dispersers produced through lines of descent consisting of only non–dispersers.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Metz","given":"J. a. J."},{"family":"Gyllenberg","given":"M."}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rspb.2000.1373","issue":"1466","issued":{"date-parts":[[2001,3,7]]},"page":"499-508","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"How should we define fitness in structured metapopulation models? Including an application to the calculation of evolutionarily stable dispersal strategies","title-short":"How should we define fitness in structured metapopulation models?","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2000.1373","volume":"268"}, + {"id":"midgleyBioMoveIntegratedPlatform2010","abstract":"BioMove simulates plant species' geographic range shifts in response to climate, habitat structure and disturbance, at annual time steps. This spatially explicit approach integrates species' bioclimatic suitability and population-level demographic rates with simulation of landscape-level processes (dispersal, disturbance, species' response to dynamic dominant vegetation structure). Species population dynamics are simulated through matrix modelling that includes scaling demographic rates by climatic suitability. Dispersal functions simulate population spread. User-specified plant functional types (PFTs) provide vegetation structure that determines resource competition and disturbance. PFTs respond annually through dispersal, inter-PFT competition and demographic shifts. BioMove provides a rich framework for dynamic range simulations.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Midgley","given":"Guy F."},{"family":"Davies","given":"Ian D."},{"family":"Albert","given":"Cécile H."},{"family":"Altwegg","given":"Res"},{"family":"Hannah","given":"Lee"},{"family":"Hughes","given":"Gregory O."},{"family":"O'Halloran","given":"Lydia R."},{"family":"Seo","given":"Changwan"},{"family":"Thorne","given":"James H."},{"family":"Thuiller","given":"Wilfried"}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2009.06000.x","ISSN":"1600-0587","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2009.06000.x","page":"612-616","source":"Wiley Online Library","title":"BioMove – an integrated platform simulating the dynamic response of species to environmental change","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2009.06000.x","volume":"33"}, + {"id":"millerSexbiasedDispersalSpeed2011","abstract":"Population models that combine demography and dispersal are important tools for forecasting the spatial spread of biological invasions. Current models describe the dynamics of only one sex (typically females). Such models cannot account for the sex-related biases in dispersal and mating behavior that are typical of many animal species. In this article, we construct a two-sex integrodifference equation model that overcomes these limitations. We derive an explicit formula for the invasion speed from the model and use it to show that sex-biased dispersal may significantly increase or decrease the invasion speed by skewing the operational sex ratio at the invasion's low-density leading edge. Which of these possible outcomes occurs depends sensitively on complex interactions among the direction of dispersal bias, the magnitude of bias, and the relative contributions of females and males to local population growth.","author":[{"family":"Miller","given":"Tom E. X."},{"family":"Shaw","given":"Allison K."},{"family":"Inouye","given":"Brian D."},{"family":"Neubert","given":"Michael G."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/659628","ISSN":"1537-5323","issue":"5","issued":{"date-parts":[[2011,5]]},"language":"eng","page":"549-561","PMID":"21508603","source":"PubMed","title":"Sex-biased dispersal and the speed of two-sex invasions","type":"article-journal","volume":"177"}, + {"id":"millerSexStochasticityAffect2013","abstract":"Understanding and predicting range expansion are key objectives in many basic and applied contexts. Among dioecious organisms, there is strong evidence for sex differences in dispersal, which could alter the sex ratio at the expansion's leading edge. However, demographic stochasticity could also affect leading-edge sex ratios, perhaps overwhelming sex-biased dispersal. We used insects in laboratory mesocosms to test the effects of sex-biased dispersal on range expansion, and a simulation model to explore interactive effects of sex-biased dispersal and demographic stochasticity. Sex-biased dispersal created spatial clines in the sex ratio, which influenced offspring production at the front and altered invasion velocity. Increasing female dispersal relative to males accelerated spread, despite the prediction that demographic stochasticity would weaken a signal of sex-biased dispersal. Our results provide the first experimental evidence for an influence of sex-biased dispersal on invasion velocity, highlighting the value of accounting for sex structure in studies of range expansion.","author":[{"family":"Miller","given":"Tom E. X."},{"family":"Inouye","given":"Brian D."}],"container-title":"Ecology Letters","container-title-short":"Ecol Lett","DOI":"10.1111/ele.12049","ISSN":"1461-0248","issue":"3","issued":{"date-parts":[[2013,3]]},"language":"eng","page":"354-361","PMID":"23237200","source":"PubMed","title":"Sex and stochasticity affect range expansion of experimental invasions","type":"article-journal","volume":"16"}, + {"id":"mitikkaRangeExpansionEuropean2010","abstract":"Climate change will influence the living conditions of all life on Earth. For some species the change in the environmental conditions that has occurred so far has already increased the risk of extinction, and the extinction risk is predicted to increase for large numbers of species in the future. Some species may have time to adapt to the changing environmental conditions, but the rate and magnitude of the change are too great to allow many species to survive via evolutionary changes. \n\nSpecies responses to climate change have been documented for some decades. Some groups of species, like many insects, respond readily to changes in temperature conditions and have shifted their distributions northwards to new climatically suitable regions. Such range shifts have been well documented especially in temperate zones. In this context, butterflies have been studied more than any other group of species, partly for the reason that their past geographical ranges are well documented, which facilitates species-climate modelling and other analyses. The aim of the modelling studies is to examine to what extent shifts in species distributions can be explained by climatic and other factors. Models can also be used to predict the future distributions of species. \n\nIn this thesis, I have studied the response to climate change of one species of butterfly within one geographically restricted area. The study species, the European map butterfly (Araschnia levana), has expanded rapidly northwards in Finland during the last two decades. I used statistical and dynamic modelling approaches in combination with field studies to analyse the effects of climate warming and landscape structure on the expansion. I studied possible role of molecular variation in phosphoglucose isomerase (PGI), a glycolytic enzyme affecting flight metabolism and thereby flight performance, in the observed expansion of the map butterfly at two separate expansion fronts in Finland. \n\nThe expansion rate of the map butterfly was shown to be correlated with the frequency of warmer than average summers during the study period. The result is in line with the greater probability of occurrence of the second generation during warm summers and previous results on this species showing greater mobility of the second than first generation individuals. The results of a field study in this thesis indicated low mobility of the first generation butterflies. Climatic variables alone were not sufficient to explain the observed expansion in Finland. There are also problems in transferring the climate model to new regions from the ones from which data were available to construct the model. The climate model predicted a wider distribution in the south-western part of Finland than what has been observed. Dynamic modelling of the expansion in response to landscape structure suggested that habitat and landscape structure influence the rate of expansion. In southern Finland the landscape structure may have slowed down the expansion rate. The results on PGI suggested that allelic variation in this enzyme may influence flight performance and thereby the rate of expansion. Genetic differences of the populations at the two expansion fronts may explain at least partly the observed differences in the rate of expansion. Individuals with the genotype associated with high flight metabolic rate were most frequent in eastern Finland, where the rate of range expansion has been highest.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Mitikka","given":"Varpu"}],"ISBN":"9789521061462","issued":{"date-parts":[[2010,3,26]]},"language":"en","note":"Accepted: 2010-11-25T13:18:36Z","publisher":"Helsingin yliopisto","source":"helda.helsinki.fi","title":"The range expansion of the European map butterfly in Finland","type":"article-journal","URL":"https://helda.helsinki.fi/handle/10138/22114"}, + {"id":"moralesBehaviorHabitatBoundaries2002","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Morales","given":"Juan Manuel"}],"container-title":"The American Naturalist","DOI":"10.1086/342076","ISSN":"0003-0147","issue":"4","issued":{"date-parts":[[2002,10,1]]},"page":"531-538","publisher":"The University of Chicago Press","source":"journals.uchicago.edu (Atypon)","title":"Behavior at Habitat Boundaries Can Produce Leptokurtic Movement Distributions.","type":"article-journal","URL":"https://www.journals.uchicago.edu/doi/full/10.1086/342076","volume":"160"}, + {"id":"moralesBuildingBridgeAnimal2010a","abstract":"While the mechanistic links between animal movement and population dynamics are ecologically obvious, it is much less clear when knowledge of animal movement is a prerequisite for understanding and predicting population dynamics. GPS and other technologies enable detailed tracking of animal location concurrently with acquisition of landscape data and information on individual physiology. These tools can be used to refine our understanding of the mechanistic links between behaviour and individual condition through ‘spatially informed’ movement models where time allocation to different behaviours affects individual survival and reproduction. For some species, socially informed models that address the movements and average fitness of differently sized groups and how they are affected by fission–fusion processes at relevant temporal scales are required. Furthermore, as most animals revisit some places and avoid others based on their previous experiences, we foresee the incorporation of long-term memory and intention in movement models. The way animals move has important consequences for the degree of mixing that we expect to find both within a population and between individuals of different species. The mixing rate dictates the level of detail required by models to capture the influence of heterogeneity and the dynamics of intra- and interspecific interaction.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Morales","given":"Juan M."},{"family":"Moorcroft","given":"Paul R."},{"family":"Matthiopoulos","given":"Jason"},{"family":"Frair","given":"Jacqueline L."},{"family":"Kie","given":"John G."},{"family":"Powell","given":"Roger A."},{"family":"Merrill","given":"Evelyn H."},{"family":"Haydon","given":"Daniel T."}],"container-title":"Philosophical Transactions of the Royal Society B: Biological Sciences","DOI":"10.1098/rstb.2010.0082","issue":"1550","issued":{"date-parts":[[2010,7,27]]},"page":"2289-2301","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Building the bridge between animal movement and population dynamics","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rstb.2010.0082","volume":"365"}, + {"id":"moralesScalingAnimalMovements2002","abstract":"Two major challenges of spatial ecology are understanding the effects of landscape heterogeneity on movement, and translating observations taken at small spatial and temporal scales into expected patterns at greater scales. Using a combination of computer simulations and micro-landscape experiments with Tribolium confusum beetles we found that conventional correlated random walk models with constant parameters severely underestimated spatial spread because organisms changed movement behaviors over time. However, a model incorporating behavioral heterogeneity between individuals, and within individuals over time, was able to account for observed patterns of spread. Our results suggest that the main challenge for scaling up movement patterns resides in the complexities of individual behavior rather than in the spatial structure of the landscape.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Morales","given":"Juan Manuel"},{"family":"Ellner","given":"Stephen P."}],"container-title":"Ecology","DOI":"10.2307/3072055","ISSN":"0012-9658","issue":"8","issued":{"date-parts":[[2002]]},"page":"2240-2247","publisher":"Ecological Society of America","source":"JSTOR","title":"Scaling up Animal Movements in Heterogeneous Landscapes: The Importance of Behavior","title-short":"Scaling up Animal Movements in Heterogeneous Landscapes","type":"article-journal","URL":"https://www.jstor.org/stable/3072055","volume":"83"}, + {"id":"munozWindLongDistanceDispersal2004","abstract":"Anisotropic (direction-dependent) long-distance dispersal (LDD) by wind has been invoked to explain the strong floristic affinities shared among landmasses in the Southern Hemisphere. Its contribution has not yet been systematically tested because of the previous lack of global data on winds. We used global winds coverage from the National Aeronautics and Space Administration SeaWinds scatterometer to test whether floristic similarities of Southern Hemisphere moss, liverwort, lichen, and pteridophyte floras conform better with (i) the anisotropic LDD hypothesis, which predicts that connection by “wind highways” increases floristic similarities, or (ii) a direction-independent LDD hypothesis, which predicts that floristic similarities among sites increase with geographic proximity. We found a stronger correlation of floristic similarities with wind connectivity than with geographic proximities, which supports the idea that wind is a dispersal vehicle for many organisms in the Southern Hemisphere.\nWind patterns, not geographical proximity, best explain the distribution of lower plants in the Southern Hemisphere.\nWind patterns, not geographical proximity, best explain the distribution of lower plants in the Southern Hemisphere.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Muñoz","given":"Jesús"},{"family":"Felicísimo","given":"Ángel M."},{"family":"Cabezas","given":"Francisco"},{"family":"Burgaz","given":"Ana R."},{"family":"Martínez","given":"Isabel"}],"container-title":"Science","DOI":"10.1126/science.1095210","ISSN":"0036-8075, 1095-9203","issue":"5674","issued":{"date-parts":[[2004,5,21]]},"language":"en","page":"1144-1147","PMID":"15155945","publisher":"American Association for the Advancement of Science","section":"Report","source":"science.sciencemag.org","title":"Wind as a Long-Distance Dispersal Vehicle in the Southern Hemisphere","type":"article-journal","URL":"https://science.sciencemag.org/content/304/5674/1144","volume":"304"}, + {"id":"murrellEvolutionDispersalDistance2002","abstract":"Most evolutionary models of dispersal have concentrated on dispersal rate, with emigration being either global or restricted to nearest neighbours. Yet most organisms fall into an intermediate region where most dispersal is local but there is a wide range of dispersal distances. We use an individual-based model with 2500 patches each with identical local dynamics and show that the dispersal distance is under selection pressure. The dispersal distance that evolves is critically dependent on the ecological dynamics. When the cost of dispersal increases linearly with distance, selection is for short-distance dispersal under stable and damped local dynamics but longer distance dispersal is favoured as local dynamics become more complex. For the cases of stable, damped and periodic patch dynamics global patch synchrony occurs even with very short-distance dispersal. Increasing the scale of dispersal for chaotic local dynamics increases the scale of synchrony but global synchrony does not neccesarily occur. We discuss these results in the light of other possible causes of dispersal and argue for the importance of incorporating non-equilibrium population dynamics into evolutionary models of dispersal distance.","author":[{"family":"Murrell","given":"David"},{"family":"Travis","given":"Justin"},{"family":"Dytham","given":"Calvin"}],"container-title":"Oikos","container-title-short":"Oikos","DOI":"10.1034/j.1600-0706.2002.970209.x","issued":{"date-parts":[[2002,5,1]]},"source":"ResearchGate","title":"The evolution of dispersal distance in spatially structured populations","type":"article-journal","volume":"97"}, + {"id":"mustinDynamicsClimateInducedRange2009","abstract":"Predicted future climate change will alter species' distributions as they attempt to track the most suitable ' climate window'. Climate envelope models indicate the direction of likely range changes but do not incorporate population dynamics, therefore observed responses may differ greatly from these projections. We use simulation modelling to explore the consequences of a period of environmental change for a species structured across an environmental gradient. Results indicate that a species' range may lag behind its climate envelope and demonstrate that the rate of movement of a range can accelerate during a period of climate change. We conclude that the inclusion of both population dynamics and spatial environmental variability is vital to develop models that can both predict, and be used to manage, the impact of changing climate on species' biogeography.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Mustin","given":"Karen"},{"family":"Benton","given":"Tim G."},{"family":"Dytham","given":"Calvin"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Oikos","ISSN":"0030-1299","issue":"1","issued":{"date-parts":[[2009]]},"page":"131-137","publisher":"[Nordic Society Oikos, Wiley]","source":"JSTOR","title":"The Dynamics of Climate-Induced Range Shifting; Perspectives from Simulation Modelling","type":"article-journal","URL":"https://www.jstor.org/stable/40235617","volume":"118"}, + {"id":"mustinRedNoiseIncreases2013","abstract":"Aim As the global climate is changing rapidly, there is a need to make conservation decisions to facilitate species' persistence under climate change. Models employed to make predictions regarding the impacts of climate change on species' distributions, and ultimately persistence, typically assume that interannual variability in environmental conditions is independent between years. However, the colour of environmental noise has been shown to affect extinction risk in populations occupying spatially static environments, and should therefore affect persistence during climate change. This study aims to investigate the importance of noise colour for extinction risk during climate-induced range shifts. Methods We use a spatially explicit coupled map lattice with a latitudinal gradient in climatic suitability, together with time series of environmental noise, to simulate periods of directional climate change and investigate the effects of noise colour on extinction risk and range size. Results Extinction risk increases with reddening of the environmental noise, and this effect is particularly pronounced over short time frames when climate change is rapid. Main conclusions Given that management decisions are typically made over such short time frames, and the rapid rates of climate change currently being experienced, we highlight the importance of incorporating realistic time series of environmental noise into models used for conservation planning under climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Mustin","given":"Karen"},{"family":"Dytham","given":"Calvin"},{"family":"Benton","given":"Tim G."},{"family":"Travis","given":"Justin M. J."}],"container-title":"Diversity and Distributions","DOI":"10.1111/ddi.12038","ISSN":"1472-4642","issue":"7","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ddi.12038","page":"815-824","source":"Wiley Online Library","title":"Red noise increases extinction risk during rapid climate change","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/ddi.12038","volume":"19"}, + {"id":"nathanDispersalKernelsReview2012","author":[{"family":"Nathan","given":"Ran"},{"family":"Klein","given":"Etienne"},{"family":"Robledo-Anuncio","given":"J.J."},{"family":"Revilla","given":"Eloy"}],"container-title":"Dispersal Ecology and Evolution","container-title-short":"Dispersal Ecology and Evolution","issued":{"date-parts":[[2012,1,1]]},"source":"ResearchGate","title":"Dispersal kernels: review. Chapter 15","title-short":"Dispersal kernels","type":"article-journal"}, + {"id":"nathanMovementEcologyParadigm2008a","abstract":"Movement of individual organisms is fundamental to life, quilting our planet in a rich tapestry of phenomena with diverse implications for ecosystems and humans. Movement research is both plentiful and insightful, and recent methodological advances facilitate obtaining a detailed view of individual movement. Yet, we lack a general unifying paradigm, derived from first principles, which can place movement studies within a common context and advance the development of a mature scientific discipline. This introductory article to the Movement Ecology Special Feature proposes a paradigm that integrates conceptual, theoretical, methodological, and empirical frameworks for studying movement of all organisms, from microbes to trees to elephants. We introduce a conceptual framework depicting the interplay among four basic mechanistic components of organismal movement: the internal state (why move?), motion (how to move?), and navigation (when and where to move?) capacities of the individual and the external factors affecting movement. We demonstrate how the proposed framework aids the study of various taxa and movement types; promotes the formulation of hypotheses about movement; and complements existing biomechanical, cognitive, random, and optimality paradigms of movement. The proposed framework integrates eclectic research on movement into a structured paradigm and aims at providing a basis for hypothesis generation and a vehicle facilitating the understanding of the causes, mechanisms, and spatiotemporal patterns of movement and their role in various ecological and evolutionary processes.\n”Now we must consider in general the common reason for moving with any movement whatever.“ (Aristotle, De Motu Animalium, 4th century B.C.)","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Nathan","given":"Ran"},{"family":"Getz","given":"Wayne M."},{"family":"Revilla","given":"Eloy"},{"family":"Holyoak","given":"Marcel"},{"family":"Kadmon","given":"Ronen"},{"family":"Saltz","given":"David"},{"family":"Smouse","given":"Peter E."}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.0800375105","ISSN":"0027-8424, 1091-6490","issue":"49","issued":{"date-parts":[[2008,12,9]]},"language":"en","page":"19052-19059","PMID":"19060196","publisher":"National Academy of Sciences","section":"Perspective","source":"www.pnas.org","title":"A movement ecology paradigm for unifying organismal movement research","type":"article-journal","URL":"https://www.pnas.org/content/105/49/19052","volume":"105"}, + {"id":"nathanSpreadNorthAmerican2011","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Nathan","given":"R."},{"family":"Horvitz","given":"N"},{"family":"He","given":"Y"},{"family":"Kuparinen, A","given":""},{"family":"Schurr","given":"F. M."},{"family":"Katul","given":"G. G."}],"container-title":"Ecology Letters","issue":"14","issued":{"date-parts":[[2011]]},"page":"211-219","title":"Spread of North American wind‐dispersed trees in future environments","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/10.1111/j.1461-0248.2010.01573.x"}, + {"id":"neubertDensitydependentVitalRates2000","abstract":"We explore a set of simple, nonlinear, two-stage models that allow us to compare the effects of density dependence on population dynamics among different kinds of life cycles. We characterize the behavior of these models in terms of their equilibria, bifurcations. and nonlinear dynamics, for a wide range of parameters. Our analyses lead to several generalizations about the effects of life history and density dependence on population dynamics. Among these are: (1) iteroparous life histories are more likely to be stable than semelparous life histories; (2) an increase in juvenile survivorship tends to be stabilizing; (3) density-dependent adult survival cannot control population growth when reproductive output is high: (4) density-dependent reproduction is more likely to cause chaotic dynamics than density dependence in other vital rates; and (5) changes in development rate have only small effects on bifurcation patterns.","author":[{"family":"Neubert","given":"M. G."},{"family":"Caswell","given":"H. C."}],"container-title":"Journal of Mathematical Biology","container-title-short":"J Math Biol","DOI":"10.1007/s002850070001","ISSN":"0303-6812","issue":"2","issued":{"date-parts":[[2000,8]]},"language":"eng","page":"103-121","PMID":"11039693","source":"PubMed","title":"Density-dependent vital rates and their population dynamic consequences","type":"article-journal","volume":"41"}, + {"id":"norbergEcoevolutionaryResponsesBiodiversity2012","abstract":"This study describes the development of a multi-species model used to explore the integrated eco-evolutionary responses to climate change. The results should help to understand and predict the responses of biological diversity, ecosystems, and ecological services to changing climate.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Norberg","given":"Jon"},{"family":"Urban","given":"Mark C."},{"family":"Vellend","given":"Mark"},{"family":"Klausmeier","given":"Christopher A."},{"family":"Loeuille","given":"Nicolas"}],"container-title":"Nature Climate Change","container-title-short":"Nature Clim Change","DOI":"10.1038/nclimate1588","ISSN":"1758-6798","issue":"10","issued":{"date-parts":[[2012,10]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Research\nSubject_term: Biodiversity;Climate change;Evolutionary ecology\nSubject_term_id: biodiversity;climate-change;evolutionary-ecology","number":"10","page":"747-751","publisher":"Nature Publishing Group","source":"www.nature.com","title":"Eco-evolutionary responses of biodiversity to climate change","type":"article-journal","URL":"https://www.nature.com/articles/nclimate1588","volume":"2"}, + {"id":"northEvolutionaryResponsesDispersal2011","abstract":"It is generally well understood that some ecological factors select for increased and others for decreased dispersal. However, it has remained difficult to assess how the evolutionary dynamics are influenced by the spatio-temporal structure of the environment. We address this question with an individual-based model that enables habitat structure to be controlled through variables such as patch size, patch turnover rate, and patch quality. Increasing patch size at the expense of patch density can select for more or less dispersal, depending on the initial configuration. In landscapes consisting of high-quality and long-lived habitat patches, patch degradation selects for increased dispersal, yet patch loss may select for reduced dispersal. These trends do not depend on the component of life-history that is affected by habitat quality or the component of life-history through which density-dependence operates. Our results are based on a mathematical method that enables derivation of both the evolutionary stable strategy and the stationary genotype distribution that evolves in a polymorphic population. The two approaches generally lead to similar predictions. However, the evolutionary stable strategy assumes that the ecological and evolutionary time scales can be separated, and we find that violation of this assumption can critically alter the evolutionary outcome.","author":[{"family":"North","given":"Ace"},{"family":"Cornell","given":"Stephen"},{"family":"Ovaskainen","given":"Otso"}],"container-title":"Evolution; International Journal of Organic Evolution","container-title-short":"Evolution","DOI":"10.1111/j.1558-5646.2011.01254.x","ISSN":"1558-5646","issue":"6","issued":{"date-parts":[[2011,6]]},"language":"eng","page":"1739-1751","PMID":"21644960","source":"PubMed","title":"Evolutionary responses of dispersal distance to landscape structure and habitat loss","type":"article-journal","volume":"65"}, + {"id":"okamotoFrameworkHighthroughputEcoevolutionary2018","abstract":"The evolutionary dynamics of quantitative traits in a species depends on demographic structure (e.g. age- and size-dependent vital rates, migration across subpopulations, mate preferences, and the presence or absence of overlapping generations), which in turn can depend on interspecific interactions with other evolving species. Furthermore, biologists increasingly appreciate that evolutionary change in a single species can substantively affect broader ecological processes, such as community assembly and ecosystem functioning. Models integrating insights from classical population and quantitative genetics, on the one hand, and community ecology theory, on the other, are therefore critical to elucidating the interplay between ecological and evolutionary processes. However, few modelling approaches integrate ecological and genetic details into a comprehensive framework. Such models are needed to account for the reciprocal feedback between evolutionary change and ecological dynamics, and develop effective responses to anthropogenic disturbances on natural communities, improve agricultural practices and manage global health risks such as emerging pathogens. Here we introduce an open-source, multi-species forward-time population genetics simulator and framework for rapidly simulating eco-evolutionary dynamics. Our approach permits building models that can account for alternative genetic architectures, non-standard population dynamics and demographic structures, including those driven by interspecific interactions with other evolving species and the spatial dynamics of metacommunities. By integrating these processes into a common framework, we aim to facilitate the development of models that can further elucidate eco-evolutionary dynamics. While multi-species, forward-time population genetic models can be computationally expensive, we show how our framework leverages relatively economical graphics cards installed in modern desktops. We illustrate the versatility and general applicability of our approach for two very different case studies: antagonistic coevolution in space, and the evolution of life-history traits in response to resource dynamics in physiologically structured populations. We find that our analyses can run up to c. 200 times faster on a single commodity graphics card than on a single CPU core, comparable to the performance gains on small-to-medium sized computer clusters. Our approach therefore substantively reduces implementation difficulties to integrating ecological and evolutionary theory.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Okamoto","given":"Kenichi W."},{"family":"Amarasekare","given":"Priyanga"}],"container-title":"Methods in Ecology and Evolution","DOI":"10.1111/2041-210X.12889","ISSN":"2041-210X","issue":"3","issued":{"date-parts":[[2018]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/2041-210X.12889","page":"525-534","source":"Wiley Online Library","title":"A framework for high-throughput eco-evolutionary simulations integrating multilocus forward-time population genetics and community ecology","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.12889","volume":"9"}, + {"id":"oldenContextdependentPerceptualRanges2004","abstract":"1 An animal's perceptual range defines the spatial extent of the landscape for which information is available to make movement decisions. Ecologists studying and modelling animal dispersal have commonly assumed that individual movements arise from a predefined set of local decision rules operating within a static isotropic (i.e. circular) perceptual range. 2 We discuss how this assumption fails to recognize the potential for plasticity in perceptual ranges and present a conceptual model that illustrates how anisotropic perceptual ranges can arise from animal orientation to environmental stimuli. 3 Using model simulations we show how perceptual distance (i.e. greatest Euclidean distance at which habitat patches can be perceived), horizon (i.e. panoramic view or angular degrees of the landscape perceived) and breadth (i.e. areal extent of the landscape perceived), change as a function of increased strength of a hypothetical stimuli. 4 Our results show that anisotropic perceptual ranges can differ substantially from traditional, isotropic perceptual ranges in all three aspects depending on the strength of the stimuli and nature in which it interacts with other elements of the landscape. 5 We highlight the implications of these findings for modelling animal movements in ecological landscapes with the hope that context-dependent perceptual ranges are considered in future studies.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Olden","given":"Julian D."},{"family":"Schooley","given":"Robert L."},{"family":"Monroe","given":"Jeremy B."},{"family":"Poff","given":"N. Leroy"}],"container-title":"Journal of Animal Ecology","DOI":"10.1111/j.0021-8790.2004.00889.x","ISSN":"1365-2656","issue":"6","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.0021-8790.2004.00889.x","page":"1190-1194","source":"Wiley Online Library","title":"Context-dependent perceptual ranges and their relevance to animal movements in landscapes","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.0021-8790.2004.00889.x","volume":"73"}, + {"id":"opdamClimateChangeMeets2004","abstract":"Climate change and habitat fragmentation are considered key pressures on biodiversity. In this paper we explore the potential synergetic effects between these factors. We argue that processes at two levels of spatial scale interact: the metapopulation level and the species range level. Current concepts of spatially dynamic metapopulations and species ranges are consistent, and integration improves our understanding of the interaction of landscape level and geographical range level processes. In landscape zones in which the degree of habitat fragmentation allows persistence, the shifting of ranges is inhibited, but not blocked. In areas where the spatial cohesion of the habitat is below the critical level of metapopulation persistence, the expansion of ranges will be blocked. An increased frequency of large-scale disturbances caused by extreme weather events will cause increasing gaps and an overall contraction of the distribution range, particularly in areas with relatively low levels of spatial cohesion. Taking into account the effects of climate change on metapopulations, habitat distribution and land use changes, future biodiversity research and conservation strategies are facing the challenge to re-orient their focus and scope by integrating spatially and conceptually more dynamic aspects at the landscape level.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Opdam","given":"Paul"},{"family":"Wascher","given":"Dirk"}],"container-title":"Biological Conservation","container-title-short":"Biological Conservation","DOI":"10.1016/j.biocon.2003.12.008","ISSN":"0006-3207","issue":"3","issued":{"date-parts":[[2004,5,1]]},"language":"en","page":"285-297","source":"ScienceDirect","title":"Climate change meets habitat fragmentation: linking landscape and biogeographical scale levels in research and conservation","title-short":"Climate change meets habitat fragmentation","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0006320703004890","volume":"117"}, + {"id":"ovaskainenBiasedMovementBoundary2003","abstract":"Motivated by edge behaviour reported for biological organisms, we show that random walks with a bias at a boundary lead to a discontinuous probability density across the boundary. We continue by studying more general diffusion processes with such a discontinuity across an interior boundary. We show how hitting probabilities, occupancy times and conditional occupancy times may be solved from problems that are adjoint to the original diffusion problem. We highlight our results with a biologically motivated example, where we analyze the movement behaviour of an individual in a network of habitat patches surrounded by dispersal habitat.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ovaskainen","given":"Otso"},{"family":"Cornell","given":"Stephen J."}],"container-title":"Journal of Applied Probability","ISSN":"0021-9002","issue":"3","issued":{"date-parts":[[2003]]},"page":"557-580","publisher":"Applied Probability Trust","source":"JSTOR","title":"Biased Movement at a Boundary and Conditional Occupancy Times for Diffusion Processes","type":"article-journal","URL":"https://www.jstor.org/stable/3215936","volume":"40"}, + {"id":"ovaskainenEmpiricalTestDiffusion2008","abstract":"Functional connectivity is a fundamental concept in conservation biology because it sets the level of migration and gene flow among local populations. However, functional connectivity is difficult to measure, largely because it is hard to acquire and analyze movement data from heterogeneous landscapes. Here we apply a Bayesian state-space framework to parameterize a diffusion-based movement model using capture-recapture data on the endangered clouded apollo butterfly. We test whether the model is able to disentangle the inherent movement behavior of the species from landscape structure and sampling artifacts, which is a necessity if the model is to be used to examine how movements depend on landscape structure. We show that this is the case by demonstrating that the model, parameterized with data from a reference landscape, correctly predicts movements in a structurally different landscape. In particular, the model helps to explain why a movement corridor that was constructed as a management measure failed to increase movement among local populations. We illustrate how the parameterized model can be used to derive biologically relevant measures of functional connectivity, thus linking movement data with models of spatial population dynamics.","author":[{"family":"Ovaskainen","given":"Otso"},{"family":"Luoto","given":"Miska"},{"family":"Ikonen","given":"Iiro"},{"family":"Rekola","given":"Hanna"},{"family":"Meyke","given":"Evgeniy"},{"family":"Kuussaari","given":"Mikko"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/587070","ISSN":"1537-5323","issue":"5","issued":{"date-parts":[[2008,5]]},"language":"eng","page":"610-619","PMID":"18419523","source":"PubMed","title":"An empirical test of a diffusion model: predicting clouded apollo movements in a novel environment","title-short":"An empirical test of a diffusion model","type":"article-journal","volume":"171"}, + {"id":"ovaskainenHabitatSpecificMovementParameters2004","abstract":"I describe a diffusion model aimed at the quantitative analysis of movement in heterogeneous landscapes. The model is based on classifying a landscape into a number of habitat types, which are assumed to differ from each other in terms of the movement behavior of the focal species. In addition to habitat-specific diffusion and mortality coefficients, the model accounts for edge-mediated behavior, meaning biased behavior close to boundaries between the habitat types. I illustrate the model with three examples. In the first example, I examine how the strength of edge-mediated behavior and the size of a habitat patch affect the probability that an individual will immigrate to a patch, the probability that an individual will emigrate from a patch, and the time that an individual is expected to spend in a patch. In the second example, I study how a dispersal corridor affects the probability that an individual will move through a landscape. In the third example, I estimate the movement parameters for a species of butterfly from mark–recapture data. In the butterfly example, I classify the landscape into habitat patches, other open areas, and forests. Edge-mediated behavior is found to have a highly significant effect on the general dispersal pattern of the butterfly: the model predicts that the density of butterflies inside habitat patches is >100 times the density of butterflies in adjacent areas.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ovaskainen","given":"Otso"}],"container-title":"Ecology","DOI":"10.1890/02-0706","ISSN":"1939-9170","issue":"1","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/02-0706","page":"242-257","source":"Wiley Online Library","title":"Habitat-Specific Movement Parameters Estimated Using Mark–Recapture Data and a Diffusion Model","type":"article-journal","URL":"https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/02-0706","volume":"85"}, + {"id":"ovaskainenModelingAnimalMovement2009","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ovaskainen","given":"Otso"},{"family":"Crone","given":"E. E."}],"container-title":"Spatial Ecology","issued":{"date-parts":[[2009]]},"language":"Finnish","publisher":"Chapman & Hall / CRC","source":"researchportal.helsinki.fi","title":"Modeling animal movement with diffusion","type":"article-journal","URL":"https://researchportal.helsinki.fi/en/publications/modeling-animal-movement-with-diffusion"}, + {"id":"ovaskainenTrackingButterflyMovements2008","abstract":"We used harmonic radar to track freely flying Glanville fritillary butterfly (Melitaea cinxia) females within an area of 30 ha. Butterflies originated from large and continuous populations in China and Estonia, and from newly established or old (> 5 years) small local populations in a highly fragmented landscape in Finland. Caterpillars were raised under common garden conditions and unmated females were tested soon after eclosion. The reconstructed flight paths for 66 individuals comprised a total distance of 51 km with high spatial resolution. Butterflies originating from large continuous populations and from old local populations in Finland exhibited similar movement behaviors, whereas butterflies originating from newly established local populations in the fragmented landscape in Finland moved significantly more than the others. There was no difference in the lengths of individual flight bouts, but the new-population females flew more frequently, resulting in longer daily movement tracks. The flight activity of all individuals was affected by environmental conditions, peaking at 19–23°C (depending on population type), in the early afternoon, and during calm weather. Butterflies from all population types showed a strong tendency to follow habitat edges between the open study area and the neighboring woodlands.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ovaskainen","given":"Otso"},{"family":"Smith","given":"Alan D."},{"family":"Osborne","given":"Juliet L."},{"family":"Reynolds","given":"Don R."},{"family":"Carreck","given":"Norman L."},{"family":"Martin","given":"Andrew P."},{"family":"Niitepõld","given":"Kristjan"},{"family":"Hanski","given":"Ilkka"}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.0802066105","ISSN":"0027-8424, 1091-6490","issue":"49","issued":{"date-parts":[[2008,12,9]]},"language":"en","page":"19090-19095","PMID":"19060191","publisher":"National Academy of Sciences","section":"Research Article","source":"www.pnas.org","title":"Tracking butterfly movements with harmonic radar reveals an effect of population age on movement distance","type":"article-journal","URL":"https://www.pnas.org/content/105/49/19090","volume":"105"}, + {"id":"pagelForecastingSpeciesRanges2012a","abstract":"Aim The study and prediction of species–environment relationships is currently mainly based on species distribution models. These purely correlative models neglect spatial population dynamics and assume that species distributions are in equilibrium with their environment. This causes biased estimates of species niches and handicaps forecasts of range dynamics under environmental change. Here we aim to develop an approach that statistically estimates process-based models of range dynamics from data on species distributions and permits a more comprehensive quantification of forecast uncertainties. Innovation We present an approach for the statistical estimation of process-based dynamic range models (DRMs) that integrate Hutchinson's niche concept with spatial population dynamics. In a hierarchical Bayesian framework the environmental response of demographic rates, local population dynamics and dispersal are estimated conditional upon each other while accounting for various sources of uncertainty. The method thus: (1) jointly infers species niches and spatiotemporal population dynamics from occurrence and abundance data, and (2) provides fully probabilistic forecasts of future range dynamics under environmental change. In a simulation study, we investigate the performance of DRMs for a variety of scenarios that differ in both ecological dynamics and the data used for model estimation. Main conclusions Our results demonstrate the importance of considering dynamic aspects in the collection and analysis of biodiversity data. In combination with informative data, the presented framework has the potential to markedly improve the quantification of ecological niches, the process-based understanding of range dynamics and the forecasting of species responses to environmental change. It thereby strengthens links between biogeography, population biology and theoretical and applied ecology.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Pagel","given":"Jörn"},{"family":"Schurr","given":"Frank M."}],"container-title":"Global Ecology and Biogeography","DOI":"10.1111/j.1466-8238.2011.00663.x","ISSN":"1466-8238","issue":"2","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1466-8238.2011.00663.x","page":"293-304","source":"Wiley Online Library","title":"Forecasting species ranges by statistical estimation of ecological niches and spatial population dynamics","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1466-8238.2011.00663.x","volume":"21"}, + {"id":"palmerInterindividualVariabilityDispersal2014","abstract":"The importance of landscape connectivity in determining biodiversity outcomes under environmental change has led to indices of connectivity becoming amongst the most widely used measures in conservation. Thus, it is vital that our understanding of connectivity and our use of indices describing it are reliable. Dispersal is the key ecological process involved in determining connectivity, and there is increasing evidence of substantial within-population variability in dispersal behaviours. Here, we incorporate this inter-individual variability into two approaches for estimating connectivity, least cost path analysis and stochastic movement simulation. Illustrative results demonstrate that including dispersal variability can yield substantially different estimates of connectivity. While connectivity is typically similar between nearby patches, the frequency of movements between patches further apart is often substantially increased when inter-individual variability is included. Given the disproportionate role that unusual long-distance dispersal events play in spatial dynamics, connectivity indices should seek to incorporate variability in dispersal behaviour.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Palmer","given":"Stephen C. F."},{"family":"Coulon","given":"Aurélie"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Oikos","DOI":"10.1111/oik.01248","ISSN":"1600-0706","issue":"8","issued":{"date-parts":[[2014]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/oik.01248","page":"923-932","source":"Wiley Online Library","title":"Inter-individual variability in dispersal behaviours impacts connectivity estimates","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/oik.01248","volume":"123"}, + {"id":"palmerIntroducingStochasticMovement2011","abstract":"1. Estimating and improving landscape connectivity has become a key topic in conservation biology. While a range of connectivity indices exist and are widely used to inform spatial planning, they have potentially serious limitations. 2. We introduce a new method for modelling animals moving between habitat patches across a heterogeneous matrix. Our approach integrates features of least cost path analysis with stochastic movement modelling. Importantly, it relaxes assumptions that are implicit in the least cost path algorithm: our method does not assume omniscience nor does it assume that an individual has a planned destination when it leaves a habitat patch. The algorithm incorporates resistance values for matrix elements and parameters that relate to both perceptual range and to the degree of correlation in movement. By simulating sets of movements for individuals emigrating from habitat patches, relative connectivities between habitat patches are estimated. 3. Using an already published stylised landscape, we demonstrate that the connectivities estimated using our new method can differ considerably from those provided by structural methods and by least cost path analysis. Further, our results emphasise the sensitivity of the relative connectivities to an organism’s perceptual range and the degree of correlation between movement steps. 4. We believe that using stochastic movement modelling can improve estimates of connectivity and also provide a method for determining how robust the indices derived from simpler methods are likely to be for different types of organisms.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Palmer","given":"Stephen C. F."},{"family":"Coulon","given":"Aurélie"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Methods in Ecology and Evolution","DOI":"10.1111/j.2041-210X.2010.00073.x","ISSN":"2041-210X","issue":"3","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.2041-210X.2010.00073.x","page":"258-268","source":"Wiley Online Library","title":"Introducing a ‘stochastic movement simulator’ for estimating habitat connectivity","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.2041-210X.2010.00073.x","volume":"2"}, + {"id":"parmesanGloballyCoherentFingerprint2003","abstract":"Causal attribution of recent biological trends to climate change is complicated because non-climatic influences dominate local, short-term biological changes. Any underlying signal from climate change is likely to be revealed by analyses that seek systematic trends across diverse species and geographic regions; however, debates within the Intergovernmental Panel on Climate Change (IPCC) reveal several definitions of a ‘systematic trend’. Here, we explore these differences, apply diverse analyses to more than 1,700 species, and show that recent biological trends match climate change predictions. Global meta-analyses documented significant range shifts averaging 6.1 km per decade towards the poles (or metres per decade upward), and significant mean advancement of spring events by 2.3 days per decade. We define a diagnostic fingerprint of temporal and spatial ‘sign-switching’ responses uniquely predicted by twentieth century climate trends. Among appropriate long-term/large-scale/multi-species data sets, this diagnostic fingerprint was found for 279 species. This suite of analyses generates ‘very high confidence’ (as laid down by the IPCC) that climate change is already affecting living systems.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Parmesan","given":"Camille"},{"family":"Yohe","given":"Gary"}],"container-title":"Nature","DOI":"10.1038/nature01286","ISSN":"1476-4687","issue":"6918","issued":{"date-parts":[[2003,1]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Research","number":"6918","page":"37-42","publisher":"Nature Publishing Group","source":"www.nature.com","title":"A globally coherent fingerprint of climate change impacts across natural systems","type":"article-journal","URL":"https://www.nature.com/articles/nature01286","volume":"421"}, + {"id":"parmesanPolewardShiftsGeographical1999","abstract":"Mean global temperatures have risen this century, and further warming is predicted to continue for the next 50–100 years1,2,3. Some migratory species can respond rapidly to yearly climate variation by altering the timing or destination of migration4, but most wildlife is sedentary and so is incapable of such a rapid response. For these species, responses to the warming trend should be slower, reflected in poleward shifts of the range. Such changes in distribution would occur at the level of the population, stemming not from changes in the pattern of individuals' movements, but from changes in the ratios of extinctions to colonizations at the northern and southern boundaries of the range. A northward range shift therefore occurs when there is net extinction at the southern boundary or net colonization at the northern boundary. However, previous evidence has been limited to a single species5 or to only a portion of the species' range6,7. Here we provide the first large-scale evidence of poleward shifts in entire species' ranges. In a sample of 35 non-migratory European butterflies, 63% have ranges that have shifted to the north by 35–240 km during this century, and only 3% have shifted to the south.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Parmesan","given":"Camille"},{"family":"Ryrholm","given":"Nils"},{"family":"Stefanescu","given":"Constantí"},{"family":"Hill","given":"Jane K."},{"family":"Thomas","given":"Chris D."},{"family":"Descimon","given":"Henri"},{"family":"Huntley","given":"Brian"},{"family":"Kaila","given":"Lauri"},{"family":"Kullberg","given":"Jaakko"},{"family":"Tammaru","given":"Toomas"},{"family":"Tennent","given":"W. John"},{"family":"Thomas","given":"Jeremy A."},{"family":"Warren","given":"Martin"}],"container-title":"Nature","DOI":"10.1038/21181","ISSN":"1476-4687","issue":"6736","issued":{"date-parts":[[1999,6]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Research","number":"6736","page":"579-583","publisher":"Nature Publishing Group","source":"www.nature.com","title":"Poleward shifts in geographical ranges of butterfly species associated with regional warming","type":"article-journal","URL":"https://www.nature.com/articles/21181","volume":"399"}, + {"id":"pattersonStateSpaceModels2008","abstract":"Detailed observation of the movement of individual animals offers the potential to understand spatial population processes as the ultimate consequence of individual behaviour, physiological constraints and fine-scale environmental influences. However, movement data from individuals are intrinsically stochastic and often subject to severe observation error. Linking such complex data to dynamical models of movement is a major challenge for animal ecology. Here, we review a statistical approach, state–space modelling, which involves changing how we analyse movement data and draw inferences about the behaviours that shape it. The statistical robustness and predictive ability of state–space models make them the most promising avenue towards a new type of movement ecology that fuses insights from the study of animal behaviour, biogeography and spatial population dynamics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Patterson","given":"Toby A."},{"family":"Thomas","given":"Len"},{"family":"Wilcox","given":"Chris"},{"family":"Ovaskainen","given":"Otso"},{"family":"Matthiopoulos","given":"Jason"}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/j.tree.2007.10.009","ISSN":"0169-5347","issue":"2","issued":{"date-parts":[[2008,2,1]]},"language":"en","page":"87-94","source":"ScienceDirect","title":"State–space models of individual animal movement","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169534707003588","volume":"23"}, + {"id":"pearsonPredictingImpactsClimate2003","abstract":"Modelling strategies for predicting the potential impacts of climate change on the natural distribution of species have often focused on the characterization of a species’ bioclimate envelope. A number of recent critiques have questioned the validity of this approach by pointing to the many factors other than climate that play an important part in determining species distributions and the dynamics of distribution changes. Such factors include biotic interactions, evolutionary change and dispersal ability. This paper reviews and evaluates criticisms of bioclimate envelope models and discusses the implications of these criticisms for the different modelling strategies employed. It is proposed that, although the complexity of the natural system presents fundamental limits to predictive modelling, the bioclimate envelope approach can provide a useful first approximation as to the potentially dramatic impact of climate change on biodiversity. However, it is stressed that the spatial scale at which these models are applied is of fundamental importance, and that model results should not be interpreted without due consideration of the limitations involved. A hierarchical modelling framework is proposed through which some of these limitations can be addressed within a broader, scale-dependent context.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Pearson","given":"Richard G."},{"family":"Dawson","given":"Terence P."}],"container-title":"Global Ecology and Biogeography","DOI":"10.1046/j.1466-822X.2003.00042.x","ISSN":"1466-8238","issue":"5","issued":{"date-parts":[[2003]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1466-822X.2003.00042.x","page":"361-371","source":"Wiley Online Library","title":"Predicting the impacts of climate change on the distribution of species: are bioclimate envelope models useful?","title-short":"Predicting the impacts of climate change on the distribution of species","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1046/j.1466-822X.2003.00042.x","volume":"12"}, + {"id":"peerBreakingFunctionalConnectivity2011","abstract":"Landscape connectivity is a key factor determining the viability of populations in fragmented landscapes. Predicting ‘functional connectivity’, namely whether a patch or a landscape functions as connected from the perspective of a focal species, poses various challenges. First, empirical data on the movement behaviour of species is often scarce. Second, animal-landscape interactions are bound to yield complex patterns. Lastly, functional connectivity involves various components that are rarely assessed separately. We introduce the spatially explicit, individual-based model FunCon as means to distinguish between components of functional connectivity and to assess how each of them affects the sensitivity of species and communities to landscape structures. We then present the results of exploratory simulations over six landscapes of different fragmentation levels and across a range of hypothetical bird species that differ in their response to habitat edges. i) Our results demonstrate that estimations of functional connectivity depend not only on the response of species to edges (avoidance versus penetration into the matrix), the movement mode investigated (home range movements versus dispersal), and the way in which the matrix is being crossed (random walk versus gap crossing), but also on the choice of connectivity measure (in this case, the model output examined). ii) We further show a strong effect of the mortality scenario applied, indicating that movement decisions that do not fully match the mortality risks are likely to reduce connectivity and enhance sensitivity to fragmentation. iii) Despite these complexities, some consistent patterns emerged. For instance, the ranking order of landscapes in terms of functional connectivity was mostly consistent across the entire range of hypothetical species, indicating that simple landscape indices can potentially serve as valuable surrogates for functional connectivity. Yet such simplifications must be carefully evaluated in terms of the components of functional connectivity they actually predict.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Pe'er","given":"Guy"},{"family":"Henle","given":"Klaus"},{"family":"Dislich","given":"Claudia"},{"family":"Frank","given":"Karin"}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0022355","ISSN":"1932-6203","issue":"8","issued":{"date-parts":[[2011,8,1]]},"language":"en","page":"e22355","publisher":"Public Library of Science","source":"PLoS Journals","title":"Breaking Functional Connectivity into Components: A Novel Approach Using an Individual-Based Model, and First Outcomes","title-short":"Breaking Functional Connectivity into Components","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0022355","volume":"6"}, + {"id":"peerIncorporatingPerceptualRange2008","abstract":"The perceptual range of an animal towards different landscape elements affects its movements through heterogeneous landscapes. However, empirical knowledge and modeling tools are lacking to assess the consequences of variation in the perceptual range for movement patterns and connectivity. In this study we tested how changes in the assumed perception of different landscape elements affect the outcomes of a connectivity model. We used an existing individual-based, spatially explicit model for the dispersal of Eurasian lynx (Lynx lynx). We systematically altered the perceptual range in which animals recognize forest fragments, water bodies or cities, as well as the probability that they respond to these landscape elements. Overall, increasing the perceptual range of the animals enhanced connectivity substantially, both qualitatively and quantitatively. An enhanced range of attraction to forests had the strongest impact, doubling immigration success; an enhanced range of attraction to rivers had a slightly lower impact; and an enhanced range of avoidance of cities had the lowest impact. Correcting the enhancement in connectivity by the abundance of each of the landscape elements in question reversed the results, indicating the potential sensitivity of connectivity models to rare landscape elements (in our case barriers such as cities). Qualitatively, the enhanced perception resulted in strong changes in movement patterns and connectivity. Furthermore, model results were highly parameter-specific and patch-specific. These results emphasize the need for further empirical research on the perceptual capabilities of different animals in different landscapes and conditions. They further indicate the usefulness of spatially explicit individual-based simulation models for recognizing consistent patterns that emerge, despite uncertainty regarding animals’ movement behavior. Altogether, this study demonstrates the need to extend the concept of ‘perceptual ranges’ beyond patch detection processes, to encompass the wide range of elements that can direct animal movements during dispersal through heterogeneous landscapes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Pe’er","given":"Guy"},{"family":"Kramer-Schadt","given":"Stephanie"}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/j.ecolmodel.2007.11.020","ISSN":"0304-3800","issue":"1","issued":{"date-parts":[[2008,4,24]]},"language":"en","page":"73-85","source":"ScienceDirect","title":"Incorporating the perceptual range of animals into connectivity models","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0304380007006199","volume":"213"}, + {"id":"peerSimpleProcessBasedSimulators2013","abstract":"Landscape simulators are widely applied in landscape ecology for generating landscape patterns. These models can be divided into two categories: pattern-based models that generate spatial patterns irrespective of the processes that shape them, and process-based models that attempt to generate patterns based on the processes that shape them. The latter often tend toward complexity in an attempt to obtain high predictive precision, but are rarely used for generic or theoretical purposes. Here we show that a simple process-based simulator can generate a variety of spatial patterns including realistic ones, typifying landscapes fragmented by anthropogenic activities. The model “G-RaFFe” generates roads and fields to reproduce the processes in which forests are converted into arable lands. For a selected level of habitat cover, three factors dominate its outcomes: the number of roads (accessibility), maximum field size (accounting for land ownership patterns), and maximum field disconnection (which enables field to be detached from roads). We compared the performance of G-RaFFe to three other models: Simmap (neutral model), Qrule (fractal-based) and Dinamica EGO (with 4 model versions differing in complexity). A PCA-based analysis indicated G-RaFFe and Dinamica version 4 (most complex) to perform best in matching realistic spatial patterns, but an alternative analysis which considers model variability identified G-RaFFe and Qrule as performing best. We also found model performance to be affected by habitat cover and the actual land-uses, the latter reflecting on land ownership patterns. We suggest that simple process-based generators such as G-RaFFe can be used to generate spatial patterns as templates for theoretical analyses, as well as for gaining better understanding of the relation between spatial processes and patterns. We suggest caution in applying neutral or fractal-based approaches, since spatial patterns that typify anthropogenic landscapes are often non-fractal in nature.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Pe'er","given":"Guy"},{"family":"Zurita","given":"Gustavo A."},{"family":"Schober","given":"Lucia"},{"family":"Bellocq","given":"Maria I."},{"family":"Strer","given":"Maximilian"},{"family":"Müller","given":"Michael"},{"family":"Pütz","given":"Sandro"}],"container-title":"PLOS ONE","container-title-short":"PLOS ONE","DOI":"10.1371/journal.pone.0064968","ISSN":"1932-6203","issue":"5","issued":{"date-parts":[[2013,5,28]]},"language":"en","page":"e64968","publisher":"Public Library of Science","source":"PLoS Journals","title":"Simple Process-Based Simulators for Generating Spatial Patterns of Habitat Loss and Fragmentation: A Review and Introduction to the G-RaFFe Model","title-short":"Simple Process-Based Simulators for Generating Spatial Patterns of Habitat Loss and Fragmentation","type":"article-journal","URL":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0064968","volume":"8"}, + {"id":"perrinDispersalInbreedingAvoidance1999","abstract":"Using a game-theoretical approach, we investigate the dispersal patterns expected if inbreeding avoidance were the only reason for dispersal. The evolutionary outcome is always complete philopatry by one sex. The rate of dispersal by the other sex depends on patch size and mating system, as well as inbreeding and dispersal costs. If such costs are sex independent, then two stable equilibria coexist (male or female philopatry), with symmetric domains of attraction. Which sex disperses is determined entirely by history, genetic drift, and gene flow. An asymmetry in costs makes one domain of attraction extend at the expense of the other. In such a case, the dispersing sex might also be, paradoxically, the one that incurs the higher dispersal costs. As asymmetry increases, one equilibrium eventually disappears, which may result in a sudden evolutionary shift in the identity of the dispersing sex. Our results underline the necessity to control for phylogenetic relationships (e.g., through the use of independent-comparisons methods) when investigating empirical trends in dispersal. Our model also makes quantitative predictions on the rate of dispersal by the dispersing sex and suggests that inbreeding avoidance may only rarely be the sole reason for dispersal.","author":[{"family":"Perrin","given":"Nicolas"},{"family":"Mazalov","given":"Vladimir"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/303236","ISSN":"1537-5323","issue":"3","issued":{"date-parts":[[1999,9]]},"language":"eng","page":"282-292","PMID":"10506544","source":"PubMed","title":"Dispersal and Inbreeding Avoidance","type":"article-journal","volume":"154"}, + {"id":"perrinLocalCompetitionInbreeding2000","abstract":"Using game theory, we developed a kin-selection model to investigate the consequences of local competition and inbreeding depression on the evolution of natal dispersal. Mating systems have the potential to favor strong sex biases in dispersal because sex differences in potential reproductive success affect the balance between local resource competition and local mate competition. No bias is expected when local competition equally affects males and females, as happens in monogamous systems and also in polygynous or promiscuous ones as long as female fitness is limited by extrinsic factors (breeding resources). In contrast, a male-biased dispersal is predicted when local mate competition exceeds local resource competition, as happens under polygyny/promiscuity when female fitness is limited by intrinsic factors (maximal rate of processing resources rather than resources themselves). This bias is reinforced by among-sex interactions: female philopatry enhances breeding opportunities for related males, while male dispersal decreases the chances that related females will inbreed. These results meet empirical patterns in mammals: polygynous/promiscuous species usually display a male-biased dispersal, while both sexes disperse in monogamous species. A parallel is drawn with sex-ratio theory, which also predicts biases toward the sex that suffers less from local competition. Optimal sex ratios and optimal sex-specific dispersal show mutual dependence, which argues for the development of coevolution models.","author":[{"family":"Perrin","given":"Nicolas"},{"family":"Mazalov","given":"Vladimir"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/303296","ISSN":"1537-5323","issue":"1","issued":{"date-parts":[[2000,1]]},"language":"eng","page":"116-127","PMID":"10657181","source":"PubMed","title":"Local Competition, Inbreeding, and the Evolution of Sex-Biased Dispersal","type":"article-journal","volume":"155"}, + {"id":"petitSurveyColumnarCacti1996","abstract":"We estimated the population sizes of the three species of columnar cacti that grow on the island of Curacao using ground and aerial transects, and we examined the island's carrying capacity for two species of nectar-feeding bats that depend on nectar from the flowers of these cacti. We calculated carrying capacity based on the daily availability of mature flowers between January and December 1993 and the field energy requirements of bats as estimated from an equation for eutherian mammals (low estimate) and one for passerine birds (high estimate) based on body mass. Additional energy requirements of pregnancy and lactation were taken into account. We estimated that 461,172 columnar cacti were present on Curacao (38% Subpilocereus repandus, 51% Stenocereus griseus, and 11% Pilosocereus lanuginosus). May through September are the critical months when bats rely most heavily on cactus for food. July 1993 was a bottleneck with the smallest number of mature flowers per day. July and August were months of greatest energy demand because females were lactating. We estimate that the carrying capacity for Glossophaga longirostris in July, when the bat (Leptonycteris curasoae) population was 900, was near 1200, an estimate that fits the observed population size of nectar-feeding bats on the island. We suggest that the extensive removal of native vegetation occurring on Curacao be strictly regulated because further destruction of the cacti will result in a decrease and potential loss of the already low populations of nectar-feeding bats.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Petit","given":"Sophie"},{"family":"Pors","given":"Leon"}],"container-title":"Conservation Biology","ISSN":"0888-8892","issue":"3","issued":{"date-parts":[[1996]]},"page":"769-775","publisher":"[Wiley, Society for Conservation Biology]","source":"JSTOR","title":"Survey of Columnar Cacti and Carrying Capacity for Nectar-Feeding Bats on Curacao","type":"article-journal","URL":"https://www.jstor.org/stable/2387099","volume":"10"}, + {"id":"phillipsLifehistoryEvolutionRangeshifting2010a","abstract":"Most evolutionary theory does not deal with populations expanding or contracting in space. Invasive species, climate change, epidemics, and the breakdown of dispersal barriers, however, all create populations in this kind of spatial disequilibrium. Importantly, spatial disequilibrium can have important ecological and evolutionary outcomes. During continuous range expansion, for example, populations on the expanding front experience novel evolutionary pressures because frontal populations are assorted by dispersal ability and have a lower density of conspecifics than do core populations. These conditions favor the evolution of traits that increase rates of dispersal and reproduction. Additionally, lowered density on the expanding front eventually frees populations on the expanding edge from specialist, coevolved enemies, permitting higher investment into traits associated with dispersal and reproduction rather than defense against pathogens. As a result, the process of range expansion drives rapid life-history evolution, and this seems to occur despite ongoing serial founder events that have complex effects on genetic diversity at the expanding front. Traits evolving on the expanding edge are smeared across the landscape as the front moves through, leaving an ephemeral signature of range expansion in the life-history traits of a species across its newly colonized range. Recent studies suggest that such nonequilibrium processes during recent population history may have contributed to many patterns usually ascribed to evolutionary forces acting in populations at spatial equilibrium.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Phillips","given":"Benjamin L."},{"family":"Brown","given":"Gregory P."},{"family":"Shine","given":"Richard"}],"container-title":"Ecology","DOI":"10.1890/09-0910.1","ISSN":"1939-9170","issue":"6","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/09-0910.1","page":"1617-1627","source":"Wiley Online Library","title":"Life-history evolution in range-shifting populations","type":"article-journal","URL":"https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/09-0910.1","volume":"91"}, + {"id":"phillipsRangeShiftPromotes2012","abstract":"Aim I investigate the counter-intuitive possibility that range shift promotes the formation of stable range edges. This might be expected because: (1) range-shifting populations typically evolve increased dispersal on the expanding range edge; (2) increased dispersal steepens the relative slope of environmental gradients (gradients appear steeper to a more dispersive population); and (3) environmental gradients that are steep relative to dispersal encourage the formation of stable range edges (when gradients appear steep, adaptation on the range edge is swamped by maladapted genes). Methods I test the idea that populations take longer to evolve across an environmental gradient when those populations have already undergone a period of spread. I do this using an individual-based coupled map lattice simulation, in which individuals carry heritable traits for dispersal probability and environment-specific fitness. Results Numerous simulations across parameter space confirm that a period of range shift almost always results in a longer time to evolve through an environmental gradient. This occurs because of both the mechanism described above and the erosion of adaptive variation resulting from the serial foundering that occurs during range advance. Main conclusions This result suggests that species may often shift their range due to intrinsic changes in the population rather than extrinsic changes in the environment. The result also suggests a new mechanism regulating the speed of invasion, and sounds a cautionary note for climate change impacts: the longer a species tracks climate change, the less able it may be to track that change into the future.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Phillips","given":"Ben L."}],"container-title":"Journal of Biogeography","DOI":"10.1111/j.1365-2699.2011.02597.x","ISSN":"1365-2699","issue":"1","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2011.02597.x","page":"153-161","source":"Wiley Online Library","title":"Range shift promotes the formation of stable range edges","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2699.2011.02597.x","volume":"39"}, + {"id":"phillipsReidParadoxRevisited2008a","abstract":"Current approaches to modeling range advance assume that the distribution describing dispersal distances in the population (the \"dispersal kernel\") is a static entity. We argue here that dispersal kernels are in fact highly dynamic during periods of range advance because density effects and spatial assortment by dispersal ability (\"spatial selection\") drive the evolution of increased dispersal on the expanding front. Using a spatially explicit individual-based model, we demonstrate this effect under a wide variety of population growth rates and dispersal costs. We then test the possibility of an evolved shift in dispersal kernels by measuring dispersal rates in individual cane toads (Bufo marinus) from invasive populations in Australia (historically, toads advanced their range at 10 km/year, but now they achieve >55 km/year in the northern part of their range). Under a common-garden design, we found a steady increase in dispersal tendency with distance from the invasion origin. Dispersal kernels on the invading front were less kurtotic and less skewed than those from origin populations. Thus, toads have increased their rate of range expansion partly through increased dispersal on the expanding front. For accurate long-range forecasts of range advance, we need to take into account the potential for dispersal kernels to be evolutionarily dynamic.","author":[{"family":"Phillips","given":"Benjamin L."},{"family":"Brown","given":"Gregory P."},{"family":"Travis","given":"Justin M. J."},{"family":"Shine","given":"Richard"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/588255","ISSN":"1537-5323","issued":{"date-parts":[[2008,7]]},"language":"eng","page":"S34-48","PMID":"18554142","source":"PubMed","title":"Reid's paradox revisited: the evolution of dispersal kernels during range expansion","title-short":"Reid's paradox revisited","type":"article-journal","volume":"172 Suppl 1"}, + {"id":"plotnickGeneralModelSimulating2002","abstract":"An individual-based, spatially explicit stochastic lattice model, CAPS, was designed to examine multiple processes responsible for spatial patterns of abundance and diversity of sessile species in heterogeneous landscapes. Species simulated by CAPS differ in habitat preferences (niche width), dispersal of propagules, and relative fecundity. The spatial distribution of habitat types are represented as heterogeneous gridded landscapes. The outcome of competition and establishment processes in successive generations is determined locally via a seed lottery. A series of 200 year-long simulations was performed to investigate the effects of variation in species characteristics and competition, landscape heterogeneity, and disturbance on patterns of species abundances. The outcome of competition was most sensitive to differences in fecundity between species, the spatial distribution of suitable habitat and the initial distribution of species. Species with a narrow niche were confined to a single habitat type and remained at or near their initialization sites. Broader niches resulted in increasing niche overlap and competition but enhanced species mobility, allowing abundance levels to approach expected values determined by map resources. Even so, initial distributions still affected the spatial patterns of species distributions at year 200. Disturbance regimes were simulated by varying the frequency, extent and spatial pattern of disturbances. Disturbance events removed species from affected sites but did not otherwise alter habitat characteristics. Results showed that disturbances may lead to a reversal in competition and establishment, dependent on species-specific differences in fecundity and dispersal. Although intermediate levels of disturbance frequency and extent increased the probability of species coexistence, the spatial pattern of disturbance played an unexpectedly important role in the tradeoff between dispersal and fecundity. The ability to simulate multiple factors affecting patterns of persistence, abundance and spatial distribution of species provided by CAPS allows new insight into the temporal and spatial patterns of community development.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Plotnick","given":"Roy E"},{"family":"Gardner","given":"Robert H"}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/S0304-3800(01)00418-5","ISSN":"0304-3800","issue":"2","issued":{"date-parts":[[2002,1,15]]},"language":"en","page":"171-197","source":"ScienceDirect","title":"A general model for simulating the effects of landscape heterogeneity and disturbance on community patterns","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0304380001004185","volume":"147"}, + {"id":"poethkeAbilityIndividualsAssess2011","abstract":"We analyze the simultaneous evolution of emigration and settlement decisions for actively dispersing species differing in their ability to assess population density. Using an individual-based model we simulate dispersal as a multi-step (patch to patch) movement in a world consisting of habitat patches surrounded by a hostile matrix. Each such step is associated with the same mortality risk. Our simulations show that individuals following an informed strategy, where emigration (and settlement) probability depends on local population density, evolve a lower (natal) emigration propensity but disperse over significantly larger distances - i.e. postpone settlement longer - than individuals performing density-independent emigration. This holds especially when variation in environmental conditions is spatially correlated. Both effects can be traced to the informed individuals' ability to better exploit existing heterogeneity in reproductive chances. Yet, already moderate distance-dependent dispersal costs prevent the evolution of multi-step (long-distance) dispersal, irrespective of the dispersal strategy.","author":[{"family":"Poethke","given":"Hans Joachim"},{"family":"Gros","given":"Andreas"},{"family":"Hovestadt","given":"Thomas"}],"container-title":"Journal of Theoretical Biology","container-title-short":"J Theor Biol","DOI":"10.1016/j.jtbi.2011.05.012","ISSN":"1095-8541","issue":"1","issued":{"date-parts":[[2011,8,7]]},"language":"eng","page":"93-99","PMID":"21605568","source":"PubMed","title":"The ability of individuals to assess population density influences the evolution of emigration propensity and dispersal distance","type":"article-journal","volume":"282"}, + {"id":"poethkeEvolutionDensityPatch2002","abstract":"Based on a marginal value approach, we derive a nonlinear expression for evolutionarily stable (ES) dispersal rates in a metapopulation with global dispersal. For the general case of density‐dependent population growth, our analysis shows that individual dispersal rates should decrease with patch capacity and—beyond a certain threshold–increase with population density. We performed a number of spatially explicit, individual‐based simulation experiments to test these predictions and to explore further the relevance of variation in the rate of population increase, density dependence, environmental fluctuations and dispersal mortality on the evolution of dispersal rates. They confirm the predictions of our analytical approach. In addition, they show that dispersal rates in metapopulations mostly depend on dispersal mortality and inter‐patch variation in population density. The latter is dominantly driven by environmental fluctuations and the rate of population increase. These conclusions are not altered by the introduction of neighbourhood dispersal. With patch capacities in the order of 100 individuals, kin competition seems to be of negligible importance for ES dispersal rates except when overall dispersal rates are low.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Poethke","given":"Hans Joachim"},{"family":"Hovestadt","given":"Thomas"}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rspb.2001.1936","issue":"1491","issued":{"date-parts":[[2002,3,22]]},"page":"637-645","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Evolution of density–and patch–size–dependent dispersal rates","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2001.1936","volume":"269"}, + {"id":"poyrySpeciesTraitsExplain2009","abstract":"This study provides a novel systematic comparative analysis of the species characteristics affecting the range margin shifts in butterflies towards higher latitudes, while taking phylogenetic relatedness among species into account. We related observed changes in the northern range margins of 48 butterfly species in Finland between two time periods (1992–1996 and 2000–2004) to 11 species traits. Species with positive records in at least ten 10 km × 10 km grid squares (in the Finnish National Butterfly Recording Scheme, NAFI) in both periods were included in the study. When corrected for range size change, the 48 butterfly species had shifted their range margins northwards on average by 59.9 km between the study periods, with maximum shifts of over 300 km for three species. This rate of range shifts exceeds all previously reported records worldwide. Our findings may be explained by two factors: the study region is situated in higher latitudes than in most previous studies and it focuses on the period of most prominent warming during the last 10–15 years. Several species traits exhibited a significant univariate relationship with the range margin shift according to generalized estimation equations (GEE) taking into account the phylogenetic relatedness among species. Nonthreatened butterflies had on average expanded their ranges strongly northwards (84.5 km), whereas the distributions of threatened species were stationary (−2.1 km). Hierarchical partitioning (HP) analysis indicated that mobile butterflies living in forest edges and using woody plants as their larval hosts exhibited largest range shifts towards the north. Thus, habitat availability and dispersal capacity of butterfly species are likely to determine whether they will be successful in shifting their ranges in response to the warming climate.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Pöyry","given":"Juha"},{"family":"Luoto","given":"Miska"},{"family":"Heikkinen","given":"Risto K."},{"family":"Kuussaari","given":"Mikko"},{"family":"Saarinen","given":"Kimmo"}],"container-title":"Global Change Biology","DOI":"10.1111/j.1365-2486.2008.01789.x","ISSN":"1365-2486","issue":"3","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2486.2008.01789.x","page":"732-743","source":"Wiley Online Library","title":"Species traits explain recent range shifts of Finnish butterflies","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2486.2008.01789.x","volume":"15"}, + {"id":"revillaEffectsMatrixHeterogeneity2004","abstract":"Mounting theoretical and empirical evidence shows that matrix heterogeneity may have contrasting effects on metapopulation dynamics by contributing to patch isolation in nontrivial ways. We analyze the movement properties during interpatch dispersal in a metapopulation of Iberian lynx (Lynx pardinus). On a daily temporal scale, lynx habitat selection defines two types of matrix habitats where individuals may move: open and dispersal habitats (avoided and used as available, respectively). There was a strong and complex impact of matrix heterogeneity on movement properties at several temporal scales (hourly and daily radiolocations and the entire dispersal event). We use the movement properties on the hourly temporal scale to build a simulation model to reconstruct individual dispersal events. The two most important parameters affecting model predictions at both the individual (daily) and metapopulation scales were related to the movement capacity (number of movement steps per day and autocorrelation in dispersal habitat) followed by the parameters representing the habitat selection in the matrix. The model adequately reproduced field estimates of population‐level parameters (e.g., interpatch connectivity, maximum and final dispersal distances), and its performance was clearly improved when including the effect of matrix heterogeneity on movement properties. To assume there is a homogeneous matrix results in large errors in the estimate of interpatch connectivity, especially for close patches separated by open habitat or corridors of dispersal habitat, showing how important it is to consider matrix heterogeneity when it is present. Movement properties affect the interaction of dispersing individuals with the landscape and can be used as a mechanistic representation of dispersal at the metapopulation level. This is so when the effect of matrix heterogeneity on movement properties is evaluated under biologically meaningful spatial and temporal scales.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Revilla","given":"Eloy"},{"family":"Wiegand","given":"Thorsten"},{"family":"Palomares","given":"Francisco"},{"family":"Ferreras","given":"Pablo"},{"family":"Delibes","given":"Miguel"}],"container-title":"The American Naturalist","DOI":"10.1086/424767","ISSN":"0003-0147","issue":"5","issued":{"date-parts":[[2004,11,1]]},"page":"E130-E153","publisher":"The University of Chicago Press","source":"journals.uchicago.edu (Atypon)","title":"Effects of Matrix Heterogeneity on Animal Dispersal: From Individual Behavior to Metapopulation‐Level Parameters.","title-short":"Effects of Matrix Heterogeneity on Animal Dispersal","type":"article-journal","URL":"https://www.journals.uchicago.edu/doi/full/10.1086/424767","volume":"164"}, + {"id":"revillaIndividualMovementBehavior2008a","abstract":"The dynamics of spatially structured populations is characterized by within- and between-patch processes. The available theory describes the latter with simple distance-dependent functions that depend on landscape properties such as interpatch distance or patch size. Despite its potential role, we lack a good mechanistic understanding of how the movement of individuals between patches affects the dynamics of these populations. We used the theoretical framework provided by movement ecology to make a direct representation of the processes determining how individuals connect local populations in a spatially structured population of Iberian lynx. Interpatch processes depended on the heterogeneity of the matrix where patches are embedded and the parameters defining individual movement behavior. They were also very sensitive to the dynamic demographic variables limiting the time moving, the within-patch dynamics of available settlement sites (both spatiotemporally heterogeneous) and the response of individuals to the perceived risk while moving. These context-dependent dynamic factors are an inherent part of the movement process, producing connectivities and dispersal kernels whose variability is affected by other demographic processes. Mechanistic representations of interpatch movements, such as the one provided by the movement-ecology framework, permit the dynamic interaction of birth–death processes and individual movement behavior, thus improving our understanding of stochastic spatially structured populations.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Revilla","given":"Eloy"},{"family":"Wiegand","given":"Thorsten"}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.0801725105","ISSN":"0027-8424, 1091-6490","issue":"49","issued":{"date-parts":[[2008,12,9]]},"language":"en","page":"19120-19125","PMID":"19060193","publisher":"National Academy of Sciences","section":"Research Article","source":"www.pnas.org","title":"Individual movement behavior, matrix heterogeneity, and the dynamics of spatially structured populations","type":"article-journal","URL":"https://www.pnas.org/content/105/49/19120","volume":"105"}, + {"id":"rickettsMatrixMattersEffective2001","abstract":"Traditional approaches to the study of fragmented landscapes invoke an island-ocean model and assume that the nonhabitat matrix surrounding remnant patches is uniform. Patch isolation, a crucial parameter to the predictions of island biogeography and metapopulation theories, is measured by distance alone. To test whether the type of interpatch matrix can contribute significantly to patch isolation, I conducted a mark-recapture study on a butterfly community inhabiting meadows in a naturally patchy landscape. I used maximum likelihood to estimate the relative resistances of the two major matrix types (willow thicket and conifer forest) to butterfly movement between meadow patches. For four of the six butterfly taxa (subfamilies or tribes) studied, conifer was 3-12 times more resistant than willow. For the two remaining taxa (the most vagile and least vagile in the community), resistance estimates for willow and conifer were not significantly different, indicating that responses to matrix differ even among closely related species. These results suggest that the surrounding matrix can significantly influence the \"effective isolation\" of habitat patches, rendering them more or less isolated than simple distance or classic models would indicate. Modification of the matrix may provide opportunities for reducing patch isolation and thus the extinction risk of populations in fragmented landscapes.","author":[{"family":"Ricketts","given":"T. H."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/320863","ISSN":"1537-5323","issue":"1","issued":{"date-parts":[[2001,7]]},"language":"eng","page":"87-99","PMID":"18707317","source":"PubMed","title":"The matrix matters: effective isolation in fragmented landscapes","title-short":"The matrix matters","type":"article-journal","volume":"158"}, + {"id":"ripaNoiseColourRisk1996","abstract":"A recurrent problem in ecology and conservation biology is to estimate the risk of population extinctions. Extinction probabilities are not only imperative for conservation and management, but may also elucidate basic mechanisms of the regulation of natural populations (Burgman et al. 1993; Pimm 1994). The usual way of modelling stochastic influence on population dynamics has been to assume that the external noise is uncorrelated. This means that each and every randomly drawn noise value is totally independent on previous ones. This is what is generally called ‘white’ noise. However, the noise itself can be temporally autocorrelated. That is, the values of the random numbers used in the noise process will depend on previous ones. Here we show that the autocorrelation, or colour, of the external noise assumed to influence population dynamics strongly modifies estimated extinction probabilities. For positively autocorrelated (‘red’) noise, the risk of extinction clearly decreases the stronger the autocorrelation is, Negatively autocorrelated (‘blue’) noise is more ambiguously related to extinction probability. Thus, the commonly assumed white noise in population modelling will severely bias population extinction risk estimates. Moreover, the extinction probability estimates are also significantly dependent on model structure which calls for a cautious use of traditional discrete-time models.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ripa","given":"Jörgen"},{"family":"Lundberg","given":"Per"}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rspb.1996.0256","issue":"1377","issued":{"date-parts":[[1996,12,22]]},"page":"1751-1753","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Noise colour and the risk of population extinctions","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.1996.0256","volume":"263"}, + {"id":"robertVariationIndividualsDemographic2003","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Robert","given":"Alexandre"},{"family":"Sarrazin","given":"François"},{"family":"Couvet","given":"Denis"}],"container-title":"Conservation Biology","ISSN":"0888-8892","issue":"4","issued":{"date-parts":[[2003]]},"page":"1166-1169","publisher":"[Wiley, Society for Conservation Biology]","source":"JSTOR","title":"Variation among Individuals, Demographic Stochasticity, and Extinction: Response to Kendall and Fox","title-short":"Variation among Individuals, Demographic Stochasticity, and Extinction","type":"article-journal","URL":"https://www.jstor.org/stable/3588874","volume":"17"}, + {"id":"ronceDispersalSyndromes2012","abstract":"This chapter focuses on dispersal syndromes and how they describe patterns of covariation of morphological, behavioural, and/or life-history traits associated with dispersal. Covariation is a continuous measure of statistical association between traits composing a complex phenotype. There are four main reasons why this chapter is interested in covariation: firstly, syndromes may help us predict a priori, from the observation of dispersal phenotypes, the intensity, nature, and modalities of movement. Secondly, they have the potential to provide information regarding the mechanistic determinants of dispersal and the constraints associated with movement. Thirdly, they may provide information about the proximate motivations and ultimate causes of dispersal. Lastly, and most convincingly, the patterns of covariation between traits associated with dispersal will critically affect both the demographic and genetic consequences of movement.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ronce","given":"Ophélie"},{"family":"Clobert","given":"Jean"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0010","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Dispersal syndromes","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-10"}, + {"id":"ronceHowDoesIt2007a","abstract":"This review proposes ten tentative answers to frequently asked questions about dispersal evolution. I examine methodological issues, model assumptions and predictions, and their relation to empirical data. Study of dispersal evolution points to the many ecological and genetic feedbacks affecting the evolution of this complex trait, which has contributed to our better understanding of life-history evolution in spatially structured populations. Several lines of research are suggested to ameliorate the exchanges between theoretical and empirical studies of dispersal evolution.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ronce","given":"Ophélie"}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","DOI":"10.1146/annurev.ecolsys.38.091206.095611","issue":"1","issued":{"date-parts":[[2007]]},"note":"_eprint: https://doi.org/10.1146/annurev.ecolsys.38.091206.095611","page":"231-253","source":"Annual Reviews","title":"How Does It Feel to Be Like a Rolling Stone? Ten Questions About Dispersal Evolution","title-short":"How Does It Feel to Be Like a Rolling Stone?","type":"article-journal","URL":"https://doi.org/10.1146/annurev.ecolsys.38.091206.095611","volume":"38"}, + {"id":"ronceLandscapeDynamicsEvolution2000","abstract":"The evolutionary consequences of changes in landscape dynamics for the evolution of life history syndromes are studied using a metapopulation model. We consider in turn the long-term effects of a change in the local disturbance rate, in the maximal local population persistence, in habitat productivity, and in habitat fragmentation. We examine the consequences of selective interactions between dispersal and reproductive effort by comparing the outcome of joint evolution to a situation where the species has lost the potential to evolve either its reproductive effort or its dispersal rate. We relax the classical assumption that any occupied site in the metapopulation reaches its carrying capacity immediately after recolonization. Our main conclusions are the following: (1) genetic diversity modifies the range of landscape parameters for which the metapopulation is viable, but it alters very little the qualitative evolutionary trends observed for each trait within this range. Although they are both part of a competition/colonization axis, reproductive effort and dispersal are not substitutable traits: their evolution reflects more directly the change in the landscape dynamics, than a selective interaction among them. (2) no general syndrome of covariation between reproductive effort and dispersal can be predicted: the pattern of association between the two traits depends on the type of change in landscape dynamics and on the saturation level. We review empirical evidence on colonizer syndromes and suggest lines for further empirical work.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ronce","given":"Ophélie"},{"family":"Perret","given":"Florence"},{"family":"Olivieri","given":"Isabelle"}],"container-title":"Evolutionary Ecology","container-title-short":"Evolutionary Ecology","DOI":"10.1023/A:1011068005057","ISSN":"1573-8477","issue":"3","issued":{"date-parts":[[2000,5,1]]},"language":"en","page":"233-260","source":"Springer Link","title":"Landscape dynamics and evolution of colonizer syndromes: interactions between reproductive effortand dispersal in a metapopulation","title-short":"Landscape dynamics and evolution of colonizer syndromes","type":"article-journal","URL":"https://doi.org/10.1023/A:1011068005057","volume":"14"}, + {"id":"roussetEvolutionDistributionDispersal2002","abstract":"We analyse the evolution of the distribution of dispersal distances in a stable and homogeneous environment in one- and two-dimensional habitats. In this model, dispersal evolves to avoid the competition between relatives although some cost might be associated with this behaviour. The evolutionarily stable dispersal distribution is characterized by an equilibration of the fitness gains among all the different dispersal distances. This cost-benefit argument has heuristic value and facilitates the comprehension of results obtained numerically. In particular, it explains why some minimal or maximal probability of dispersal may evolve at intermediate distances when the cost of dispersal function is an increasing function of distance. We also show that kin selection may favour long range dispersal even if the survival cost of dispersal is very high, provided the survival probability does not vanish at long distances.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Rousset","given":"F."},{"family":"Gandon","given":"S."}],"container-title":"Journal of Evolutionary Biology","DOI":"10.1046/j.1420-9101.2002.00430.x","ISSN":"1420-9101","issue":"4","issued":{"date-parts":[[2002]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1046/j.1420-9101.2002.00430.x","page":"515-523","source":"Wiley Online Library","title":"Evolution of the distribution of dispersal distance under distance-dependent cost of dispersal","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1046/j.1420-9101.2002.00430.x","volume":"15"}, + {"id":"ruokolainenEcologicalEvolutionaryDynamics2009","abstract":"Environmental variation is a ubiquitous component of individual, population and community processes in the natural world. Here, we review the consequences of spatio-temporally autocorrelated (coloured) environmental variation for ecological and evolutionary population dynamics. In single-species population models, environmental reddening increases (decreases) the amplitude of fluctuations in undercompensatory (overcompensatory) populations. This general result is also found in structurally more complex models (e.g. with space or species interactions). Environmental autocorrelation will also influence evolutionary dynamics as the changing environment is filtered through ecological dynamics. In the context of long-term environmental change, it becomes crucial to understand the potential impacts of different regimes of environmental variation at different scales of organization, from genes to species to communities.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ruokolainen","given":"Lasse"},{"family":"Lindén","given":"Andreas"},{"family":"Kaitala","given":"Veijo"},{"family":"Fowler","given":"Mike S."}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends in Ecology & Evolution","DOI":"10.1016/j.tree.2009.04.009","ISSN":"0169-5347","issue":"10","issued":{"date-parts":[[2009,10,1]]},"language":"en","page":"555-563","source":"ScienceDirect","title":"Ecological and evolutionary dynamics under coloured environmental variation","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0169534709001864","volume":"24"}, + {"id":"ruxtonFitnessDependentDispersal1998","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Ruxton","given":"G. D."},{"family":"Rohani","given":"P"}],"container-title":"Journal of Animal Ecology","issue":"67","issued":{"date-parts":[[1998]]},"page":"530-539","title":"Fitness‐dependent dispersal in metapopulations and its consequences for persistence and synchrony","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/10.1046/j.1365-2656.1999.00300.x"}, + {"id":"saupeAlgorithmsRandomFractals1988","abstract":"For about 200 years now mathematicians have developed the theory of smooth curves and surfaces in two, three or higher dimensions. These are curves and surfaces that globally may have a very complicated structure but in small neighborhoods they are just straight lines or planes. The discipline that deals with these objects is differential geometry. It is one of the most evolved and fascinating subjects in mathematics. On the other hand fractals feature just the opposite of smoothness. While the smooth objects do not yield any more detail on smaller scales a fractal possesses infinite detail at all scales no matter how small they are. The fascination that surrounds fractals has two roots: Fractals are very suitable to simulate many natural phenomena. Stunning pictures have already been produced, and it will not take very long until an uninitiated observer will no longer be able to tell whether a given scene is natural or just computer simulated. The other reason is that fractals are simple to generate on computers. In order to generate a fractal one does not have to be an expert of an involved theory such as calculus, which is necessary for differential geometry. More importantly, the complexity of a fractal, when measured in terms of the length of the shortest computer program that can generate it, is very small.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Saupe","given":"Dietmar"}],"container-title":"The Science of Fractal Images","DOI":"10.1007/978-1-4612-3784-6_2","editor":[{"family":"Barnsley","given":"Michael F."},{"family":"Devaney","given":"Robert L."},{"family":"Mandelbrot","given":"Benoit B."},{"family":"Peitgen","given":"Heinz-Otto"},{"family":"Saupe","given":"Dietmar"},{"family":"Voss","given":"Richard F."},{"family":"Peitgen","given":"Heinz-Otto"},{"family":"Saupe","given":"Dietmar"}],"event-place":"New York, NY","ISBN":"978-1-4612-3784-6","issued":{"date-parts":[[1988]]},"language":"en","page":"71-136","publisher":"Springer","publisher-place":"New York, NY","source":"Springer Link","title":"Algorithms for random fractals","type":"chapter","URL":"https://doi.org/10.1007/978-1-4612-3784-6_2"}, + {"id":"schiffersLimitedEvolutionaryRescue2013","abstract":"Dispersal is a key determinant of a population's evolutionary potential. It facilitates the propagation of beneficial alleles throughout the distributional range of spatially outspread populations and increases the speed of adaptation. However, when habitat is heterogeneous and individuals are locally adapted, dispersal may, at the same time, reduce fitness through increasing maladaptation. Here, we use a spatially explicit, allelic simulation model to quantify how these equivocal effects of dispersal affect a population's evolutionary response to changing climate. Individuals carry a diploid set of chromosomes, with alleles coding for adaptation to non-climatic environmental conditions and climatic conditions, respectively. Our model results demonstrate that the interplay between gene flow and habitat heterogeneity may decrease effective dispersal and population size to such an extent that substantially reduces the likelihood of evolutionary rescue. Importantly, even when evolutionary rescue saves a population from extinction, its spatial range following climate change may be strongly narrowed, that is, the rescue is only partial. These findings emphasize that neglecting the impact of non-climatic, local adaptation might lead to a considerable overestimation of a population's evolvability under rapid environmental change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schiffers","given":"Katja"},{"family":"Bourne","given":"Elizabeth C."},{"family":"Lavergne","given":"Sébastien"},{"family":"Thuiller","given":"Wilfried"},{"family":"Travis","given":"Justin M. J."}],"container-title":"Philosophical Transactions of the Royal Society B: Biological Sciences","container-title-short":"Philos Trans R Soc Lond B Biol Sci","DOI":"10.1098/rstb.2012.0083","ISSN":"0962-8436","issue":"1610","issued":{"date-parts":[[2013,1,19]]},"page":"20120083","PMCID":"PMC3538450","PMID":"23209165","source":"PubMed Central","title":"Limited evolutionary rescue of locally adapted populations facing climate change","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3538450/","volume":"368"}, + {"id":"schtickzelleBehaviouralResponsesHabitat2003","abstract":"We studied the consequences of behaviour at habitat patch boundaries on dispersal for the bog fritillary butterfly Proclossiana eunomia Esper in two networks of habitat differing in fragmentation and matrix quality. We tested for differences in responses to patch boundaries according to the fragmentation level of the network by analysing movement paths of adult butterflies. Butterflies systematically engaged in U-turns when they reached a boundary in the fragmented network while they crossed over boundaries in more than 40% of boundary encounters in the continuous one. We applied the Virtual Migration model (Hanski, Alho & Moilanen 2000) to capture–mark–recapture data collected in both networks. The model indicated (i) a lower dispersal rate and (ii) a lower survival during dispersal in the fragmented network. This latter difference is likely to be the key biological process leading to behavioural avoidance of patch boundary crossings. On the basis of this behavioural difference, we designed an individual-based simulation model to explore the relationship between patch area, boundary permeability and emigration rate. Predictions of the model fitted observed results of the effect of patch area on emigration rate according to fragmentation: butterflies are more likely to leave small patches than large ones in fragmented landscapes (where patch boundary permeability is low), while this relationship disappears in more continuous landscapes (where patch boundary permeability is high).","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schtickzelle","given":"Nicolas"},{"family":"Baguette","given":"Michel"}],"container-title":"Journal of Animal Ecology","DOI":"10.1046/j.1365-2656.2003.00723.x","ISSN":"1365-2656","issue":"4","issued":{"date-parts":[[2003]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1046/j.1365-2656.2003.00723.x","page":"533-545","source":"Wiley Online Library","title":"Behavioural responses to habitat patch boundaries restrict dispersal and generate emigration–patch area relationships in fragmented landscapes","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1046/j.1365-2656.2003.00723.x","volume":"72"}, + {"id":"schtickzelleDispersalDepressionHabitat2006","abstract":"Habitat fragmentation is expected to impose strong selective pressures on dispersal rates. However, evolutionary responses of dispersal are not self-evident, since various selection pressures act in opposite directions. Here we disentangled the components of dispersal behavior in a metapopulation context using the Virtual Migration model, and we linked their variation to habitat fragmentation in the specialist butterfly Proclossiana eunomia. Our study provided a nearly unique opportunity to study how habitat fragmentation modifies dispersal at the landscape scale, as opposed to microlandscapes or simulation studies. Indeed, we studied the same species in four landscapes with various habitat fragmentation levels, in which large amounts of field data were collected and analyzed using similar methodologies. We showed the existence of quantitative variations in dispersal behavior correlated with increased fragmentation. Dispersal propensity from habitat patches (for a given patch size), and mortality during dispersal (for a given patch connectivity) were lower in more fragmented landscapes. We suggest that these were the consequences of two different evolutionary responses of dispersal behavior at the individual level: (1) when fragmentation increased, the reluctance of individuals to cross habitat patch boundaries also increased; (2) when individuals dispersed, they flew straighter in the matrix, which is the best strategy to improve dispersal success. Such evolutionary responses could generate complex nonlinear patterns of dispersal changes at the metapopulation level according to habitat fragmentation. Due to the small size and increased isolation of habitat patches in fragmented landscapes, overall emigration rate and mortality during dispersal remained high. As a consequence, successful dispersal at the metapopulation scale remained limited. Therefore, to what extent the selection of individuals with a lower dispersal propensity and a higher survival during dispersal is able to limit detrimental effects of habitat fragmentation on dispersal success is unknown, and any conclusion that metapopulations would compensate for them is flawed.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schtickzelle","given":"Nicolas"},{"family":"Mennechez","given":"Gwénaëlle"},{"family":"Baguette","given":"Michel"},{"family":"Mennechez","given":"Gwénnaëlle"}],"container-title":"Ecology","ISSN":"0012-9658","issue":"4","issued":{"date-parts":[[2006]]},"page":"1057-1065","publisher":"Ecological Society of America","source":"JSTOR","title":"Dispersal Depression with Habitat Fragmentation in the Bog Fritillary Butterfly","type":"article-journal","URL":"https://www.jstor.org/stable/20069035","volume":"87"}, + {"id":"schtickzelleTemporalVariationDispersal2012","abstract":"This chapter aims to quantify the temporal variation existing in the dispersal kernel by making the kernels comparable. Variation of dispersal kernels in time has received less attention, even if temporal change in dispersal rates among local populations has been repeatedly documented in the metapopulation literature. Changes in individual mobility that generate temporal shifts in dispersal kernels would obviously be context- and phenotypic-dependent. Both environmental conditions and conspecific density are thus expected to play a central role in temporal variation of dispersal kernels. This chapter uses standardized capture-mark-recapture (CMR) data from long-term monitoring of bog fritillary butterfly, Boloria eunomia, metapopulation dynamics in a single landscape to investigate the amount of temporal variability and the amount of this temporal variability that has been explained by climatic variables and conspecific density.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schtickzelle","given":"Nicolas"},{"family":"Turlure","given":"Camille"},{"family":"Baguette","given":"Michel"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0018","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Temporal variation in dispersal kernels in a metapopulation of the bog fritillary butterfly (Boloria eunomia)","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-18"}, + {"id":"schultzEdgeMediatedDispersalBehavior2001","abstract":"Animal responses to habitat boundaries will influence the effects of habitat fragmentation on population dynamics. Although this is an intuitive and often observed animal behavior, the influences of habitat boundaries have rarely been quantified in the field or considered in theoretical models of large scale processes. We quantified movement behavior of the Fender's blue butterfly (Icaricia icarioides fenderi) as a function of distance from host-plant patches. We measured the butterfly's tendency to move toward habitat patches (bias) and their tendency to continue to move in the direction they were already going (correlation). We found that butterflies significantly modify their behavior within 10-22 m from the habitat boundary. We used these data to predict large scale patterns of residence time as a function of patch size, using three dispersal models: homogeneous response to habitat, heterogeneous response to habitat, and heterogeneous response to habitat with edge-mediated behavior. We simulated movement for males and females in eight patch sizes (0.1-8 ha) and asked how residence time varies among the models. We found that adding edge-mediated behavior significantly increases the residence of Fender's blue butterflies in their natal patch. Only the model with edge-mediated behavior for females was consistent with independent mark-release-recapture (MRR) estimates of residence time; other models dramatically underestimated residence times, relative to MRR data.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schultz","given":"Cheryl B."},{"family":"Crone","given":"Elizabeth E."}],"container-title":"Ecology","DOI":"10.2307/2680054","ISSN":"0012-9658","issue":"7","issued":{"date-parts":[[2001]]},"page":"1879-1892","publisher":"Ecological Society of America","source":"JSTOR","title":"Edge-Mediated Dispersal Behavior in a Prairie Butterfly","type":"article-journal","URL":"https://www.jstor.org/stable/2680054","volume":"82"}, + {"id":"schurrHowRandomDispersal2012","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schurr","given":"F. M."}],"container-title":"Dispersal Ecology and Evolution","editor":[{"family":"Clobert","given":"J"},{"family":"Baguette","given":"M"},{"family":"Benton","given":"T G"},{"family":"Bullock","given":"J M"}],"issued":{"date-parts":[[2012]]},"page":"240-247","publisher":"Oxford University Press","title":"How random is dispersal? From stochasticity to process in the description of seed movement","type":"chapter","URL":"https://oxford.universitypressscholarship.com/view/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-19"}, + {"id":"schurrHowUnderstandSpecies2012","abstract":"Range dynamics causes mismatches between a species’ geographical distribution and the set of suitable environments in which population growth is positive (the Hutchinsonian niche). This is because source–sink population dynamics cause species to occupy unsuitable environments, and because environmental change creates non-equilibrium situations in which species may be absent from suitable environments (due to migration limitation) or present in unsuitable environments that were previously suitable (due to time-delayed extinction). Because correlative species distribution models do not account for these processes, they are likely to produce biased niche estimates and biased forecasts of future range dynamics. Recently developed dynamic range models (DRMs) overcome this problem: they statistically estimate both range dynamics and the underlying environmental response of demographic rates from species distribution data. This process-based statistical approach qualitatively advances biogeographical analyses. Yet, the application of DRMs to a broad range of species and study systems requires substantial research efforts in statistical modelling, empirical data collection and ecological theory. Here we review current and potential contributions of these fields to a demographic understanding of niches and range dynamics. Our review serves to formulate a demographic research agenda that entails: (1) advances in incorporating process-based models of demographic responses and range dynamics into a statistical framework, (2) systematic collection of data on temporal changes in distribution and abundance and on the response of demographic rates to environmental variation, and (3) improved theoretical understanding of the scaling of demographic rates and the dynamics of spatially coupled populations. This demographic research agenda is challenging but necessary for improved comprehension and quantification of niches and range dynamics. It also forms the basis for understanding how niches and range dynamics are shaped by evolutionary dynamics and biotic interactions. Ultimately, the demographic research agenda should lead to deeper integration of biogeography with empirical and theoretical ecology.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schurr","given":"Frank M."},{"family":"Pagel","given":"Jörn"},{"family":"Cabral","given":"Juliano Sarmento"},{"family":"Groeneveld","given":"Jürgen"},{"family":"Bykova","given":"Olga"},{"family":"O’Hara","given":"Robert B."},{"family":"Hartig","given":"Florian"},{"family":"Kissling","given":"W. Daniel"},{"family":"Linder","given":"H. Peter"},{"family":"Midgley","given":"Guy F."},{"family":"Schröder","given":"Boris"},{"family":"Singer","given":"Alexander"},{"family":"Zimmermann","given":"Niklaus E."}],"container-title":"Journal of Biogeography","DOI":"10.1111/j.1365-2699.2012.02737.x","ISSN":"1365-2699","issue":"12","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2699.2012.02737.x","page":"2146-2162","source":"Wiley Online Library","title":"How to understand species’ niches and range dynamics: a demographic research agenda for biogeography","title-short":"How to understand species’ niches and range dynamics","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2699.2012.02737.x","volume":"39"}, + {"id":"schwagerDoesRedNoise2006","abstract":"Recent theoretical studies have shown contrasting effects of temporal correlation of environmental fluctuations (red noise) on the risk of population extinction. It is still debated whether and under which conditions red noise increases or decreases extinction risk compared with uncorrelated (white) noise. Here, we explain the opposing effects by introducing two features of red noise time series. On the one hand, positive autocorrelation increases the probability of series of poor environmental conditions, implying increasing extinction risk. On the other hand, for a given time period, the probability of at least one extremely bad year (\"catastrophe\") is reduced compared with white noise, implying decreasing extinction risk. Which of these two features determines extinction risk depends on the strength of environmental fluctuations and the sensitivity of population dynamics to these fluctuations. If extreme (catastrophic) events can occur (strong noise) or sensitivity is high (overcompensatory density dependence), then temporal correlation decreases extinction risk; otherwise, it increases it. Thus, our results provide a simple explanation for the contrasting previous findings and are a crucial step toward a general understanding of the effect of noise color on extinction risk.","author":[{"family":"Schwager","given":"Monika"},{"family":"Johst","given":"Karin"},{"family":"Jeltsch","given":"Florian"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/503609","ISSN":"1537-5323","issue":"6","issued":{"date-parts":[[2006,6]]},"language":"eng","page":"879-888","PMID":"16615033","source":"PubMed","title":"Does red noise increase or decrease extinction risk? Single extreme events versus series of unfavorable conditions","title-short":"Does red noise increase or decrease extinction risk?","type":"article-journal","volume":"167"}, + {"id":"schymanskiProcessCorrelationParameter2013","abstract":"In a recent article (Dormann et al., 2012, Journal of Biogeography, 39, 2119—2131), we compared different approaches to species distribution modelling and depicted modelling approaches along an axis from purely 'correlative' to 'forward process-based' models. In their correspondence, Kriticos et al. (2013, Journal of Biogeography, doi:10.1111/j.1365-2699.2012.02791.x) challenge this view, claiming that our continuum representation neglects differences among models and does not consider the ability of fitted process-based models to combine the advantages of both process-based and correlative modelling approaches. Here we clarify that the continuum view resulted from recognition of the manifold differences between models. We also reinforce the point that the current trend towards combining different modelling approaches may lead not only to the desired combination of the advantages but also to the accumulation of the disadvantages of those approaches. This point has not been made sufficiently clear previously.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Schymanski","given":"Stanislaus J."},{"family":"Dormann","given":"Carsten F."},{"family":"Cabral","given":"Juliano"},{"family":"Chuine","given":"Isabelle"},{"family":"Graham","given":"Catherine H."},{"family":"Hartig","given":"Florian"},{"family":"Kearney","given":"Michael"},{"family":"Morin","given":"Xavier"},{"family":"Römermann","given":"Christine"},{"family":"Schröder","given":"Boris"},{"family":"Singer","given":"Alexander"}],"container-title":"Journal of Biogeography","ISSN":"0305-0270","issue":"3","issued":{"date-parts":[[2013]]},"page":"611-613","publisher":"Wiley","source":"JSTOR","title":"Process, correlation and parameter fitting in species distribution models: a response to Kriticos et al.","title-short":"Process, correlation and parameter fitting in species distribution models","type":"article-journal","URL":"https://www.jstor.org/stable/23354625","volume":"40"}, + {"id":"sextonEvolutionEcologySpecies2009","abstract":"Species range limits involve many aspects of evolution and ecology, from species distribution and abundance to the evolution of niches. Theory suggests myriad processes by which range limits arise, including competitive exclusion, Allee effects, and gene swamping; however, most models remain empirically untested. Range limits are correlated with a number of abiotic and biotic factors, but further experimentation is needed to understand underlying mechanisms. Range edges are characterized by increased genetic isolation, genetic differentiation, and variability in individual and population performance, but evidence for decreased abundance and fitness is lacking. Evolution of range limits is understudied in natural systems; in particular, the role of gene flow in shaping range limits is unknown. Biological invasions and rapid distribution shifts caused by climate change represent large-scale experiments on the underlying dynamics of range limits. A better fusion of experimentation and theory will advance our understanding of the causes of range limits.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Sexton","given":"Jason P."},{"family":"McIntyre","given":"Patrick J."},{"family":"Angert","given":"Amy L."},{"family":"Rice","given":"Kevin J."}],"container-title":"Annual Review of Ecology, Evolution, and Systematics","DOI":"10.1146/annurev.ecolsys.110308.120317","issue":"1","issued":{"date-parts":[[2009]]},"note":"_eprint: https://doi.org/10.1146/annurev.ecolsys.110308.120317","page":"415-436","source":"Annual Reviews","title":"Evolution and Ecology of Species Range Limits","type":"article-journal","URL":"https://doi.org/10.1146/annurev.ecolsys.110308.120317","volume":"40"}, + {"id":"shreeveLandscapeScaleConservation2011","abstract":"Landscape scale conservation efforts are becoming more commonplace in conservation, with a move from single species to multi-species initiatives. These initiatives are reliant on modelling processes, largely underpinned by metapopulation models. We argue that generic models developed for individual species in particular landscapes over selected time periods may only be applicable to alternative landscapes and time periods in restricted circumstances. Variability in species responses to landscapes and environmental conditions is dependent on a range of species-specific intrinsic characteristics, dependent on their responses to resources, (including weather) and also individual states. We propose that the behavioural component of how species respond to resources needs to be taken into account in modelling species responses to landscape, and therefore how limited resources for conservation are deployed. Species behaviours are inherently complex. We argue that because of this complexity the conservation of the majority of species, especially of the least rare, may be best served if conservation effort is additionally focused on increasing landscape heterogeneity and disturbance. This may also facilitate persistence in the face of climate change. We suggest that heterogeneity should be promoted through agri-environment schemes.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Shreeve","given":"T. G."},{"family":"Dennis","given":"R. L. H."}],"container-title":"Journal of Insect Conservation","container-title-short":"J Insect Conserv","DOI":"10.1007/s10841-010-9336-9","ISSN":"1572-9753","issue":"1","issued":{"date-parts":[[2011,4,1]]},"language":"en","page":"179-188","source":"Springer Link","title":"Landscape scale conservation: resources, behaviour, the matrix and opportunities","title-short":"Landscape scale conservation","type":"article-journal","URL":"https://doi.org/10.1007/s10841-010-9336-9","volume":"15"}, + {"id":"simmonsChangesDispersalSpecies2004","abstract":"Explanations for rapid species' range expansions have typically been purely ecological, with little attention given to evolutionary processes. We tested predictions for the evolution of dispersal during range expansion using four species of wing-dimorphic bush cricket (Conocephalus discolor, Conocephalus dorsalis, Metrioptera roeselii, and Metrioptera brachyptera). We observed distinct changes in dispersal in the two species with expanding ranges. Recently colonized populations at the range margin showed increased frequencies of dispersive, long-winged (macropterous) individuals, compared with longer-established populations in the range core. This increase in dispersal appeared to be short-lived because 5-10 years after colonization populations showed similar incidences of macroptery to populations in the range core. These changes are consistent with evolutionary change; field patterns persisted when nymphs were reared under controlled environmental conditions, and range margin individuals reared in the laboratory flew farther than range core individuals in a wind tunnel. There was also a reproductive trade-off with dispersal in both females and males, which could explain the rapid reversion to lower rates of dispersal once populations become established. The effect of population density on wing morphology differed between populations from the range core (no significant effect of density) and expanding range margins (negative density dependence), which we propose is part of the mechanism of the changes in dispersal. Transient changes in dispersal are likely to be common in many species undergoing range expansion and can have major population and biogeographic consequences.","author":[{"family":"Simmons","given":"Adam D."},{"family":"Thomas","given":"Chris D."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/423430","ISSN":"1537-5323","issue":"3","issued":{"date-parts":[[2004,9]]},"language":"eng","page":"378-395","PMID":"15478092","source":"PubMed","title":"Changes in dispersal during species' range expansions","type":"article-journal","volume":"164"}, + {"id":"sinclairHowUsefulAre2010","abstract":"ABSTRACT. Climate change presents unprecedented challenges for biological conservation. Agencies are increasingly looking to modeled projections of species’ distributions under future climates to inform management strategies. As government scientists with a responsibility to communicate the best available science to our policy colleagues, we question whether current modeling approaches and outputs are practically useful. Here, we synthesize conceptual problems with species distribution models (SDMs) associated with interspecific interactions, dispersal, ecological equilibria and time lags, evolution, and the sampling of niche space. Although projected SDMs have undoubtedly been critical in alerting us to the magnitude of climate change impacts, we conclude that until they offer insights that are more precise than what we can derive from basic ecological theory, we question their utility in deciding how to allocate scarce funds to large-scale conservation projects.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Sinclair","given":"Steve J."},{"family":"White","given":"Matthew D."},{"family":"Newell","given":"Graeme R."}],"container-title":"Ecology and Society","ISSN":"1708-3087","issue":"1","issued":{"date-parts":[[2010]]},"publisher":"Resilience Alliance Inc.","source":"JSTOR","title":"How Useful Are Species Distribution Models for Managing Biodiversity under Future Climates?","type":"article-journal","URL":"https://www.jstor.org/stable/26268111","volume":"15"}, + {"id":"singerInterspecificInteractionsAffect2013","abstract":"The response of individual species to climate change may alter the composition and dynamics of communities. Here, we show that the impacts of environmental change on communities can depend on the nature of the interspecific interactions: mutualistic communities typically respond differently than commensalistic or parasitic communities. We model and analyse the geographic range shifting of metapopulations of two interacting species – a host and an obligate species. Different types of interspecific interactions are implemented by modifying local extinction rates according to the presence/absence of the other species. We distinguish and compare three fundamentally different community types: mutualism, commensalism and parasitism. We find that community dynamics during geographic range shifting critically depends on the type of interspecific interactions. Parasitic interactions exacerbate the negative effect of environmental change whereas mutualistic interactions only partly compensate it. Commensalistic interactions exhibit an intermediate response. Based on these model outcomes, we predict that parasitic species interactions may be more vulnerable to geographic range shifting than commensalistic or mutualistic ones. However, we observe that when climate stabilises following a period of change, the rate of community recovery is largely independent of the type of interspecific interactions. These results emphasize that communities respond delicately to environmental change, and that local interspecific interactions can affect range shifting communities at large spatial scales.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Singer","given":"Alexander"},{"family":"Travis","given":"Justin M. J."},{"family":"Johst","given":"Karin"}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2012.20465.x","ISSN":"1600-0706","issue":"3","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2012.20465.x","page":"358-366","source":"Wiley Online Library","title":"Interspecific interactions affect species and community responses to climate shifts","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0706.2012.20465.x","volume":"122"}, + {"id":"smithStabilityPredatorPreySystems1973","abstract":"The interactions between a predator and prey species have been analyzed by computer simulation of a model in which there are discrete breeding seasons, separated by a winter during which the predator must be able to find prey at a certain minimum rate or starve. The model is intended to represent a warm-blooded vertebrate predator and its prey. The main conclusions are: (1) Coexistence of predator and prey is possible, but if so, the number of prey present will not be substantially below the equilibrium number in the absence of predators. Mutual regulation of predator and prey, with the latter substantially below the carrying capacity of the environment, is unstable. (2) Coexistence is more likely if there are differences in hunting ability between different individual predators--for example, between young and old predators. (3) Cover for the prey enables the prey species to survive the extinction of the predator, but does not make coexistence more likely.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Smith","given":"J. Maynard"},{"family":"Slatkin","given":"M."}],"container-title":"Ecology","DOI":"10.2307/1934346","ISSN":"0012-9658","issue":"2","issued":{"date-parts":[[1973]]},"page":"384-391","publisher":"Ecological Society of America","source":"JSTOR","title":"The Stability of Predator-Prey Systems","type":"article-journal","URL":"https://www.jstor.org/stable/1934346","volume":"54"}, + {"id":"smouseStochasticModellingAnimal2010","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Smouse","given":"Peter E"},{"family":"Focardi","given":"S"},{"family":"Moorcroft","given":"P.R."},{"family":"Kie","given":"John G"},{"family":"Forester","given":"J. D."},{"family":"Morales","given":"Juan M"}],"container-title":"Philosophical Transactions of the Royal Society of London. Series B, Biological Sciences","issue":"365","issued":{"date-parts":[[2010]]},"page":"2201-2211","title":"Stochastic modelling of animal movement","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rstb.2010.0078"}, + {"id":"spearUseResistanceSurfaces2010","abstract":"Measures of genetic structure among individuals or populations collected at different spatial locations across a landscape are commonly used as surrogate measures of functional (i.e. demographic or genetic) connectivity. In order to understand how landscape characteristics influence functional connectivity, resistance surfaces are typically created in a raster GIS environment. These resistance surfaces represent hypothesized relationships between landscape features and gene flow, and are based on underlying biological functions such as relative abundance or movement probabilities in different land cover types. The biggest challenge for calculating resistance surfaces is assignment of resistance values to different landscape features. Here, we first identify study objectives that are consistent with the use of resistance surfaces and critically review the various approaches that have been used to parameterize resistance surfaces and select optimal models in landscape genetics. We then discuss the biological assumptions and considerations that influence analyses using resistance surfaces, such as the relationship between gene flow and dispersal, how habitat suitability may influence animal movement, and how resistance surfaces can be translated into estimates of functional landscape connectivity. Finally, we outline novel approaches for creating optimal resistance surfaces using either simulation or computational methods, as well as alternatives to resistance surfaces (e.g. network and buffered paths). These approaches have the potential to improve landscape genetic analyses, but they also create new challenges. We conclude that no single way of using resistance surfaces is appropriate for every situation. We suggest that researchers carefully consider objectives, important biological assumptions and available parameterization and validation techniques when planning landscape genetic studies.","author":[{"family":"Spear","given":"Stephen F."},{"family":"Balkenhol","given":"Niko"},{"family":"Fortin","given":"Marie-Josée"},{"family":"McRae","given":"Brad H."},{"family":"Scribner","given":"Kim"}],"container-title":"Molecular Ecology","container-title-short":"Mol Ecol","DOI":"10.1111/j.1365-294X.2010.04657.x","ISSN":"1365-294X","issue":"17","issued":{"date-parts":[[2010,9]]},"language":"eng","page":"3576-3591","PMID":"20723064","source":"PubMed","title":"Use of resistance surfaces for landscape genetic studies: considerations for parameterization and analysis","title-short":"Use of resistance surfaces for landscape genetic studies","type":"article-journal","volume":"19"}, + {"id":"stampsConspecificAttractionAggregation1988","abstract":"For many years, field studies of birds have suggested that territorial individuals may be attracted to one another, forming territorial clusters independent of resource distributions. However, virtually no experiments have studied these phenomena in either the laboratory or the field. The present field study was designed to test whether prospective territory owners preferentially settle near conspecifics and form territorial aggregations when territory quality is held constant. Juvenile Anolis aeneus lizards arriving at juvenile habitats in clearings were given a choice of artificial homesites arranged around a clear-walled enclosure divided into two parts, one of which contained resident A. aeneus juveniles. Juveniles showed a clear preference for the homesites adjacent to the established territorial residents (the \"experimental\" homesites). In each of eight trials, the first arrivals appeared on the experimental homesites. Juveniles that first appeared on the experimental homesites were more apt to settle in the clearing, and colonists on the experimental side moved around less before choosing a final territory. During the colonization process, juveniles spent more time on the experimental sides of the enclosures; and by the end of the trials, more juveniles had eventually settled on the experimental homesites. Throughout the settlement process, new territory owners tended to cluster around the previous residents within the experimental side of the enclosures. These results indicate that A. aeneus juveniles are attracted to conspecifics while settling a territory and that this process can lead to territorial aggregations that are independent of territory quality.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Stamps","given":"J. A."}],"container-title":"The American Naturalist","ISSN":"0003-0147","issue":"3","issued":{"date-parts":[[1988]]},"page":"329-347","publisher":"[University of Chicago Press, American Society of Naturalists]","source":"JSTOR","title":"Conspecific Attraction and Aggregation in Territorial Species","type":"article-journal","URL":"https://www.jstor.org/stable/2461973","volume":"131"}, + {"id":"stampsEffectsNatalExperience2006","abstract":"We studied the effects of natal experience on preference for a postdispersal habitat (natal habitat preference induction, NHPI) in groups of newly eclosed female Drosophila melanogaster, using multilevel statistical models to take into account dependencies of responses from individuals making choices within the same hour. Groups consisting of flies with one of five genotypes (crosses of highly inbred female isolines) were allowed free access to a high-quality natal habitat after emergence from their pupae. The flies were then allowed to select one of two new habitats in a large 'seminatural' environment over the next 3 days. The flies showed strong positive effects of training habitat on their choice of a new habitat, after controlling for potential dependence in choices within hours and trials. The genotypes also varied with respect to the effects of conspecifics and humidity on individual choice. A second analysis using data aggregated at the trial level and a traditional statistical approach (a generalized linear model, GLM) also detected effects of training on habitat choice. However, the GLM produced other results that may have been artefacts resulting from the omission of within-trial factors with important effects on choice in this trial-level analysis. This study shows the advantages of using multilevel models rather than aggregating data to control for interactions among subjects when animals select items in groups. (PsycINFO Database Record (c) 2017 APA, all rights reserved)","author":[{"family":"Stamps","given":"Judy A."},{"family":"Blozis","given":"Shelley A."}],"container-title":"Animal Behaviour","DOI":"10.1016/j.anbehav.2005.07.015","event-place":"Netherlands","ISSN":"1095-8282(Electronic),0003-3472(Print)","issue":"3","issued":{"date-parts":[[2006]]},"page":"663-672","publisher":"Elsevier Science","publisher-place":"Netherlands","source":"APA PsycNET","title":"Effects of natal experience on habitat selection when individuals make choices in groups: A multilevel analysis","title-short":"Effects of natal experience on habitat selection when individuals make choices in groups","type":"article-journal","volume":"71"}, + {"id":"stampsHabitatSelectionDispersers2001","abstract":"Behavioural research is shedding new light on the complex relationships between the proximate mechanisms involved in habitat selection and the selective pressures that may have contributed to the evolution of those mechanisms. Habitat selection by dispersers can be divided into three stages (search, settlement and residency); recent studies suggest that the adaptive significance of behaviour at each of these stages may differ from the assumptions of traditional habitat selection theory. For instance, dispersers may benefit from the presence of conspecifics or heterospecifics while searching for, settling in, or living in new habitats, and individuals may prefer to settle in post-dispersal habitats similar to their pre-dispersal habitats, because this behaviour reduces the costs of detecting or assessing suitable habitats (habitat cuing) or because experience in a pre-dispersal habitat improves performance if an animal settles in the same type of habitat after dispersing (habitat training). Dispersers have evolved a variety of proximate behavioural mechanisms to reduce search and settlement costs in natural environments, but if they currently rely on these processes, species living in areas modified by human activities may not exhibit 'ideal' habitat selection behaviour. Insights from recent studies of habitat selection may help solve specific problems in conservation biology, and more generally, help biologists understand the intimate relationship between dispersal and habitat selection behaviour.","author":[{"family":"Stamps","given":"Judy"}],"container-title":"Dispersal","editor":[{"family":"Clobert","given":"J."},{"family":"Danchin","given":"Etienne"},{"family":"Dhondt","given":"Andre A."},{"family":"Nichols","given":"James D."}],"event-place":"Oxford","issued":{"date-parts":[[2001,1,1]]},"page":"230-242","publisher":"Oxford University Press","publisher-place":"Oxford","source":"ResearchGate","title":"Habitat selection by dispersers: integrating proximate and ultimate approaches","title-short":"Habitat selection by dispersers","type":"chapter"}, + {"id":"stampsHowDifferentTypes2009","abstract":"Abstract: In many animals, exposure to cues in a natal habitat increases disperser preferences for those cues (natal habitat preference induction [NHPI]), but the proximate and ultimate bases for this phenomenon are obscure. We developed a Bayesian model to study how different types of experience in the natal habitat and survival to the age/stage of dispersal interact to affect a disperser’s estimate of the quality of new natal‐type habitats. The model predicts that the types of experience a disperser had before leaving its natal habitat will affect the attractiveness of cues from new natal‐type habitats and that favorable experiences will increase the level of preference for natal‐type habitats more than unfavorable experiences will decrease it. An experimental study of NHPI in Drosophila melanogaster provided with “good” and “bad” experiences in their natal habitats supports these predictions while also indicating that the effects of different types of natal experience on NHPI vary across genotypes. If habitat preferences are modulated by an individual’s experience before dispersal as described in this study, then NHPI may have stronger effects on sympatric speciation, metapopulation dynamics, conservation biology, and pest management than previously supposed.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Stamps","given":"Judy A."},{"family":"Krishnan","given":"V. V."},{"family":"Willits","given":"Neil H."},{"family":"Ketterson","given":"Associate Editor: Ellen D."},{"family":"Shaw","given":"Editor: Ruth G."}],"container-title":"The American Naturalist","DOI":"10.1086/644526","ISSN":"0003-0147","issue":"5","issued":{"date-parts":[[2009]]},"page":"623-630","publisher":"[The University of Chicago Press, The American Society of Naturalists]","source":"JSTOR","title":"How Different Types of Natal Experience Affect Habitat Preference","type":"article-journal","URL":"https://www.jstor.org/stable/10.1086/644526","volume":"174"}, + {"id":"stampsSearchCostsHabitat2005","abstract":"The effects of search costs on habitat selection by dispersers are largely unknown. We explore how habitat selection behavior is affected by the risk of mortality en route and by deferred search costs (i.e., costs incurred during search that reduce fitness after arrival in the new habitat), using a model designed for long-distance natal dispersers searching for scarce patches of suitable habitat embedded within a matrix of unsuitable habitat. In this situation, increases in the risk of mortality during search reduce disperser selectivity, where selectivity is reflected by the period during search when dispersers are only willing to accept a high-quality habitat. However, the effects of deferred costs on selectivity depend on other factors with pronounced effects on selectivity, including encounter rates with high-quality habitats, relative habitat quality, and total search time. Surprisingly, under some sets of conditions, increases in deferred costs lead to increases in disperser selectivity. Overall, the effects of mortality and deferred costs on selectivity are small relative to the effects of other factors on selectivity. For instance, our model suggests that selectivity is much more strongly affected by total search time than by search costs, and it predicts a positive relationship between total search time and disperser selectivity across individuals in the same population, even in the face of considerable inter-individual variation in risk of mortality or deferred search costs.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Stamps","given":"Judy A."},{"family":"Krishnan","given":"V. V."},{"family":"Reid","given":"Mary L."}],"container-title":"Ecology","ISSN":"0012-9658","issue":"2","issued":{"date-parts":[[2005]]},"page":"510-518","publisher":"Ecological Society of America","source":"JSTOR","title":"Search Costs and Habitat Selection by Dispersers","type":"article-journal","URL":"https://www.jstor.org/stable/3450970","volume":"86"}, + {"id":"starrfeltParentoffspringConflictEvolution2010","abstract":"Parent-offspring conflict emerges in many different contexts, but a rarely emphasized perspective is that of space as a resource that is allocated or acquired through dispersal. Early theoretical work has shown that there are different optima in rates of dispersal between parents and offspring. Here we examine this principle when space is explicitly modeled and dispersal is achieved through a dispersal kernel. We find a consistent pattern that selection favors longer dispersal distances under maternal control of dispersal (e.g., maternal tissue surrounding a seed) compared with scenarios where offspring themselves control dispersal (as in many animals). Intriguingly, offspring control leads to better resource utilization (higher habitat occupancy) in equilibrium scenarios than does maternal control. In contrast, in species that expand their ranges, maternal control of dispersal initially leads to faster range expansion. If there is evolutionary potential for dispersal kernels to change at the leading edge of a population, this difference vanishes quickly during an invasion because offspring-controlled dispersal evolves faster and catches up with scenarios involving maternal control. There is thus less conflict in nonequilibrium scenarios. In invasive scenarios with an evolving kernel shape, disruptive selection against intermediate distances can make the kernel not only fat-tailed but also bimodal.","author":[{"family":"Starrfelt","given":"Jostein"},{"family":"Kokko","given":"Hanna"}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/648605","ISSN":"1537-5323","issue":"1","issued":{"date-parts":[[2010,1]]},"language":"eng","page":"38-49","PMID":"19911910","source":"PubMed","title":"Parent-offspring conflict and the evolution of dispersal distance","type":"article-journal","volume":"175"}, + {"id":"stensethAnimalDispersalSmall1992","abstract":"4.1.1 Demographic significance Confined populations grow more rapidly than populations from which dispersal is permitted (Lidicker, 1975; Krebs, 1979; Tamarin et at., 1984), and demography in island populations where dispersal is restricted differs greatly from nearby mainland populations (Lidicker, 1973; Tamarin, 1977, 1978; Gliwicz, 1980), clearly demonstrating the demographic signi­ ficance of dispersal. The prevalence of dispersal in rapidly expanding populations is held to be the best evidence for presaturation dispersal. Because dispersal reduces the growth rate of source populations, it is generally believed that emigration is not balanced by immigration, and that mortality of emigrants occurs as a result of movement into a 'sink' of unfavourable habitat. If such dispersal is age- or sex-biased, the demo­ graphy of the population is markedly affected, as a consequence of differ­ ences in mortality in the dispersive sex or age class. Habitat heterogeneity consequently underlies this interpretation of dispersal and its demographic consequences, although the spatial variability of environments is rarely assessed in dispersal studies.","accessed":{"date-parts":[[2021,8,9]]},"DOI":"10.1007/978-94-011-2338-9","editor":[{"family":"Stenseth","given":"N. C."},{"family":"Lidicker","given":"W. Z."}],"ISBN":"978-0-412-29330-6","issued":{"date-parts":[[1992]]},"language":"en","publisher":"Springer Netherlands","source":"www.springer.com","title":"Animal Dispersal: Small mammals as a model","title-short":"Animal Dispersal","type":"book","URL":"https://www.springer.com/gp/book/9780412293306"}, + {"id":"stevensGeneFlowFunctional2006","abstract":"Functional connectivity is a key factor for the persistence of many specialist species in fragmented landscapes. However, connectivity estimates have rarely been validated by the observation of dispersal movements. In this study, we estimated functional connectivity of a real landscape by modelling dispersal for the endangered natterjack toad (Bufo calamita) using cost distance. Cost distance allows the evaluation of 'effective distances', which are distances corrected for the costs involved in moving between habitat patches in spatially explicit landscapes. We parameterized cost-distance models using the results of our previous experimental investigation of natterjack's movement behaviour. These model predictions (connectivity estimates from the GIS study) were then confronted to genetic-based dispersal rates between natterjack populations in the same landscape using Mantel tests. Dispersal rates between the populations were inferred from variation at six microsatellite loci. Based on these results, we conclude that matrix structure has a strong effect on dispersal rates. Moreover, we found that cost distances generated by habitat preferences explained dispersal rates better than did the Euclidian distances, or the connectivity estimate based on patch-specific resistances (patch viscosity). This study is a clear example of how landscape genetics can validate operational functional connectivity estimates.","author":[{"family":"Stevens","given":"Virginie M."},{"family":"Verkenne","given":"Catherine"},{"family":"Vandewoestijne","given":"Sofie"},{"family":"Wesselingh","given":"Renate A."},{"family":"Baguette","given":"Michel"}],"container-title":"Molecular Ecology","container-title-short":"Mol Ecol","DOI":"10.1111/j.1365-294X.2006.02936.x","ISSN":"0962-1083","issue":"9","issued":{"date-parts":[[2006,8]]},"language":"eng","page":"2333-2344","PMID":"16842409","source":"PubMed","title":"Gene flow and functional connectivity in the natterjack toad","type":"article-journal","volume":"15"}, + {"id":"stevensLandscapeEffectsSpatial2012","abstract":"This chapter discusses the two reasons that make dispersal a key process in population dynamics: first, the movement of individuals impacts population dynamics, and second, dispersal movement also has important consequences for the degree of genetic mixing expected among populations, and hence on the genetic variation found within populations. This chapter, in the attempt to address the question of what landscape changes may affect spatial dynamics, presents an example of a species with limited mobility and one which has been extensively studied in this regard — the natterjack toad. Firstly, empirical studies were used to measure the effects of landscape elements on movement patterns. Secondly, the results from these empirical studies were used to model the effects of landscape on movement patterns. Thirdly, the model was validated through a comparison of the movements predicted by the models with those estimated by the analysis of gene flow among populations. Finally, the model was used to predict natterjack population dynamics under different landscape management scenarios.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Stevens","given":"Virginie M."},{"family":"Coulon","given":"Aurélie"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0022","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Landscape effects on spatial dynamics: the natterjack toad as a case study","title-short":"Landscape effects on spatial dynamics","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-22"}, + {"id":"stevensMetaanalysisDispersalButterflies2010","abstract":"Dispersal has recently gained much attention because of its crucial role in the conservation and evolution of species facing major environmental changes such as habitat loss and fragmentation, climate change, and their interactions. Butterflies have long been recognized as ideal model systems for the study of dispersal and a huge amount of data on their ability to disperse has been collected under various conditions. However, no single ‘best’ method seems to exist leading to the co-occurrence of various approaches to study butterfly mobility, and therefore a high heterogeneity among data on dispersal across this group. Accordingly, we here reviewed the knowledge accumulated on dispersal and mobility in butterflies, to detect general patterns. This meta-analysis specifically addressed two questions. Firstly, do the various methods provide a congruent picture of how dispersal ability is distributed across species? Secondly, is dispersal species-specific? Five sources of data were analysed: multisite mark-recapture experiments, genetic studies, experimental assessments, expert opinions, and transect surveys. We accounted for potential biases due to variation in genetic markers, sample sizes, spatial scales or the level of habitat fragmentation. We showed that the various dispersal estimates generally converged, and that the relative dispersal ability of species could reliably be predicted from their relative vagrancy (records of butterflies outside their normal habitat). Expert opinions gave much less reliable estimates of realized dispersal but instead reflected migration propensity of butterflies. Within-species comparisons showed that genetic estimates were relatively invariable, while other dispersal estimates were highly variable. This latter point questions dispersal as a species-specific, invariant trait.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Stevens","given":"Virginie M."},{"family":"Turlure","given":"Camille"},{"family":"Baguette","given":"Michel"}],"container-title":"Biological Reviews","DOI":"10.1111/j.1469-185X.2009.00119.x","ISSN":"1469-185X","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1469-185X.2009.00119.x","page":"625-642","source":"Wiley Online Library","title":"A meta-analysis of dispersal in butterflies","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1469-185X.2009.00119.x","volume":"85"}, + {"id":"stevensQuantifyingFunctionalConnectivity2006","abstract":"Like other pond-breeding amphibians, the natterjack toad (Bufo calamita) typically presents a patchy distribution. Because the species experiences high probabilities of local population extinction, its persistence within landscapes relies on both local and landscape-scale processes [dispersal allowing the (re)colonization of habitat patches]. However, the structure and composition of the matrix surrounding local populations can alter the dispersal rates between populations. As shown previously (Landscape Ecol 19:829–842, 2004), the locomotor performances of individuals at the dispersal stage depend on the nature of the component crossed: some landscape components offer high resistance to movement (high resistance or high viscosity components) whereas others allow high efficiency of movement (low resistance components). We now examine the ability of individuals to discriminate between landscape components and select low-resistance components. Our experimental study investigates the ways in which young natterjack toads choose from among landscape components common to southern Belgium. Toadlets (the dispersal stage) were experimentally confronted with boundaries between surrogates of sandy soils, roads, forests, agricultural fields and intensive pastures. Our results show: 1 the ability of toadlets to react to boundaries between landscape components, 2 differences in permeability among boundaries, and 3 our inability to predict correctly the permeability of the boundaries from the patch-specific resistance assessed previously. Toadlets showed a preference for bare environments and forests, whereas they avoided the use of agricultural environments. This pattern could not be explained in terms of patch-specific resistance only, and is discussed in terms of mortality risks and resource availability in the various landscape components, with particular attention to repercussions on conservation strategies.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Stevens","given":"Virginie M."},{"family":"Leboulengé","given":"Éric"},{"family":"Wesselingh","given":"Renate A."},{"family":"Baguette","given":"Michel"}],"container-title":"Oecologia","container-title-short":"Oecologia","DOI":"10.1007/s00442-006-0500-6","ISSN":"1432-1939","issue":"1","issued":{"date-parts":[[2006,11,1]]},"language":"en","page":"161-171","source":"Springer Link","title":"Quantifying functional connectivity: experimental assessment of boundary permeability for the natterjack toad (Bufo calamita)","title-short":"Quantifying functional connectivity","type":"article-journal","URL":"https://doi.org/10.1007/s00442-006-0500-6","volume":"150"}, + {"id":"thomasClimateClimateChange2010","abstract":"Aim A major issue in ecology, biogeography, conservation biology and invasion biology is the extent to which climate, and hence climate change, contributes to the positions of species’ range boundaries. Thirty years of rapid climate warming provides an excellent opportunity to test the hypothesis that climate acts as a major constraint on range boundaries, treating anthropogenic climate change as a large-scale experiment. Location UK and global data, and literature. Methods This article analyses the frequencies with which species have responded to climate change by shifting their range boundaries. It does not consider abundance or other changes. Results For the majority of species, boundaries shifted in a direction that is concordant with being a response to climate change; 84% of all species have expanded in a polewards direction as the climate has warmed (for the best data available), which represents an excess of 68% of species after taking account of the fact that some species may shift in this direction for non-climatic reasons. Other data sets also show an excess of animal range boundaries expanding in the expected direction. Main conclusions Climate is likely to contribute to the majority of terrestrial and freshwater range boundaries. This generalization excludes species that are endemic to specific islands, lakes, rivers and geological outcrops, although these local endemics are not immune from the effects of climate change. The observed shifts associated with recent climate change are likely to have been brought about through both direct and indirect (changes to species’ interactions) effects of climate; indirect effects are discussed in relation to laboratory experiments and invasive species. Recent observations of range boundary shifts are consistent with the hypothesis that climate contributes to, but is not the sole determinant of, the position of the range boundaries of the majority of terrestrial animal species.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Thomas","given":"Chris D."}],"container-title":"Diversity and Distributions","DOI":"10.1111/j.1472-4642.2010.00642.x","ISSN":"1472-4642","issue":"3","issued":{"date-parts":[[2010]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1472-4642.2010.00642.x","page":"488-495","source":"Wiley Online Library","title":"Climate, climate change and range boundaries","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1472-4642.2010.00642.x","volume":"16"}, + {"id":"thomasExtinctionRiskClimate2004","abstract":"Climate change over the past ∼30 years has produced numerous shifts in the distributions and abundances of species1,2 and has been implicated in one species-level extinction3. Using projections of species' distributions for future climate scenarios, we assess extinction risks for sample regions that cover some 20% of the Earth's terrestrial surface. Exploring three approaches in which the estimated probability of extinction shows a power-law relationship with geographical range size, we predict, on the basis of mid-range climate-warming scenarios for 2050, that 15–37% of species in our sample of regions and taxa will be ‘committed to extinction’. When the average of the three methods and two dispersal scenarios is taken, minimal climate-warming scenarios produce lower projections of species committed to extinction (∼18%) than mid-range (∼24%) and maximum-change (∼35%) scenarios. These estimates show the importance of rapid implementation of technologies to decrease greenhouse gas emissions and strategies for carbon sequestration.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Thomas","given":"Chris D."},{"family":"Cameron","given":"Alison"},{"family":"Green","given":"Rhys E."},{"family":"Bakkenes","given":"Michel"},{"family":"Beaumont","given":"Linda J."},{"family":"Collingham","given":"Yvonne C."},{"family":"Erasmus","given":"Barend F. N."},{"family":"Siqueira","given":"Marinez Ferreira","non-dropping-particle":"de"},{"family":"Grainger","given":"Alan"},{"family":"Hannah","given":"Lee"},{"family":"Hughes","given":"Lesley"},{"family":"Huntley","given":"Brian"},{"family":"Jaarsveld","given":"Albert S.","non-dropping-particle":"van"},{"family":"Midgley","given":"Guy F."},{"family":"Miles","given":"Lera"},{"family":"Ortega-Huerta","given":"Miguel A."},{"family":"Townsend Peterson","given":"A."},{"family":"Phillips","given":"Oliver L."},{"family":"Williams","given":"Stephen E."}],"container-title":"Nature","DOI":"10.1038/nature02121","ISSN":"1476-4687","issue":"6970","issued":{"date-parts":[[2004,1]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Research","number":"6970","page":"145-148","publisher":"Nature Publishing Group","source":"www.nature.com","title":"Extinction risk from climate change","type":"article-journal","URL":"https://www.nature.com/articles/nature02121","volume":"427"}, + {"id":"thomasTranslocationSpeciesClimate2011","abstract":"Many of the species at greatest risk of extinction from anthropogenic climate change are narrow endemics that face insurmountable dispersal barriers. In this review, I argue that the only viable option to maintain populations of these species in the wild is to translocate them to other locations where the climate is suitable. Risks of extinction to native species in destination areas are small, provided that translocations take place within the same broad geographic region and that the destinations lack local endemics. Biological communities in these areas are in the process of receiving many hundreds of other immigrant species as a result of climate change; ensuring that some of the 'new' inhabitants are climate-endangered species could reduce the net rate of extinction.","author":[{"family":"Thomas","given":"Chris D."}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends Ecol Evol","DOI":"10.1016/j.tree.2011.02.006","ISSN":"1872-8383","issue":"5","issued":{"date-parts":[[2011,5]]},"language":"eng","page":"216-221","PMID":"21411178","source":"PubMed","title":"Translocation of species, climate change, and the end of trying to recreate past ecological communities","type":"article-journal","volume":"26"}, + {"id":"thuillerBIOMODPlatformEnsemble2009a","abstract":"BIOMOD is a computer platform for ensemble forecasting of species distributions, enabling the treatment of a range of methodological uncertainties in models and the examination of species-environment relationships. BIOMOD includes the ability to model species distributions with several techniques, test models with a wide range of approaches, project species distributions into different environmental conditions (e.g. climate or land use change scenarios) and dispersal functions. It allows assessing species temporal turnover, plot species response curves, and test the strength of species interactions with predictor variables. BIOMOD is implemented in R and is a freeware, open source, package.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Thuiller","given":"Wilfried"},{"family":"Lafourcade","given":"Bruno"},{"family":"Engler","given":"Robin"},{"family":"Araújo","given":"Miguel B."}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2008.05742.x","ISSN":"1600-0587","issue":"3","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2008.05742.x","page":"369-373","source":"Wiley Online Library","title":"BIOMOD – a platform for ensemble forecasting of species distributions","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2008.05742.x","volume":"32"}, + {"id":"thuillerClimateChangeThreats2005","abstract":"Climate change has already triggered species distribution shifts in many parts of the world. Increasing impacts are expected for the future, yet few studies have aimed for a general understanding of the regional basis for species vulnerability. We projected late 21st century distributions for 1,350 European plants species under seven climate change scenarios. Application of the International Union for Conservation of Nature and Natural Resources Red List criteria to our projections shows that many European plant species could become severely threatened. More than half of the species we studied could be vulnerable or threatened by 2080. Expected species loss and turnover per pixel proved to be highly variable across scenarios (27-42% and 45-63% respectively, averaged over Europe) and across regions (2.5-86% and 17-86%, averaged over scenarios). Modeled species loss and turnover were found to depend strongly on the degree of change in just two climate variables describing temperature and moisture conditions. Despite the coarse scale of the analysis, species from mountains could be seen to be disproportionably sensitive to climate change (≈60% species loss). The boreal region was projected to lose few species, although gaining many others from immigration. The greatest changes are expected in the transition between the Mediterranean and Euro-Siberian regions. We found that risks of extinction for European plants may be large, even in moderate scenarios of climate change and despite inter-model variability.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Thuiller","given":"Wilfried"},{"family":"Lavorel","given":"Sandra"},{"family":"Araújo","given":"Miguel B."},{"family":"Sykes","given":"Martin T."},{"family":"Prentice","given":"I. Colin"}],"container-title":"Proceedings of the National Academy of Sciences","container-title-short":"PNAS","DOI":"10.1073/pnas.0409902102","ISSN":"0027-8424, 1091-6490","issue":"23","issued":{"date-parts":[[2005,6,7]]},"language":"en","page":"8245-8250","PMID":"15919825","publisher":"National Academy of Sciences","section":"Biological Sciences","source":"www.pnas.org","title":"Climate change threats to plant diversity in Europe","type":"article-journal","URL":"https://www.pnas.org/content/102/23/8245","volume":"102"}, + {"id":"thuillerPredictingGlobalChange2008","abstract":"Given the rate of projected environmental change for the 21st century, urgent adaptation and mitigation measures are required to slow down the on-going erosion of biodiversity. Even though increasing evidence shows that recent human-induced environmental changes have already triggered species’ range shifts, changes in phenology and species’ extinctions, accurate projections of species’ responses to future environmental changes are more difficult to ascertain. This is problematic, since there is a growing awareness of the need to adopt proactive conservation planning measures using forecasts of species’ responses to future environmental changes. There is a substantial body of literature describing and assessing the impacts of various scenarios of climate and land-use change on species’ distributions. Model predictions include a wide range of assumptions and limitations that are widely acknowledged but compromise their use for developing reliable adaptation and mitigation strategies for biodiversity. Indeed, amongst the most used models, few, if any, explicitly deal with migration processes, the dynamics of population at the “trailing edge” of shifting populations, species’ interactions and the interaction between the effects of climate and land-use. In this review, we propose two main avenues to progress the understanding and prediction of the different processes occurring on the leading and trailing edge of the species’ distribution in response to any global change phenomena. Deliberately focusing on plant species, we first explore the different ways to incorporate species’ migration in the existing modelling approaches, given data and knowledge limitations and the dual effects of climate and land-use factors. Secondly, we explore the mechanisms and processes happening at the trailing edge of a shifting species’ distribution and how to implement them into a modelling approach. We finally conclude this review with clear guidelines on how such modelling improvements will benefit conservation strategies in a changing world.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Thuiller","given":"Wilfried"},{"family":"Albert","given":"Cécile"},{"family":"Araújo","given":"Miguel B."},{"family":"Berry","given":"Pam M."},{"family":"Cabeza","given":"Mar"},{"family":"Guisan","given":"Antoine"},{"family":"Hickler","given":"Thomas"},{"family":"Midgley","given":"Guy F."},{"family":"Paterson","given":"James"},{"family":"Schurr","given":"Frank M."},{"family":"Sykes","given":"Martin T."},{"family":"Zimmermann","given":"Niklaus E."}],"collection-title":"Space matters - Novel developments in plant ecology through spatial modelling","container-title":"Perspectives in Plant Ecology, Evolution and Systematics","container-title-short":"Perspectives in Plant Ecology, Evolution and Systematics","DOI":"10.1016/j.ppees.2007.09.004","ISSN":"1433-8319","issue":"3","issued":{"date-parts":[[2008,3,6]]},"language":"en","page":"137-152","source":"ScienceDirect","title":"Predicting global change impacts on plant species’ distributions: Future challenges","title-short":"Predicting global change impacts on plant species’ distributions","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S1433831907000376","volume":"9"}, + {"id":"thuillerRoadMapIntegrating2013","abstract":"The demand for projections of the future distribution of biodiversity has triggered an upsurge in modelling at the crossroads between ecology and evolution. Despite the enthusiasm around these so-called biodiversity models, most approaches are still criticised for not integrating key processes known to shape species ranges and community structure. Developing an integrative modelling framework for biodiversity distribution promises to improve the reliability of predictions and to give a better understanding of the eco-evolutionary dynamics of species and communities under changing environments. In this article, we briefly review some eco-evolutionary processes and interplays among them, which are essential to provide reliable projections of species distributions and community structure. We identify gaps in theory, quantitative knowledge and data availability hampering the development of an integrated modelling framework. We argue that model development relying on a strong theoretical foundation is essential to inspire new models, manage complexity and maintain tractability. We support our argument with an example of a novel integrated model for species distribution modelling, derived from metapopulation theory, which accounts for abiotic constraints, dispersal, biotic interactions and evolution under changing environmental conditions. We hope such a perspective will motivate exciting and novel research, and challenge others to improve on our proposed approach.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Thuiller","given":"Wilfried"},{"family":"Münkemüller","given":"Tamara"},{"family":"Lavergne","given":"Sébastien"},{"family":"Mouillot","given":"David"},{"family":"Mouquet","given":"Nicolas"},{"family":"Schiffers","given":"Katja"},{"family":"Gravel","given":"Dominique"}],"container-title":"Ecology Letters","DOI":"10.1111/ele.12104","ISSN":"1461-0248","issue":"s1","issued":{"date-parts":[[2013]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/ele.12104","page":"94-105","source":"Wiley Online Library","title":"A road map for integrating eco-evolutionary processes into biodiversity models","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/ele.12104","volume":"16"}, + {"id":"travisAcceleratingInvasionRates2009","abstract":"Evolutionary processes play an important role in shaping the dynamics of range expansions, and selection on dispersal propensity has been demonstrated to accelerate rates of advance. Previous theory has considered only the evolution of unconditional dispersal rates, but dispersal is often more complex. For example, many species emigrate in response to crowding. Here, we use an individual-based model to investigate the evolution of density dependent dispersal into empty habitat, such as during an invasion. The landscape is represented as a lattice and dispersal between populations follows a stepping-stone pattern. Individuals carry three ‘genes’ that determine their dispersal strategy when experiencing different population densities. For a stationary range we obtain results consistent with previous theoretical studies: few individuals emigrate from patches that are below equilibrium density. However, during the range expansion of a previously stationary population, we observe evolution towards dispersal strategies where considerable emigration occurs well below equilibrium density. This is true even for moderate costs to dispersal, and always results in accelerating rates of range expansion. Importantly, the evolution we observe at an expanding front depends upon fitness integrated over several generations and cannot be predicted by a consideration of lifetime reproductive success alone. We argue that a better understanding of the role of density dependent dispersal, and its evolution, in driving population dynamics is required especially within the context of range expansions.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"Justin M. J."},{"family":"Mustin","given":"Karen"},{"family":"Benton","given":"Tim G."},{"family":"Dytham","given":"Calvin"}],"container-title":"Journal of Theoretical Biology","container-title-short":"Journal of Theoretical Biology","DOI":"10.1016/j.jtbi.2009.03.008","ISSN":"0022-5193","issue":"1","issued":{"date-parts":[[2009,7,7]]},"language":"en","page":"151-158","source":"ScienceDirect","title":"Accelerating invasion rates result from the evolution of density-dependent dispersal","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0022519309001155","volume":"259"}, + {"id":"travisClimateChangeHabitat2003","abstract":"Climate change and habitat destruction are two of the greatest threats to global biodiversity. Lattice models have been used to investigate how hypothetical species with different characteristics respond to habitat loss. The main result shows that a sharp threshold in habitat availability exists below which a species rapidly becomes extinct. Here, a similar modelling approach is taken to establish what determines how species respond to climate change. A similar threshold exists for the rate of climate change as has been observed for habitat loss—patch occupancy remains high up to a critical rate of climate change, beyond which species extinction becomes likely. Habitat specialists, especially those of relatively poor colonizing ability are least able to keep pace with climate change. The interaction between climate change and habitat loss might be disastrous. During climate change, the habitat threshold occurs sooner. Similarly, species suffer more from climate change in a fragmented habitat.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"J. M. J."}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","DOI":"10.1098/rspb.2002.2246","issue":"1514","issued":{"date-parts":[[2003,3,7]]},"page":"467-473","publisher":"Royal Society","source":"royalsocietypublishing.org (Atypon)","title":"Climate change and habitat destruction: a deadly anthropogenic cocktail","title-short":"Climate change and habitat destruction","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.2002.2246","volume":"270"}, + {"id":"travisColorNoiseEvolution2001","abstract":"The process of dispersal is vital for the long-term persistence of all species and hence is a ubiquitous characteristic of living organisms. A present challenge is to increase our understanding of the factors that govern the dispersal rate of individuals. Here I extend previous work by incorporating both spatial and temporal heterogeneity in terms of patch quality into a spatially explicit lattice model. The spatial heterogeneity is modeled as a two-dimensional fractal landscape, while temporal heterogeneity is included by using one-dimensional noise. It was found that the color of both the spatial and temporal variability influences the rate of dispersal selected as reddening of the temporal noise leads to a reduction in dispersal, while reddening of spatial variability results in an increase in the dispersal rate. These results demonstrate that the color of environmental noise should be considered in future studies looking at the evolution of life history characteristics.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"Justin M. J."}],"container-title":"Ecological Research","container-title-short":"Ecol Res","DOI":"10.1046/j.1440-1703.2001.00381.x","ISSN":"1440-1703","issue":"1","issued":{"date-parts":[[2001,3,1]]},"language":"en","page":"157-163","source":"Springer Link","title":"The color of noise and the evolution of dispersal","type":"article-journal","URL":"https://doi.org/10.1046/j.1440-1703.2001.00381.x","volume":"16"}, + {"id":"travisDispersalClimateChange2012","abstract":"This chapter focuses on how models of dispersal can improve our understanding, prediction, and management of species' range shifts under environmental change. Most models of species distribution and spread represent dispersal quite crudely; this chapter begins with some thoughts on how these might be integrated with more sophisticated models of dispersal. The importance of inter-individual variability in dispersal and the role that dispersal evolution may play in range shifting is considered. An example of evolutionary entrapment that arises when species expand their ranges over fragmented landscapes is then presented. Finally, potential management strategies that may be used to promote range shifting are considered.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"Justin M. J."},{"family":"Dytham","given":"Calvin"}],"container-title":"Dispersal Ecology and Evolution","DOI":"10.1093/acprof:oso/9780199608898.003.0026","event-place":"Oxford","ISBN":"978-0-19-960889-8","issued":{"date-parts":[[2012]]},"language":"eng","publisher":"Oxford University Press","publisher-place":"Oxford","source":"University Press Scholarship","title":"Dispersal and climate change: a review of theory","title-short":"Dispersal and climate change","type":"chapter","URL":"https://oxford.universitypressscholarship.com/10.1093/acprof:oso/9780199608898.001.0001/acprof-9780199608898-chapter-26"}, + {"id":"travisDispersalEvolutionInvasions2002","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"Justin M J"},{"family":"Dytham","given":"Calvin"}],"container-title":"Evolutionary Ecology Research","container-title-short":"Evol.Ecol.Res.","ISSN":"1522-0613","issue":"8","issued":{"date-parts":[[2002]]},"language":"English","page":"1119-1129","publisher":"EVOLUTIONARY ECOLOGY LTD","source":"abdn.pure.elsevier.com","title":"Dispersal evolution during invasions","type":"article-journal","URL":"https://abdn.pure.elsevier.com/en/publications/dispersal-evolution-during-invasions","volume":"4"}, + {"id":"travisDispersalSpeciesResponses2014","abstract":"Dispersal is fundamental in determining biodiversity responses to rapid climate change, but recently acquired ecological and evolutionary knowledge is seldom accounted for in either predictive methods or conservation planning. We emphasise the accumulating evidence for direct and indirect impacts of climate change on dispersal. Additionally, evolutionary theory predicts increases in dispersal at expanding range margins, and this has been observed in a number of species. This multitude of ecological and evolutionary processes is likely to lead to complex responses of dispersal to climate change. As a result, improvement of models of species’ range changes will require greater realism in the representation of dispersal. Placing dispersal at the heart of our thinking will facilitate development of conservation strategies that are resilient to climate change, including landscape management and assisted colonisation. Synthesis This article seeks synthesis across the fields of dispersal ecology and evolution, species distribution modelling and conservation biology. Increasing effort focuses on understanding how dispersal influences species' responses to climate change. Importantly, though perhaps not broadly widely-recognised, species' dispersal characteristics are themselves likely to alter during rapid climate change. We compile evidence for direct and indirect influences that climate change may have on dispersal, some ecological and others evolutionary. We emphasise the need for predictive modelling to account for this dispersal realism and highlight the need for conservation to make better use of our existing knowledge related to dispersal.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"J. M. J."},{"family":"Bocedi","given":"Greta"},{"family":"Baguette","given":"Michel"},{"family":"Bartoń","given":"Kamil"},{"family":"Bonte","given":"Dries"},{"family":"Boulangeat","given":"Isabelle"},{"family":"Hodgson","given":"Jenny A."},{"family":"Kubisch","given":"Alexander"},{"family":"Penteriani","given":"Vincenzo"},{"family":"Saastamoinen","given":"Marjo"},{"family":"Stevens","given":"Virginie M."},{"family":"Bullock","given":"James M."}],"container-title":"Oikos","DOI":"10.1111/j.1600-0706.2013.00399.x","ISSN":"1600-0706","issue":"11","issued":{"date-parts":[[2014]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0706.2013.00399.x","page":"1532-1540","source":"Wiley Online Library","title":"Dispersal and species’ responses to climate change","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0706.2013.00399.x","volume":"122"}, + {"id":"travisEvolutionDensitydependentDispersal1999","abstract":"Despite a large body of empirical evidence suggesting that the dispersal rates of many species depend on population density, most metapopulation models assume a density-independent rate of dispersal. Similarly, studies investigating the evolution of dispersal have concentrated almost exclusively on density-independent rates of dispersal. We develop a model that allows density-dependent dispersal strategies to evolve. Our results demonstrate that a density-dependent dispersal strategy almost always evolves and that the form of the relationship depends on reproductive rate, type of competition, size of subpopulation equilibrium densities and cost of dispersal. We suggest that future metapopulation models should account for density-dependent dispersal","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"J. M. J."},{"family":"Murrell","given":"D. J."},{"family":"Dytham","given":"C."}],"container-title":"Proceedings of the Royal Society B: Biological Sciences","container-title-short":"Proc Biol Sci","DOI":"10.1098/rspb.1999.0854","ISSN":"0962-8452","issue":"1431","issued":{"date-parts":[[1999,9,22]]},"page":"1837","PMCID":"PMC1690220","PMID":"null","source":"PubMed Central","title":"The evolution of density-dependent dispersal","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1690220/","volume":"266"}, + {"id":"travisHabitatPersistenceHabitat1999","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"J. M. J."},{"family":"Dytham","given":"C."}],"container-title":"Proceedings of the Royal Society of London. Series B: Biological Sciences","issue":"266","issued":{"date-parts":[[1999]]},"page":"723-728","title":"Habitat persistence, habitat availability and the evolution of dispersal","type":"article-journal","URL":"https://royalsocietypublishing.org/doi/10.1098/rspb.1999.0696"}, + {"id":"travisImprovingPredictionManagement2011a","abstract":"1. Improving the understanding, prediction and management of range expansions is a key challenge for ecology. Over recent years, there has been a rapid increase in modelling effort focussed on range expansions and a shift from predominantly theoretical developments towards application. This is especially the case in the field of invasion biology and also in relation to reintroductions and species’ responses to climate change. 2. While earlier models were exclusively analytical, individual-based models (IBMs) are now increasingly widely used. We argue that instead of being viewed as competing methodologies, analytical and individual-based methods can valuably be used in conjunction. 3. We use a mechanistic wind dispersal model to generate age-specific dispersal kernels for the invasive shrub, Rhododendron ponticum. To demonstrate the utility of employing both modelling approaches, this information along with demographic parameters is incorporated into an IBM and an analytical, integrodifference model. From both models, the equilibrium rate of spread is calculated. 4. Estimates of wavespeeds were similar for the two models, although slower rates of spread were consistently projected by the IBM. Further, our results demonstrate the wavespeed to be sensitive to the characterisation of age structure in the model; when few age classes are used, much higher rates of spread are projected. 5. The analytical model is extremely efficient at providing elasticity analysis of the wavespeed, which can provide helpful information for management. We gain qualitatively similar results using the IBM but obtaining the results is time-consuming and, because the model is stochastic, they are noisy and harder to interpret. We argue that analytically derived transient elasticity analyses are needed for the many cases where success of control is measured on a relatively short time horizon. 6. To demonstrate the flexibility of the IBM approach, we run it on a real landscape comprising different habitat types. The comparison of two different control scenarios is an example of the utility of this approach for more tactical applications. 7. As a general conclusion of the study, we emphasise that analytical and individual-based approaches offer different, but complementary, advantages and suggest how their joint use can facilitate the improvement in biodiversity management at a range of spatial scales.","accessed":{"date-parts":[[2021,8,10]]},"author":[{"family":"Travis","given":"J. M. J."},{"family":"Harris","given":"Catriona M."},{"family":"Park","given":"Kirsty J."},{"family":"Bullock","given":"James M."}],"container-title":"Methods in Ecology and Evolution","DOI":"10.1111/j.2041-210X.2011.00104.x","ISSN":"2041-210X","issue":"5","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.2041-210X.2011.00104.x","page":"477-488","source":"Wiley Online Library","title":"Improving prediction and management of range expansions by combining analytical and individual-based modelling approaches","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.2041-210X.2011.00104.x","volume":"2"}, + {"id":"travisMechanisticUnderstandingDispersal2010","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"Justin M. J."},{"family":"Smith","given":"Hannah S."},{"family":"Ranwala","given":"Sudheera M. W."}],"container-title":"Diversity and Distributions","DOI":"10.1111/j.1472-4642.2010.00674.x","issue":"4","issued":{"date-parts":[[2010,7]]},"language":"English","page":"690-702","publisher":"WILEY-BLACKWELL","source":"abdn.pure.elsevier.com","title":"Towards a mechanistic understanding of dispersal evolution in plants: conservation implications","title-short":"Towards a mechanistic understanding of dispersal evolution in plants","type":"article-journal","URL":"https://abdn.pure.elsevier.com/en/publications/towards-a-mechanistic-understanding-of-dispersal-evolution-in-pla","volume":"16"}, + {"id":"travisMethodSimulatingPatterns2004","abstract":"The dynamics of populations inhabiting range margins are likely to be critically important in determining the response of species to climate change. Despite this, there is a lack of both empirical and theoretical work that examines the behaviour of these populations. Populations living on the edge of a species' range frequently inhabit a more patchily distributed habitat than those that live closer to the centre of the range. This difference is likely to play an important role in determining the dynamics of range margin populations, both when the range is static and when it is dynamic, for example shifting in response to climate change. Here, we present a simple method that simulates the distribution of suitable habitat sites at the edge of a range. Habitat availability is determined as a function of both latitudinal and local environmental variability, and the relative importance of the two can be adjusted. The method is readily extended to describe shifting habitat availability during a period of climate change. We suggest that there is a need for a greater effort to examine the ecology of range margin populations, and believe that the method presented here could be of considerable use in future theoretical studies.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"J. M. J."},{"family":"Dytham","given":"C."}],"container-title":"Oikos","ISSN":"0030-1299","issue":"2","issued":{"date-parts":[[2004]]},"page":"410-416","publisher":"[Nordic Society Oikos, Wiley]","source":"JSTOR","title":"A Method for Simulating Patterns of Habitat Availability at Static and Dynamic Range Margins","type":"article-journal","URL":"https://www.jstor.org/stable/3547970","volume":"104"}, + {"id":"travisModellingDispersalEcoevolutionary2012a","abstract":"1. Understanding the causes and consequences of dispersal remains a central topic in ecology and evolution. However, a mismatch exists between our empirical understanding of the complexity of dispersal and our representation of dispersal in models. While the empirical literature is replete with examples of condition dependence at the emigration, movement and settlement phases, models rarely incorporate realism or complexity to this degree. Nor do models often include the different costs associated with dispersal, which can themselves be linked to one or more of the three key phases. 2. Here, we propose that by explicitly accounting for emigration, movement and settlement (and the multiple costs associated with each) we can substantially improve our understanding of both the dispersal process itself and how dispersal traits trade off against other life-history characteristics. We explore some of these issues conceptually, before presenting illustrative results gained from a flexible individual-based model which incorporates considerable dispersal complexity. 3. These results emphasise the nonlinear interplay between the different dispersal stages. For example, we find that investment in movement ability (at a cost to fecundity) depends upon the propensity to emigrate (and vice versa). However, owing to selection acting at the metapopulation level as well as at the individual level, the relationship between the two is not straightforward. Importantly, the shape of the trade-off between movement ability and reproductive potential can strongly influence the joint evolution of dispersal parameters controlling the degree of investment in safer movement, the probability of emigration and the straightness of movement. 4. Our results highlight that the joint evolution of dispersal characteristics can have major implications for spatial population dynamics and we argue that, in addition to increasing our fundamental biological understanding, a new generation of dispersal modelling, which exploits recent empirical advances, can substantially improve our ability to predict and manage the response of species to environmental change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Travis","given":"J. M. J."},{"family":"Bartoń","given":"Kamil A."},{"family":"Benton","given":"Tim G."},{"family":"Clobert","given":"Jean"},{"family":"Delgado","given":"Maria M."},{"family":"Dytham","given":"Calvin"},{"family":"Hovestadt","given":"Thomas"},{"family":"Palmer","given":"Stephen C. F."},{"family":"Dyck","given":"Hans Van"},{"family":"Bonte","given":"Dries"}],"container-title":"Methods in Ecology and Evolution","DOI":"10.1111/j.2041-210X.2012.00193.x","ISSN":"2041-210X","issue":"4","issued":{"date-parts":[[2012]]},"language":"en","note":"_eprint: https://besjournals.onlinelibrary.wiley.com/doi/pdf/10.1111/j.2041-210X.2012.00193.x","page":"628-641","source":"Wiley Online Library","title":"Modelling dispersal: an eco-evolutionary framework incorporating emigration, movement, settlement behaviour and the multiple costs involved","title-short":"Modelling dispersal","type":"article-journal","URL":"https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/j.2041-210X.2012.00193.x","volume":"3"}, + {"id":"turlureSpeciesSexspecificAdjustments2011","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Turlure","given":"Camille"},{"family":"Baguette","given":"M"},{"family":"Stevens","given":"Virginie M"},{"family":"Maes","given":"D"}],"container-title":"Behavioral Ecology","issue":"22","issued":{"date-parts":[[2011]]},"page":"967-975","title":"Species- and sex-specific adjustments of movement behavior to landscape heterogeneity in butterflies","type":"article-journal","URL":"https://academic.oup.com/beheco/article/22/5/967/251656?login=true"}, + {"id":"turnerUsefulnessSpatiallyExplicit1995","abstract":"Land managers need new tools, such as spatial models, to aid them in their decision-making processes because managing for biodiversity, water quality, or natural disturbance is challenging, and landscapes are complex and dynamic. Spatially explicit population models are helpful to managers because these models consider both species-habitat relationships and the arrangement of habitats in space and time. The visualizations that typically accompany spatially explicit models also permit managers to 'see' the effects of alternative management strategies on populations of interest. However, the expense entailed in developing the data bases required for spatially explicit models may limit widespread implementation. In addition, many of the models are developed for one or a few species, and dealing with multiple species in a landscape remains a significant challenge. To be most useful to land managers, spatially explicit population models should be user friendly, easily portable, operate on spatial and temporal scales appropriate to management decisions, and use input and output variables that can be measured affordably.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Turner","given":"Monica G."},{"family":"Arthaud","given":"Greg J."},{"family":"Engstrom","given":"R. Todd"},{"family":"Hejl","given":"Sallie J."},{"family":"Liu","given":"Jianguo"},{"family":"Loeb","given":"Susan"},{"family":"McKelvey","given":"Kevin"}],"container-title":"Ecological Applications","DOI":"10.2307/1942046","ISSN":"1939-5582","issue":"1","issued":{"date-parts":[[1995]]},"language":"en","note":"_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.2307/1942046","page":"12-16","source":"Wiley Online Library","title":"Usefulness of Spatially Explicit Population Models in Land Management","type":"article-journal","URL":"https://esajournals.onlinelibrary.wiley.com/doi/abs/10.2307/1942046","volume":"5"}, + {"id":"urbanMovingForwardDispersal2013","abstract":"We need accurate predictions about how climate change will alter species distributions and abundances around the world. Most predictions assume simplistic dispersal scenarios and ignore biotic interactions. We argue for incorporating the complexities of dispersal and species interactions. Range expansions depend not just on mean dispersal, but also on the shape of the dispersal kernel and the population's growth rate. We show how models using species-specific dispersal can produce more accurate predictions than models applying all-or-nothing dispersal scenarios. Models that additionally include species interactions can generate distinct outcomes. For example, species interactions can slow climate tracking and produce more extinctions than models assuming no interactions. We conclude that (1) just knowing mean dispersal is insufficient to predict biotic responses to climate change, and (2) considering interspecific dispersal variation and species interactions jointly will be necessary to anticipate future changes to biological diversity. We advocate for collecting key information on interspecific dispersal differences and strong biotic interactions so that we can build the more robust predictive models that will be necessary to inform conservation efforts as climates continue to change.","author":[{"family":"Urban","given":"Mark C."},{"family":"Zarnetske","given":"Phoebe L."},{"family":"Skelly","given":"David K."}],"container-title":"Annals of the New York Academy of Sciences","container-title-short":"Ann N Y Acad Sci","DOI":"10.1111/nyas.12184","ISSN":"1749-6632","issued":{"date-parts":[[2013,9]]},"language":"eng","page":"44-60","PMID":"23819864","source":"PubMed","title":"Moving forward: dispersal and species interactions determine biotic responses to climate change","title-short":"Moving forward","type":"article-journal","volume":"1297"}, + {"id":"vandermeerMetapopulationDynamicsQuality2001","abstract":"In both strictly theoretical and more applied contexts it has been historically assumed that metapopulations exist within a featureless, uninhabitable matrix and that dynamics within the matrix are unimportant. In this article, we explore the range of theoretical consequences that result from relaxing this assumption. We show, with a variety of modeling techniques, that matrix quality can be extremely important in determining metapopulation dynamics. A higher-quality matrix generally buffers against extinction. However, in some situations, an increase in matrix quality can generate chaotic subpopulation dynamics, where stability had been the rule in a lower-quality matrix. Furthermore, subpopulations acting as source populations in a low-quality matrix may develop metapopulation dynamics as the quality of the matrix increases. By forcing metapopulation dynamics on a formerly heterogeneous (but stable within subpopulations) population, the probability of simultaneous extinction of all subpopulations actually increases. Thus, it cannot be automatically assumed that increasing matrix quality will lower the probability of global extinction of a population.","author":[{"family":"Vandermeer","given":"J."},{"family":"Carvajal","given":"R."}],"container-title":"The American Naturalist","container-title-short":"Am Nat","DOI":"10.1086/321318","ISSN":"1537-5323","issue":"3","issued":{"date-parts":[[2001,9]]},"language":"eng","page":"211-220","PMID":"18707319","source":"PubMed","title":"Metapopulation dynamics and the quality of the matrix","type":"article-journal","volume":"158"}, + {"id":"vasseurColorEnvironmentalNoise2004","abstract":"Biological populations are strongly influenced by the random variation in their environment. The spectrum of frequencies in noise is particularly important to dynamics and persistence. Here we present an analysis of the variance spectra of a wide variety of long-term time series of environmental variables. Spectra were well approximated by the inverse power law 1/fβ within the appropriate range of frequencies f; however, the majority of spectra were “flattened” at low frequencies. With some qualification we found the spectral exponents (β) to corroborate an earlier suggestion that terrestrial noise tends to be “white” (β < 0.5), while marine environments tend to be “red” (β ≈ 1) or “brown” (β ≈ 2). As well, we found a tendency for whiter noise in temperate latitudes than in either high or low latitudes. These results have wide-ranging consequences for ecosystem fragility and species conservation.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Vasseur","given":"David A."},{"family":"Yodzis","given":"Peter"}],"container-title":"Ecology","DOI":"10.1890/02-3122","ISSN":"1939-9170","issue":"4","issued":{"date-parts":[[2004]]},"language":"en","note":"_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/02-3122","page":"1146-1152","source":"Wiley Online Library","title":"The Color of Environmental Noise","type":"article-journal","URL":"https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/02-3122","volume":"85"}, + {"id":"verbeylenDoesMatrixResistance2003","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Verbeylen","given":"Goedele"},{"family":"Bruyn","given":"Luc De"},{"family":"Adriaensen","given":"F."},{"family":"Matthysen","given":"E."}],"container-title":"Landscape Ecology","DOI":"10.1023/B:LAND.0000014492.50765.05","issue":"8","issued":{"date-parts":[[2003]]},"language":"English","page":"791-805","source":"pureportal.inbo.be","title":"Does matrix resistance influence red squirrel (Sciurus vulgaris l. 1758) distribution in an urban landscape?","type":"article-journal","URL":"https://pureportal.inbo.be/en/publications/does-matrix-resistance-influence-red-squirrel-emsciurus-vulgarise","volume":"18"}, + {"id":"verboomPopulationDynamicsIncreasing2010","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Verboom","given":"J."},{"family":"Schippers","given":"P."},{"family":"Cormont","given":"A."},{"family":"Sterk","given":"M."},{"family":"Vos","given":"C. C."},{"family":"Opdam","given":"P. F. M."}],"container-title":"Landscape Ecology","DOI":"10.1007/s10980-010-9497-7","ISSN":"0921-2973","issued":{"date-parts":[[2010]]},"language":"English","page":"1289-1298","publisher":"Springer Verlag","source":"research.wur.nl","title":"Population dynamics under increasing environmental variability: implications of climate change for ecological network design criteria","title-short":"Population dynamics under increasing environmental variability","type":"article-journal","URL":"https://research.wur.nl/en/publications/population-dynamics-under-increasing-environmental-variability-im","volume":"25"}, + {"id":"verckenImportanceGoodNeighborhood2012","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Vercken","given":"E."},{"family":"Sinervo","given":"B."},{"family":"Clobert","given":"J"}],"container-title":"Behavioral Ecology","issue":"23","issued":{"date-parts":[[2012]]},"page":"1059-1067","title":"The importance of a good neighborhood: dispersal decisions in juvenile common lizards are based on social environment","type":"article-journal","URL":"https://academic.oup.com/beheco/article/23/5/1059/233208"}, + {"id":"vittAssistedMigrationPart2009","author":[{"family":"Vitt","given":"Pati"},{"family":"Havens","given":"Kayri"},{"family":"Hoegh-Guldberg","given":"Ove"}],"container-title":"Trends in Ecology & Evolution","container-title-short":"Trends Ecol Evol","DOI":"10.1016/j.tree.2009.05.007","ISSN":"0169-5347","issue":"9","issued":{"date-parts":[[2009,9]]},"language":"eng","page":"473-474; author reply 476-477","PMID":"19595474","source":"PubMed","title":"Assisted migration: part of an integrated conservation strategy","title-short":"Assisted migration","type":"article-journal","volume":"24"}, + {"id":"vuilleumierAnimalDispersalModelling2006","abstract":"Animal dispersal in a fragmented landscape depends on the complex interaction between landscape structure and animal behavior. To better understand how individuals disperse, it is important to explicitly represent the properties of organisms and the landscape in which they move. A common approach to modelling dispersal includes representing the landscape as a grid of equal sized cells and then simulating individual movement as a correlated random walk. This approach uses a priori scale of resolution, which limits the representation of all landscape features and how different dispersal abilities are modelled. We develop a vector-based landscape model coupled with an object-oriented model for animal dispersal. In this spatially explicit dispersal model, landscape features are defined based on their geographic and thematic properties and dispersal is modelled through consideration of an organism's behavior, movement rules and searching strategies (such as visual cues). We present the model's underlying concepts, its ability to adequately represent landscape features and provide simulation of dispersal according to different dispersal abilities. We demonstrate the potential of the model by simulating two virtual species in a real Swiss landscape. This illustrates the model's ability to simulate complex dispersal processes and provides information about dispersal such as colonization probability and spatial distribution of the organism's path.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Vuilleumier","given":"Séverine"},{"family":"Metzger","given":"Richard"}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/j.ecolmodel.2005.04.017","ISSN":"0304-3800","issue":"1","issued":{"date-parts":[[2006,1,10]]},"language":"en","page":"159-170","source":"ScienceDirect","title":"Animal dispersal modelling: Handling landscape features and related animal choices","title-short":"Animal dispersal modelling","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S030438000500222X","volume":"190"}, + {"id":"vuilleumierEffectsCognitiveAbilities2006","abstract":"Connectivity among demes in a metapopulation depends on both the landscape's and the focal organism's properties (including its mobility and cognitive abilities). Using individual-based simulations, we contrast the consequences of three different cognitive strategies on several measures of metapopulation connectivity. Model animals search suitable habitat patches while dispersing through a model landscape made of cells varying in size, shape, attractiveness and friction. In the blind strategy, the next cell is chosen randomly among the adjacent ones. In the near-sighted strategy, the choice depends on the relative attractiveness of these adjacent cells. In the far-sighted strategy, animals may additionally target suitable patches that appear within their perceptual range. Simulations show that the blind strategy provides the best overall connectivity, and results in balanced dispersal. The near-sighted strategy traps animals into corridors that reduce the number of potential targets, thereby fragmenting metapopulations in several local clusters of demes, and inducing sink-source dynamics. This sort of local trapping is somewhat prevented in the far-sighted strategy. The colonization success of strategies depends highly on initial energy reserves: blind does best when energy is high, near-sighted wins at intermediate levels, and far-sighted outcompetes its rivals at low energy reserves. We also expect strong effects in terms of metapopulation genetics: the blind strategy generates a migrant-pool mode of dispersal that should erase local structures. By contrast, near- and far-sighted strategies generate a propagule-pool mode of dispersal and source-sink behavior that should boost structures (high genetic variance among-and low variance within local clusters of demes), particularly if metapopulation dynamics is also affected by extinction-colonization processes. Our results thus point to important effects of the cognitive ability of dispersers on the connectivity, dynamics and genetics of metapopulations.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Vuilleumier","given":"Séverine"},{"family":"Perrin","given":"Nicolas"},{"family":"Ranta","given":"Esa"}],"container-title":"Oikos","ISSN":"0030-1299","issue":"1","issued":{"date-parts":[[2006]]},"page":"139-147","publisher":"[Nordic Society Oikos, Wiley]","source":"JSTOR","title":"Effects of Cognitive Abilities on Metapopulation Connectivity","type":"article-journal","URL":"https://www.jstor.org/stable/3548543","volume":"113"}, + {"id":"wangDispersalGlanvilleFritillary2011","abstract":"1. Habitat fragmentation may lead to natural selection on dispersal rate and other life-history traits. Both theoretical analyses and empirical studies suggest that habitat fragmentation may select either for increased or decreased dispersal depending on the traits of the species and the characteristics of the landscape. 2. Dispersal and movement rates in Glanville fritillary butterflies (Melitaea cinxia) originating from a continuous landscape in China and from a highly fragmented landscape in Finland were compared using three different methods. 3. The methods included replicated mark-release-recapture (MRR) experiments conducted in the natural environments in China and Finland, tracking with harmonic radar of captive-reared but free-flying butterflies in a common environment in the field, and replicated common garden experiments in a large outdoor population cage. 4. The results were largely consistent, showing that butterflies from the more continuous landscape in China had a lower movement rate than butterflies originating from the fragmented landscape in Finland. Butterflies originating from newly-established populations in Finland moved significantly longer distances than butterflies originating from old populations in Finland or from China, demonstrating significant intra-specific variation in dispersal rate in Finland. These results are consistent with model predictions for the Glanville fritillary. 5. The tracking experiment revealed a result that would have been impossible to obtain with MRR experiments: movement rate was influenced by a significant interaction between population origin (China vs. Finland) and ambient air temperature.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Wang","given":"Rongjiang"},{"family":"Ovaskainen","given":"Otso"},{"family":"Cao","given":"Yundong"},{"family":"Chen","given":"Houqiang"},{"family":"Zhou","given":"Yan"},{"family":"Xu","given":"Chongren"},{"family":"Hanski","given":"Ilkka"}],"container-title":"Ecological Entomology","DOI":"10.1111/j.1365-2311.2011.01267.x","ISSN":"1365-2311","issue":"2","issued":{"date-parts":[[2011]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1365-2311.2011.01267.x","page":"251-260","source":"Wiley Online Library","title":"Dispersal in the Glanville fritillary butterfly in fragmented versus continuous landscapes: comparison between three methods","title-short":"Dispersal in the Glanville fritillary butterfly in fragmented versus continuous landscapes","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2311.2011.01267.x","volume":"36"}, + {"id":"warrenRapidResponsesBritish2001","abstract":"Habitat degradation and climate change are thought to be altering the distributions and abundances of animals and plants throughout the world, but their combined impacts have not been assessed for any species assemblage1,2,3,4. Here we evaluated changes in the distribution sizes and abundances of 46 species of butterflies that approach their northern climatic range margins in Britain—where changes in climate and habitat are opposing forces. These insects might be expected to have responded positively to climate warming over the past 30 years, yet three-quarters of them declined: negative responses to habitat loss have outweighed positive responses to climate warming. Half of the species that were mobile and habitat generalists increased their distribution sites over this period (consistent with a climate explanation), whereas the other generalists and 89% of the habitat specialists declined in distribution size (consistent with habitat limitation). Changes in population abundances closely matched changes in distributions. The dual forces of habitat modification and climate change are likely to cause specialists to decline, leaving biological communities with reduced numbers of species and dominated by mobile and widespread habitat generalists.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Warren","given":"M. S."},{"family":"Hill","given":"J. K."},{"family":"Thomas","given":"J. A."},{"family":"Asher","given":"J."},{"family":"Fox","given":"R."},{"family":"Huntley","given":"B."},{"family":"Roy","given":"D. B."},{"family":"Telfer","given":"M. G."},{"family":"Jeffcoate","given":"S."},{"family":"Harding","given":"P."},{"family":"Jeffcoate","given":"G."},{"family":"Willis","given":"S. G."},{"family":"Greatorex-Davies","given":"J. N."},{"family":"Moss","given":"D."},{"family":"Thomas","given":"C. D."}],"container-title":"Nature","DOI":"10.1038/35102054","ISSN":"1476-4687","issue":"6859","issued":{"date-parts":[[2001,11]]},"language":"en","note":"Bandiera_abtest: a\nCg_type: Nature Research Journals\nPrimary_atype: Research","number":"6859","page":"65-69","publisher":"Nature Publishing Group","source":"www.nature.com","title":"Rapid responses of British butterflies to opposing forces of climate and habitat change","type":"article-journal","URL":"https://www.nature.com/articles/35102054","volume":"414"}, + {"id":"wattsTargetingEvaluatingBiodiversity2010","abstract":"The focus of biodiversity conservation is shifting to larger spatial scales in response to habitat fragmentation and the need to integrate multiple landscape objectives. Conservation strategies increasingly incorporate measures to combat fragmentation such as ecological networks. These are often based on assessment of landscape structure but such approaches fail to capitalise on the potential offered by more ecologically robust assessments of landscape function and connectivity. In this paper, we describe a modelling approach to identifying functional habitat networks and demonstrate its application to a fragmented landscape where policy initiatives seek to improve conditions for woodland biodiversity including increasing woodland cover. Functional habitat networks were defined by identifying suitable habitat and by modelling connectivity using least-cost approaches to account for matrix permeability. Generic focal species (GFS) profiles were developed, in consultation with stakeholders, to represent species with high and moderate sensitivity to fragmentation. We demonstrated how this form of analysis can be used to aid the spatial targeting of conservation actions. This ‘targeted’ action scenario was tested for effectiveness against comparable scenarios, which were based on random and clumped actions within the same landscape. We tested effectiveness using structural metrics, network-based metrics and a published functional connectivity indicator. Targeting actions within networks resulted in the highest mean woodland area and highest connectivity indicator value. Our approach provides an assessment of landscape function by recognising the importance of the landscape matrix. It provides a framework for the targeting and evaluation of alternative conservation options, offering a pragmatic, ecologically-robust solution to a current need in applied landscape ecology.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Watts","given":"Kevin"},{"family":"Eycott","given":"Amy E."},{"family":"Handley","given":"Phillip"},{"family":"Ray","given":"Duncan"},{"family":"Humphrey","given":"Jonathan W."},{"family":"Quine","given":"Christopher P."}],"container-title":"Landscape Ecology","container-title-short":"Landscape Ecol","DOI":"10.1007/s10980-010-9507-9","ISSN":"1572-9761","issue":"9","issued":{"date-parts":[[2010,11,1]]},"language":"en","page":"1305-1318","source":"Springer Link","title":"Targeting and evaluating biodiversity conservation action within fragmented landscapes: an approach based on generic focal species and least-cost networks","title-short":"Targeting and evaluating biodiversity conservation action within fragmented landscapes","type":"article-journal","URL":"https://doi.org/10.1007/s10980-010-9507-9","volume":"25"}, + {"id":"weeksAssessingBenefitsRisks2011","abstract":"Translocations are being increasingly proposed as a way of conserving biodiversity, particularly in the management of threatened and keystone species, with the aims of maintaining biodiversity and ecosystem function under the combined pressures of habitat fragmentation and climate change. Evolutionary genetic considerations should be an important part of translocation strategies, but there is often confusion about concepts and goals. Here, we provide a classification of translocations based on specific genetic goals for both threatened species and ecological restoration, separating targets based on ‘genetic rescue’ of current population fitness from those focused on maintaining adaptive potential. We then provide a framework for assessing the genetic benefits and risks associated with translocations and provide guidelines for managers focused on conserving biodiversity and evolutionary processes. Case studies are developed to illustrate the framework.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Weeks","given":"Andrew R"},{"family":"Sgro","given":"Carla M"},{"family":"Young","given":"Andrew G"},{"family":"Frankham","given":"Richard"},{"family":"Mitchell","given":"Nicki J"},{"family":"Miller","given":"Kim A"},{"family":"Byrne","given":"Margaret"},{"family":"Coates","given":"David J"},{"family":"Eldridge","given":"Mark D B"},{"family":"Sunnucks","given":"Paul"},{"family":"Breed","given":"Martin F"},{"family":"James","given":"Elizabeth A"},{"family":"Hoffmann","given":"Ary A"}],"container-title":"Evolutionary Applications","container-title-short":"Evol Appl","DOI":"10.1111/j.1752-4571.2011.00192.x","ISSN":"1752-4571","issue":"6","issued":{"date-parts":[[2011,11]]},"page":"709-725","PMCID":"PMC3265713","PMID":"22287981","source":"PubMed Central","title":"Assessing the benefits and risks of translocations in changing environments: a genetic perspective","title-short":"Assessing the benefits and risks of translocations in changing environments","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3265713/","volume":"4"}, + {"id":"wiegandEffectsHabitatLoss2005","abstract":"We used a spatially explicit population model that was generalized to produce nine ecological profiles of long-lived species with stable home ranges and natal dispersal to investigate the effects of habitat loss and fragmentation on population dynamics. We simulated population dynamics in landscapes composed of three habitat types (good-quality habitat ranging from 10-25%, poor-quality habitat ranging from 10-70%, and matrix). Landscape structures varied from highly fragmented to completely contiguous. The specific aims of our model were (1) to investigate under which biological circumstances the traditional approach of using two types only (habitat and matrix) failed and assess the potential impact of restoring matrix to poor-quality habitat, (2) to investigate how much of the variation in population size was explained by landscape composition alone and which key attributes of landscape structure can serve as predictors of population response, and (3) to estimate the maximum fragmentation effects expressed in equivalent pure loss of good-quality habitat. Poor-quality habitat mattered most in situations when it was generally not considered (i.e., for metapopulations or spatially structured populations when it provides dispersal habitat). Population size increased up to 3 times after restoring matrix to poor-quality habitat. Overall, habitat amount accounted for 68%) of the variation in population size, whereas ecological profile and fragmentation accounted for approximately 13%> each. The maximal effect of (good-quality) habitat fragmentation was equivalent to a pure loss of up to 15%> of good-quality habitat, and the maximal loss of individuals resulting from maximal fragmentation reached 80%. Abundant dispersal habitat and sufficiently large dispersal potential, however, resulted in functionally connected landscapes, and maximal fragmentation had no effect at all. Our findings suggest that predicting fragmentation effects requires a good understanding of the biology and habitat use of the species in question and that the uniqueness of species and the landscapes in which they live confound simple analysis.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Wiegand","given":"Thorsten"},{"family":"Revilla","given":"Eloy"},{"family":"Moloney","given":"Kirk A."}],"container-title":"Conservation Biology","ISSN":"0888-8892","issue":"1","issued":{"date-parts":[[2005]]},"page":"108-121","publisher":"[Wiley, Society for Conservation Biology]","source":"JSTOR","title":"Effects of Habitat Loss and Fragmentation on Population Dynamics","type":"article-journal","URL":"https://www.jstor.org/stable/3591014","volume":"19"}, + {"id":"willisAssistedColonizationChanging2009","abstract":"Recent climatic change in temperate regions has been rapid and there is mounting speculation that species are failing to keep track of suitable climate, perhaps necessitating assisted colonization for some species. An inability to spread into new areas may result in large reductions in species’ ranges in the future, and threaten the survival of some species. Here we use “species-climate” models to predict suitable sites for introductions beyond current range margins, using two U.K. butterfly species. We introduced Melanargia galathea (marbled white) and Thymelicus sylvestris (small skipper) into two sites in northern England, ∼65 and ∼35 km beyond their then-range margins, respectively, to sites that were predicted to be climatically suitable and that appeared to contain suitable habitat for the species. Both introduced populations grew and expanded their range over 6 years (2001–2006; still thriving in 2008), suggesting the existence of a colonization lag and providing evidence that well-planned assisted colonization can be successful. We suggest that assisted colonization may be a feasible and cost-effective means of enabling certain species to track climatic change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Willis","given":"Stephen G."},{"family":"Hill","given":"Jane K."},{"family":"Thomas","given":"Chris D."},{"family":"Roy","given":"David B."},{"family":"Fox","given":"Richard"},{"family":"Blakeley","given":"David S."},{"family":"Huntley","given":"Brian"}],"container-title":"Conservation Letters","DOI":"10.1111/j.1755-263X.2008.00043.x","ISSN":"1755-263X","issue":"1","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://conbio.onlinelibrary.wiley.com/doi/pdf/10.1111/j.1755-263X.2008.00043.x","page":"46-52","source":"Wiley Online Library","title":"Assisted colonization in a changing climate: a test-study using two U.K. butterflies","title-short":"Assisted colonization in a changing climate","type":"article-journal","URL":"https://conbio.onlinelibrary.wiley.com/doi/abs/10.1111/j.1755-263X.2008.00043.x","volume":"2"}, + {"id":"willisDynamicDistributionModelling2009","abstract":"Confidence in projections of the future distributions of species requires demonstration that recently-observed changes could have been predicted adequately. Here we use a dynamic model framework to demonstrate that recently-observed changes at the expanding northern boundaries of three British butterfly species can be predicted with good accuracy. Previous work established that the distributions of the study species currently lag behind climate change, and so we presumed that climate is not currently a major constraint at the northern range margins of our study species. We predicted 1970–2000 distribution changes using a colonisation model, MIGRATE, superimposed on a high-resolution map of habitat availability. Thirty-year rates and patterns of distribution change could be accurately predicted for each species (κ goodness-of-fit of models >0.64 for all three species, corresponding to >83% of grid cells correctly assigned), using a combination of individual species traits, species-specific habitat associations and distance-dependent dispersal. Sensitivity analyses showed that population productivity was the most important determinant of the rate of distribution expansion (variation in dispersal rate was not studied because the species are thought to be similar in dispersal capacity), and that each species’ distribution prior to expansion was critical in determining the spatial pattern of the current distribution. In future, modelling approaches that combine climate suitability and spatially-explicit population models, incorporating demographic variables and habitat availability, are likely to be valuable tools in projecting species’ responses to climatic change and hence in anticipating management to facilitate species’ dispersal and persistence.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Willis","given":"Stephen G."},{"family":"Thomas","given":"Chris D."},{"family":"Hill","given":"Jane K."},{"family":"Collingham","given":"Yvonne C."},{"family":"Telfer","given":"Mark G."},{"family":"Fox","given":"Richard"},{"family":"Huntley","given":"Brian"}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2008.05711.x","ISSN":"1600-0587","issue":"1","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2008.05711.x","page":"5-12","source":"Wiley Online Library","title":"Dynamic distribution modelling: predicting the present from the past","title-short":"Dynamic distribution modelling","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2008.05711.x","volume":"32"}, + {"id":"wiszRoleBioticInteractions2013","abstract":"Predicting which species will occur together in the future, and where, remains one of the greatest challenges in ecology, and requires a sound understanding of how the abiotic and biotic environments interact with dispersal processes and history across scales. Biotic interactions and their dynamics influence species' relationships to climate, and this also has important implications for predicting future distributions of species. It is already well accepted that biotic interactions shape species' spatial distributions at local spatial extents, but the role of these interactions beyond local extents (e.g. 10 km(2) to global extents) are usually dismissed as unimportant. In this review we consolidate evidence for how biotic interactions shape species distributions beyond local extents and review methods for integrating biotic interactions into species distribution modelling tools. Drawing upon evidence from contemporary and palaeoecological studies of individual species ranges, functional groups, and species richness patterns, we show that biotic interactions have clearly left their mark on species distributions and realised assemblages of species across all spatial extents. We demonstrate this with examples from within and across trophic groups. A range of species distribution modelling tools is available to quantify species environmental relationships and predict species occurrence, such as: (i) integrating pairwise dependencies, (ii) using integrative predictors, and (iii) hybridising species distribution models (SDMs) with dynamic models. These methods have typically only been applied to interacting pairs of species at a single time, require a priori ecological knowledge about which species interact, and due to data paucity must assume that biotic interactions are constant in space and time. To better inform the future development of these models across spatial scales, we call for accelerated collection of spatially and temporally explicit species data. Ideally, these data should be sampled to reflect variation in the underlying environment across large spatial extents, and at fine spatial resolution. Simplified ecosystems where there are relatively few interacting species and sometimes a wealth of existing ecosystem monitoring data (e.g. arctic, alpine or island habitats) offer settings where the development of modelling tools that account for biotic interactions may be less difficult than elsewhere.","author":[{"family":"Wisz","given":"Mary Susanne"},{"family":"Pottier","given":"Julien"},{"family":"Kissling","given":"W. Daniel"},{"family":"Pellissier","given":"Loïc"},{"family":"Lenoir","given":"Jonathan"},{"family":"Damgaard","given":"Christian F."},{"family":"Dormann","given":"Carsten F."},{"family":"Forchhammer","given":"Mads C."},{"family":"Grytnes","given":"John-Arvid"},{"family":"Guisan","given":"Antoine"},{"family":"Heikkinen","given":"Risto K."},{"family":"Høye","given":"Toke T."},{"family":"Kühn","given":"Ingolf"},{"family":"Luoto","given":"Miska"},{"family":"Maiorano","given":"Luigi"},{"family":"Nilsson","given":"Marie-Charlotte"},{"family":"Normand","given":"Signe"},{"family":"Öckinger","given":"Erik"},{"family":"Schmidt","given":"Niels M."},{"family":"Termansen","given":"Mette"},{"family":"Timmermann","given":"Allan"},{"family":"Wardle","given":"David A."},{"family":"Aastrup","given":"Peter"},{"family":"Svenning","given":"Jens-Christian"}],"container-title":"Biological Reviews of the Cambridge Philosophical Society","container-title-short":"Biol Rev Camb Philos Soc","DOI":"10.1111/j.1469-185X.2012.00235.x","ISSN":"1469-185X","issue":"1","issued":{"date-parts":[[2013,2]]},"language":"eng","page":"15-30","PMCID":"PMC3561684","PMID":"22686347","source":"PubMed","title":"The role of biotic interactions in shaping distributions and realised assemblages of species: implications for species distribution modelling","title-short":"The role of biotic interactions in shaping distributions and realised assemblages of species","type":"article-journal","volume":"88"}, + {"id":"withApplicationNeutralLandscape1997","abstract":"Neutral landscape models, derived from percolation theory in the field of landscape ecology, are grid-based maps in which complex habitat distributions are generated by random or fractal algorithms. This grid-based representation of landscape structure is compatible with the raster-based format of geographical information systems (GIS), which facilitates comparisons between theoretical and real landscapes. Neutral landscape models permit the identification of critical thresholds in connectivity, which can be used to predict when landscapes will become fragmented. The coupling of neutral landscape models with generalized population models, such as metapopulation theory, provides a null model for generating predictions about population dynamics in fragmented landscapes. Neutral landscape models can contribute to the following applications in conservation: (1) incorporation of complex spatial patterns in (meta)population models; (2) identification of species' perceptions of landscape structure; (3) determination of landscape connectivity; (4) evaluation of the consequences of habitat fragmentation for population subdivision; (5) identification of the domain of metapopulation dynamics; (6) prediction of the occurrence of extinction thresholds; (7) determination of the genetic consequences of habitat fragmentation; and (8) reserve design and ecosystem management. This generalized, spatially explicit framework bridges the gap between spatially implicit, patch-based models and spatially realistic GIS applications which are usually parameterized for a single species in a specific landscape. Development of a generalized, spatially explicit framework is essential in conservation biology because we will not be able to develop individual models for every species of management concern.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"With","given":"Kimberly A."}],"container-title":"Conservation Biology","ISSN":"0888-8892","issue":"5","issued":{"date-parts":[[1997]]},"page":"1069-1080","publisher":"[Wiley, Society for Conservation Biology]","source":"JSTOR","title":"The Application of Neutral Landscape Models in Conservation Biology","type":"article-journal","URL":"https://www.jstor.org/stable/2387389","volume":"11"}, + {"id":"withExtinctionThresholdsSpecies1999","abstract":"Abstract: Predicting species’ responses to habitat loss and fragmentation is one of the greatest challenges facing conservation biologists, particularly if extinction is a threshold phenomenon. Extinction thresholds are abrupt declines in the patch occupancy of a metapopulation across a narrow range of habitat loss. Metapopulation-type models have been used to predict extinction thresholds for endangered populations. These models often make simplifying assumptions about the distribution of habitat (random) and the search for suitable habitat sites (random dispersal). We relaxed these two assumptions in a modeling approach that combines a metapopulation model with neutral landscape models of fractal habitat distributions. Dispersal success for suitable, unoccupied sites was higher on fractal landscapes for nearest-neighbor dispersers (moving through adjacent cells of the landscape) than for dispersers searching at random (random distance and direction between steps) on random landscapes. Consequently, species either did not suffer extinction thresholds or extinction thresholds occurred later, at lower levels of habitat abundance, than predicted previously. The exception is for species with limited demographic potential, owing to low reproductive output , in which extinction thresholds occurred sooner than on random landscapes in all but the most clumped fractal landscapes . Furthermore, the threshold was more precipitous for these species. Many species of conservation concern have limited demographic potential, and these species may be at greater risk from habitat loss and fragmentation than previously suspected.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"With","given":"Kimberly A."},{"family":"King","given":"Anthony W."}],"container-title":"Conservation Biology","DOI":"10.1046/j.1523-1739.1999.013002314.x","ISSN":"1523-1739","issue":"2","issued":{"date-parts":[[1999]]},"language":"en","note":"_eprint: https://conbio.onlinelibrary.wiley.com/doi/pdf/10.1046/j.1523-1739.1999.013002314.x","page":"314-326","source":"Wiley Online Library","title":"Extinction Thresholds for Species in Fractal Landscapes","type":"article-journal","URL":"https://conbio.onlinelibrary.wiley.com/doi/abs/10.1046/j.1523-1739.1999.013002314.x","volume":"13"}, + {"id":"zhengModellingDispersalDiffusion2009a","abstract":"Quantifying dispersal is crucial both for understanding ecological population dynamics, and for gaining insight into factors that affect the genetic structure of populations. The role of dispersal becomes pronounced in highly fragmented landscapes inhabited by spatially structured populations. We consider a landscape consisting of a set of habitat patches surrounded by unsuitable matrix, and model dispersal by assuming that the individuals follow a random walk with parameters that may be specific to the habitat type. We allow for spatial variation in patch quality, and account for edge-mediated behavior, the latter meaning that the individuals bias their movement towards the patches when close to an edge between a patch and the matrix. We employ a diffusion approximation of the random walk model to derive analytical expressions for various characteristics of the dispersal process. For example, we derive formulae for the time that an individual is expected to spend in its current patch i, and for the time that it will spend in the matrix, both conditional on the individual hitting next a given patch j before hitting any of the other patches or dying. The analytical formulae are based on the assumptions that the landscape is infinitely large, that the patches are circularly shaped, and that the patches are small compared to interpatch distances. We evaluate the effect of these assumptions by comparing the analytical results to numerical results in a real patch network that violates all of the three assumptions. We then consider a landscape that fulfills the assumptions, and show that in this case the analytical results are in a very good agreement with the numerical results. The results obtained here allow the construction of computationally efficient dispersal models that can be used as components of metapopulation models.","accessed":{"date-parts":[[2021,8,10]]},"author":[{"family":"Zheng","given":"Chaozhi"},{"family":"Pennanen","given":"Juho"},{"family":"Ovaskainen","given":"Otso"}],"container-title":"Ecological Modelling","container-title-short":"Ecological Modelling","DOI":"10.1016/j.ecolmodel.2009.02.024","ISSN":"0304-3800","issue":"12","issued":{"date-parts":[[2009,6,24]]},"language":"en","page":"1495-1505","source":"ScienceDirect","title":"Modelling dispersal with diffusion and habitat selection: Analytical results for highly fragmented landscapes","title-short":"Modelling dispersal with diffusion and habitat selection","type":"article-journal","URL":"https://www.sciencedirect.com/science/article/pii/S0304380009001203","volume":"220"}, + {"id":"zhengModellingSingleNucleotide2009","abstract":"Dispersal comprises a complex life-history syndrome that influences the demographic dynamics of especially those species that live in fragmented landscapes, the structure of which may in turn be expected to impose selection on dispersal. We have constructed an individual-based evolutionary sexual model of dispersal for species occurring as metapopulations in habitat patch networks. The model assumes correlated random walk dispersal with edge-mediated behaviour (habitat selection) and spatially correlated stochastic local dynamics. The model is parametrized with extensive data for the Glanville fritillary butterfly. Based on empirical results for a single nucleotide polymorphism (SNP) in the phosphoglucose isomerase (Pgi) gene, we assume that dispersal rate in the landscape matrix, fecundity and survival are affected by a locus with two alleles, A and C, individuals with the C allele being more mobile. The model was successfully tested with two independent empirical datasets on spatial variation in Pgi allele frequency. First, at the level of local populations, the frequency of the C allele is the highest in newly established isolated populations and the lowest in old isolated populations. Second, at the level of sub-networks with dissimilar numbers and connectivities of patches, the frequency of C increases with decreasing network size and hence with decreasing average metapopulation size. The frequency of C is the highest in landscapes where local extinction risk is high and where there are abundant opportunities to establish new populations. Our results indicate that the strength of the coupling of the ecological and evolutionary dynamics depends on the spatial scale and is asymmetric, demographic dynamics having a greater immediate impact on genetic dynamics than vice versa.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Zheng","given":"Chaozhi"},{"family":"Ovaskainen","given":"Otso"},{"family":"Hanski","given":"Ilkka"}],"container-title":"Philosophical Transactions of the Royal Society B: Biological Sciences","container-title-short":"Philos Trans R Soc Lond B Biol Sci","DOI":"10.1098/rstb.2009.0005","ISSN":"0962-8436","issue":"1523","issued":{"date-parts":[[2009,6,12]]},"page":"1519-1532","PMCID":"PMC2690501","PMID":"19414467","source":"PubMed Central","title":"Modelling single nucleotide effects in phosphoglucose isomerase on dispersal in the Glanville fritillary butterfly: coupling of ecological and evolutionary dynamics","title-short":"Modelling single nucleotide effects in phosphoglucose isomerase on dispersal in the Glanville fritillary butterfly","type":"article-journal","URL":"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2690501/","volume":"364"}, + {"id":"zollnerBehavioralTradeoffsWhen2005","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Zollner","given":"Patrick A."},{"family":"Lima","given":"Steven L."}],"container-title":"OIKOS","issued":{"date-parts":[[2005]]},"language":"en","page":"219-230","source":"www.fs.usda.gov","title":"Behavioral tradeoffs when dispersing across a patchy landscape.","type":"article-journal","URL":"https://www.fs.usda.gov/treesearch/pubs/12821","volume":"108"}, + {"id":"zollnerLandscapelevelPerceptualAbilities1997","abstract":"We define perceptual range as the distance from which an animal can perceive key landscape elements, such as distant patches of forested habitat. We argue that perceptual range should be a determinant of not only dispersal success in unfamiliar or hostile landscapes, but also of several landscape-level ecological processes influencing population dynamics. To redress the absence of empirical information on perceptual ranges, we simulated the dispersal of forest-dwelling white-footed mice (Peromyscus leucopus) across an agricultural landscape by releasing mice into unfamiliar, hostile agricultural habitat at various distances from fragments of forested habitat. We found that these forest mice have a remarkably low perceptual range with regard to detecting their forested (core) habitat. Mice released into bare fields failed to even orient towards forested habitat as little as 30 m distant, while mice in crop fields appeared unable to locate forest habitat as little as 10 m distant. These mice seemed to locate forested habitat by vision, despite the availability of non-visual cues. Future work will undoubtedly demonstrate vast differences in landscape-level perceptual abilities among animals, and show clearly that the ecological effects of a given landscape configuration will be influenced by the behavioral attributes of the species in question.","author":[{"family":"Zollner","given":"P."},{"family":"Lima","given":"S. L."}],"container-title":"Oikos","DOI":"10.2307/3546515","issue":"1","issued":{"date-parts":[[1997]]},"page":"51-60","source":"Semantic Scholar","title":"Landscape-level perceptual abilities in white-footed mice : perceptual range and the detection of forested habitat","title-short":"Landscape-level perceptual abilities in white-footed mice","type":"article-journal","volume":"80"}, + {"id":"zollnerSearchStrategiesLandscapeLevel1999","abstract":"Ecologists need a better understanding of how animals make decisions about moving across landscapes. To this end, we developed computer simulations that contrast the effectiveness of various search strategies at finding habitat patches in idealized landscapes (uniform, random, or clumped patches), where searchers have different energy reserves and face different mortality risks. Nearly straight correlated random walks always produced better dispersal success than relatively uncorrelated random walks. However, increasing patch density decreased the degree of correlation that maximized dispersal success. Only under high mortality and low energy reserves in a uniform landscape did absolutely straight-line search perform better than any random walk. With low mortality risks and high energy reserves, exhaustive systematic search was superior to the best correlated random walk; an increase in the perceptual range of the searcher (i.e., patch detectability) also favored exhaustive search over relatively straight random walks. For all conditions examined, the “average distance rule,” a hybrid search rule incorporating both straight-line and systematic search, was best. Overall, however, our results suggest that a simple and effective search rule for many landscape-explicit models would involve straight or nearly straight movements.","accessed":{"date-parts":[[2021,8,10]]},"author":[{"family":"Zollner","given":"Patrick"},{"family":"Lima","given":"Steven L."}],"container-title":"Ecology","DOI":"10.1890/0012-9658(1999)080[1019:SSFLLI]2.0.CO;2","ISSN":"1939-9170","issue":"3","issued":{"date-parts":[[1999]]},"language":"en","note":"_eprint: https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/0012-9658%281999%29080%5B1019%3ASSFLLI%5D2.0.CO%3B2","page":"1019-1030","source":"Wiley Online Library","title":"Search Strategies for Landscape-Level Interpatch Movements","type":"article-journal","URL":"https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/0012-9658%281999%29080%5B1019%3ASSFLLI%5D2.0.CO%3B2","volume":"80"}, + {"id":"zotero-2098","type":"article-journal"}, + {"id":"zurellStaticSpeciesDistribution2009","abstract":"It is widely acknowledged that species respond to climate change by range shifts. Robust predictions of such changes in species’ distributions are pivotal for conservation planning and policy making, and are thus major challenges in ecological research. Statistical species distribution models (SDMs) have been widely applied in this context, though they remain subject to criticism as they implicitly assume equilibrium, and incorporate neither dispersal, demographic processes nor biotic interactions explicitly. In this study, the effects of transient dynamics and ecological properties and processes on the prediction accuracy of SDMs for climate change projections were tested. A spatially explicit multi-species dynamic population model was built, incorporating species-specific and interspecific ecological processes, environmental stochasticity and climate change. Species distributions were sampled in different scenarios, and SDMs were estimated by applying generalised linear models (GLMs) and boosted regression trees (BRTs). Resulting model performances were related to prevailing ecological processes and temporal dynamics. SDM performance varied for different range dynamics. Prediction accuracies decreased when abrupt range shifts occurred as species were outpaced by the rate of climate change, and increased again when a new equilibrium situation was realised. When ranges contracted, prediction accuracies increased as the absences were predicted well. Far-dispersing species were faster in tracking climate change, and were predicted more accurately by SDMs than short-dispersing species. BRTs mostly outperformed GLMs. The presence of a predator, and the inclusion of its incidence as an environmental predictor, made BRTs and GLMs perform similarly. Results are discussed in light of other studies dealing with effects of ecological traits and processes on SDM performance. Perspectives are given on further advancements of SDMs and for possible interfaces with more mechanistic approaches in order to improve predictions under environmental change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Zurell","given":"Damaris"},{"family":"Jeltsch","given":"Florian"},{"family":"Dormann","given":"Carsten F."},{"family":"Schröder","given":"Boris"}],"container-title":"Ecography","DOI":"10.1111/j.1600-0587.2009.05810.x","ISSN":"1600-0587","issue":"5","issued":{"date-parts":[[2009]]},"language":"en","note":"_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1600-0587.2009.05810.x","page":"733-744","source":"Wiley Online Library","title":"Static species distribution models in dynamically changing systems: how good can predictions really be?","title-short":"Static species distribution models in dynamically changing systems","type":"article-journal","URL":"https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1600-0587.2009.05810.x","volume":"32"}, + {"id":"zurellUncertaintyPredictionsRange2012a","abstract":"Empirical species distribution models (SDMs) constitute often the tool of choice for the assessment of rapid climate change effects on species’ vulnerability. Conclusions regarding extinction risks might be misleading, however, because SDMs do not explicitly incorporate dispersal or other demographic processes. Here, we supplement SDMs with a dynamic population model 1) to predict climate‐induced range dynamics for black grouse in Switzerland, 2) to compare direct and indirect measures of extinction risks, and 3) to quantify uncertainty in predictions as well as the sources of that uncertainty. To this end, we linked models of habitat suitability to a spatially explicit, individual‐based model. In an extensive sensitivity analysis, we quantified uncertainty in various model outputs introduced by different SDM algorithms, by different climate scenarios and by demographic model parameters. Potentially suitable habitats were predicted to shift uphill and eastwards. By the end of the 21st century, abrupt habitat losses were predicted in the western Prealps for some climate scenarios. In contrast, population size and occupied area were primarily controlled by currently negative population growth and gradually declined from the beginning of the century across all climate scenarios and SDM algorithms. However, predictions of population dynamic features were highly variable across simulations. Results indicate that inferring extinction probabilities simply from the quantity of suitable habitat may underestimate extinction risks because this may ignore important interactions between life history traits and available habitat. Also, in dynamic range predictions uncertainty in SDM algorithms and climate scenarios can become secondary to uncertainty in dynamic model components. Our study emphasises the need for principal evaluation tools like sensitivity analysis in order to assess uncertainty and robustness in dynamic range predictions. A more direct benefit of such robustness analysis is an improved mechanistic understanding of dynamic species’ responses to climate change.","accessed":{"date-parts":[[2021,8,9]]},"author":[{"family":"Zurell","given":"Damaris"},{"family":"Grimm","given":"Volker"},{"family":"Rossmanith","given":"Eva"},{"family":"Zbinden","given":"Niklaus"},{"family":"Zimmermann","given":"Niklaus E."},{"family":"Schröder","given":"Boris"}],"ISSN":"0906-7590","issued":{"date-parts":[[2012]]},"language":"en","source":"pubag.nal.usda.gov","title":"Uncertainty in predictions of range dynamics: black grouse climbing the Swiss Alps","title-short":"Uncertainty in predictions of range dynamics","type":"article-journal","URL":"https://pubag.nal.usda.gov/catalog/517524"} +] diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.pdf b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.pdf new file mode 100644 index 0000000..e4d893d Binary files /dev/null and b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.pdf differ diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.png b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.png new file mode 100644 index 0000000..9a2c4fd Binary files /dev/null and b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.png differ diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.svg b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.svg new file mode 100644 index 0000000..f1fb167 --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_big.svg @@ -0,0 +1,1117 @@ + + + + + + + + + + + + + + + + + + Species' + + +distribution map + + + + Species'distribution map + + + + + + + + + + + Landscape map + + + + Landscape map + + + + + + + + + Artificial environ- + + +mental gradient + + + + Artificial environ-mental gradient + + + + + + + + + + + Initialisation + + + + Initialisation + + + + + + + + + + No + + + + No + + + + + + + + + + Yes + + + + Yes + + + + + + + + Gradient  + + +shifting? + + + + + + Gradientshifting? + + + Translocation? + + + + + + + + + Yes + + + + Yes + + + + + + + + + + No + + + + No + + + + + + + + + Shifting + + + + + + Shifting + Translocation + + + + + + + + + + + + Population + + +dynamics + + + + Populationdynamics + + + + + + + + + + + Dispersal + + + + Dispersal + + + + + + + + + Outputs +(Range, populations, individuals, + + +traits, genetic, connectivity matrix, + + +SMS paths) + + + + + Outputs(range, populations, individuals,traits, genetics, connectivity matrix) + + + + + + + + + + + + Reproductive seasons + + + + + Reproductive seasons + + + + + + + + + + + + Years + + + + + Years + + + + + + + + + + + Environmental + + +stochasticity? + + + + Environmentalstochasticity? + + + + No + + Yes + + + + + + + + + + + Environmental + + stochasticity + + + + + Environmentalstochasticity + + + + + + + + Text is not SVG - cannot display + + + diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.pdf b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.pdf new file mode 100644 index 0000000..3413646 Binary files /dev/null and b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.pdf differ diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.png b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.png new file mode 100644 index 0000000..85d91e4 Binary files /dev/null and b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.png differ diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.svg b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.svg new file mode 100644 index 0000000..57677a6 --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/RSflowchart_detail.svg @@ -0,0 +1,1378 @@ + + + + + + + + + + + + + + + + + + + Reproduction + + + + Reproduction + + + + + + + + + + + Emigration + + + + Emigration + + + + + + + + + + + Transfer + + + + Transfer + + + + + + + + + + No + + + + No + + + + + + + + + + Yes + + + + Yes + + + + + + + + + Movement + + +process? + + + + Movementprocess? + + + + + + + + + + + Settlement + + + + Settlement + + + + + + + + + + Yes + + + + Yes + + + + + + + + + Stage-structure & + + +survival between  + + +repr. seasons?  + + + + Stage-structure &survival betweenrepr.seasons? + + + + + + + + + + + Survival & + + +Development + + + + Survival &development + + + + + + + + + + Yes + + + + Yes + + + + + + + + + + + + + Aging + + + + Aging + + + + + + + + Ind. variability / + + +traits evolution? + + + + Ind. variability /traits evolution? + + + + + + + + + Steps + + + + Steps + + + + + + + + + + No + + + + No + + + + + + + + + + No + + + + No + + + + + + + + + + + + Reproductive seasons + + + + + Reproductive seasons + + + + + + + + + + + + Years + + + + + + Years + + + + + + Text is not SVG - cannot display + + + + + + + + + + + + Stage-structure & + + +survival between  + + +repr. seasons?  + + + + Stage-structure &annual survival? + + + + + + + + Survival & + + +Development + + + + Survival &development + + + + + + + + + + + + + + Yes + + + + Yes + + + + + + + + + No + + + + No + + + + + + + + + + + + + + Traits + + +inheritance + + + + Traitinheritance + + + + + + + + Traits + + +mutation + + + + Traitsmutation + + + diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/ecography.csl b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/ecography.csl new file mode 100644 index 0000000..3e4f59e --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/ecography.csl @@ -0,0 +1,17 @@ + + diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/skeleton.Rmd b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/skeleton.Rmd new file mode 100644 index 0000000..5237499 --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/skeleton.Rmd @@ -0,0 +1,945 @@ +--- +title: "ODD protocol" +subtitle: "automatically generated for the study entitled `r params$subtitle`" +output: + md_document: + toc: TRUE + word_document: + reference_docx: style-template.docx + toc: TRUE + rtf_document: + toc: TRUE + pdf_document: + latex_engine: xelatex + toc: TRUE + keep_md: TRUE + keep_tex: TRUE +params: + format: "word" + subtitle: "Your study title here" +bibliography: RS_ODD.json +csl: ecography.csl +--- +`r if(params$format!="md"){" +"}` + + +```{r, echo=FALSE, results='asis'} +if (params$format == "pdf") { + cat("\\newpage\n") +} else if (params$format == "word" || params$format == "rtf") { + cat("\\pagebreak\n") +} else { + cat("
\n") +} +``` + +--- + +# Disclaimer {.unnumbered .unlisted} + +This ODD protocol is derived from the *RangeShifter* user manual written by Greta Bocedi, Stephen C. F. Palmer, and Justin M. J. Travis (published at ). The protocol text describing model structure, processes, and assumptions is therefore authored by the developers of the *RangeShifter* platform, not by the authors of the present case study. + +The ODD protocol was generated automatically from the parameter configuration used in this study and includes only those conceptual options and parameter settings selected by the user. No new model components or mechanisms were introduced beyond those documented in the *RangeShifter* manual. + +--- + +```{r, echo=FALSE, results='asis'} +if (params$format == "pdf") { + cat("\\newpage\n") +} else if (params$format == "word" || params$format == "rtf") { + cat("\\pagebreak\n") +} else { + cat("
\n") +} +``` + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE) + +# global output settings +output_format <- params$format + +# Environmental stochasticity +environmental_stochasticity <- F +env_stoch_loc <- F +env_stoch_K <- F +env_stoch_R <- F + +# Outputs +output_range <- F +output_occ <- F +output_pop <- F +output_ind <- F +output_conn <- F +output_paths <- F +output_heatmaps <-F + +# landscape parameters +local_ext_prob <- F +arti_land <- F +arti_land_continuous <- F +real_land <- F +cell_based <- FALSE +patch_based <- F +habitat_type <- FALSE +habitat_quality <- F +dynamic_landscape <- F +resolution <- "" + +#population dynamics +stage_structured <- F +sexual <- F +only_female <- F +asexual <- F +rep_seasons <- 1 +rep_interval <- 0 +mating_simple <- F +mating_complex <- F +demography_sexdep <- F +repro_densdep <- F +repro_stagedep <- F +survival_densdep <- F +survival_stagedep <- F +survival_schedule <- 1 +develop_densdep <- F +develop_stagedep <- F + +# transfer TODO: check ups, e.g. if SMS T -> movement_model T +dispersal_kernel <- F +dispersal_kernel_simple <- F +dispersal_kernel_mixed <- F +movement_sexdep <- F +movement_stagedep <- F +movement_model <- F +movement_SMS <- F +movement_corrRW <- F +movement_cost <- F +movement_cost_file <- F +movement_SMS_PRmethod <- 0 +goal_type <- 0 + +# settlement +max_steps <- F +min_steps <- F +step_mortality <- F +mate_finding <- F +maleFindMate <- F +femaleFindMate <- F +settlement_densdep <- F +settlement_stagedep <- F +settlement_sexdep <- F + +# emigration +emigration_densdep <- F +emigration_sexdep <- F +emigration_stagedep <- F + +# management +management <- F +translocation <- F +``` + +```{r, echo =FALSE} +# environmental stochasticity +if(s@simul@EnvStoch==0) environmental_stochasticity <- F +if(s@simul@EnvStoch==1) {environmental_stochasticity <- T; env_stoch_loc <- F} +if(s@simul@EnvStoch==2) {environmental_stochasticity <- T; env_stoch_loc <- T} +if(s@simul@EnvStochType==0) {env_stoch_R <- T; env_stoch_K <- F} +if(s@simul@EnvStochType==1) {env_stoch_R <- F; env_stoch_K <- T} + +# outputs +if(s@simul@OutIntRange>=1) output_range <- T +if(s@simul@OutIntOcc>=1) output_occ <- T +if(s@simul@OutIntPop>=1) output_pop <- T +if(s@simul@OutIntInd>=1) output_ind <- T +if(s@simul@OutIntConn>=1) output_conn <- T +if(s@simul@OutIntPaths>=1) output_paths <- T +if(s@simul@SMSHeatMap>=1) output_heatmaps <- T + +# landscape +if(class(s@land)=="ArtificialLandscape") { + arti_land <- T + if (s@land@continuous) arti_land_continuous <- T + } +if(class(s@land)=="ImportedLandscape") real_land <- T +if(class(s@land)=="ImportedLandscape" & length(s@land@DynamicLandYears)>1) dynamic_landscape <- T +if(length(s@land@PatchFile)==0) cell_based <- T +if(length(s@land@PatchFile)!=0) patch_based <- T +if(s@land@HabPercent) habitat_quality <- T else habitat_type <- T +if(s@simul@LocalExt) local_ext_prob <- T + +resolution <- paste(s@land@Resolution, "m x ", s@land@Resolution,"m", sep="") + +# demography +if(s@demog@ReproductionType==0) {asexual <- T; only_female <- T} +if(s@demog@ReproductionType==1) {sexual <- T; mating_simple <- T} +if(s@demog@ReproductionType==2) {sexual <- T; mating_complex <- T} +if(s@demog@Rmax<0){ + stage_structured <- T + survival_schedule <- s@demog@StageStruct@SurvSched + rep_seasons <- s@demog@StageStruct@RepSeasons + rep_interval <- s@demog@StageStruct@RepInterval + if(s@demog@StageStruct@FecDensDep) repro_densdep <- T + if(s@demog@StageStruct@SurvDensDep) survival_densdep <- T + if(s@demog@StageStruct@DevDensDep) develop_densdep <- T + if(s@demog@StageStruct@FecStageWts) repro_stagedep <- T + if(s@demog@StageStruct@SurvStageWts) survival_stagedep <- T + if(s@demog@StageStruct@DevStageWts) develop_stagedep <- T +} + +# dispersal +# emigration +if(s@dispersal@Emigration@DensDep) emigration_densdep <- T +if(s@dispersal@Emigration@SexDep) emigration_sexdep <- T +if(s@dispersal@Emigration@StageDep) emigration_stagedep <- T + +# transfer +if(class(s@dispersal@Transfer)=="DispersalKernel") { + dispersal_kernel <- T + if(s@dispersal@Transfer@DoubleKernel) {dispersal_kernel_mixed <- T} else {dispersal_kernel_simple <- T} + if(s@dispersal@Transfer@SexDep) movement_sexdep <- T + if(s@dispersal@Transfer@StageDep) movement_stagedep <- T +} +if(class(s@dispersal@Transfer)=="CorrRW") { + movement_model <- T + movement_corrRW <- T + if(length(s@dispersal@Transfer@StepMort)>1){ + step_mortality <- T + } else if (s@dispersal@Transfer@StepMort>0){ + step_mortality <- T + } + if(any(s@dispersal@Settlement@MinSteps>0)) min_steps <- T + if(any(s@dispersal@Settlement@MaxSteps>0)) max_steps <- T +} + +if(class(s@dispersal@Transfer)=="StochMove"){ + movement_model <- T + movement_SMS <- T + goal_type <- s@dispersal@Transfer@GoalType + if(is.numeric(s@dispersal@Transfer@Costs)){ + if(sum(s@dispersal@Transfer@Costs)>0) movement_cost <- T + } + if(!is.null(s@land@CostsFile) || length(s@land@CostsMatrix)>0) {movement_cost_file <- T; movement_cost <- T} + if(length(s@dispersal@Transfer@StepMort)>1){ + step_mortality <- T + } else if (s@dispersal@Transfer@StepMort>0){ + step_mortality <- T + } + movement_SMS_PRmethod <- s@dispersal@Transfer@PRMethod + if(s@dispersal@Settlement@MinSteps>0) min_steps <- T + if(s@dispersal@Settlement@MaxSteps>0) max_steps <- T +} + +# settlement +if(s@dispersal@Settlement@DensDep) settlement_densdep <- T +if(s@dispersal@Settlement@SexDep) settlement_sexdep <- T +if(s@dispersal@Settlement@StageDep) settlement_stagedep <- T +if(any(s@dispersal@Settlement@FindMate)){ + mate_finding <- T + # check if this is sex dependent, and if so which sex depend on the existence of the other to settle + if(settlement_sexdep){ + # the second column of s@dispersal@Settlement@Settle holds the code for female (0) and male (1), + # the s@dispersal@Settlement@FindMate vector holds the code for whether settlement depends on the presence of mates (TRUE) or not (FALSE) + # I need to check if in any cells where s@dispersal@Settlement@Settle[,2]==1, there is a TRUE in s@dispersal@Settlement@FindMate and if so, set maleFindMate to TRUE + if(any(s@dispersal@Settlement@FindMate[s@dispersal@Settlement@Settle[,2]==1])) { + maleFindMate <- T + } else { + maleFindMate <- F + } + # same for females + if(any(s@dispersal@Settlement@FindMate[s@dispersal@Settlement@Settle[,2]==0])) { + femaleFindMate <- T + } else { + femaleFindMate <- F + } + } +} + +# Management + +if(!is.logical(s@management@Translocation)){ + translocation <- T +} + +if(translocation) management <- T + +# general settings +dispersal_densdep <- if(emigration_densdep | settlement_densdep) T else F +dispersal_sexdep <- if(emigration_sexdep | settlement_sexdep | movement_sexdep) T else F +dispersal_stagedep <- if(emigration_stagedep | settlement_stagedep | movement_stagedep) T else F +# genetics? +if(s@dispersal@Emigration@IndVar | s@dispersal@Transfer@IndVar | s@dispersal@Settlement@IndVar | s@gene@Architecture) { + genetics <- T +} else { + genetics <- F +} +``` + + + +# Purpose and patterns + +The RangeShifter model is a single-species, spatially-explicit and stochastic individual-based model (IBM), built around the integration of two fundamental components: population dynamics and dispersal behaviour. +In this specific use case, population dynamics, represented as `r if(stage_structured){"stage-structured, "}` `r if(only_female){"only-female populations, "}` `r if(stage_structured){"with overlapping generations, "}` and dispersal (explicitly modeled in its three phases of emigration, transfer and settlement`r if(dispersal_densdep | dispersal_sexdep | dispersal_stagedep){" accounting for "}``r if(dispersal_densdep & !dispersal_sexdep & !dispersal_stagedep){" context dependency"}``r if(!dispersal_densdep & dispersal_sexdep & !dispersal_stagedep){" sex specificity"}``r if(!dispersal_densdep & !dispersal_sexdep & dispersal_stagedep){" stage specificity"}``r if(!dispersal_densdep & dispersal_sexdep & dispersal_stagedep){" sex and stage specificity"}``r if(dispersal_densdep & !dispersal_sexdep & dispersal_stagedep){" context dependency and stage specificity"}``r if(dispersal_densdep & dispersal_sexdep & !dispersal_stagedep){" context dependency and sex specificity"}``r if(dispersal_densdep & dispersal_sexdep & dispersal_stagedep){" context dependency, sex specificity, and stage specificity"}`) are played out on top of gridded multi-habitat landscape. + +`r if(environmental_stochasticity){"This landscape includes environmental stochasticity."}` + +Individuals are the basic entity of the model. + +# Entities, state variables and scales + +## Individuals + +Individuals are the basic entities of the RangeShifter model. Each individual has a unique ID number and, in this specific use case, is defined by the following state variables: + +* status + +* initial (natal) and current location + +`r if (sexual){"* sex \n"}` +* age `r if(stage_structured){" and stage"}` + +## Populations + +Populations are defined by the individuals occupying `r if (cell_based){"a single cell"}``r if(patch_based){"a single patch"}` and they represent the scale at which individuals interact and density dependencies act. Populations are characterized by their size and location`r if(sexual){" and by the number of individuals of each sex"}``r if(stage_structured){" and the number in each stage class"}`. + +## Landscape units + +The model runs over a grid-based map. +In this specific use case, each cell stores `r if(habitat_type){"a particular land-cover type (which can be breeding habitat for the species or otherwise)"}``r if(habitat_quality){"a habitat quality index"}`. Each cell is defined as suitable or not suitable for a species based on the presence/absence of habitat, and it is characterized by a species’ nature of demographic density dependence. +`r if(environmental_stochasticity & !movement_cost & !local_ext_prob){"An additional state variable is an environmental noise value $\\epsilon$."}` +`r if(!environmental_stochasticity & movement_cost & !local_ext_prob){"An additional state variable is the cost of movement through the cell."}` +`r if(!environmental_stochasticity & !movement_cost & local_ext_prob){"An additional state variable is the local extinction probability."}` +`r if(environmental_stochasticity & movement_cost & !local_ext_prob){"Additional state variables are: an environmental noise value $\\epsilon$, and the cost of movement through the cell."}` +`r if(!environmental_stochasticity & movement_cost & local_ext_prob){"Additional state variables are: the cost of movement through the cell and local extinction probability."}` +`r if(!environmental_stochasticity & !movement_cost & local_ext_prob){"Additional state variables are: an environmental noise value $\\epsilon$ and local extinction probability."}` +`r if(environmental_stochasticity & movement_cost & local_ext_prob){"Additional state variables are:an environmental noise value $\\epsilon$, the cost of movement through the cell and local extinction probability."}` + + +`r if(patch_based){"The model is patch-based. Each patch is a higher-level entity composed of a group of one or more cells (typically adjacent, although that is not a necessary condition). A patch is characterized by a unique ID number, the number of cells that it contains, a list of these cells’ coordinates and its maximum and minimum x and y coordinates. The species’ demographic density dependence is a characteristic of the patch and not of the cell."}` + +## Spatial and temporal scales + +The cell size (resolution) is `r resolution`. +`r if(cell_based){"The cell resolution represents the spatial scale at which the two fundamental processes of population dynamics and dispersal occur. This means that the density dependency in the model"}``r if(cell_based & (repro_densdep | survival_densdep | emigration_densdep | settlement_densdep)){" (on "}``r if(cell_based & repro_densdep & !survival_densdep & !emigration_densdep & !settlement_densdep){" reproduction"}``r if(cell_based & !repro_densdep & survival_densdep & !emigration_densdep & !settlement_densdep){"survival"}``r if(cell_based & !repro_densdep & !survival_densdep & emigration_densdep & !settlement_densdep){"emigration"}``r if(cell_based & !repro_densdep & !survival_densdep & !emigration_densdep & settlement_densdep){"settlement"}``r if(cell_based & repro_densdep & survival_densdep & !emigration_densdep & !settlement_densdep){"reproduction and survival"}``r if(cell_based & repro_densdep & !survival_densdep & emigration_densdep & !settlement_densdep){"reproduction and emigration"}``r if(cell_based & repro_densdep & !survival_densdep & !emigration_densdep & settlement_densdep){"reproduction and settlement"}``r if(cell_based & !repro_densdep & survival_densdep & emigration_densdep & !settlement_densdep){"survival and emigration"}``r if(cell_based & !repro_densdep & survival_densdep & !emigration_densdep & settlement_densdep){"survival and settlement"}``r if(cell_based & !repro_densdep & !survival_densdep & emigration_densdep & settlement_densdep){"emigration and settlement"}``r if(cell_based & repro_densdep & survival_densdep & emigration_densdep & !settlement_densdep){"reproduction, survival and emigration"}``r if(cell_based & repro_densdep & survival_densdep & !emigration_densdep & settlement_densdep){"reproduction, survival and settlement"}``r if(cell_based & repro_densdep & !survival_densdep & emigration_densdep & settlement_densdep){"reproduction, emigration and settlement"}``r if(cell_based & !repro_densdep & survival_densdep & emigration_densdep & settlement_densdep){"survival, emigration and settlement"}``r if(cell_based & repro_densdep & survival_densdep & emigration_densdep & settlement_densdep){"reproduction, survival, emigration and settlement"}``r if(cell_based & (repro_densdep | survival_densdep | emigration_densdep | settlement_densdep)){")"}``r if(cell_based){" acts at the cell scale and the same scale is used as a single step unit for discrete movement models."}``r if(patch_based){"Two spatial scales are simultaneously represented in the patch-based model: the cell scale, which in this case is used just for the transfer phase of dispersal (movements) and the patch scale, at which the density dependencies are acting"}``r if(patch_based & (repro_densdep | survival_densdep | emigration_densdep | settlement_densdep)){" (on "}``r if(patch_based & repro_densdep & !survival_densdep & !emigration_densdep & !settlement_densdep){" reproduction"}``r if(patch_based & !repro_densdep & survival_densdep & !emigration_densdep & !settlement_densdep){"survival"}``r if(patch_based & !repro_densdep & !survival_densdep & emigration_densdep & !settlement_densdep){"emigration"}``r if(patch_based & !repro_densdep & !survival_densdep & !emigration_densdep & settlement_densdep){"settlement"}``r if(patch_based & repro_densdep & survival_densdep & !emigration_densdep & !settlement_densdep){"reproduction and survival"}``r if(patch_based & repro_densdep & !survival_densdep & emigration_densdep & !settlement_densdep){"reproduction and emigration"}``r if(patch_based & repro_densdep & !survival_densdep & !emigration_densdep & settlement_densdep){"reproduction and settlement"}``r if(patch_based & !repro_densdep & survival_densdep & emigration_densdep & !settlement_densdep){"survival and emigration"}``r if(patch_based & !repro_densdep & survival_densdep & !emigration_densdep & settlement_densdep){"survival and settlement"}``r if(patch_based & !repro_densdep & !survival_densdep & emigration_densdep & settlement_densdep){"emigration and settlement "}``r if(patch_based & repro_densdep & survival_densdep & emigration_densdep & !settlement_densdep){"reproduction, survival and emigration"}``r if(patch_based & repro_densdep & survival_densdep & !emigration_densdep & settlement_densdep){"reproduction, survival and settlement"}``r if(patch_based & repro_densdep & !survival_densdep & emigration_densdep & settlement_densdep){"reproduction, emigration and settlement"}``r if(patch_based & !repro_densdep & survival_densdep & emigration_densdep & settlement_densdep){"survival, emigration and settlement"}``r if(patch_based & repro_densdep & survival_densdep & emigration_densdep & settlement_densdep){"reproduction, survival, emigration and settlement"}``r if(patch_based & (repro_densdep | survival_densdep | emigration_densdep | settlement_densdep)){")"}``r if(patch_based){"."}` +There are three distinct temporal scales. The highest-level one has years as units`r if(environmental_stochasticity){" and represents the scale at which variations in the abiotic environment are modeled"}`. The intermediate scale is the species’ reproductive season. The model simulates `r if(rep_seasons==1){"1 reproductive season"} else{cat(rep_seasons, "reproductive seasons")}` per year. `r if(movement_model){"Finally, the smallest time scale is represented by the number of steps that emigrants take during the movement phase of dispersal. This is determined by "}``r if(max_steps & !step_mortality){"the maximum number of steps."}``r if(!max_steps & step_mortality){"the per-step mortality."}``r if(max_steps & step_mortality){"the maximum number of steps and per-step mortality."}` + +\newpage + +# Process overview and scheduling + +![General model workflow and schedule. The settings of this specific use case may not include all available submodules. Only relevant submodules are described in this document. The core of the model highlighted in blue is expanded in the flow chart in Fig. 2](./RSflowchart_big.png){height=60%} + +\newpage + +![General flowchart of the core model. `r if(!genetics){"The settings of this studies' specific use case do not include genetics, i.e. individual variability o trait evolution. "}`Only relevant submodules are described in this document.](./RSflowchart_detail.png){height=60%} + + + +`r if(stage_structured){"At the beginning of each year, reproduction is the first process to be modelled."}` `r if(stage_structured & survival_schedule==0){"Survival and development of all the stages (apart from stage 0) occur simultaneously with reproduction, followed by dispersal and finally survival and development of stage 0. Individuals age at the end of each year."}` `r if(stage_structured & survival_schedule==1){"Reproduction is followed by dispersal. After each reproductive season, survival and successive development of all the stages are modelled. Aging occurs at the end of the year."}` `r if(stage_structured & survival_schedule==2){"Reproduction is followed by dispersal after each reproductive event. Survival and development of all stages happen only at the end of all reproductive seasons, followed by aging at the end of the year."}` + +# Design concepts + +## Basic principles + +`r if(arti_land){"### Fractal landscape + +To generate fractal landscapes, the midpoint displacement algorithm [@saupeAlgorithmsRandomFractals1988] is applied, adapted to allow for the generation of elongated landscapes. This fractal method has proven useful as a null model to investigate population responses to landscape changes such as habitat loss and fragmentation [@withExtinctionThresholdsSpecies1999; @plotnickGeneralModelSimulating2002]. Fractal landscapes are characterized by possessing greater structure than a completely random landscape, but less than a completely deterministic one [@withApplicationNeutralLandscape1997]."}` + +`r if(environmental_stochasticity){"### Environmental stochasticity + +Temporal environmental stochasticity is a ubiquitous and fundamental factor affecting both ecological and evolutionary processes acting at all levels of biological organization, from individuals to ecosystems [@vasseurColorEnvironmentalNoise2004; @ruokolainenEcologicalEvolutionaryDynamics2009]. Importantly, it has been demonstrated to interact with the density dependence of a species’ demography to influence population dynamics profoundly, and, as consequence, extinction risk [@ruokolainenEcologicalEvolutionaryDynamics2009]. In particular, in unstructured populations, red noise (low frequency fluctuations) is predicted to increase extinction risk, especially in a population having under-compensatory dynamics [@ripaNoiseColourRisk1996; @johstExtinctionRiskTemporally1997; @schwagerDoesRedNoise2006; @heinoExtinctionRiskColoured2000a; @greenmanImpactEnvironmentalFluctuations2005; @fowlerConfoundingEnvironmentalColour2013]. This body of theory has focused on local populations, and there has been much less effort devoted to understanding how inter-annual variability influences species’ large-scale responses to climate change. One recent model shows that red noise can increase species’ regional extinction risks under periods of climate change [@mustinRedNoiseIncreases2013]. By incorporating inter-annual variability, RangeShifter provides an ideal platform for generating improved knowledge relating to eco-evolutionary responses to environmental changes in the presence of inter-annual variability. +There is evidence that inter-annual variability in weather is increasing and is expected to increase further and also to redden under climate change [@easterlingClimateExtremesObservations2000; @coumouDecadeWeatherExtremes2012; @hansenPerceptionClimateChange2012]. Despite its importance as a selective pressure and in determining a species’ extinction risk, especially for small fragmented populations already stressed by anthropogenic disturbances, environmental stochasticity has rarely been included in models that try to make predictions regarding species’ future distribution and persistence [@mclaughlinClimateChangeHastens2002; @verboomPopulationDynamicsIncreasing2010]. Please see the submodel description for further details."}` + +### Population dynamics + +Demographic stochasticity is fundamentally important for the dynamics of populations that are naturally small or have declined to low abundances owing to anthropogenic pressures. Additionally, inter-individual variability within populations can have a major influence on dynamics. Modelling stochastic events that happen to individuals is crucial for avoiding systematic overestimation of population viability or rate of spread [@clarkInvasionExtremesPopulation2001; @kendallUnstructuredIndividualVariation2003; @robertVariationIndividualsDemographic2003; @grimmIndividualbasedModelingEcology2005; @jongejansDispersalDemographySpatial2008; @travisImprovingPredictionManagement2011a]. Thus, population dynamics in RangeShifter were constructed to be fully individual-based and stochastic. Each reproductive individual produces a discrete number of offspring sampled from a Poisson distribution with a mean that is influenced by the species’ demographic parameters and the local population density. + +### Definition of populations + +`r if(cell_based){"The cell is the scale at which processes such as population dynamics and dispersal act. The individuals present in a cell define a distinct population, and density-dependencies "}``r if(cell_based & repro_densdep & emigration_densdep & settlement_densdep){"for reproduction, emigration and settlement all "}``r if(cell_based & repro_densdep & emigration_densdep & !settlement_densdep){"for reproduction and emigration both "}``r if(cell_based & repro_densdep & !emigration_densdep & settlement_densdep){"for reproduction and settlement both "}``r if(cell_based & !repro_densdep & emigration_densdep & settlement_densdep){"for emigration and settlement both "}``r if(cell_based & repro_densdep & !emigration_densdep & !settlement_densdep){"for reproduction "}``r if(cell_based & !repro_densdep & emigration_densdep & !settlement_densdep){"for emigration "}``r if(cell_based & !repro_densdep & !emigration_densdep & settlement_densdep){"for settlement "}``r if(cell_based){"operate at this scale. Even in the case where two habitat cells are adjacent, they still hold separate populations. + +A cell-based model provides an excellent abstraction of space for many theoretical studies. +"}` + +`r if(patch_based){"Population dynamics happen at the patch level, a patch being an assemblage of landscape cells of potentially different habitat types or quality. Patches are not defined automatically. Rather, the definition which cells belong to which patch is obtained by an additional patch file, taking into account the ecological understanding of the study species. Density-dependencies "}``r if(patch_based & repro_densdep & emigration_densdep & settlement_densdep & !develop_densdep & !survival_densdep){"regarding reproduction, emigration and settlement "}``r if(patch_based & repro_densdep & emigration_densdep & !settlement_densdep & !develop_densdep & !survival_densdep){"regarding reproduction and emigration "}``r if(patch_based & repro_densdep & !emigration_densdep & settlement_densdep & !develop_densdep & !survival_densdep){"regarding reproduction and settlement "}``r if(patch_based & !repro_densdep & emigration_densdep & settlement_densdep & !develop_densdep & !survival_densdep){"regarding emigration and settlement "}``r if(patch_based & repro_densdep & !emigration_densdep & !settlement_densdep & !develop_densdep & !survival_densdep){"regarding reproduction "}``r if(patch_based & !repro_densdep & emigration_densdep & !settlement_densdep & !develop_densdep & !survival_densdep){"regarding emigration "}``r if(patch_based & !repro_densdep & !emigration_densdep & settlement_densdep & !develop_densdep & !survival_densdep){"regarding settlement "}` + +`r if(patch_based & repro_densdep & emigration_densdep & settlement_densdep & develop_densdep & !survival_densdep){"regarding reproduction, development, emigration and settlement "}``r if(patch_based & repro_densdep & emigration_densdep & settlement_densdep & !develop_densdep & survival_densdep){"regarding reproduction, emigration, settlement and survival "}``r if(patch_based & repro_densdep & emigration_densdep & settlement_densdep & develop_densdep & survival_densdep){"regarding reproduction, development, emigration, settlement and survival "}``r if(patch_based & repro_densdep & emigration_densdep & !settlement_densdep & !develop_densdep & survival_densdep){"regarding reproduction, emigration and survival "}``r if(patch_based & repro_densdep & emigration_densdep & !settlement_densdep & develop_densdep & !survival_densdep){"regarding reproduction, development and emigration "}``r if(patch_based & repro_densdep & emigration_densdep & !settlement_densdep & develop_densdep & survival_densdep){"regarding reproduction, development, emigration and survival "}``r if(patch_based & repro_densdep & !emigration_densdep & settlement_densdep & develop_densdep & !survival_densdep){"regarding reproduction,development and settlement "}``r if(patch_based & repro_densdep & !emigration_densdep & settlement_densdep & !develop_densdep & survival_densdep){"regarding reproduction, settlement and survival "}``r if(patch_based & repro_densdep & !emigration_densdep & settlement_densdep & develop_densdep & survival_densdep){"regarding reproduction, development, settlement and survival "}``r if(patch_based & !repro_densdep & emigration_densdep & settlement_densdep & !develop_densdep & survival_densdep){"regarding development, emigration and settlement "}``r if(patch_based & !repro_densdep & emigration_densdep & settlement_densdep & develop_densdep & !survival_densdep){"regarding emigration, settlement and survival "}``r if(patch_based & !repro_densdep & emigration_densdep & settlement_densdep & develop_densdep & survival_densdep){"regarding development, emigration, settlement and survival "}``r if(patch_based & repro_densdep & !emigration_densdep & !settlement_densdep & !develop_densdep & survival_densdep){"regarding reproduction and survival "}``r if(patch_based & repro_densdep & !emigration_densdep & !settlement_densdep & develop_densdep & !survival_densdep){"regarding reproduction and development "}``r if(patch_based & repro_densdep & !emigration_densdep & !settlement_densdep & develop_densdep & survival_densdep){"regarding reproduction, development and survival "}``r if(patch_based & !repro_densdep & emigration_densdep & !settlement_densdep & !develop_densdep & survival_densdep){"regarding emigration and survival "}``r if(patch_based & !repro_densdep & emigration_densdep & !settlement_densdep & develop_densdep & !survival_densdep){"regarding development and emigration "}``r if(patch_based & !repro_densdep & emigration_densdep & !settlement_densdep & develop_densdep & survival_densdep){"regarding development, emigration and survival "}``r if(patch_based & !repro_densdep & !emigration_densdep & settlement_densdep & !develop_densdep & survival_densdep){"regarding settlement and survival "}``r if(patch_based & !repro_densdep & !emigration_densdep & settlement_densdep & develop_densdep & !survival_densdep){"regarding development and settlement "}``r if(patch_based & !repro_densdep & !emigration_densdep & settlement_densdep & develop_densdep & survival_densdep){"regarding development, settlement and survival "}``r if(patch_based){"will depend on the density of individuals in a patch. However, discrete step-wise movements during the transfer phase will always use the cell as the resolution at which steps occur, thus retaining important information about the landscape heterogeneity. + +The patch-based implementation allows separating the scales used for population dynamics and movements. In this case, the landscape can be modelled at very fine resolution in order to capture the features that are likely to influence movements without constraining the local population dynamics to operate at too small a scale."}` + +`r if(!stage_structured){"### Population structure + +Implementing non-overlapping generations which are not stage-structured is the appropriate way to model species that have discrete generations. At each generation the life cycle comprises: reproduction, death of the adults and offspring dispersal (in that order). These discrete generation models can be applied to asexual species, species for which it is assumed that females play the dominant role in spatial dynamics and for species for which it is considered crucial to model both sexes explicitly."}` + +`r if(stage_structured){"### Population structure + +Implementing overlapping generations which are stage-structured is the appropriate choice for species in which generations can overlap and individuals can be classified in different stages (e.g. immature vs. breeding individuals) differing in their demographic parameters. Individuals are characterized by their age and stage. Each stage has a certain fecundity, survival and probability of developing to the next stage. The parameters are provided through classical transition matrices [@caswellMatrixPopulationModels2001a]. However, in RangeShifter, these are not solved analytically as is typical for matrix models but, instead, the parameters are applied stochastically in an individual-based fashion. Presenting the demographic parameters in the standard matrix notation, Bocedi et al. [-@bocediRangeShifterPlatformModelling2014] believed to ease parameterization, as most population modellers are used to matrix models and, additionally, the number of parameters is kept to the minimum. It has the further important benefit of helping bridging the gap between analytical models and IBMs, the joint use of which has considerable potential, especially for improving modelling for conservation [@travisImprovingPredictionManagement2011a]."}` + +### Dispersal + +Dispersal is defined as movement leading to spatial gene flow, and it typically involves three phases: emigration, transfer and settlement [@stensethAnimalDispersalSmall1992; @clobertDispersal2001; @bowlerCausesConsequencesAnimal2005a; @ronceHowDoesIt2007a]. The key role of dispersal in species persistence and responses to environmental change is increasingly recognized [@travisDispersalSpeciesResponses2014]. Moreover, the importance of modelling dispersal as a complex process, explicitly considering its three phases, each of which has its own mechanisms and costs, has been recently highlighted [@bonteCostsDispersal2012a; @travisModellingDispersalEcoevolutionary2012a; @travisDispersalSpeciesResponses2014]. The implementation of the dispersal process in RangeShifter is based on these recent frameworks and the substantial dispersal theory that has been developed so far [@clobertDispersalEcologyEvolution2012a]. + +#### Emigration + +Emigration is the first phase of dispersal. Emigration itself can be a complex process determined by multiple proximate and ultimate causes. Multiple emigration strategies can be present across the species’ range, inside a single population or even within the same individual in form of plastic emigration behaviour. + +The theory on emigration accounts for context dependencies, plasticity and inter-individual variability in emigration strategies. Much work has been conducted to understand the role of density dependence in emigration [@travisEvolutionDensitydependentDispersal1999; @metzHowShouldWe2001; @poethkeEvolutionDensityPatch2002;@matthysenDensitydependentDispersalBirds2005; @kunEvolutionDensityDependentDispersal2006; @chaput-bardyConditionPhenotypeDependentDispersal2010; @demeesterInformationUseDensitydependent2010]. + +In RangeShifter, emigration is modelled as the probability that an individual will leave its natal patch during the present year (or season). See the description of the submodel for further details. + +#### Transfer + +Transfer is the second phase of dispersal, and consists of the movement of an individual starting from when it emigrates from its natal patch and ending with settlement in another patch or mortality. The main components of this phase are the individual movement ability and navigation capacity in response to the characteristics of the environment. The interaction between these components and their associated costs will determine the distance moved, the movement path and the chance of surviving the transfer phase. + +Understanding and modelling how species move is not a simple task, and, perhaps more than for the other phases of dispersal, much effort has been spent in two separate and not always interacting fields: dispersal ecology [@travisMechanisticUnderstandingDispersal2010] and movement ecology [@nathanMovementEcologyParadigm2008a]. While the former seeks to understand movements as a part of the dispersal process and has often described transfer with phenomenological dispersal kernels (but see recent developments in fitting mechanistic kernels: [@schurrHowRandomDispersal2012]), the latter is more focused on understanding the mechanisms of the movement process itself, even though recent emphasis has been put on the consequences of movements for population dynamics [@moralesBuildingBridgeAnimal2010a]. Modelling dispersal in IBMs needs to draw from both fields. + +`r if(dispersal_kernel){" +Phenomenological dispersal kernels were used to model the transfer phase.Dispersal kernels are statistical distributions that are largely used to describe dispersal distances. For a comprehensive review about theory and empirical estimation of dispersal kernels we refer to Clobert et al. [-@clobertDispersalEcologyEvolution2012a], Part IV. + +Dispersal kernels have been largely used in dispersal ecology both for describing dispersal patterns and for theoretical studies, as well as in metapopulation theory. Recently they have been incorporated in species distribution models [@travisDispersalSpeciesResponses2014], either at population or individual level [@keithPredictingExtinctionRisks2008; @andersonDynamicsRangeMargins2009; @englerMigClimPredictingPlant2009; @willisDynamicDistributionModelling2009; @mitikkaRangeExpansionEuropean2010; @boulangeatAccountingDispersalBiotic2012; @pagelForecastingSpeciesRanges2012a; @schurrHowUnderstandSpecies2012]. The main assumption behind dispersal kernels is that the principal determinant of the probability of an individual dispersing to a particular site is the distance from the starting location. However, it is well recognized and supported by data [@hovestadtEvolutionEmergenceDispersal2012; @baguetteIndividualDispersalLandscape2013], that in most cases realized kernels are the results of multiple factors, such as the interaction between individual movement capacity and landscape structure, making Euclidean distance a poor predictor of dispersal. Dispersal kernels are not a fixed characteristic of the species, but are likely to vary between and within populations depending upon landscape structure and the history of movement rule evolution [@dyckHabitatFragmentationInsect1999; @hanskiVariationMigrationPropensity2004; @merckxLandscapeStructurePhenotypic2006; @fahrigNonoptimalAnimalMovement2007a; @ovaskainenTrackingButterflyMovements2008; @stevensMetaanalysisDispersalButterflies2010; @wangDispersalGlanvilleFritillary2011]. Dispersal kernels can vary through time [@schtickzelleTemporalVariationDispersal2012], and there can be considerable variability between individuals, sexes and stage classes [@delgadoEffectPhenotypicTraits2010; @turlureSpeciesSexspecificAdjustments; @bentonDispersalInvertebratesInfluences2012; @matthysenMulticausalityDispersalReview2012]."}``r if(dispersal_kernel_mixed){" + +Particular emphasis has been placed during the last decade on rare long-distance dispersal events, which have been found fundamental for explaining phenomena such as rate of species’ range shifting in response to past and present climate change [@clarkReidParadoxRapid1998; @nathanSpreadNorthAmerican; @lesserContributionsLongdistanceDispersal2013] and connectivity of isolated populations [@johstMetapopulationPersistenceDynamic2002; @baguetteLongDistanceDispersal2003; @munozWindLongDistanceDispersal2004]. These events are difficult to capture and model with traditional kernels. Therefore, fat-tailed kernels and mixed kernels have started to be used [@bullockLongDistanceSeed2000; @clarkInvasionExtremesPopulation2001; @hovestadtAllInterpatchMovements2011; @fronhoferPickyHitchhikersVector2013a]."}` + +`r if(dispersal_kernel){"Kernels are considered as ‘distance kernels’, i.e. the statistical distribution of the probability that an individual will move a certain distance [@hovestadtEvolutionEmergenceDispersal2012; @nathanDispersalKernelsReview2012]. These kernels are specifically used for the transfer phase, meaning that they do not incorporate information on the emigration or settlement probabilities, which are modelled independently. Therefore, dispersal kernels are applied only to dispersing individuals and not normally to the entire population. + +There are many possible statistical distributions that have been fitted to dispersal data, which in many cases perform better than the negative exponential [@nathanDispersalKernelsReview2012]. However, the negative exponential is still commonly used, has been found useful for describing dispersal patterns of certain organisms."}``r if(dispersal_kernel_mixed){", and the combination of two different negative exponentials has been demonstrated to be a valuable method for discerning between common short-distance and rare long-distance dispersal [@hovestadtAllInterpatchMovements2011]. "}` + +`r if(movement_model){" +It is increasingly acknowledged that individual movements within and between habitat patches, and consequently also population dynamics, are strongly affected by the behavioural and physical traits of individuals and by the landscape structure and composition [@moralesScalingAnimalMovements2002; @hawkesLinkingMovementBehaviour2009; @stevensLandscapeEffectsSpatial2012; @baguetteIndividualDispersalLandscape2013]. This has led to the development of mechanistic models where movement behaviour and its interaction with the environment is explicitly described [@nathanMovementEcologyParadigm2008a; @revillaIndividualMovementBehavior2008a; @moralesBuildingBridgeAnimal2010a; @palmerIntroducingStochasticMovement2011; @peerBreakingFunctionalConnectivity2011]. The classical method to represent individuals’ movements mechanistically is to use a random walk [@codlingRandomWalkModels2008], or its diffusion approximation, assuming that individuals are moving randomly in a homogeneous landscape and that they are all following the same rules. From this basis, there have been recent developments in diffusion models for including landscape heterogeneity and some behavioural responses, like reaction to habitat boundaries, directly derived from empirical data through state-space models [@ovaskainenBiasedMovementBoundary2003; @ovaskainenHabitatSpecificMovementParameters2004; @ovaskainenEmpiricalTestDiffusion2008; @pattersonStateSpaceModels2008; @zhengModellingDispersalDiffusion2009a; @ovaskainenModelingAnimalMovement2009]. Yet, these models do not account for individual variability or for many behavioural components including memory, perceptual range and movement modes. Despite this simplicity, diffusion models, and especially their recent developments, can still be satisfactory at large temporal and spatial scales and serve as a null hypothesis against which to test more complex movement models. Moreover they can provide a basis for building blocks for population dynamics models. + +Mechanistic IBMs allow extending the “random paradigm” by incorporating behavioural elements that are likely to be crucial in affecting species’ spatial dynamics [@limaBehavioralEcologyEcological1996; @baguetteLandscapeConnectivityAnimal2007; @knowltonUsingBehavioralLandscape2010; @shreeveLandscapeScaleConservation2011]. These elements can be assigned into six main categories: (i) the switching between different movement modes [for example foraging within the home range vs. dispersal [@fryxellMultipleMovementModes2008; @delattreDispersalMoodRevealed2010; @peerBreakingFunctionalConnectivity2011]]; (ii) the individuals’ perceptual range [@zollnerLandscapelevelPerceptualAbilities1997; @zollnerBehavioralTradeoffsWhen2005; @gardnerSimulatingDispersalReintroduced2004b; @oldenContextdependentPerceptualRanges2004; @vuilleumierAnimalDispersalModelling2006; @vuilleumierEffectsCognitiveAbilities2006; @peerIncorporatingPerceptualRange2008; @palmerIntroducingStochasticMovement2011]; (iii) the use of information in movement choices [@clobertInformedDispersalHeterogeneity2009] and the memory of previous experience [@smouseStochasticModellingAnimal2010]; (iv) the influence of habitat fragmentation and matrix heterogeneity on movement behaviours [@rickettsMatrixMattersEffective2001; @vandermeerMetapopulationDynamicsQuality2001; @schtickzelleBehaviouralResponsesHabitat2003; @revillaEffectsMatrixHeterogeneity2004; @wiegandEffectsHabitatLoss2005; @fahrigNonoptimalAnimalMovement2007a; @doverInfluencesLandscapeStructure2009]; (v) the individual responses to habitat boundaries [@schultzEdgeMediatedDispersalBehavior2001; @moralesBehaviorHabitatBoundaries2002; @merckxEvolutionMovementsBehaviour2003; @ovaskainenHabitatSpecificMovementParameters2004; @stevensQuantifyingFunctionalConnectivity2006; @peerBreakingFunctionalConnectivity2011]; and (vi) the period of activity [@revillaEffectsMatrixHeterogeneity2004] and the time scale of movements [@lambinHighConnectivityHigh2012]. + +A general framework for a mechanistic representation of movements has been outlined by Nathan et al. [-@nathanMovementEcologyParadigm2008a], who identified four basic components: the internal state of the individual (why does it move?), its motion capacities (how does it move?), its navigation capacities (when and where does it move?) and external factors that affect the movement. This framework allows us, starting from individual movements, and taking into account individual variability, to predict movement patterns over large temporal and spatial scales and potentially to scale up to populations, communities, ecosystems and to multi-generation / evolutionary processes [@holyoakTrendsMissingParts2008]. The ultimate limitation is likely to be the quantity and the type of data needed to parameterize this /these kind of models; therefore, the challenge is to understand which level of detail is needed to make reliable projections in different contexts and for different purposes [@limaBehavioralEcologyEcological1996; @moralesBuildingBridgeAnimal2010a]. + +Movement behaviours during the transfer phase are a core component of the dispersal strategy of an individual, and therefore they come under selection and they can evolve [@merckxEvolutionMovementsBehaviour2003; @fahrigNonoptimalAnimalMovement2007a; @hawkesLinkingMovementBehaviour2009; @travisModellingDispersalEcoevolutionary2012a]. Ultimately, it is the evolution of movement behaviours that leads to what we consider the evolution of dispersal kernels. A handful of theoretical studies have so far explored the evolution of movement rules. For example, it has been shown how the landscape composition and configuration, in interaction with the ecology of the species, can affect the evolution of movement patterns, such that the greater the costs of dispersal the more highly correlated are the emerging walks [@heinzAdaptivePatchSearching2006; @bartonEvolutionIntelligentDispersal2009]. Moreover, straighter movement paths [@phillipsLifehistoryEvolutionRangeshifting2010a] and riskier strategies seem to be selected during range expansion in such a way that the rate of expansion is maximized at the expense of the survival probability of the single individual [@bartonRiskyMovementIncreases2012]."}` + +`r if(movement_SMS){"A Stochastic Movement Simulator (SMS, [@palmerIntroducingStochasticMovement2011]) is implemented in this specific use case. "}``r if(movement_corrRW){"A corelated random walk is implemented."}``r if(movement_model){"The submodel is fully individual-based and explicitly describes the movement behaviour of individuals with a level of detail, and hence parameters, which is probably close to the most parsimonious for a mechanistic movement model. However, it facilitates considerably increasing the complexity and realism with which the transfer phase is modelled."}` + +See the submodel description for further details. + +#### Settlement + +Settlement, or immigration, is the last phase of dispersal, when the organism stops in a new cell or patch of breeding habitat. This phase is determined by a suite of strategies, behaviours and reaction norms that lead individuals to the decision to stop in a particular place. Habitat selection, mate finding and density dependence are probably three of the main processes involved, but not the only ones. Like emigration, settlement is a complex process affected by multiple criteria including inter-individual variability and context dependencies. It can be influenced by the causes and mechanisms of the previous phases of dispersal [@clobertInformedDispersalHeterogeneity2009] and it has associated specific costs [@bonteCostsDispersal2012a], which can also feed back to the previous phases [@legalliardPatternsProcessesDispersal2012]. + +As for the previous phases, the use of different sources of abiotic and biotic information is likely to be crucial in the settlement decision, for which evidence is now accumulating. For example, studies have demonstrated that in some species, dispersing individuals exhibit a preference for habitat that is similar to the natal one, philopatry being a stronger predictor of habitat preferences for settlement than intrinsic habitat quality [@haughlandExplorationCorrelatesSettlement2004; @stampsEffectsNatalExperience2006; @stampsHowDifferentTypes2009]. Conspecific density and performance have also been demonstrated to be important cues for settlement decisions (conspecific attraction), because they can provide a rapid approximation of the habitat quality [@stampsConspecificAttractionAggregation1988; @doligezAvailabilityUsePublic2004; @fletcherSpeciesInteractionsPopulation2007; @verckenImportanceGoodNeighborhood2012; @clotucheSettlementDecisionsTwospotted2013]. + +From the theoretical point of view, much work has been conducted on habitat selection during settlement decisions and its consequences for species’ population dynamics and spatial genetic structure. The basic assumption is that individuals are expected to select habitat patches where their expected fitness is greater than the one expected in the natal patch, weighted by the costs of searching [@ruxtonFitnessDependentDispersal1998; @stampsHabitatSelectionDispersers2001; @bakerIncrementalCostsBenefits2004; @stampsSearchCostsHabitat2005; @armsworthStructureClinesFitness2008; @bonteCostsDispersal2012a]. Recently the idea of ‘matching habitat choice’ has been proposed, for which individuals aim to settle where the environment best matches with their phenotype. This process, expected to be more important for species with limited phenotypic plasticity, can have important implications for processes such as local adaptation, adaptive peak shifts and evolution of niche width, and speciation [@edelaarMatchingHabitatChoice2008]. Other factors affecting settlement such as density dependence [@poethkeAbilityIndividualsAssess2011], conspecific attraction (Fletcher 2006) or mate finding [@gilroyMateFindingOverlookedCritical2012], their evolution and their consequences on species’ responses to environmental changes, have been much less theoretically investigated. + +This specific use case of RangeShifter incorporates some basic settlement rules. In any case, dispersing individuals are not allowed to settle in their natal `r if(cell_based){"cell"}``r if(patch_based){"patch"}`. + +For more details, see the description of the submodel. + +#### Dispersal mortality + +Dispersal is often a costly process for an organism [@bonteCostsDispersal2012a] and, in some cases, a dispersing individual may suffer mortality. Obtaining a sensible representation of dispersal requires that these mortality costs are described appropriately and, for this, it is important to recognize how dispersal mortality is incorporated in RangeShifter. +First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. `r if(dispersal_kernel){"For example, when individuals have no possibility to search for locally-suitable habitat, mortality occurs to all individuals that arrive in unsuitable habitat."}` `r if(movement_model){"For example, some individuals may fail to find suitable habitat before they use up a maximum number of movement steps. In this first case, dispersal mortality clearly depends upon the proportion of suitable habitat in the landscape and will increase as the availability of habitat declines."}` + +`r if(dispersal_kernel){"A second source of dispersal mortality can be a constant or a density-dependent (i.e. individuals that travel further are more likely to die) probability of mortality. The latter may be thought to represent the increased energetic, time or attritional costs that longer-distance dispersers will experience [@bonteCostsDispersal2012a]."}` +`r if(movement_model){"A second source of dispersal mortality can be a per-step probability of mortality. This can be useful for representing mortality risks that increase with distance or time spent travelling."}``r if(movement_model & movement_cost){"Additionally, movement across a complex landscape is modeled more explicitly: the per-step mortality varies according to the nature of the local environment."}` + +For more details, see the description of the submodel. + +### Management + +`r if(translocation){"#### Translocation"}else{"Not applicable."}` + +`r if(translocation){"Translocation, the intentional capture and following release of animals in new areas, is a common conservation practice. They are used to establish new populations, to increase the size of small populations, to reintroduce species in areas where they have been extirpated, and to increase genetic diversity. Individuals are selected based on the specific purpose: e.g., to secure successful establishment of new populations, individuals are required to be either within a reproductive stage or at least become reproductive within a short time span. Additionally, for sexual reproductive species, it is important that both sexes are present in the new location. On the other hand, translocations can be a tool to improve the genetic diversity in established populations which are very isolated and where gene flow is limited. In this case, it is not necessarily important to translocate individuals from both sexes. + +The selection of a suitable source population as well as target location is similar crucial for a successful conservation measure as the selection of the individuals. It needs to be ensured that the source population is healthy and genetically diverse, and that the target location is suitable for the species regarding the resources as well as the size of the patch. The target location should be free of threats that could endanger the new population, and it should be connected to other populations to allow for rang eexpansion in the new region as well as gene flow. + +For more details how translocations were implemented in this model, see the description of the submodel. +"}` + + +## Emergence + +Species range distributions emerge from the population dynamics and the dispersal behaviour of the individuals. + +## Adaptation + +`r if(movement_SMS){"During the transfer process, individuals move according to what they can perceive of the landscape within their perceptual range $PR$. However, individuals do not know a priori their final destination. The $PR$ is defined by a number of cells. At each step, the individual evaluates the surrounding habitat in order to determine the effective cost of taking a particular step to each of the eight neighbouring cells. The effective cost is a mean of the cost of the neighbouring cell and the surrounding cells beyond it within the $PR$."}` + +`r if(!movement_SMS){"Not applicable."}` + +## Objectives + +`r if (movement_SMS & goal_type==2){"The only goal of the dispersing individuals is to move away from the natal location. Individuals follow a straighter trajectory initially, and later become more tortuous and responsive to perceived landscape costs."}` +`r if (!movement_SMS & !goal_type==2){"Not applicable."}` + +## Learning + +Not applicable. + +## Prediction + +Not applicable. + +## Sensing + +`r if(mate_finding){"Individuals of both sexes need to be in the same cell in order to reproduce. Individuals in the same cell are aware of the sex of others."}` +`r if(movement_SMS){"Dispersing individuals can perceive the surrounding landscape within their perceptual range $PR$."}` +`r if(cell_based & dispersal_kernel){ if(s@dispersal@Settlement@Settle>=2){"Dispersing individuals perceive the suitability of cells and might settle in a suitable neighbouring cell if the arrival cell is unsuitable."}}` +`r if(patch_based & dispersal_kernel){ if(s@dispersal@Settlement@Settle>=2){"Dispersing individuals perceive the suitability of patches and might settle in a suitable neighbouring patch if the arrival patch is unsuitable."}}` +`r if(cell_based & movement_model & settlement_densdep){"Dispersing individuals can perceive the density in cells and potentially decide to continue dispersing if the density is high."}` +`r if(patch_based & movement_model & settlement_densdep){"Dispersing individuals can perceive the density in patches and potentially decide to continue dispersing if the density is high."}` +`r if(!mate_finding & !movement_SMS){"Not applicable"}` + + +## Interaction + +No interaction is considered in the model. + +## Stochasticity + +`r if(environmental_stochasticity){"Environmental stochasticity is considered in the model. "}else{"Not applicable. "}``r if(env_stoch_K & !stage_structured){"It acts on the capacity $K$."}``r if(env_stoch_R & !stage_structured){"It acts on the growth rate $r$."}``r if(env_stoch_K & stage_structured){"It acts on the strength of density dependence $1/b$."}``r if(env_stoch_R & stage_structured){"It acts on the fecundity $\\phi$."}` + +Demographic stochasticity is explicitly included in all processes by default. + + +## Collectives + +Not applicable + +## Observation + +`r if(output_range){"### Range +The output _Sim0_Range.txt_ contains the following general information regarding the species' range: Replicate number, year, reproductive season within the year, total number of individuals"}``r if(output_range & stage_structured){", total number of individuals in each stage, total number of juveniles born"}``r if(output_range){", total number of "}``r if(output_range & cell_based){"cells"}``r if(output_range & patch_based){"patches"}``r if(output_range){" occupied by a population capable of breeding, ratio between occupied and suitable "}``r if(output_range & cell_based){"cells"}``r if(output_range & patch_based){"patches"}``r if(output_range){", species range in term of maximum and minimum coordinates of"}``r if(output_range & cell_based){" cells"}``r if(output_range & patch_based){" patches"}``r if(output_range){" occupied by breeding populations."}` + +`r if(output_occ){"### Occupancy +This output reports the "}``r if(output_occ & cell_based){"cell"}``r if(output_occ & patch_based){"patch"}``r if(output_occ){" probability of occupancy by a breeding population. This is only permissible for multiple replicates. Data will be recorded at the beginning of the year before any other process (and only once a year no matter the number of reproductive seasons per year). Two files will be produced: 1. _Sim0_Occupancy.txt_: This file contains a list of "}``r if(output_occ & cell_based){"all the cells in the landscape (x and y coordinates)"}``r if(output_occ & patch_based){"all the patches (PatchID)"}``r if(output_occ){". The remaining columns give the occupancy probability of the "}``r if(output_occ & cell_based){"cell"}``r if(output_occ & patch_based){"patch"}``r if(output_occ){" at defined time steps. The occupancy probability is obtained by dividing the number of times (replicates) that the "}``r if(output_occ & cell_based){"cell"}``r if(output_occ & patch_based){"patch"}``r if(output_occ){" has been occupied in a given year by the total number of replicates. 2. _Sim0_Occupancy_Stats.txt_: Summary occupancy statistics, i.e. the mean ratio between occupied and suitable cells (Mean_OccupSuit) and its standard error (Std_error) at the set time interval."}` + +`r if(output_pop){"### Populations +The population output, _Sim0_Pop.txt_ contains statistics regarding each population present in the landscape at a given time interval. Data are collected before reproduction at each reproductive season at the specified yearly interval and at the end of the simulation. This output file contains the following information: Replicate number, year, reproductive season, "}``r if(output_pop & cell_based){"cell location"}``r if(output_pop & patch_based){"patch ID"}``r if(output_pop){", species number, number of individuals in the population"}``r if(output_pop & stage_structured & !sexual){", the number of individuals in each stage (NInd_stageX)"}``r if(output_pop & sexual & stage_structured){", the number of females (Nfemales_stageX) and of males (Nmales_stageX) in each stage"}``r if(output_pop & !stage_structured & sexual){", the number of females (Nfemales) and of males (Nmales) in the population"}``r if(output_pop & stage_structured & !sexual){", the number of juveniles born (NJuvs)"}``r if(output_pop & sexual){", the number of females juveniles (NJuvFemales) and males (NJuvMales)"}``r if(output_pop){"."}` + +`r if(output_ind){"### Individuals +This output, _Sim0_Rep0_Inds.txt_, contains information regarding each individual at a given time step. To avoid the production of huge files, a separate file is saved for each replicate (here assumed to be 0). "}``r if(output_ind & stage_structured){"Data are recorded after settlement and before aging, in order that dispersal data for individuals which die may be reported."}``r if(output_ind){" Individuals data for year $T$ therefore correspond to Population summary data for year $T+1$ (and individuals which die in year $T$ must be excluded for the data to match at population level). For each individual the following data are collected: Replicate number, year, reproductive season within the year, species number, individual ID, individuals status, natal cell and current "}``r if(output_ind & cell_based){"cell"}``r if(output_ind & patch_based){"patch"}``r if(output_ind){". If the individual has crossed an absorbing landscape or 'no-data' boundary, the current "}``r if(output_ind & cell_based){"cell"}``r if(output_ind & patch_based){"patch"}``r if(output_ind){" will be missing"}``r if(output_ind & sexual){", sex"}``r if(output_ind){", age"}``r if(output_ind & stage_structured){", stage"}``r if(output_ind){", distance moved in meters (linear distance from the centre of the starting cell to the centre of the arrival cell - DistMoved); if the individual has crossed an absorbing landscape or 'no-data' boundary, the distance moved will be missing (set to -1)"}``r if(output_ind & movement_model){", number of steps taken for movement models"}``r if(output_ind){"."}` + +```{r eval=output_ind, echo=F, include=T} +if (cell_based){ + create.table <- data.frame("Status code" = c(0:9), "Description"=c( + "Initial status in natal patch/philopatric recruit", + "Disperser", + "Disperser awaiting settlement in possible suitable cell", + "Waiting between dispersal events", + "Completed settlement", + "Completed settlement in a suitable neighbouring cell", + "Died during transfer by failing to find a suitable patch (includes exceeding the maximum number of steps or crossing an absorbing boundary)", + "Died during transfer by constant, step-dependent, habitat-dependent or distance-dependent mortality", + "Failed to survive annual (demographic) mortality", + "Exceeded maximum age" + )) +} +if (patch_based){ + create.table <- data.frame("Status code" = c(0:9), "Description"=c( + "Initial status in natal patch/philopatric recruit", + "Disperser", + "Disperser awaiting settlement in possible suitable patch", + "Waiting between dispersal events", + "Completed settlement", + "Completed settlement in a suitable neighbouring patch", + "Died during transfer by failing to find a suitable patch \n (includes exceeding the maximum number of steps or crossing an absorbing boundary)", + "Died during transfer by constant, step-dependent, habitat-dependent \n or distance-dependent mortality", + "Failed to survive annual (demographic) mortality", + "Exceeded maximum age" + )) +} +knitr::kable(create.table, col.names = gsub("[.]", " ", names(create.table)), caption = 'Status codes of individuals', format.args = list(width=10)) +``` + +`r if(output_conn){"### Connectivity +The connectivity matrix output, _Sim0_Connect.txt_, presents counts of the number of individuals successfully dispersing from each patch to each other patch for each year specified by the Connectivity Matrix every (years) box. If there is more than one reproductive season during the year, cumulative year-end totals are reported. Although the file contains the data required for true N x N matrices, the data are presented in list format (which can readily be converted to matrices by most analytical software): 1. Replicate number (Rep), 2. Year +3. ID number of natal patch (StartPatch), 4. ID number of settlement patch (EndPatch), 5. Number of individuals dispersing from StartPatch to EndPatch (NInds). +The rows having an entry of -999 are summary rows, showing the total number of successful emigrants from a patch (if EndPatch = -999) and the total number of successful immigrants into a patch (if StartPatch = -999). They are included to facilitate quick examination of the file without having to sum all the individual rows for a patch in any one year. +"}` + +`r if(output_paths){"### SMS paths +Sim0_Rep0_SMSpaths.txt lists the cell-based trajectories of all (successfully or unsuccessfully) dispersed individuals from the natal to the final (settlement or fatal) patch for each year specified by OutIntPaths, starting from OutStartPaths. The data are presented in list format with the columns: Year, individual ID, consecutive step number, coordinates of cell at this step, status of individual. The status is an integer number that codes for the following possible states: +0 = natal patch, +1 = disperser, +2 = disperser awaiting settlement in possible suitable patch, +3 = waiting between dispersal events, +4 = completed settlement, +5 = completed settlement in a suitable neighbouring cell, +6 = died during transfer by failing to find a suitable patch (includes exceeding maximum number of steps or crossing absorbing boundary), +7 = died during transfer by constant, step-dependent, habitat-dependent or distance-dependent mortality, +8 = failed to survive annual (demographic) mortality, +9 = exceeded maximum age."}` + +`r if(output_heatmaps){"### SMS Heat map +OutputMaps/Sim0_Land0_Rep0_Visits.txt is a series of maps in ASCII raster format, showing how many times each cell has been visited by a dispersing individual across the whole time period of the simulation. These heat maps may be useful, for example, for identifying corridors which are heavily used during the dispersal phase. One raster map is created in the Output_Maps folder for each replicate simulation, and is in the same format as the input habitat file. +"}` + +# Initialization + +`r if((real_land & habitat_quality) | arti_land) {"## Initialization of landscape "}` + +`r if(real_land & habitat_quality){"Landscapes are initialized according to the input raster maps. The density dependence of each cell is set as the respective fraction of the given maximum density dependence."}` +`r if(real_land & habitat_quality){"Landscapes are initialized according to the input raster maps. The density dependence of each cell is set according the given values for each habitat type."}` +`r if(arti_land){"An artificial landscape is generated according to the given parameters (see submodule description). "}``r if(arti_land & arti_land_continuous){"Each cell is given a continuous value between 0 and 1, which describes the percentage of habitat cover or habitat quality. within a cell. The effective density dependence of that cell is calculated as the respective fraction of the given maximum density dependence."}``r if(arti_land & !arti_land_continuous){"The resulting landscape is binary, with the two values Habitat and Matrix (i.e. Non-habitat)."}` + + + +## Initialization of populations + +`r if(s@init@InitType==0 & s@init@FreeType==0 & cell_based){cat("Populations are initialized randomly in ", s@init@NrCells, " cells according to the habitat map.")}` +`r if(s@init@InitType==0 & s@init@FreeType==0 & patch_based){cat("Populations are initialized randomly in ", s@init@NrCells, " patches according to the habitat map.")}` +`r if(s@init@InitType==0 & s@init@FreeType==1 & cell_based){"Populations are initialized randomly in all suitable cells according to the habitat map."}` +`r if(s@init@InitType==0 & s@init@FreeType==1 & patch_based){"Populations are initialized randomly in all suitable patches according to the habitat map."}` +`r if(s@init@InitType==1 & s@init@SpType==0){"Initial populations are loaded from a species distribution map in all suitable cells within all distribution presence cells."}` +`r if(s@init@InitType==1 & s@init@SpType==1){cat("Initial populations are loaded from a species distribution map in ",s@init@NrCells ," randomly chosen presence cells.")}` +`r if(s@init@InitType==2 ){"Populations are initialized from a file listing the initial individuals (of given"}``r if(s@init@InitType==2 & sexual & stage_structured){" sex, age and stage"}``r if(s@init@InitType==2 & !sexual & stage_structured){" age and stage"}``r if(s@init@InitType==2 & !sexual & !stage_structured){" age"}``r if(s@init@InitType==2 & cell_based){" in specified cells. This option allows simulation of a reintroduction scenario."}``r if(s@init@InitType==2 & patch_based){" in specified patches. This option allows simulation of a reintroduction scenario."}` `r if(s@init@InitDens==2 & patch_based){cat(s@init@IndsHaCell, " number of individuals per hectare are seeded in each patch.")}` `r if(s@init@InitDens==2 & cell_based){cat(s@init@IndsHaCell, " number of individuals per hectare are seeded in each cell.")}` `r if(s@init@InitDens==0 & patch_based & !stage_structured){"The number of seeded individuals per hectare in each patch is determined by $K$."}``r if(s@init@InitDens==0 & patch_based & stage_structured){"The number of seeded individuals per hectare in each patch is determined by $1/b$."}``r if(s@init@InitDens==0 & cell_based & !stage_structured){"The number of seeded individuals per hectare in each cell is determined by $K$."}``r if(s@init@InitDens==0 & cell_based & stage_structured){"The number of seeded individuals per hectare in each cell is determined by $1/b$."}``r if(s@init@InitDens==1 & patch_based & !stage_structured){"The number of seeded individuals per hectare in each patch is determined by half of $K$."}``r if(s@init@InitDens==1 & patch_based & stage_structured){"The number of seeded individuals per hectare in each patch is determined by half of $1/b$."}``r if(s@init@InitDens==1 & cell_based & !stage_structured){"The number of seeded individuals per hectare in each cell is determined by half of $K$."}``r if(s@init@InitDens==1 & cell_based & stage_structured){"The number of seeded individuals per hectare in each cell is determined by half of $1/b$."}` + +`r if(stage_structured & s@init@InitType!=2 & s@init@InitAge==0){"The proportion of individuals that is initialised at each stage class is set via a numeric vector $PropStages$. It has as many entries as number of stages, starting from the juvenile stage (0). The age is set as the minimal age of the respective stage."}` +`r if(stage_structured & s@init@InitType!=2 & s@init@InitAge==1){"The proportion of individuals that is initialised at each stage class is set via a numeric vector $PropStages$. It has as many entries as number of stages, starting from the juvenile stage (0). The age is set randomly between the minimal and maximal age of the respective stage."}` +`r if(stage_structured & s@init@InitType!=2 & s@init@InitAge==2){"The proportion of individuals that is initialised at each stage class is set via a numeric vector $PropStages$. It has as many entries as number of stages, starting from the juvenile stage (0). The age is set approximately in accordance with the number of years taken to pass through the stage and the survival rate of the respective stage."}` + +`r if(stage_structured & s@init@InitType==2){"The proportion of individuals that is initialised at each stage class and the age distributions are loaded via the file listing the initial individuals."}` + +`r if(s@init@minX>0 | s@init@maxX>0 | s@init@minY>0 | s@init@maxY>0 | s@init@InitFreezeYear>0 | s@init@RestrictFreq>0 | s@init@RestrictRows>0 | s@init@FinalFreezeYear>0){"$\\color{red}{\\text{These options were not yet integrated in the ODD template.}}$ $\\color{red}{\\text{Please include the discribtion on your own.}}$"} ` + +# Input data + +The model requires the following input data: + +`r if(real_land & habitat_quality & !dynamic_landscape){"* The underlying landscape raster map as a text file in ESRI ASCII raster format. The grid needs to contain values for each cell, one line per row. Each cell in the landscape is assigned a continuous percentage value between 0.0 and 100.0 (of the maximum density dependence "}``r if(real_land & habitat_quality & !dynamic_landscape & stage_structured){"$1/b$"}``r if(real_land & habitat_quality & !dynamic_landscape & !stage_structured){"$K$"}``r if(real_land & habitat_quality & !dynamic_landscape){"). There are no explicit habitat or land-cover types. This allows integrating different methods for calculating the habitat suitability for a given species. For example, qualities can result from different methods of suitability modelling, which incorporate multiple variables like habitat types, elevation, climate, etc. In the current version of the program, a straight-line relationship between the habitat quality and the actual density-dependence of the population dynamics is assumed. "}` + +`r if(real_land & habitat_type & !dynamic_landscape){"* The underlying landscape raster map as a text file in ESRI ASCII raster format. The grid needs to contain values for each cell, one line per row. Each habitat or land-cover type has a unique integer code. Each cell in the file contains a single habitat code and 100 percent coverage is assumed for the cell. The landscape is therefore composed of discrete habitat cells. The codes are required to be sequential integers starting from 1 and ranging to Nhabitats. "}` + +`r if(real_land & habitat_quality & dynamic_landscape){"* (A vector of) All underlying landscape raster maps as a text files in ESRI ASCII raster format. The grids need to contain values for each cell, one line per row. Each cell in the landscapes is assigned a continuous percentage value between 0.0 and 100.0 (of the maximum density dependence "}``r if(real_land & habitat_quality & dynamic_landscape & stage_structured){"$1/b$"}``r if(real_land & habitat_quality & dynamic_landscape & !stage_structured){"$K$"}``r if(real_land & habitat_quality & dynamic_landscape){". There are no explicit habitat or land-cover types. This allows integrating different methods for calculating the habitat suitability for a given species. For example, qualities can result from different methods of suitability modelling, which incorporate multiple variables like habitat types, elevation, climate, etc. In the current version of the program, a straight-line relationship between the habitat quality and the actual density-dependence of the population dynamics is assumed. Therefore, the quality should be scaled accordingly in case of a curvilinear relationship. Any part of the original landscape which was a ‘no-data’ region (e.g. the sea or land beyond a study area boundary) must remain in that state for the whole simulation. "}` + +`r if(real_land & habitat_type & dynamic_landscape){"* (A vector of) All underlying landscape raster maps as a text file in ESRI ASCII raster format. The grids need to contain values for each cell, one line per row. Each habitat or land-cover type has a unique integer code. Each cell in the files contains a single habitat code and 100 percent coverage is assumed for the cell. The landscapes are therefore composed of discrete habitat cells. The codes are required to be sequential integers starting from 1 and ranging to Nhabitats. Any part of the original landscape which was a ‘no-data’ region (e.g. the sea or land beyond a study area boundary) must remain in that state for the whole simulation. "}` + +`r if(patch_based & real_land & !dynamic_landscape){"* A raster map as a text file in ESRI ASCII raster format of the same landscape, where each cell contains the ID number of the patch to which it belongs. Each patch must have a unique positive integer ID. The ID of every cell that does not belong to a patch (i.e. non-habitat/matrix) must be zero. Note that a single patch is the unit at which the density dependence in the population dynamics acts. Therefore, a patch can be discontinuous, i.e. it can contain cells that do not belong to the patch if they are assumed not to affect the dynamics, or on the other hand, patch cells that are not physically contiguous to the rest of the patch cells. "}` + +`r if(patch_based & real_land & dynamic_landscape){"* Raster maps as text files in ESRI ASCII raster format of the same landscapes, where each cell contains the ID number of the patch to which it belongs. Each patch must have a unique positive integer ID. The ID of every cell that does not belong to a patch (i.e. non-habitat/matrix) must be zero. Note that a single patch is the unit at which the density dependence in the population dynamics acts. Therefore, a patch can be discontinuous, i.e. it can contain cells that do not belong to the patch if they are assumed not to affect the dynamics, or on the other hand, patch cells that are not physically contiguous to the rest of the patch cells. The identity of patches is not cross-checked between changes, and care must therefore be taken to ensure consistency; otherwise, a patch (and its resident population) can jump to a distant location or be split into two or more disjunct parts, with unpredictable and possibly weird consequences. It is legitimate for a patch to be split into two or more separate patches (e.g. by construction of a motorway or some other barrier), but any existing population will remain with the part (if any) which retains the original patch number, and populations within the other parts (having a new patch number) must arise through colonisation. Possible ways to work around this restriction include: + + * Assign to all post-change parts of the original patch a new, unique patch number and specify that dispersal is allowed after population destruction (which is possible only for a structured population), in which case some colonisation of the new patches should occur. Note that the connectivity matrix will be misleading in such cases, as every successful ‘disperser’ will appear to have moved from patch N to patch M (where M is the new patch number). + + * Instead of a single original patch, define two (or more) distinct but adjacent patches in the original landscape, so that they each retain their own populations when they become separated by the landscape change. "}` + +`r if(real_land & !dynamic_landscape & movement_cost_file){"* A raster map as a text file in ESRI ASCII raster format containing the SMS costs. The specified map has to match the landscape raster in extent, coordinates and resolution, and each cell contains a cost value, with the minimal possible cost being 1. "}` + +`r if(real_land & dynamic_landscape & movement_cost_file){"* Raster maps as text files in ESRI ASCII raster format containing the SMS costs. The specified maps have to match the landscape rasters in extent, coordinates and resolution, and each cell contains a cost value, with the minimal possible cost being 1. "}` + +`r if(real_land & s@init@InitType==1 & s@init@SpType==0){"* A species distribution map as a text file in ESRI ASCII raster format containing the initial destribution. It must be aligned with the landscape map, i.e. the coordinates of the lower-left corner must be the same. The extent of the map does not have to be necessarily the same as the landscape. The resolution can be the same or coarser, provided that it is a multiple of the landscape resolution. For example, if the landscape cell size is 250m, the species distribution can be at the resolution of 250m, 500m, 750m, 1000m etc. Each cell of the species distribution map must contain either 0 (species absent or not recorded) or 1 (species present). "}` + +`r if(s@init@InitType==2){"* An initial individuals list file. The population is initialised according to a list of specific individuals (of given sex, age and stage, if appropriate) in specified cells/patches. It must be a tab-separated list with explicit column headers and one row for each individual to be initialized. The expected column headers must match the following order exactly: 'Year', 'Species' (must = 0), "}``r if(s@init@InitType==2 & cell_based){"'X', 'Y', "}``r if(s@init@InitType==2 & patch_based){"'PatchID', "}``r if(s@init@InitType==2){"'Ninds', "}``r if(s@init@InitType==2 & sexual){"'Sex', 'Age'"}``r if(s@init@InitType==2 & stage_structured){"', Stage'"}``r if(s@init@InitType==2){"."}``r if(s@init@InitType==2 & sexual){" The sex is specified with 0 for female and 1 for male."}` + +# Submodels + +`r if(arti_land){"## Landscape + +To generate a fractal landscape, the midpoint displacement algorithm [@saupeAlgorithmsRandomFractals1988] is applied, adapted to allow for the generation of elongated landscapes (useful for theoretical studies on range shifting and environmental gradients). Landscape structure is determined by two parameters: the proportion of landscape occupied by suitable habitat $p$ and the degree of spatial autocorrelation (Hurst exponent, $H$) which ranges from > 0.0 (low autocorrelation but still not completely spatially independent) to < 1.0 (high autocorrelation, i.e. high habitat aggregation). +The resulting landscape is"}``r if(arti_land & arti_land_continuous){"continuous. It describes the percentage of habitat cover or habitat quality within a cell. The effective "}``r if(arti_land & arti_land_continuous & stage_structured){" demographic density dependence $1/b$ "}``r if(arti_land & arti_land_continuous & !stage_structured){" limiting carrying capacity $K$ "}``r if(arti_land & arti_land_continuous){" of that cell is calculated as the respective fraction of the value of "}``r if(arti_land & arti_land_continuous & stage_structured){" the demographic density dependence $1/b$."}``r if(arti_land & arti_land_continuous & !stage_structured){" the limiting carrying capacity $K$."}``r if(arti_land & !arti_land_continuous){"binary, either being habitat or matrix (i.e. non-habitat)."}` + +`r if(real_land & !dynamic_landscape){"## Landscape + +A real landscape is imported consisting of"}` `r if(real_land & habitat_quality & !dynamic_landscape){" continuous values, ranging from 0.0 to 100.0, that represent percentages of habitat cover or quality."}``r if(real_land & habitat_type & !dynamic_landscape){" unique integer habitat codes to characterise the habitat type of each cell. "}``r if(real_land & patch_based & !dynamic_landscape){"An additional file of the same landscape is provided, where each cell contains the ID number of the patch to which it belongs. Each patch has a unique positive integer ID. The ID of every cell that does not belong to a patch (i.e. non-habitat/matrix) must be zero. Note that a single patch is the unit at which the density dependence in the population dynamics acts. Therefore, a patch can be discontinuous, i.e. it can contain cells that do not belong to the patch if they are assumed not to affect the dynamics, or on the other hand, patch cells that are not physically contiguous to the rest of the patch cells."}` +`r if(dynamic_landscape){"## Landscape + +Dynamic landscapes are imported consisting of"}` `r if(dynamic_landscape & real_land & habitat_quality){" continuous values, ranging from 0.0 to 100.0, that represent percentages of habitat cover or quality."}``r if(dynamic_landscape & real_land & habitat_type){" unique integer habitat codes to characterise the habitat type of each cell. The attributes of cells change at specified years during the course of a simulation. Any landscape change occurs at the start of the year, i.e. before the reproductive season."}` +`r if(dynamic_landscape & real_land & patch_based){"Additional files of the same landscapes are provided, where each cell contains the ID number of the patch to which it belongs. Each patch has a unique positive integer ID. The ID of every cell that does not belong to a patch (i.e. non-habitat/matrix) must be zero. Note that a single patch is the unit at which the density dependence in the population dynamics acts. Therefore, a patch can be discontinuous, i.e. it can contain cells that do not belong to the patch if they are assumed not to affect the dynamics, or on the other hand, patch cells that are not physically contiguous to the rest of the patch cells. As the landscape is dynamic, the shape of patches may change, patches may be removed and new patches may be created where there was previously inter-patch matrix. +"}``r if(dynamic_landscape){"Thus some populations may be extirpated "}``r if(dynamic_landscape & !stage_structured){"(all individuals die)"}``r if(dynamic_landscape & stage_structured){"(all individuals either die or have an immediate opportunity to disperse)"}``r if(dynamic_landscape){", and new populations may arise from colonisation of newly suitable areas. "}``r if(dynamic_landscape & movement_cost_file){"In addition, the cost map for the movement processes is dynamic."}` + +`r if(real_land & !stage_structured){"In addition, the limiting carrying capacity $K$ is given in units of the number of individuals per hectare. "}``r if(real_land & stage_structured){"In addition, the demographic density dependence $1/b$ is given in units of the number of individuals per hectare. "}``r if(real_land & habitat_type){"A vector of the length of the habitat types specifies the respective density dependence for every habitat code."}``r if(real_land & habitat_quality){" +The given density dependence is interpreted as the maximum density reached in cells with 100% habitat. All other cells hold the respective fraction of the density dependence."}` + +`r if(environmental_stochasticity){"## Environmental stochasticity + +In RangeShifter, environmental stochasticity is implemented using a first order autoregressive process to generate time series of the noise value $\\epsilon$ [@ruokolainenEcologicalEvolutionaryDynamics2009]: + +$$\\epsilon_{t+1} = \\kappa \\epsilon_{t} + \\omega_{t} \\sqrt{1−\\kappa^2}$$ + +where $\\kappa$ is the autocorrelation coefficient and $\\omega$ is a random normal variable drawn from $N(0,\\sigma)$."}``r if(environmental_stochasticity & s@simul@ac==0){" In this specific use case auto correlation is switched of ($\\kappa$ = 0) and only red noise is considered."}``r if(environmental_stochasticity){"Changing $\\omega$ changes the amplitude of the fluctuations. The spatial scale of the variation is"}``r if(environmental_stochasticity & !env_stoch_loc){" global (a single time series for the entire landscape)"}``r if(environmental_stochasticity & env_stoch_loc){" local (each cell fluctuates independently)"}``r if(environmental_stochasticity){", and is always applied on a yearly basis. Different degrees of spatial autocorrelation are not implemented in the current version."}` + +`r if(environmental_stochasticity & env_stoch_K & !stage_structured){"The noise affects the species’ demographic density-dependence $K$ through the following equation: +$$K_{x,y,t} = K_{x,y,0} + K*\\epsilon_{t}$$ +where $x$ and $y$ are the cell coordinates and $K$ is the local carrying capacity in absence of stochasticity. In the absence of an environmental gradient, $K_{x,y,0}$ is equal to $K$."}` + +`r if(environmental_stochasticity & env_stoch_K & stage_structured){"The noise affects the species’ demographic density-dependence $1/b$ through the following equation: +$${1/b}0_{x,y,t} = {1/b}_{x,y,0} + {1/b}*\\epsilon_{t}$$ +where $x$ and $y$ are the cell coordinates and $1/b$ is the nature of demographic density-dependence) in absence of stochasticity. In the absence of an environmental gradient, $1/b_{x,y,0}$ is equal to $1/b$."}` + +`r if(environmental_stochasticity & env_stoch_R & !stage_structured){"The noise affects the species’ growth rate $R$ through the following equation: +$$R_{x,y,t} = R_{x,y,0} + R*\\epsilon_{t}$$ +where $x$ and $y$ are the cell coordinates and $R$ is the growth rate in absence of stochasticity. In the absence of an environmental gradient, $R_{x,y,0}$ is equal to $R$."}` + +`r if(environmental_stochasticity & env_stoch_R & stage_structured){"The noise affects the species’ fecundity $\\phi$ through the following equation: + +$$\\phi_{x,y,t} = \\phi_{x,y,0} + \\phi*\\epsilon_{t}$$ + +where $x$ and $y$ are the cell coordinates and $\\phi$ is the fecundity in absence of stochasticity. In the absence of an environmental gradient, $\\phi_{x,y,0}$ is equal to $\\phi$."}` + +## Reproduction +`r if(stage_structured){"At the beginning of each year, reproduction is the first process to be modelled. "}`The model simulates `r if(rep_seasons==1){"1 reproductive season"} else{cat(rep_seasons, "reproductive seasons")}` per year. `r if(stage_structured & survival_schedule==0){"Survival and development of all the stages (apart from stage 0) occur simultaneously with reproduction, followed by dispersal and finally survival and development of stage 0. Individuals age at the end of each year."}` `r if(stage_structured & survival_schedule==1){"Reproduction is followed by dispersal. After each reproductive season, survival and successive development of all the stages are modelled (between reproductive seasons). Aging occurs at the end of the year."}` `r if(stage_structured & survival_schedule==2){"Reproduction is followed by dispersal after each reproductive event. Survival and development of all stages happen only at the end of all reproductive seasons (annually), followed by aging at the end of the year."}` +`r if(!stage_structured){"At each generation the life cycle comprises: reproduction, death of the adults and offspring dispersal (in that order)."}` +`r if(!stage_structured & !sexual & cell_based){"Recruitment is determined by a stochastic, individual-based formulation of Maynard-Smith and Slatkin’s [-@smithStabilityPredatorPreySystems1973] population model, where the number of offspring produced by a single individual in the cell $i$ at time $t$, is drawn from the following distribution: + +$$Poisson(\\dfrac{R_{i,t}}{{1+|R_{i,t}-1|*\\dfrac{N_{i,t}}{K_{i,t}}^{b_{c}}}})$$ + +Here, $R_{i,t}$ is the maximum growth rate (obtained at very low density only) and $K_{i,t}$ is the carrying capacity."}` +`r if(!stage_structured & !sexual & patch_based){"Recruitment is determined by a stochastic, individual-based formulation of Maynard-Smith and Slatkin’s [-@smithStabilityPredatorPreySystems1973] population model, where the number of offspring produced by a single individual in the patch $i$ at time t, is drawn from the following distribution: + +$$Poisson(\\dfrac{R_{i,t}}{{1+|R_{i,t}-1|*\\dfrac{N_{i,t}}{K_{i,t}}^{b_{c}}}})$$ + +Here, $R_{i,t}$ is the maximum growth rate (obtained at very low density only) and $K_{i,t}$ is the carrying capacity."}` +`r if(!stage_structured & !sexual & (dynamic_landscape | environmental_stochasticity) ){"$R_{i}$ and $K_{i,t}$ vary in space and time."}` +`r if(!stage_structured & !sexual){"$b_{c}$ is the competition coefficient which describes the type of density regulation, providing for under-compensatory ($b_{c}$ < 1), compensatory ($b_{c}$ = 1) or over-compensatory ($b_{c}$ > 1) dynamics."}` + +`r if(!stage_structured & sexual){"Individuals are explicitly characterized by their sex. The proportion of each sex in the population is controlled by setting the proportion of males (this is interpreted as the probability that an individual is male; hence a skewed sex-ratio at birth (or initialisation) may occur in a small population)."}` +`r if(!stage_structured & sexual & mating_simple){"Each female individual is assumed to mate, as long as there is at least one male in the population. The Maynard Smith and Slatkin model is used to determine the expected number of offspring produced by each female.$R_{i,t}$ is multiplied by 2 to maintain equivalence compared to the standard equation [@lindstromSexualReproductionPopulation1998]: + +$$Poisson(\\dfrac{(2*R_{i,t})}{{1+|R_{i,t}-1|*\\dfrac{N_{i,t}}{K_{i,t}}^{b_{c}}}})$$"}` +`r if(!stage_structured & sexual & mating_complex){"The mating system is explicitly modelled through a mating function [@lindstromSexualReproductionPopulation1998; @legendreAgeStructureMating2004; @gomesDiscreteTwosexModels2010], where the number of mated females $c$ is given by: + +$$c = min(1,2hm/f+hm)f$$ + +where $f$ and $m$ are the numbers of potentially reproductive females and males, respectively, and $h$ is the maximum harem size, i.e. the maximum number of pair bonds that a male can establish. $h$ = 1 corresponds to monogamy, 0 < $h$ < 1 to polyandry and $h$ > 1 to polygyny. +Each potentially reproductive female has a probability of reproducing pr given by: + +$p_{r}=\\dfrac{c}{f}$ + +A Bernoulli trial, $Bern(p_{r})$, determines if the female reproduces or not. Hence, the specification of the mating system determines the probability for each female to reproduce. However, no explicit pair bonds are formed. For females that reproduce, the number of offspring is determined through + +$$Poisson(\\dfrac{(2*R_{i,t})}{{1+|R_{i,t}-1|*\\dfrac{N_{i,t}}{K_{i,t}}^{b_{c}}}})$$"}` + +`r if(stage_structured){"Generations overlap and individuals are classified in different stages (e.g. immature vs. breeding individuals) differing in their demographic parameters. Individuals are characterized by their age and stage. Each stage has a certain fecundity $\\phi$, survival $\\sigma$ and probability of developing to the next stage $\\gamma$. The parameters are provided through classical transition matrices [@caswellMatrixPopulationModels2001a]. However, these are not solved analytically as is typical for matrix models but, instead, the parameters are applied stochastically in an individual-based fashion. +At each reproductive season, two parameters control the likelihood that each individual / female reproduces: + +* First, it is determined whether a reproductively mature female is a potential reproducer."}``r if(stage_structured & rep_interval>0){cat("A female, which has already reproduced, has to wait", rep_interval," reproductive seasons to be able to reproduce again. Only those mature females that are either yet to reproduce, or last reproduced more than this number of reproductive seasons previously, are potential breeders. ")}``r if(stage_structured & rep_interval==0){"Only those mature females that are able to reproduce, are potential breeders. "}` +`r if(stage_structured){" + +* Potential breeders all reproduce with set probability $\\phi$. +"}` + +`r if(stage_structured & !sexual){"In this specific use case, an asexual/only-female model was implemented. To avoid the problem of offspring developing to the next stage in the same year without losing the offspring stage, and hence the chance for simulating post-natal dispersal, an explicit juvenile stage (stage 0) is added: + +$$A = \\begin{pmatrix} 0 & 0 & \\phi \\\\ +1.0 & \\sigma(1-\\gamma) & 0 \\\\ +0 & \\sigma\\gamma & \\sigma +\\end{pmatrix}$$ + +Juveniles have to develop to stage 1 in the same year they are born. It is important to note that juvenile mortality can be accounted for in two ways. Either it is included in adult fecundity $\\phi$ (by appropriately reducing its value), and $\\sigma_{0}\\gamma_{0-1}$ is equal to 1.0. This is how it is typically accounted for in matrix models. Or, alternatively, $\\phi$ is equal to the true maximum fecundity and $\\sigma_{0}\\gamma_{0-1}$ is less than 1.0. Only the first approach allows straightforward direct comparison with standard analytical matrix models. +The parameters in the matrix are used in a stochastic way at the individual level. Each individual/female at stage $s$, if it reproduces, produces a number of offspring given by Poisson($\\phi_{s}$). "}` + +`r if(stage_structured & sexual & !demography_sexdep){"To avoid the problem of offspring developing to the next stage in the same year without losing the offspring stage, and hence the chance for simulating post-natal dispersal, we added an explicit juvenile stage (stage 0): + +$$A = \\begin{pmatrix} 0 & 0 & \\phi \\\\ +1.0 & \\sigma(1-\\gamma) & 0 \\\\ +0 & \\sigma\\gamma & \\sigma +\\end{pmatrix}$$ + +Juveniles have to develop to stage 1 in the same year they are born. It is important to note that juvenile mortality can be accounted for in two ways. Either it is included in adult fecundity $\\phi$ (by appropriately reducing its value), and $\\sigma_{0}\\gamma_{0-1}$ is equal to 1.0. This is how it is typically accounted for in matrix models. Or, alternatively, $\\phi$ is equal to the true maximum fecundity and $\\sigma_{0}\\gamma_{0-1}$ is less than 1.0. Only the first approach allows straightforward direct comparison with standard analytical matrix models. +The parameters in the matrix are used in a stochastic way at the individual level. Individuals are defined by their sex and the sex is acknowledged also in the dispersal process. $\\phi$ refers to the number of offspring (males and females) per female. Each female at stage $s$, if it reproduces, produces a number of offspring given by Poisson($\\phi_{s}$). "}` + +`r if(stage_structured & sexual & demography_sexdep){"The mating system is explicitly modelled. The mating system is explicitly modelled through a mating function [@lindstromSexualReproductionPopulation1998; @legendreAgeStructureMating2004; @gomesDiscreteTwosexModels2010], where the number of mated females $c$ is given by: + +$$c = min(1,2hm/f+hm)f$$ + +where $f$ and $m$ are the numbers of potentially reproductive females and males, respectively, and $h$ is the maximum harem size, i.e. the maximum number of pair bonds that a male can establish. $h$ = 1 corresponds to monogamy, 0 < $h$ < 1 to polyandry and $h$ > 1 to polygyny. +Each potentially reproductive female has a probability of reproducing $pr$ given by: + +$$p_{r}=\\dfrac{c}{f}$$ + +A Bernoulli trial, $Bern(p_{r})$, determines if the female reproduces or not. Hence, the specification of the mating system determines the probability for each female to reproduce. However, no explicit pair bonds are formed. +Additionally, the demographic parameters are sex-dependent. +$\\gamma_{m}$ and $\\gamma_{f}$ are the probability of developing from stage 1 to stage 2 of males and females +respectively, $\\sigma_{1m}$, $\\sigma_{1f}$, $\\sigma_{2m}$ and $\\sigma_{2f}$ are the two sexes’ survival probabilities at each stage and +$\\phi_{m}$ and $\\phi_{f}$ are their fecundities. In the classical matrix modelling framework, $\\phi_{m}$ and $\\phi_{f}$ are +derived from a birth function, which takes into account the number of males and females, +the harem size and the clutch size [@caswellTwoSexModelsChaos1986; @caswellMatrixPopulationModels2001a]. In RangeShifter, the mating and the birth processes are modelled explicitly and separately in an individual-based +manner; therefore, the fecundity parameter utilized is the same as in the non sexspecific +model, as the differences between sexes are already accounted for during the mating +process (i.e. number of offspring per female). What the user still needs to determine before +running structured explicit mating system models in RangeShifter is at which stages males +are reproductive. +To avoid the problem of offspring developing to the next stage in the same year without losing the offspring stage, and hence the chance for simulating post-natal dispersal, an explicit juvenile stage (stage 0) is added: + +$$A = \\begin{pmatrix} 0 & 0 & 0 & 0 & \\phi_{m} & \\phi_{f}\\\\ +1.0 & 0 & \\sigma_{1m}(1-\\gamma_{m}) & 0 & 0 & 0\\\\ +0 & 1.0 & 0 & \\sigma_{1f}(1-\\gamma_{f}) & 0 & 0\\\\ +0 & 0 & \\sigma_{1m}\\gamma_{m} & 0 & \\sigma_{2m} & 0\\\\ +0 & 0 & 0 & \\sigma_{1f}\\gamma_{f} & 0 & \\sigma_{2f} +\\end{pmatrix}$$"}` + +`r if(stage_structured & repro_densdep & !repro_stagedep){"Reproduction is density-dependent. Following Neubert & Caswell [-@neubertDensitydependentVitalRates2000], density +dependence in fecundity is implemented as an exponential decay: +$$\\phi_{i} = \\phi_{0,i}*e^{-bN_{t}}$$ +where $\\phi_{i}$ is the fecundity of stage $i$, $\\phi_{0,i}$ is its maximum fecundity at low densities, $b$ is the +strength of density dependence and $N_{t}$ is the total number of individuals in the local +population at time $t$."}` + +`r if(stage_structured & repro_densdep & repro_stagedep){"Reproduction is density- and stage-dependent. Following Neubert & Caswell [-@neubertDensitydependentVitalRates2000], density and stage +dependence in fecundity is implemented as an exponential decay: + +$$\\phi_{i} = \\phi_{0,i}*e^{-b\\sum_{j = 1}^{S} \\omega_{ij}N_{j,t}}$$ + +where $\\phi_{i}$ is the fecundity of stage $i$, $\\phi_{0,i}$ is its maximum fecundity at low densities, $b$ is the +strength of density dependence, $S$ indicates the number of stages and $\\omega_{ij}$ is contribution of stage $j$ to the density dependence in the fecundity of stage $i$ and $N_{j,t}$ the number of individuals in stage $j$ at time $t$ (e.g. [@caswellSensitivityAnalysisEquilibrium2004])."}` + +## Survival `r if(stage_structured){"& Development"}` +`r if(stage_structured & survival_schedule==0){"Survival and development of all the stages (apart from stage 0) occur simultaneously with reproduction, followed by dispersal and finally survival and development of stage 0."}` +`r if(stage_structured & survival_schedule==1){"Reproduction is first followed by dispersal. Only then survival and successive development of all the stages are modelled."}` +`r if(stage_structured & survival_schedule==2){"Reproduction is first followed by dispersal after each reproductive event. Survival and development of all stages happen only at the end of all reproductive seasons."}` + +`r if(!stage_structured & !local_ext_prob){"In this specific use case, survival is not explicitly modelled."}` +`r if(stage_structured & !survival_densdep & !survival_stagedep){"In this specific use case, survival is neither density nor stage dependent. Bernoulli trials $Bern(\\sigma)$ determine if an individual survives or not."}` +`r if(stage_structured & !survival_densdep & survival_stagedep){"In this specific use case, survival is stage dependent. Bernoulli trials $Bern(\\sigma_{s})$ determine if an individual survives or not. "}` + +`r if(stage_structured & survival_densdep & !survival_stagedep){"In this specific use case, survival is density dependent. Density dependence in survival is implemented as an exponential decay: + +$$\\sigma_{i} = \\sigma_{0,i}*e^{-C_{\\sigma}bN_{t}}$$ + +where $\\sigma_{i}$ is the survival probability of stage $i$, $\\sigma_{0,i}$ is its survival probability at low densities, $b$ is the strength of density dependence and $N_{t}$ is the total number of individuals in the local population at time $t$. To allow for the possibility of having different strengths of density dependence in different processes, we introduce the coefficient $C_{\\sigma}$, which scales the strength of density dependence in survival relative to the strength of density dependence $b$ in fecundity. +Bernoulli trials $Bern(\\sigma_{i})$ determine if an individual develops to the next stage or not. +"}` + +`r if(stage_structured & survival_densdep & survival_stagedep){"In this specific use case, survival is density dependent. Density and stage dependence in survival is implemented as an exponential decay: + +$$\\sigma_{i} = \\sigma_{0,i}*e^{-C_{\\sigma}b\\sum_{j = 1}^{S} \\omega_{ij}N_{j,t}}$$ + +where $\\sigma_{i}$ is the survival probability of stage $i$, $\\sigma_{0,i}$ is its survival probability at low densities, $b$ is the strength of density dependence, $S$ indicates the number of stage, $\\omega_{ij}$ is contribution of stage $j$ to the density dependence in the fecundity of stage $i$ and $N_{j,t}$ the number of individuals in stage $j$ at time $t$ (e.g. [@caswellSensitivityAnalysisEquilibrium2004]). To allow for the possibility of having different strengths of density dependence in different processes, we introduce the coefficient $C_{\\sigma}$, which scales the strength of density dependence in survival relative to the strength of density dependence $b$ in fecundity. +Bernoulli trials $Bern(\\sigma_{i})$ determine if an individual develops to the next stage or not. +"}` + +`r if(stage_structured & !develop_densdep & !develop_stagedep){"In this specific use case, development is neither density nor stage dependent. Bernoulli trials $Bern(\\gamma)$ determine if an individual develops to the next stage or not."}` +`r if(stage_structured & !survival_densdep & survival_stagedep){"In this specific use case, development is stage dependent. Bernoulli trials $Bern(\\gamma_{s})$ determine if an individual develops to the next stage or not. "}` + +`r if(stage_structured & develop_densdep & !develop_stagedep){"In this specific use case, development into higher stages is density dependent. Density dependence in development is implemented as an exponential decay: +$\\gamma_{i} = \\gamma_{0,i}*e^{-C_{\\gamma}bN_{t}}$ +where $\\gamma_{i}$ is the development probability of stage $i$, $\\gamma_{0,i}$ is its development probability at low densities, $b$ is the strength of density dependence and $N_{t}$ is the total number of individuals in the local population at time $t$. To allow for the possibility of having different strengths of density dependence in different processes, we introduce the coefficient $C_{\\gamma}$ scales the strength of density dependence in development relative to the strength of density dependence $b$ in fecundity. +Bernoulli trials $Bern(\\gamma_{i})$ determine if an individual develops to the next stage or not."}` + +`r if(stage_structured & develop_densdep & develop_stagedep){"In this specific use case, development into higher stages is density dependent. Density and stage dependence in development is implemented as an exponential decay: +$\\gamma_{i} = \\gamma_{0,i}*e^{-C_{\\gamma}b\\sum_{j = 1}^{S} \\omega_{ij}N_{j,t}}}$ +where $\\gamma_{i}$ is the development probability of stage $i$, $\\gamma_{0,i}$ is its development probability at low densities, $b$ is the strength of density dependence, $S$ indicates the number of stage, $\\omega_{ij}$ is contribution of stage $j$ to the density dependence in the fecundity of stage $i$ and $N_{j,t}$ the number of individuals in stage $j$ at time $t$ (e.g. [@caswellSensitivityAnalysisEquilibrium2004]). To allow for the possibility of having different strengths of density dependence in different processes, we introduce the coefficient $C_{\\gamma}$, which scales the strength of density dependence in development relative to the strength of density dependence $b$ in fecundity. +Bernoulli trials $Bern(\\gamma_{i})$ determine if an individual develops to the next stage or not. +"}` + +`r if(cell_based & local_ext_prob){"RangeShifter implements random local extinction probability. In each year, every population has an identical probability of going extinct. This does not affect the demographic parameter but simply kills-off the local population."}` + +## Emigration + +Emigration is the first phase of dispersal. It is modeled as the probability that an individual will leave its natal patch during the present year. `r if(stage_structured){"If a stage having non-zero $d$ can last for more than one year, an individual has multiple opportunities to emigrate, each with probability $d$, and hence the realised overall emigration rate will be larger than $d$."}` The emigration probability $d$ is `r if(!emigration_densdep){"density-independent, and hence constant. "}``r if(emigration_densdep & !stage_structured){"density dependent. It is given by the following function, introduced by Kun and Scheuring [-@kunEvolutionDensityDependentDispersal2006] + +$$d = \\dfrac{D_{0}}{1 + e^{-(N_{i,t}/K_{i,t}-\\beta)\\alpha}}$$ + +Here, $D_{0}$ is the maximum emigration probability, $\\beta$ is the inflection point of the function and $\\alpha$ is the slope at the inflection point. We chose this one because it is a flexible function that allows for modeling a range of different reaction norms, as well as their emergence through evolution. We assume individuals to have full knowledge of the population density and habitat quality in their natal patch. Information acquisition is not explicitly modeled in RangeShifter."}``r if(emigration_densdep & stage_structured){"density dependent. It is given by the following function, introduced by Kun and Scheuring [-@kunEvolutionDensityDependentDispersal2006] + +$$d = \\dfrac{D_{0}}{1 + e^{-(b_{i,t}N_{i,t}-\\beta)\\alpha}}$$ + +Here, $D_{0}$ is the maximum emigration probability, $\\beta$ is the inflection point of the function, $\\alpha$ is the slope at the inflection point and $b$ represents the strength of density dependence used for the population dynamics. We chose this one because it is a flexible function that allows for modeling a range of different reaction norms, as well as their emergence through evolution. We assume individuals to have full knowledge of the population density and habitat quality in their natal patch. Information acquisition is not explicitly modeled in RangeShifter."}` + +`r if(!emigration_sexdep & !emigration_stagedep){"The emigration probability is the same and fixed for every individual."}` + +`r if(emigration_sexdep & !emigration_stagedep & emigration_densdep){"Emigration probability is modelled sex-specific. Thus, each sex has different emigration parameters."}` + +`r if(emigration_stagedep & !emigration_sexdep & emigration_densdep){"Emigration probability is modelled stage-specific. Thus, each stage has different emigration parameters."}` + +`r if(emigration_stagedep & emigration_sexdep & emigration_densdep){"Emigration probability is modelled stage- and sex-specific. Thus, each stage and sex has different emigration parameters."}` + + +`r if(emigration_sexdep & !emigration_stagedep & !emigration_densdep){"Emigration probability is modelled sex-specific. Thus, each sex has different emigration parameter."}` + +`r if(emigration_stagedep & !emigration_sexdep & !emigration_densdep){"Emigration probability is modelled stage-specific. Thus, each stage has different emigration parameter."}` + +`r if(emigration_stagedep & emigration_sexdep & !emigration_densdep){"Emigration probability is modelled stage- and sex-specific. Thus, each stage and sex has different emigration parameter."}` + + +## Transfer + +`r if(cell_based){"Transfer is the second phase of dispersal, and consists of the movement of an individual starting from when it emigrates from its natal cell and ending with settlement in another cell or mortality. The main components of this phase are the individual movement ability and navigation capacity in response to the characteristics of the environment. The interaction between these components and their associated costs will determine the distance moved, the movement path and the chance of surviving the transfer phase."}` + +`r if(patch_based){"Transfer is the second phase of dispersal, and consists of the movement of an individual starting from when it emigrates from its natal patch and ending with settlement in another patch or mortality. The main components of this phase are the individual movement ability and navigation capacity in response to the characteristics of the environment. The interaction between these components and their associated costs will determine the distance moved, the movement path and the chance of surviving the transfer phase."}` + +`r if(dispersal_kernel){"The transfer phase is modeled as phenomenological dispersal kernel. The kernel is considered as 'distance kernel', i.e. the statistical distribution of the probability that an individual will move a certain distance [@hovestadtEvolutionEmergenceDispersal2012; @nathanDispersalKernelsReview2012]. The dispersal kernel is only applied to dispersing individuals. If the individual disperses, the distance and the movement direction are determined in continuous space."}` +`r if(dispersal_kernel_simple){"The distance is drawn from a negative exponential distribution with a given mean $\\delta$, and the direction is selected randomly from a uniform distribution between 0 and 2$\\pi$ radians."}` `r if(dispersal_kernel_mixed){"The distance an individual moves is sampled from a mixed kernel given by the combination of two negative exponentials with different means $\\delta_{1}$ and $\\delta_{2}$, occurring with probability $p$ and $1-p$ respectively (Hovestadt et al. 2011). The direction is selected randomly from a uniform distribution between 0 and 2$\\pi$ radians."}` +`r if(dispersal_kernel){"If the arrival point lies beyond the boundary of the landscape, distance and direction are re-drawn."}``r if(cell_based & dispersal_kernel){"The individual is displaced from a random point (using continuous coordinates) inside the natal cell to the arrival cell where the model switches back to discrete space [@bocediProjectingSpeciesRange2012a]. If the arrival point is inside the natal cell, individual starting position, distance and direction are re-sampled until the individual leaves the natal cell."}``r if(patch_based & dispersal_kernel){"The individual is assumed to disperse from a random point in the natal patch and this position, the dispersal distance and direction are drawn until the individual leaves the patch."}` + +`r if(dispersal_kernel & emigration_densdep){"In order to separate emigration and transfer explicitly, and to avoid potential infinite re-sampling, the program requires the mean of the kernel to be greater or equal the cell resolution."}` + +`r if(dispersal_kernel & !emigration_densdep){"The kernel is applied to the entire population without re-sampling. Individuals which draw a short movement distance do not leave the natal "}` +`r if(cell_based & dispersal_kernel & !emigration_densdep){"cell"}``r if(patch_based & dispersal_kernel & !emigration_densdep){"patch"}` +`r if(dispersal_kernel & !emigration_densdep){" and implicitly become sedentary, and therefore the kernel itself defines the proportion of individuals which emigrate."}` + +`r if(dispersal_kernel & !emigration_densdep & emigration_sexdep & emigration_stagedep){"The emigration probability for those stages and sexes which disperse is set to 1.0; otherwise, only a proportion of such individuals would use the kernel to determine whether or not they emigrate."}` + +`r if(dispersal_kernel & !emigration_densdep & emigration_sexdep & !emigration_stagedep){"The emigration probability for those sexes which disperse is set to 1.0; otherwise, only a proportion of such individuals would use the kernel to determine whether or not they emigrate."}` + +`r if(dispersal_kernel & !emigration_densdep & !emigration_sexdep & emigration_stagedep){"The emigration probability for those stages which disperse is set to 1.0; otherwise, only a proportion of such individuals would use the kernel to determine whether or not they emigrate."}` + +`r if(movement_model){"The movement model is fully individual-based and explicitly decribes the movement behaviour of individuals with a level of detail, and hence parameters, which is probably close to the most parsimonious for a mechanisctic movement model."}` + +`r if(movement_SMS){"The stochastic movement simulator (SMS) is a stochastic individual-based model where organisms move through the grid-based, landscape. The model uses similar cost surfaces as the least cost path (LCP) [@adriaensenApplicationLeastcostModelling2003; @chardonIncorporatingLandscapeElements2003; @stevensGeneFlowFunctional2006; @driezenEvaluatingLeastcostModel2007], but it relaxes two of the main assumptions/limitations of the latter. Firstly, individuals are not assumed to be omniscient, but move according to what they can perceive of the landscape within their perceptual range. Secondly, individuals do not know a priori their final destination, which is a reasonable assumption for dispersing individuals. Here, the core components of SMS are briefly described; see Palmer et al. [-@palmerIntroducingStochasticMovement2011] for a complete description of the method."}` +`r if(movement_SMS & habitat_type){"SMS uses cost maps where a relative cost to movement is assigned to each habitat type. Costs are integer numbers and represent the cost of moving through a particular land cover relative to the cost of moving through breeding habitat (conventionally set to a cost of 1). "}``r if(movement_SMS & habitat_quality){"SMS uses cost maps with a relative cost to movement is assigned to each habitat cell. Costs are integer numbers and represent the cost of moving through a particular cell relative to the cost of moving through breeding habitat (conventionally set to a cost of 1). "}` +`r if(movement_SMS){"Individuals take single-cell steps basing their decisions on three parameters: their perceptual range $PR$, the method used to evaluate the landscape within their perceptual range and their directional persistence $DP$, which corresponds to their tendency to follow a correlated random walk. The $PR$ is defined by a number of cells. At each step, the individual evaluates the surrounding habitat in order to determine the effective cost of taking a particular step to each of the eight neighbouring cells. The effective cost is a mean of the cost of the neighbouring cell and the surrounding cells beyond it within the $PR$, and is calculated by "}``r if(movement_SMS & movement_SMS_PRmethod == 1){"arithmetic mean."}``r if(movement_SMS & movement_SMS_PRmethod == 2){"harmonic mean."}``r if(movement_SMS & movement_SMS_PRmethod == 3){"weighted arithmetic mean."}` `r if(movement_SMS){"The effective cost of each neighbouring cell is weighted by the $DP$, which is lowest in the direction of travel. Specifically, $DP$ is raised to the power 4 in the direction of travel, to the power 3 at 45$^\\circ$ to the direction of travel and so on down to the power 0 at 180$^\\circ$ to the direction of travel. Thus, for example, if $DP$ is set to 3.0, an individual is 9 times more likely to continue in its current direction (assuming homogeneous costs) than it is to make a right-angle turn, and 81 times more likely to go straight on than to turn around and retrace its last move. $DP$ can be calculated over more steps than just the previous one (up to a maximum of 14), controlled by the memory size parameter $MemSize$ [@palmerInterindividualVariabilityDispersal2014; @abenSimpleIndividualbasedModels2014]. Increasing the memory size means that an individual retains for longer its tendency to move in a certain direction, and hence paths tend to become somewhat smoother. "}``r if(movement_SMS & goal_type==2){"A goal bias $GB$ was included, i.e. a tendency to move towards a particular destination [@abenSimpleIndividualbasedModels2014]. It is applied only in the ‘negative’ sense of moving away from the natal location, i.e. as a dispersal bias, which is implemented in a similar way to $DP$ but relative to the direction from the natal site to the current location. Moreover, dispersal bias is subject to a decay in strength as a function of the accumulated number of steps taken. This enables a dispersal path to follow a straighter trajectory initially, and later become more tortuous and responsive to perceived landscape costs. The reciprocals of the product of effective cost, $DP$ and dispersal bias, scaled to sum to one, give the probabilities that the individual will move to each neighbouring cell."}` +`r if(movement_SMS & goal_type!=2){"The reciprocals of the product of effective cost and $DP$ , scaled to sum to one, give the probabilities that the individual will move to each neighbouring cell. "}``r if(movement_SMS){"All the dispersing individuals move simultaneously, i.e. at each time-step they all make one move."}` `r if(movement_SMS & patch_based){"The individual is forced to leave the natal patch by increasing its $DP$ ten-fold until it has taken a number of steps (equal to twice the perceptual range) outside the natal patch."}` + +`r if(movement_corrRW){"A simple correlated random walk without any bias is implemented. This model is implemented in continuous space on the top of the landscape grid. Individuals take steps of a constant step length (metres); the direction is sampled from a wrapped Cauchy distribution having a correlation parameter $\\rho$ in the range 0 to 1 [@zollnerSearchStrategiesLandscapeLevel1999; @bartonEvolutionIntelligentDispersal2009]. All individuals take each step simultaneously."}``r if(movement_corrRW & patch_based){"$\\rho$ is automatically set to 0.99 until the individual steps outside the natal patch, after which the value of $\\rho$ set by the user is restored."}` + +## Settlement + +Settlement, or immigration, is the last phase of dispersal, when the organism stops in a new `r if(cell_based){"cell"}``r if(patch_based){"patch"}` of breeding habitat. Dispersing individuals are not allowed to settle in their natal `r if(cell_based){"cell"}``r if(patch_based){"patch"}`. +`r if(dispersal_kernel){"Individuals are displaced directly from the starting location to the arrival location.The suitability of the arrival"}``r if(dispersal_kernel & cell_based){"cell"}``r if(dispersal_kernel & patch_based){"patch"}``r if(dispersal_kernel){"determines whether the disperser is successful or not."}` `r if(dispersal_kernel & !stage_structured & cell_based){"The model has two options if the arrival cell is unsuitable: the individual either dies or it can move to one of the eight neighbouring cells in the case that at least one of them is suitable. In the latter case, if more than one of the neighbouring cells is suitable, the individual is placed in one of them chosen randomly."}``r if(dispersal_kernel & !stage_structured & patch_based){"The model has two options if the arrival cell is unsuitable: the individual either dies or can move to a randomly chosen neighbouring suitable patch, provided that the new patch is only one cell apart from the arrival patch."}``r if(dispersal_kernel & stage_structured & cell_based){"The model has four options if the arrival cell is unsuitable: (1) the individual dies, (2) it can move to a randomly chosen neighboring suitable cell, (3) the individual can stay there waiting until the next dispersal event when it will disperse again according to the set kernel, (4) if both the arrival cell and all eight neighbouring cells are unsuitable the individual can wait in the arrival cell before moving again at the next dispersal event."}``r if(dispersal_kernel & stage_structured & patch_based){"The model has four options if the arrival cell is unsuitable: (1) the individual dies, (2) it can move to a randomly chosen neighbouring suitable patch, provided that the new patch is only one cell apart from the arrival patch, (3) the individual can stay there waiting until the next dispersal event when it will disperse again according to the set kernel, (4) if both the arrival patch and all eventual neighbouring patches are unsuitable the individual can wait in the arrival patch before moving again at the next dispersal event."}` +`r if(dispersal_kernel & cell_based){"The arrival cell is considered suitable if it contains breeding habitat. "}` `r if(dispersal_kernel & patch_based){"The arrival patch is considered suitable if it contains breeding habitat. "}` `r if(dispersal_kernel & cell_based & mate_finding){"Additionally, individuals are required to find a mate, i.e. there has to be at least one individual of the opposite sex present for the cell to be considered suitable for settlement."}` `r if(dispersal_kernel & patch_based & mate_finding){"Additionally, individuals are required to find a mate, i.e. there has to be at least one individual of the opposite sex present for the patch to be considered suitable for settlement."}` + +`r if(movement_model & cell_based){"At each step (made simultaneously) dispersing individuals each evaluate their current cell for the possibility of settling."}` `r if(movement_model & patch_based){"At each step (made simultaneously) dispersing individuals each evaluate their current patch for the possibility of settling. "}` `r if(movement_model){"The individual decides to stop if there is suitable habitat; this is a necessary condition. "}``r if(movement_model & settlement_densdep){"Additionally, the settlement decision is density-dependent. The individual has a probability $p_{s}$ of settling in the "}` `r if(movement_model & settlement_densdep & cell_based){"cell"}``r if(movement_model & settlement_densdep & patch_based){"patch"}``r if(movement_model & settlement_densdep){" $i$, given by:"}` +`r if(movement_model & settlement_densdep & !stage_structured & cell_based){" + +$$p_{s} = \\dfrac{S_{0}}{1+e^{-(N_{i}/K_{i}-\\beta_{i})*\\alpha_{s}}}$$ + +Here, $N_{i}$ and $K_{i}$ are the number of individuals and the carrying capacity of the cell $i$, $S_{0}$ is the maximum settlement probability, $\\beta_{s}$ is the inflection point and $\\alpha_{s}$ is the slope of the function."}` +`r if(movement_model & settlement_densdep & !stage_structured & patch_based){" + +$$p_{s} = \\dfrac{S_{0}}{1+e^{-(N_{i}/K_{i}-\\beta_{i})*\\alpha_{s}}}$$ + +Here, $N_{i}$ and $K_{i}$ are the number of individuals and the carrying capacity of the patch $i$, $S_{0}$ is the maximum settlement probability, $\\beta_{s}$ is the inflection point and $\\alpha_{s}$ is the slope of the function."}` +`r if(movement_model & settlement_densdep & stage_structured & cell_based){" + +$$p_{s} = \\dfrac{S_{0}}{1+e^{-(bN_{i}-\\beta_{i})*\\alpha_{s}}}$$ + +Here, $N_{i}$ is the number of individuals of the cell $i$, $b$ represents the strength of density dependence used for the population dynamics, $S_{0}$ is the maximum settlement probability, $\\beta_{s}$ is the inflection point and $\\alpha_{s}$ is the slope of the function."}` +`r if(movement_model & settlement_densdep & stage_structured & patch_based){" + +$$p_{s} = \\dfrac{S_{0}}{1+e^{-(bN_{i}-\\beta_{i})*\\alpha_{s}}}$$ + +Here, $N_{i}$ is the number of individuals of the patch $i$, $b$ represents the strength of density dependence used for the population dynamics, $S_{0}$ is the maximum settlement probability, $\\beta_{s}$ is the inflection point and $\\alpha_{s}$ is the slope of the function."}` +`r if(movement_model & settlement_densdep & cell_based & mate_finding & !settlement_sexdep){"Individuals are required to find a mate in order to settle. This requirement is satisfied if there is at least one individual of the opposite sex in the cell."}` +`r if(movement_model & settlement_densdep & cell_based & mate_finding & maleFindMate){"Males are required to find a mate in order to settle. This requirement is satisfied if there is at least one female in the cell."}` +`r if(movement_model & settlement_densdep & cell_based & mate_finding & femaleFindMate){"Females are required to find a mate in order to settle. This requirement is satisfied if there is at least one male in the cell."}` +`r if(movement_model & settlement_densdep & patch_based & mate_finding & maleFindMate){"In this specific use case, males are required to find a mate in order to settle. This requirement is satisfied if there is at least one female in the patch."}` +`r if(movement_model & settlement_densdep & patch_based & mate_finding & femaleFindMate){"In this specific use case, females are required to find a mate in order to settle. This requirement is satisfied if there is at least one male in the patch."}` +`r if(movement_model & settlement_densdep & patch_based & mate_finding & !settlement_sexdep){"In this specific use case, individuals are required to find a mate in order to settle. This requirement is satisfied if there is at least one individual of the opposite sex in the patch."}` + +`r if(step_mortality | max_steps){"To avoid having individuals moving perpetually because they cannot find suitable conditions to settle, the model includes "}``r if(step_mortality & max_steps){"a per-step mortality and a maximum number of steps."}``r if(step_mortality & !max_steps){"a per-step mortality."}``r if(!step_mortality & max_steps){"a maximum number of steps."}` `r if(max_steps){"The maximum number of steps defines the maximum time length of the transfer period. When an individual reaches the maximum number of steps, it stops where it is regardless of the suitability of the location."}``r if(max_steps & !stage_structured){"This results in automatic death if the individual stops in unsuitable habitat."}``r if(max_steps & stage_structured){"In the next season, if still alive, it will move again."}` + +`r if(min_steps){"Additionally, a minimum number of steps that each individual must take before settlement is set simulating situations where animals, in a ‘dispersal mode’, will keep moving and not consider settling even if suitable conditions are available (e.g. [@bartonRiskyMovementIncreases2012])."}` +`r if(settlement_sexdep & settlement_stagedep){"Settlement rules are sex- and stage-specific."}` +`r if(settlement_sexdep & !settlement_stagedep){"Settlement rules are sex-specific."}` +`r if(!settlement_sexdep & settlement_stagedep){"Settlement rules are stage-specific."}` + +## Aging + +Aging occurs at the end of each year. + +`r if(management){"## Management"} ` + +`r if(management && translocation){"### Translocation + +- Define a translocation event + +For each translocation event, all individuals matching the given characteristics in the source patch/location are collected. Only individuals, which have not yet dispersed (status 0), or successfully dispersed (status 4 or 5) are considered for translocation. The given number of these individuals are then randomly sampled and tried to be caught with a catching probability of X. If an individual is caught, it is translocated to the target patch/location of this translocation event. If the individual has not been caught, it remains in the source patch/location. Once translocation of an individual is completed, its status is set to 10 as being a translocated individual. Translocated individuals are not allowed to disperse after the translocation event. + +- There are x translocation events happening in the years xyz +- in year x, translocated individuals should have the following characterstics... + +- individuals which were caught are then translocated to the target patch x +- add table? +"}` + +# References diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/style-template.docx b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/style-template.docx new file mode 100644 index 0000000..6e6e260 Binary files /dev/null and b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/skeleton/style-template.docx differ diff --git a/RangeShiftR/inst/rmarkdown/templates/odd_protocol/template.yaml b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/template.yaml new file mode 100644 index 0000000..cb80689 --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/odd_protocol/template.yaml @@ -0,0 +1,4 @@ +name: ODD_protocoll +description: > + A description of the template +create_dir: FALSE diff --git a/RangeShiftR/inst/rmarkdown/templates/parameter_table/skeleton/skeleton.Rmd b/RangeShiftR/inst/rmarkdown/templates/parameter_table/skeleton/skeleton.Rmd new file mode 100644 index 0000000..97b17fa --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/parameter_table/skeleton/skeleton.Rmd @@ -0,0 +1,1056 @@ +--- +title: "Model parameter settings of the study" +subtitle: "`r params$subtitle`" +output: + word_document: + toc: FALSE + pdf_document: + latex_engine: xelatex + keep_md: TRUE + keep_tex: TRUE + md_document: + toc: FALSE +params: + format: "word" + subtitle: "Your study title" +--- + +```{r setup, include=T, echo=F} +knitr::opts_chunk$set(echo = TRUE) + +# global output settings +output_format <- params$format + +# Environmental stochasticity +environmental_stochasticity <- F +env_stoch_loc <- F +env_stoch_K <- F +env_stoch_R <- F + +# Outputs +output_range <- F +output_occ <- F +output_pop <- F +output_ind <- F +output_conn <- F +output_paths <- F +output_heatmaps <-F + +# landscape parameters +local_ext_prob <- F +arti_land <- F +arti_land_continuous <- F +real_land <- F +cell_based <- FALSE +patch_based <- F +habitat_type <- FALSE +habitat_quality <- F +dynamic_landscape <- F +spatiotemporal_demography <- F +resolution <- "" +matrix_input <- F + +#population dynamics +stage_structured <- F +sexual <- F +only_female <- F +asexual <- F +rep_seasons <- 1 +rep_interval <- 0 +mating_simple <- F +mating_complex <- F +demography_sexdep <- F +repro_densdep <- F +repro_stagedep <- F +survival_densdep <- F +survival_stagedep <- F +survival_schedule <- 1 +develop_densdep <- F +develop_stagedep <- F + + +# transfer TODO: check ups, e.g. if SMS T -> movement_model T +dispersal_kernel <- F +dispersal_kernel_simple <- F +dispersal_kernel_mixed <- F +movement_model <- F +movement_SMS <- F +movement_corrRW <- F +movement_cost <- F +movement_cost_file <- F +movement_SMS_PRmethod <- 0 +goal_type <- 0 + +# settlement +max_steps <- F +min_steps <- F +step_mortality <- F +mate_finding <- F +settlement_densdep <- F +settlement_stagedep <- F +settlement_sexdep <- F + +# emigration +emigration_densdep <- F +emigration_sexdep <- F +emigration_stagedep <- F + +# management +translocation <- F +management <- F + +# genetics +neutral_genetics <- F +geneticload <- F +dispersal_genes <- F +emigration_genes <- F +transfer_genes <- F +settlement_genes <- F +genetics <- F + +# neutral genetics +# genetic load +# dispersal genetics + + + +research_question <- NULL # Please add your research question here [In parentheses "your text"] + +# environmental stochasticity +if(s@simul@EnvStoch==0) environmental_stochasticity <- F +if(s@simul@EnvStoch==1) {environmental_stochasticity <- T; env_stoch_loc <- F} +if(s@simul@EnvStoch==2) {environmental_stochasticity <- T; env_stoch_loc <- T} +if(s@simul@EnvStochType==0) {env_stoch_R <- T; env_stoch_K <- F} +if(s@simul@EnvStochType==1) {env_stoch_R <- F; env_stoch_K <- T} + +# outputs +if(s@simul@OutIntRange>=1) output_range <- T +if(s@simul@OutIntOcc>=1) output_occ <- T +if(s@simul@OutIntPop>=1) output_pop <- T +if(s@simul@OutIntInd>=1) output_ind <- T +if(s@simul@OutIntConn>=1) output_conn <- T +if(s@simul@OutIntPaths>=1) output_paths <- T +if(s@simul@SMSHeatMap>=1) output_heatmaps <- T + +# landscape +if(class(s@land)=="ArtificialLandscape") { + arti_land <- T + if (s@land@continuous) arti_land_continuous <- T + } +if(class(s@land)=="ImportedLandscape") real_land <- T +if(anyNA(s@land@LandscapeFile) || length(s@land@LandscapeFile)==0) matrix_input <- T +if(class(s@land)=="ImportedLandscape" & length(s@land@DynamicLandYears)>1) dynamic_landscape <- T +if(length(s@land@PatchFile)==0) cell_based <- T +if(length(s@land@PatchFile)!=0) patch_based <- T +if(s@land@HabPercent) habitat_quality <- T else habitat_type <- T +if(s@simul@LocalExt) local_ext_prob <- T + +if(s@land@nrDemogScaleLayers>0) spatiotemporal_demography <- T + +resolution <- paste(s@land@Resolution, "m x ", s@land@Resolution,"m", sep="") + +# demography +if(s@demog@ReproductionType==0) {asexual <- T; only_female <- T} +if(s@demog@ReproductionType==1) {sexual <- T; mating_simple <- T} +if(s@demog@ReproductionType==2) {sexual <- T; mating_complex <- T} +if(s@demog@Rmax<0){ + stage_structured <- T + survival_schedule <- s@demog@StageStruct@SurvSched + rep_seasons <- s@demog@StageStruct@RepSeasons + rep_interval <- s@demog@StageStruct@RepInterval + if(s@demog@StageStruct@FecDensDep) repro_densdep <- T + if(s@demog@StageStruct@SurvDensDep) survival_densdep <- T + if(s@demog@StageStruct@DevDensDep) develop_densdep <- T + if(s@demog@StageStruct@FecStageWts) repro_stagedep <- T + if(s@demog@StageStruct@SurvStageWts) survival_stagedep <- T + if(s@demog@StageStruct@DevStageWts) develop_stagedep <- T +} + +# dispersal +# emigration +if(s@dispersal@Emigration@DensDep) emigration_densdep <- T +if(s@dispersal@Emigration@SexDep) emigration_sexdep <- T +if(s@dispersal@Emigration@StageDep) emigration_stagedep <- T + +# transfer +if(class(s@dispersal@Transfer)=="DispersalKernel") { + dispersal_kernel <- T + if(s@dispersal@Transfer@DoubleKernel) {dispersal_kernel_mixed <- T} else {dispersal_kernel_simple <- T} +} +if(class(s@dispersal@Transfer)=="CorrRW") { + movement_model <- T + movement_corrRW <- T + if(length(s@dispersal@Transfer@StepMort)>1){ + step_mortality <- T + } else if (s@dispersal@Transfer@StepMort>0){ + step_mortality <- T + } + if(any(s@dispersal@Settlement@MinSteps>0)) min_steps <- T + if(any(s@dispersal@Settlement@MaxSteps>0)) max_steps <- T +} + +if(class(s@dispersal@Transfer)=="StochMove"){ + movement_model <- T + movement_SMS <- T + goal_type <- s@dispersal@Transfer@GoalType + if(is.numeric(s@dispersal@Transfer@Costs)){ + if(sum(s@dispersal@Transfer@Costs)>0) movement_cost <- T + } + if(!is.null(s@land@CostsFile)) {movement_cost_file <- T; movement_cost <- T} + if(length(s@dispersal@Transfer@StepMort)>1){ + step_mortality <- T + } else if (s@dispersal@Transfer@StepMort>0){ + step_mortality <- T + } + movement_SMS_PRmethod <- s@dispersal@Transfer@PRMethod + if(any(s@dispersal@Settlement@MinSteps>0)) min_steps <- T + if(any(s@dispersal@Settlement@MaxSteps>0)) max_steps <- T +} + +# settlement +if(s@dispersal@Settlement@DensDep) settlement_densdep <- T +if(s@dispersal@Settlement@SexDep) settlement_sexdep <- T +if(s@dispersal@Settlement@StageDep) settlement_stagedep <- T +if(any(s@dispersal@Settlement@FindMate)) mate_finding <- T + +# create a data.frame with all the parameter settings +# help function to transform any arrays to latex + array_to_LaTeX <- function(arr){ + rows <- apply(arr, MARGIN=1, paste, collapse = " & ") + matrix_string <- paste(rows, collapse = " \\\\ ") + return(paste("$$\\begin{bmatrix}", matrix_string, "\\end{bmatrix}$$")) + } +# help function to transform list of character vectors to LaTeX table +list_to_LaTeX_array <- function(lst, align = "l") { + stopifnot(is.list(lst)) + + n_cols <- max(lengths(lst)) + align_string <- paste(rep(align, n_cols), collapse = "") + + rows <- vapply( + lst, + function(x) paste(x, collapse = " & "), + character(1) + ) + + body <- paste(rows, collapse = " \\\\ ") + + paste0( + "$\\begin{array}{", align_string, "} ", + body, + " \\end{array}$" + ) +} + + +range <- paste(s@init@minX, s@init@maxX, s@init@minY, s@init@maxY) +PropStages <- as.vector(s@init@PropStages) +res <- toString(PropStages) +if(real_land){ + if(matrix_input){ + nb_landscapes <- length(s@land@LandscapeMatrix) + + LandFile <- "provided as matrices" + + if(length(s@land@PatchMatrix)>0){PatchFile <- "provided as matrices"} + else {PatchFile <- ""} + + if(length(s@land@CostsMatrix)>0){CostsFile <- "provided as matrices"} + else {CostsFile <- ""} + + if(spatiotemporal_demography) demogScaleMatrix <- "provided as matrices" + + + }else{ + nb_landscapes <- length(s@land@LandscapeFile) + + LandFile <- as.vector(s@land@LandscapeFile) + LandFile <- toString(LandFile) + + PatchFile <- as.vector(s@land@PatchFile) + PatchFile <- toString(PatchFile) + + CostsFile <- as.vector(s@land@CostsFile) + CostsFile <- toString(CostsFile) + + if(spatiotemporal_demography) demogScaleFile <- list_to_LaTeX_array(s@land@demogScaleLayersFile)# this is a list of character vectors, one per landscape. How to best transform it for a table? + + } + + Nhabitats <- as.vector(s@land@Nhabitats) + Nhabitats <- toString(Nhabitats) + + K_or_DensDep <- as.vector(s@land@K_or_DensDep) + K_or_DensDep <- toString(K_or_DensDep) + + DynamicLandYears <- as.vector(s@land@DynamicLandYears) + DynamicLandYears <- toString(DynamicLandYears) +} + +if(stage_structured){ + # prepare transition matrix for output + matrix <- array_to_LaTeX(s@demog@StageStruct@TransMatrix) + + # prepare minage for output + MinAge <-toString(s@demog@StageStruct@MinAge) + + # prepare weight matrices for output + if(s@demog@StageStruct@FecStageWts){ + FecStageWtsMatrix <- array_to_LaTeX(s@demog@StageStruct@FecStageWtsMatrix) + } else {FecStageWtsMatrix="Not selected."} + + if(s@demog@StageStruct@DevStageWts){ + DevStageWtsMatrix <- array_to_LaTeX(s@demog@StageStruct@DevStageWtsMatrix) + } else {DevStageWtsMatrix="Not selected."} + + if(s@demog@StageStruct@SurvStageWts){ + SurvStageWtsMatrix <- array_to_LaTeX(s@demog@StageStruct@SurvStageWtsMatrix) + } else {SurvStageWtsMatrix="Not selected."} + + # prepare FecLayer matrices for output + if(spatiotemporal_demography){ + if(length(s@demog@StageStruct@FecLayer) > 0){ + FecLayerMatrix <- array_to_LaTeX(s@demog@StageStruct@FecLayer) + } else{ + FecLayerMatrix <- "Not selected." + } + if(length(s@demog@StageStruct@DevLayer) > 0){ + DevLayerMatrix <- array_to_LaTeX(s@demog@StageStruct@DevLayer) + } else{ + DevLayerMatrix <- "Not selected." + } + if(length(s@demog@StageStruct@SurvLayer) > 0){ + SurvLayerMatrix <- array_to_LaTeX(s@demog@StageStruct@SurvLayer) + } else{ + SurvLayerMatrix <- "Not selected." + } + } else { + FecLayerMatrix <- "Not selected." + DevLayerMatrix <- "Not selected." + SurvLayerMatrix <- "Not selected." + } +} + +if(class(s@dispersal@Emigration@EmigProb)[1]=="matrix"){ + emigprob <- array_to_LaTeX(s@dispersal@Emigration@EmigProb) +} else emigprob <- s@dispersal@Emigration@EmigProb + +if(dispersal_kernel){ + if(class(s@dispersal@Transfer@Distances=="matrix")){ + Distances <- array_to_LaTeX(s@dispersal@Transfer@Distances) + }else Distances <- s@dispersal@Transfer@Distances +} + + + +if(movement_SMS){ + if(class(s@dispersal@Transfer@Costs)=="numeric"){ + Costs <- toString(s@dispersal@Transfer@Costs) + }else Costs <- as.character(s@dispersal@Transfer@Costs) + + if(length(s@dispersal@Transfer@StepMort)>1){ + StepMort_SMS <- toString(s@dispersal@Transfer@StepMort) + } else StepMort_SMS <- s@dispersal@Transfer@StepMort +} + +if(movement_corrRW){ + if(length(s@dispersal@Transfer@StepMort)>1){ + StepMort_CorrRW <- toString(s@dispersal@Transfer@StepMort) + } else StepMort_CorrRW <- s@dispersal@Transfer@StepMort +} + +if(length(s@dispersal@Settlement@Settle)>1) Settle<- array_to_LaTeX(s@dispersal@Settlement@Settle) else Settle <- s@dispersal@Settlement@Settle + +Min_steps <- as.vector(s@dispersal@Settlement@MinSteps) +Min_steps <- toString(Min_steps) + +Max_steps <- as.vector(s@dispersal@Settlement@MaxSteps) +Max_steps <- toString(Max_steps) + +Max_steps_year <- toString(s@dispersal@Settlement@MaxStepsYear) + +# Genetics +if(s@gene@Traits@Neutral) neutral_genetics <- T else neutral_genetics <- F +if(s@gene@Traits@GeneticLoad) geneticload <- T else geneticload <- F +if(s@gene@Traits@EmigrationGenes) emigration_genes <- T else emigration_genes <- F +if(s@gene@Traits@KernelGenes) kernel_genes <- T else kernel_genes <- F +if(s@gene@Traits@CorrRWGenes) corrRW_genes <- T else corrRW_genes <- F +if(s@gene@Traits@SMSGenes) SMS_genes <- T else SMS_genes <- F +if(s@gene@Traits@SettlementGenes) settlement_genes <- T else settlement_genes <- F +if(any(c(neutral_genetics, geneticload, emigration_genes, kernel_genes, corrRW_genes, SMS_genes, settlement_genes))) genetics <- T else genetics <- F +if(any(c(kernel_genes, corrRW_genes, SMS_genes))) transfer_genes <- T else transfer_genes <- F + +if(!is.character(s@gene@PatchList)){ + PatchList <- toString(s@gene@PatchList) +} else PatchList <- s@gene@PatchList + +if(neutral_genetics){ + # Positions: if numeric, array to string + if(is.numeric(s@gene@NeutralGenes@Positions)){ + Neutral_positions <- toString(s@gene@NeutralGenes@Positions) + } else Neutral_positions <- s@gene@NeutralTraits@Positions + + # Initial positions + if(is.numeric(s@gene@NeutralGenes@InitialPositions)){ + Neutral_initpositions <- toString(s@gene@NeutralGenes@InitialPositions) + } else Neutral_initpositions <- s@gene@NeutralGenes@InitialPositions +} + + + +# Management +if(!is.logical(s@management@Translocation)){ + translocation <- T + management <- T + if(length(s@management@Translocation@years)>1){ + Translocation_years <- toString(s@management@Translocation@years) + } else Translocation_years <- s@management@Translocation@years + Translocation_matrix <- array_to_LaTeX(s@management@Translocation@TransLocMat) +} + +## Create data.frames for each module + + +Simulation <- data.frame( + "Parameter "=c( + "Year", + "Replicates", + "Absorbing", + "LocalExt", + "LocalEctProb", + "EnvStoch", + "EnvStochType", + "std", + "ac", + "minR", + "maxR", + "minK", + "maxK", + "OutIntRange", + "OutIntOcc", + "OutIntPop", + "OutIntInd", + "OutIntConn", + "OutIntPaths", + "OutStartPop", + "OutStartInd", + "OutStartConn", + "OutStartPaths", + "SMSHeatMap" + ), + "Description"=c( + "Number of simulated years", + "Number of simulation iterations", + "Whether non-valid cells lead to direct mortality of the individual during transfer", + "Local extinction", + "Local extinction probability", + "Environmental stochasticity (0: none, 1: global, 2: local)", + "Parameter on which environmental stochasticity acts (0: growth rate/fecundity, 1: demographic density dependence)", + "Magnitude of stochastic fluctuations", + "Temporal autocorrelation coefficient", + "Minimum growth rate", + "Maximum growth rate", + "Minimum density dependence value", + "Maximum density dependence value", + "Output of range file", + "Output of occupancy file", + "Output of population file", + "Output of individual file", + "Output of connectivity file", + "Output of SMS paths file", + "Starting year for output population file", + "Starting year for output individual file", + "Starting year for output connectivity file", + "Starting year for output SMS paths file", + "Output SMS heat map raster file" + ), + "Values"=c( + as.character(s@simul@Years), + as.character(s@simul@Replicates), + as.character(s@simul@Absorbing), + as.character(s@simul@LocalExt), + as.character(s@simul@LocalExtProb), + as.character(s@simul@EnvStoch), + as.character(s@simul@EnvStochType), + as.character(s@simul@std), + as.character(s@simul@ac), + as.character(s@simul@minR), + as.character(s@simul@maxR), + as.character(s@simul@minK), + as.character(s@simul@maxK), + as.character(s@simul@OutIntRange), + as.character(s@simul@OutIntOcc), + as.character(s@simul@OutIntPop), + as.character(s@simul@OutIntInd), + as.character(s@simul@OutIntConn), + as.character(s@simul@OutIntPaths), + as.character(s@simul@OutStartPop), + as.character(s@simul@OutStartInd), + as.character(s@simul@OutStartConn), + as.character(s@simul@OutStartPaths), + as.character(s@simul@SMSHeatMap)) + ) + +Initialisation <- data.frame( + "Parameter "=c( + "InitType", + "FreeType", + "NrCells", + "SpType", + "InitIndsFile", + "InitDens", + "IndsHaCell", + "PropStages", + "InitAge", + "minX, maxX, minY, maxY", + "InitFreezeYear", + "RestrictRows", + "RestrictFreq", + "FinalFreezeYear" + ), + "Description "=c( + "Type of initialisation (0: free initialisation according to habitat map, 1: from loaded species distribution map, 2: from initial individuals list file)", + "Option for free initialisation (0: random in given number of cells, 1: all suitable cells/patches)", + "Number of cells to initialise", + "Option for initialisation from species distribution map (0: all suitable cells within all distribution presence cells, 1: all suitable cells within given number of randomly chosen presence cells)", + "Name if the initial individuals list file", + "Number of individuals seeded in each cell/patch (0: at demographic density dependence, 1: at half of the demographic density dependence, 2: according to quasi-equilibrium distribution)", + "Specified number of individuals per hectare", + "Proportion of initialised individuals in each stage", + "Initial age distribution (0: minimum age for the respective stage, 1: random age between the minimum and maximum age for the respective stage, 2: according to a quasi-equilibrium distribution)", + "Restrict initial range", + "Year until which species is confined to its initial range limits", + "Number of rows at northern front to restrict range.", + "Frequency in years at which range is restricted to northern front.", + "The year after which species is confined to its new, current range limits, after a period of range expansion." + ), + "Values"=c( + as.character(s@init@InitType), + as.character(s@init@FreeType), + as.character(s@init@NrCells), + as.character(s@init@SpType), + as.character(s@init@InitIndsFile), + as.character(s@init@InitDens), + as.character(s@init@IndsHaCell), + res, + as.character(s@init@InitAge), + range, + as.character(s@init@InitFreezeYear), + as.character(s@init@RestrictRows), + as.character(s@init@RestrictFreq), + as.character(s@init@FinalFreezeYear)) + ) + +if(real_land){ + Landscape <- data.frame( + "Parameter "=c( + if (matrix_input) "LandscapeMatrix" else "LandscapeFile", + # if(!matrix_input) rep("", nb_landscapes - 1), + "Resolution", + if (matrix_input) "OriginCoords", + "HabPercent", + "NHabitats", + "K_or_DensDep", + if (matrix_input) "PatchMatrix" else "PatchFile", + if (matrix_input) "CostsMatrix" else "CostsFile", + "DynamicLandYears", + if (matrix_input) "SpDistMatrix" else "SpDistFile", + "SpDistResolution", + if (spatiotemporal_demography && matrix_input) "demogScaleLayersMatrix", + if (spatiotemporal_demography && !matrix_input) "demogScaleLayersFile", + if (spatiotemporal_demography) "nrDemogScaleLayers" + ), + "Description "=c( + if(matrix_input) "Matrices of the landscape map(s)" else "Filename(s) of the landscape map(s)", + #if(!matrix_input) rep("", nb_landscapes-1), + "Resolution in meters", + if(matrix_input) "X- and Y-coordinates of the map origin given in meters", + "Whether habitat types/codes or habitat cover/quality", + "Number of different habitat codes", + "Demographic density dependence", + if(matrix_input) "List of matrices of the patch map(s)" else "Filename(s) of the patch map(s)", + if(matrix_input) "List of matrices of the SMS cost map(s)" else "Filename(s) of the SMS cost map(s)", + "Years of landscape changes", + if(matrix_input) "List of one matrix containing the species' initial distribution map" else "Filename of the species initial distribution map", + "Resolution of the distribution map in meters", + if (spatiotemporal_demography && matrix_input) "List of arrays with additional landscape layers which can be used to locally scale certain demographic rates", + if (spatiotemporal_demography && !matrix_input) "List of vectors with file names of additional landscape layers which can be used to locally scale certain demographic rates", + if (spatiotemporal_demography) "number of additional landscape layers for spatial demographic scaling" + ), + "Values"=c( + LandFile, + #rep("", nb_landscapes), + s@land@Resolution, + if(matrix_input) toString(as.vector(s@land@OriginCoords)), + s@land@HabPercent, + Nhabitats, + K_or_DensDep, + PatchFile, + CostsFile, + DynamicLandYears, + if(matrix_input) "provided as matrix" else s@land@SpDistFile, + s@land@SpDistResolution, + if(spatiotemporal_demography && matrix_input) "provided as matrices", + if(spatiotemporal_demography && !matrix_input) demogScaleMatrix, + if(spatiotemporal_demography) s@land@nrDemogScaleLayers + )) +} + +if(arti_land){ + Landscape <- data.frame( + "Parameter "=c( + "propSuit", + "K_orDensDep", + "Resolution", + "dimX", + "dimY", + "fractal", + "hurst", + "continuous", + "minPct", + "maxPct" + ), + "Description "=c( + "Proportion of suitable habitat cells", + "Demographic density dependence", + "Resolution in meters", + "Number of cells along the x-axis", + "Number of cells along the y-axis", + "Whether a random or fractal landscape is generated", + "Hurst exponent", + "Continuous or binary habitat", + "Minimum percentage of habitat cover within a cell", + "Maximum percentage of habitat cover within a cell" + ), + "Values"=c( + s@land@propSuit, + s@land@K_or_DensDep, + s@land@Resolution, + s@land@dimX, + s@land@dimY, + s@land@fractal, + s@land@continuous, + s@land@minPct, + s@land@maxPct + )) +} + +if(s@demog@Rmax>0){ + Demography <- data.frame( + "Parameter"=c( + "Rmax", + "bc", + "ReproductionType", + "PropMales", + "Harem" + ), + "Description"=c( + "Maximum growth rate (number of offspring per female at very low density)", + "Competition coefficient (describes the type of density regulation)", + "Decribes the reproduction type (0: asexual/only female; 1: simple sexual model; 2: sexual model with explicit mating system)", + "Proportion of males in the population", + "Maximum harem size" + ), + "Values"=c( + as.character(s@demog@Rmax), + as.character(s@demog@bc), + as.character(s@demog@ReproductionType), + as.character(s@demog@PropMales), + as.character(s@demog@Harem) + ) + ) +} + +if(s@demog@Rmax<0){ + Demography <- data.frame( + "Parameter "=c( + "Stages", + "TransMatrix", + "MaxAge", + "MinAge", + "RepSeasons", + "RepInterval", + "PRep", + "SurvSched", + "FecDensDep", + "DevDensDep", + "SurvDensDep", + "DevDensCoeff", + "SurvDensCoeff", + "FecStageWtsMatrix", + "DevStageWtsMatrix", + "SurvStageWtsMatrix", + "FecLayer", + "DevLayer", + "SurvLayer", + "PostDestrictn", + "ReproductionType", + "PropMales", + "Harem" + ), + "Description"=c( + "Number of life stages", + "Transition matrix. Defines the development probabilities from each stage into the next as well as the respective survival probabilities and fecundities", + "Maximum age in years", + "Ages which an individual in stage i-1 must already have reached before it can develop into the next stage i.", + "Number of potential reproduction events per year", + "Number of reproductive seasons which must be missed following a reproduction attempt before another reproduction attempt may occur", + "Probability of reproducing in subsequent reproductive seasons", + "Scheduling of survival (0: at reproduction, 1: between reproductive events, 2: annually)", + "whether density dependent fecundity probability is modelled", + "Whether density dependent development probability is modelled", + "Whether density dependent survival probability is modelled", + "Relative density dependence coefficient for development", + "Relative density dependence coefficient for survival", + "Stage-dependent weights in density dependence of fecundity", + "Stage-dependent weights in density dependence of development", + "Stage dependent weights in density dependence of survival", + "Matrix of layer indices for the fecundity if spatially varying. The indices match the scaling layers given in the ImportedLandscape module.", + "Matrix of layer indices for the development if spatially varying. The indices match the scaling layers given in the ImportedLandscape module.", + "Matrix of layer indices for the survival if spatially varying. The indices match the scaling layers given in the ImportedLandscape module.", + "Whether individuals of a population die (FALSE) or disperse (TRUE) if its patch gets destroyed", + "Decribes the reproduction type (0: asexual/only female; 1: simple sexual model; 2: sexual model with explicit mating system)", + "Proportion of males in the population", + "Maximum harem size" + ), + "Values"=c( + s@demog@StageStruct@Stages, + matrix, + s@demog@StageStruct@MaxAge, + MinAge, + s@demog@StageStruct@RepSeasons, + s@demog@StageStruct@RepInterval, + s@demog@StageStruct@PRep, + s@demog@StageStruct@SurvSched, + s@demog@StageStruct@FecDensDep, + s@demog@StageStruct@DevDensDep, + s@demog@StageStruct@SurvDensDep, + s@demog@StageStruct@DevDensCoeff, + s@demog@StageStruct@SurvDensCoeff, + FecStageWtsMatrix, + DevStageWtsMatrix, + SurvStageWtsMatrix, + FecLayerMatrix, + DevLayerMatrix, + SurvLayerMatrix, + s@demog@StageStruct@PostDestructn, + s@demog@ReproductionType, + s@demog@PropMales, + s@demog@Harem + ) + ) +} + +# create df for each type of transfer + +# DispersalKernel +if(dispersal_kernel){ + transfer <- data.frame("Parameter"=c( + "Type", + "Distances", + "DoubleKernel", + "SexDep", + "StageDep", + "IndVar", + "DistMort", + "MortProb", + "InflPoint", + "Slope"), + "Description"=c( + "Type of transfer", + "Matrix containing all dispersal kernel parameters","(#columns) for each stage/sex (#rows).", "Its structure depends on the other parameters.", + "Use a mixed (i.e. double negative exponential) kernel?", + "Sex-dependent dispersal kernel?", + "Stage-dependent dispersal kernel?", + "Individual variability in dispersal kernel traits?", + "Distance-dependent mortality probability?", + "Constant mortality probability", + "Inflection point for the mortality distance dependence function.", + "Slope at inflection point for the mortality distance dependence function." + ), + "Values"=c( + as.character(class(s@dispersal@Transfer)), + Distances,"","", + as.character(s@dispersal@Transfer@DoubleKernel), + as.character(s@dispersal@Transfer@SexDep), + as.character(s@dispersal@Transfer@StageDep), + as.character(s@dispersal@Transfer@IndVar), + as.character(s@dispersal@Transfer@DistMort), + as.character(s@dispersal@Transfer@MortProb), + as.character(s@dispersal@Transfer@InflPoint), + as.character(s@dispersal@Transfer@Slope) + ) + ) +} + +if(movement_SMS){ + transfer <- data.frame("Parameter"=c( + "Type", + "PR", + "PRMethod", + "MemSize", + "DP", + "GoalType", + "GoalBias", + "AlphaDB", + "BetaDB", + "IndVar", + "Costs", + "StepMort", + "StraightenPath" + ), + "Description"=c( + "Type of transfer", + "Perceptual range", + "Method to evaluate the effective cost of a particular step from the landdscape within the perceptual range: 1: Arithmetic mean 2: Harmonic mean 3: Weighted arithmetic mean", + "Size of memory, given as the number of previous steps over which to calculate current direction to apply directional persistence", + "Directional persistence. Corresponds to the tendency to follow a correlated random walk.", + "Goal bias type 0: None, 2: dispersal bias", + "Goal bias strength", + "Dispersal bias decay rate", + "Dispersal bias decay inflection point (number of steps)", + "Individual variability in SMS traits?", + "Describes the landscapes resistance to movement: Either habitat-specific costs for each habitat type or 'file'/'matrix', to indictae to use the cost raster map(s) or matrices specified in the landscape module.", + "Per-step mortality probability: constant or habitat-specific", + "Straighten path after decision not to settle in a patch?" + ), + "Values"=c( + as.character(class(s@dispersal@Transfer)), + s@dispersal@Transfer@PR, + s@dispersal@Transfer@PRMethod, + s@dispersal@Transfer@MemSize, + s@dispersal@Transfer@DP, + s@dispersal@Transfer@GoalType, + s@dispersal@Transfer@GoalBias, + s@dispersal@Transfer@AlphaDB, + s@dispersal@Transfer@BetaDB, + as.character(s@dispersal@Transfer@IndVar), + Costs, + StepMort_SMS, + as.character(s@dispersal@Transfer@StraightenPath) + )) +} + +if(movement_corrRW) { + transfer <- data.frame("Parameter"=c( + "Type", + "StepLength", + "Rho", + "IndVar", + "StraightenPath", + "StepMort" + ), + "Description"=c( + "Type of transfer", + "Step length given in meters", + "Correlation parameter", + "Individual variability in CorrRW traits?", + "Straighten path after decision not to settle in a patch?", + "Per-step mortality probability: constant or habitat-specific" + ), + "Values"=c( + as.character(class(s@dispersal@Transfer)), + s@dispersal@Transfer@StepLength, + s@dispersal@Transfer@Rho, + as.character(s@dispersal@Transfer@IndVar), + s@dispersal@Transfer@StraightenPath, + StepMort_CorrRW + ) + ) +} + + +Dispersal <- data.frame( + "Process "=c( + "Emigration ","", "","","","", + "Transfer ", rep("",nrow(transfer)-1), + "Settlement ", if(!dispersal_kernel){rep("",9)} else{rep("",6)} + ), + "Parameter "=c( + # Emigration + "EmigProb", # can be Matrix or single value + "SexDep", + "StageDep", + "DensDep", + "IndVar", + "UseFullKern", + #Transfer + transfer$Parameter, + "DensDep", + "SexDep", + "StageDep", + "IndVar", + "Settle","",if(dispersal_kernel){rep("",4)}, + if(!dispersal_kernel){c("MinSteps", + "MaxSteps", + "MaxStepsYear")}, + "FindMate" + ), + "Description "=c( + #Emigration + "Emigration probabilities/parameters for each stage/sex", + "Sex-dependent emigration probability?", + "Stage-dependent emigration probability?", + "Density-dependent emigration probability?", + "Individual variability in emigration traits?", + "Shall the emigration probability be derived from dispersal kernel?", + #Transfer + transfer$Description, + #Settlement + "Density-dependent settlement requirements?", + "Sex-dependent settlement requirements?", + "Stage-dependent settlement requirements?", + "Individual variability in settlement traits?", + if(dispersal_kernel){"Settlement codes (for DispersalKernel)"} + else {"Settlement probability parameters"} + ,"for all stages/sexes.", + if(dispersal_kernel){c("0 = die (default)","1 = wait (stage-structured models only)","2 = randomly choose a suitable neighbouring cell or die","3 = randomly choose a suitable neighbouring cell"," or wait (stage-structured models only)")}, + if(!dispersal_kernel){c("Minimum number of steps", + "Maximum number of steps", + "Maximum number of steps per year")}, + "Mating requirements to settle?" + ), + "Values"=c( + #emigration + emigprob, + as.character(s@dispersal@Emigration@SexDep), + as.character(s@dispersal@Emigration@StageDep), + as.character(s@dispersal@Emigration@DensDep), + as.character(s@dispersal@Emigration@IndVar), + as.character(s@dispersal@Emigration@UseFullKern), + #Transfer + transfer$Values, + #Settlement + as.character(s@dispersal@Settlement@DensDep), + as.character(s@dispersal@Settlement@SexDep), + as.character(s@dispersal@Settlement@StageDep), + as.character(s@dispersal@Settlement@IndVar), + Settle, if(dispersal_kernel){rep("",6)} else{""}, + if(movement_model){c(Min_steps, + Max_steps, + Max_steps_year) + }, + toString(s@dispersal@Settlement@FindMate) + ) +) + +# Management +if (management){ +Management <- data.frame( + "Management "=c( + "Translocation ","", "", "", "", "" + ), + "Parameter "=c( + # Translocation + "Catching_rate", + "years", + "TransLocMat", "", "", "" + ), + "Description "=c( + #Translocation + "Probability of successfully catching a chosen individual", + "Year(s) in which translocation events are implemented", + "Translocation matrix with column names ", + "year, source (patch ID or XY coordinates), target (patch ID or XY coordinates), ", + "number of selected individual, minimal age, maximal age, stage and sex", + "Rows represent one specific translocation event." + ), + "Values"=c( + # Translocation + as.character(s@management@Translocation@catching_rate), + Translocation_years, + Translocation_matrix, "", "", "" + ) +) +} + +# neutral_genetics <- F +# geneticload <- F +# dispersal_genes <- F +# emigration_genes <- F +# transfer_genes <- F +# settlement_genes <- F +# genetics <- F + +if(genetics){ + Genetics <- data.frame( + "Genetic parameters"=c(), + "Description"=c(), + "Values"=c() +} +if(neutral_genetics){ + NeutralGenetics <- data.frame( + "Genetic traits"=c( + + ), + "Description"=c( + + ), + "Values"=c( + ) + ) +} +if(geneticload){ + GeneticLoad <- data.frame( + "Genetic traits"=c( + + ), + "Description"=c( + + ), + "Values"=c( + ) + ) +} +if(emigration_genes){ + EmigrationGenes <- data.frame( + "Genetic traits"=c( + ), + "Description" = c( + ), + "Values" = c( + ) +} +if(settlement_genes){ + SettlementGenes <- data.frame( + "Genetic traits"=c( + ), + "Description" = c( + ), + "Values" = c( + ) +} +if(transfer_genes){ + TransferGenes <- data.frame( + "Genetic traits"=c( + ), + "Description" = c( + ), + "Values" = c( + ) +} +if(dispersal_genes){ + DispersalGenes <- data.frame( + +} + + +# delete all off-switches +Landscape <- Landscape[Landscape$Values!=-9 & Landscape$Values!="NULL",] +rownames(Landscape) <- NULL +Demography <- Demography[Demography$Values!=-9 & Demography$Values!="NULL",] +rownames(Demography) <- NULL +Initialisation <- Initialisation[Initialisation$Values!=-9 & Initialisation$Values!="NULL" & Initialisation$Values!="-9 -9 -9 -9",] +rownames(Initialisation) <- NULL +Simulation <- Simulation[Simulation$Values!=-9,] +rownames(Simulation) <- NULL + +# TODO: delete unset/unused variables +knitr::kable(Simulation, col.names = gsub("[.]", " ", names(Simulation)), caption = 'Simulation parameters') +knitr::kable(Landscape, col.names = gsub("[.]", " ", names(Landscape)), caption = 'Landscape parameters') +knitr::kable(Demography, col.names = gsub("[.]", " ", names(Demography)), caption = 'Demography parameters') +knitr::kable(Dispersal, col.names = gsub("[.]", " ", names(Dispersal)), caption = 'Dispersal parameters') +if(management) knitr::kable(Management, col.names = gsub("[.]", " ", names(Management)), caption = 'Management parameters') +knitr::kable(Initialisation, col.names = gsub("[.]", " ", names(Initialisation)), caption = 'Initialisation parameters') +``` + diff --git a/RangeShiftR/inst/rmarkdown/templates/parameter_table/template.yaml b/RangeShiftR/inst/rmarkdown/templates/parameter_table/template.yaml new file mode 100644 index 0000000..38983d2 --- /dev/null +++ b/RangeShiftR/inst/rmarkdown/templates/parameter_table/template.yaml @@ -0,0 +1,4 @@ +name: parameter_table +description: > + A description of the template +create_dir: FALSE diff --git a/RangeShiftR/man/ArtificialLandscape.Rd b/RangeShiftR/man/ArtificialLandscape.Rd new file mode 100644 index 0000000..5844ca4 --- /dev/null +++ b/RangeShiftR/man/ArtificialLandscape.Rd @@ -0,0 +1,67 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_LandParams.R +\docType{class} +\name{ArtificialLandscape} +\alias{ArtificialLandscape} +\title{Create an Artificial Landscape} +\usage{ +ArtificialLandscape(propSuit = 0.5, K_or_DensDep = 10, Resolution = 100, dimX = 65, dimY = 65, + fractal = FALSE, hurst, continuous = FALSE, minPct, maxPct) +} +\arguments{ +\item{propSuit}{Proportion of suitable habitat cells, defaults to \eqn{0.5}.} + +\item{K_or_DensDep}{determines the demographic density dependence of the modelled species and is given in units of the number of individuals per hectare (defaults to \eqn{10}). +Its precise interpretation depends on the structure of the species' \code{\link[RangeShiftR]{Demography}}:\cr +If combined with a \code{\link[RangeShiftR]{StageStructure}}d model, \code{K_or_DensDep} will be used as the \emph{strength of demographic density dependence} \ifelse{html}{\out{b-1}}{\eqn{1/b}}. +If combined with a non-structured model, \code{K_or_DensDep} will be interpreted as \emph{limiting carrying capacity} \eqn{K}.\cr} + +\item{Resolution}{Cell size in meters, defaults to \eqn{100}. (integer)} + +\item{dimX, dimY}{Number of cells along the x- and y-axis, both default to \eqn{65}. (integer) \cr +If \code{fractal=TRUE}, \code{dimX} and \code{dimY} must be powers of \eqn{2} plus \eqn{1} (\eqn{2^n+1}) and \code{dimX} \eqn{\le} \code{dimY} .} + +\item{fractal}{If \code{FALSE} (default), a random landscape is generated. Each cell has a certain probability of being a habitat.\cr +If \code{TRUE}, a fractal landscape is generated. These landscapes contain a greater structure than random landscapes but less than a completely deterministic one.} + +\item{hurst}{Required if \code{fractal=TRUE}: Hurst exponent. Can be any number in the open interval \eqn{(0,1)}.} + +\item{continuous}{Use continuous or binary habitat values to describe each cell?\cr If \code{FALSE} (default), the resulting landscape +is binary, with the two values \emph{Habitat} and \emph{Matrix} (i.e. Non-habitat).\cr If \code{TRUE}, each cell is given a continuous value +between \eqn{0} and \eqn{1}, which describes the percentage of habitat cover or habitat quality. +within a cell. The effective \code{K_or_DensDep} of that cell is calculated as the respective fraction of the value of \eqn{K_or_DensDep}.} + +\item{minPct, maxPct}{Required if \code{continuous=TRUE}: Minimum and Maximum percentage of habitat cover within a cell. Can be any number in the open interval \eqn{(0,1)}, +\code{maxPct} may be exactly \eqn{1}. \code{minPct} must be smaller than \code{maxPct}.} +} +\value{ +A parameter object of class "ArtificialLandscape" +} +\description{ +An artificial landscape can be generated with a random or fractal spatial structure, and may be using binary or continuous habitat values to characterise each cell. +} +\details{ +For theoretical studies which might be related to fundamental questions in eco-evolutionary dynamics or strategic questions concerning +conservation ecology, it is often desirable to use artificial landscapes.\cr +Fractal landscapes are characterised by possessing greater structure than a completely random landscape, but less than a +completely deterministic one \insertCite{with1997application}{RangeShiftR} – but note that the spatial structure of landscapes fragmented +by human activities is often not fractal in nature and, depending upon the research question, other landscape generators may be more +appropriate \insertCite{@see review by @pe2013simple}{RangeShiftR}. + +Internally generated artificial landscapes may not be dynamic. + +The fractal landscape generator implemented in \emph{RangeShiftR} uses the midpoint displacemeant algorithm \insertCite{saupe1988algorithms}{RangeShiftR}. +The Hurst exponent, often referred to as \eqn{H}, describes the degree of spatial autocorrelation of the landscape configuration. +Values close to \eqn{0} represent a low autocorrelation but the generated landscapes still aren't completely spatially independent. +On the contrary, values close to \eqn{1} represent high autocorrelation, i.e. high habitat aggregation.\cr + +Note that more complex algorithms are available for providing fractals where setting \eqn{H = 0.0} results in no spatial autocorrelation +\insertCite{@see @chipperfield2011updated}{RangeShiftR}. For applications where the embedded algorithm is not sufficient, we recommend +to import landscapes generated by these alternative algorithms. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/ColonisationStats.Rd b/RangeShiftR/man/ColonisationStats.Rd new file mode 100644 index 0000000..f95ec67 --- /dev/null +++ b/RangeShiftR/man/ColonisationStats.Rd @@ -0,0 +1,39 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{ColonisationStats} +\alias{ColonisationStats} +\title{ColonisationStats} +\usage{ +ColonisationStats(x, y = getwd(), years = numeric(0), maps = FALSE) +ColonisationStats(x, y = NULL, years = numeric(0)) +} +\arguments{ +\item{x, y}{Either the parameter master (\code{x}) and RS directory path (\code{y}) of the simulation or, alternatively,\cr +the population output as a dataframe (\code{x}). In this case \code{y} is an optional parameter taking the patch map(s) as a raster layer (stack), +which will then be used to produce maps of the patch statistics. For more info on this, see the Details.} + +\item{years}{Years at which the probabilty of occupancy over all replicates will be calculated.} + +\item{maps}{Only in the parameter master (=\code{x}) notation: For each given \code{year}, uses the current patch map (in case of a dynamic landscape, otherwise the static patch map) +to produce a raster of occupancy probabilties. For time to colonisation, uses the current patch map of last year of population record.} +} +\value{ +a list with the elements +\code{occ_prob} (a dataframe with mean (over all replicates) probabilty of occupancy for each patch (in rows) at the given year(s) in columns),\cr +\code{col_time} (a dataframe with first recorded year of colonisation for each patch; with replicates in columns and rows named by patch-IDs),\cr +Optional:\cr\cr +\code{patch_occ_prob} (a raster (stack) with the data from \code{occ_prob} stored in the respective patch cells per given year),\cr +\code{patch_col_time} (a raster with the data from \code{col_time_mean} stored in their respective patch cells) +} +\description{ +This function produces patch statistics and maps on occupancy probability and mean time to colonisation. +} +\details{ +It uses the RangeShiftR 'population' output data. + +In the population dataframe (=\code{x}) notation, there are 3 options on how many maps to produce: +(1) y = NULL: no raster maps produced. +(2) y is a RasterLayer: All statistics projected onto the same patch map. +(3) y is a RasterStack with 2 layers: The first will be used for probabilty of occupancy for all years, the second will be used for time to colonisation. +(4) y is a RasterStack with length(years)+1 layers: The first ones will be used for probabilty of occupancy on each year, the last for time to colonisation. +} diff --git a/RangeShiftR/man/CorrRW.Rd b/RangeShiftR/man/CorrRW.Rd new file mode 100644 index 0000000..6da143a --- /dev/null +++ b/RangeShiftR/man/CorrRW.Rd @@ -0,0 +1,74 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{CorrRW} +\alias{CorrRW} +\title{Set up a Correlated Random Walk} +\usage{ +CorrRW(StepLength = 1, Rho = 0.5, + IndVar = FALSE, + StraightenPath = FALSE, + StepMort = 0.0) +} +\arguments{ +\item{StepLength}{Step length given in meters, defaults to \eqn{1}.\cr If \code{IndVar=TRUE}, \code{NULL} and define the trait in \code{\link[RangeShiftR]{CorrRWTraits}}.} + +\item{Rho}{Correlation parameter \eqn{ρ}, defaults to \eqn{0.5}. Must be in the open interval \eqn{(0,1)}.\cr If \code{IndVar=TRUE}, \code{NULL} and define the trait in \code{\link[RangeShiftR]{CorrRWTraits}}} + +\item{IndVar}{Individual variability in CorrRW traits (i.e. \code{StepLength} and \code{Rho})? Defaults to \code{FALSE}. if \code{TRUE}, define CorrRWTraits in \code{\link[RangeShiftR]{CorrRWTraits}}} + +\item{StraightenPath}{Straighten path after decision not to settle in a patch? Defaults to \code{TRUE}, see Details below.} + +\item{StepMort}{Per-step mortality probability. Can be either \emph{constant}, in which case a single numeric is expected (the default, with +value \eqn{0.0}) or \emph{habitat-specific}, in which case a numeric vector is expected with a length of, respectively, \code{Nhabitats} for an +\code{\link[RangeShiftR]{ImportedLandscape}} with habitat codes (i.e. \code{HabPercent=FALSE})) or length \eqn{2} for an +\code{\link[RangeShiftR]{ArtificialLandscape}} (mortality probabilities for matrix and habitat cells).\cr +All values must be within the half-open interval \eqn{[0,1)}.\cr +For an imported habitat quality landscape (\code{HabPercent=TRUE}), only constant per-step mortality is allowed.} +} +\value{ +a parameter object of class "CorrRW" +} +\description{ +A method to describe \code{\link[RangeShiftR]{Transfer}}: +A simple correlated random walk without any bias; implemented in continuous space on the top of the landscape grid. +} +\details{ +Individuals take steps of a constant \code{StepLength}; the direction is sampled from a wrapped Cauchy distribution having a +correlation parameter \eqn{Rho} in the range \eqn{0} to \eqn{1} \insertCite{barton2009evolution,zollner1999search}{RangeShiftR}. +As for \code{\link[RangeShiftR]{SMS}}, all individuals take each step +simultaneously. In the case of patch-based models, +\eqn{Rho} is automatically set to \eqn{0.99} until the individual steps outside its natal patch, after which the value of +\eqn{Rho} set by the user is restored. \cr +The \code{StepLength} and \eqn{Rho} can be set to vary between individuals and evolve (set \code{IndVar=TRUE}). +In this case, \code{StepLength} and \eqn{Rho} must be set to \code{NULL} and the corresponding traits must be defined in \code{\link[RangeShiftR]{CorrRWTraits}} (see also \code{\link[RangeShiftR]{Genetics}}). \cr +Note that the step length may not evolve below one fifth of +the landscape resolution, and correlation may not evolve above \eqn{0.999}. \cr +Per-step mortality is not allowed to vary between individuals or to evolve. \cr +There is no implementation of sex- or stage-specific CRW. + +When an individual arrives in a non-natal patch and decides not to settle there (as a result of a density-dependent or mate-finding settlement +rule, see \code{\link[RangeShiftR]{Settlement}}), then there is the option that its path is straightened (\code{StraightenPath=TRUE}). This means +that it leaves the patch as soon as possible in order to search for another patch. This is achieved by increasing its path correlation to +\code{Rho}\eqn{=0.999}. However, in certain types of model, e.g. when arbitrary contiguous patches have been defined for what is basically a continuous +population, this can lead to the path always being straightened, as an individual enters a new patch as soon as it has left the one it has +rejected. In such cases, it is advisable to disable the feature (\code{StraightenPath=FALSE}), although care must be taken that individuals +do not become trapped in patches surrounded by very high cost matrix. + +\emph{Mortality}\cr +There are two main sources of mortality: First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. Some individuals may fail +to find suitable habitat before they use up their maximum number of movement steps (\code{MaxSteps} in \code{\link[RangeShiftR]{Settlement}}). +In this first case, dispersal mortality clearly depends upon the proportion of suitable habitat in the landscape and will increase as the +availability of habitat declines.\cr +A second source of dispersal mortality can be specified by the user in form of a per-step probability of mortality (\code{StepMort}. +This can be useful for representing mortality risks that increase with distance or time spent travelling \insertCite{bonte2012costs}{RangeShiftR}. + +Note that the total dispersal mortality experienced will be the sum of the mortalities due to the two sources identified above and, in parameterising the model, +it will be important to recognize this such that dispersal mortality is not double-accounted. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/CorrRWTraits.Rd b/RangeShiftR/man/CorrRWTraits.Rd new file mode 100644 index 0000000..32f324a --- /dev/null +++ b/RangeShiftR/man/CorrRWTraits.Rd @@ -0,0 +1,76 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{CorrRWTraits} +\alias{CorrRWTraits} +\title{Set genetic traits structure for CorrRW traits} +\usage{ +CorrRWTraits(Positions = list("random","random"), +NbOfPositions = c(10, 10), +ExpressionType = rep("additive",2), +InitialAlleleDistribution = rep("normal",2), +InitialAlleleParameters = matrix(c(rep(0.5,2),(rep(0.1,2), nrow=2), +IsInherited = rep(FALSE,2), +MutationDistribution = rep("normal",2), +MutationParameters = matrix(c(rep(0.5,2),(rep(0.2,2), nrow=2), +MutationRate = rep(0.0001,2), +OutputValues = rep(FALSE,2)) +} +\arguments{ +\item{Positions}{Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{NbOfPositions}{Only specify when the \code{Positions} of the CorrRW trait is set to ‘random’, else must be blank (NULL). +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{ExpressionType}{Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{InitialAlleleDistribution}{Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{InitialAlleleParameters}{Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an CorrRW trait. The number of rows must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{IsInherited}{Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{MutationParameters}{Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an CorrRW trait. The number of rows must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} + +\item{OutputValues}{If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +The length must be 2 for the required CorrRW traits \code{Steplength} and \code{Rho}.} +} +\value{ +a parameter object of class "CorrRWTraitsParams" +} +\description{ +Depending on the settings of \code{\link[RangeShiftR]{CorrRW}}, the following traits can be evolvable: + +- The length of a single transfer step \code{Steplength} \cr +- The angle correlation parameter of the random walk \code{Rho} \cr + +The entries of the trait parameters must be provided in the same order as the CorrRW traits are listed above (first \code{StepLength} and second \code{Rho}). If parameters expect a matrix, the rows must match the order of CorrRW traits listed above. +} +\details{ +Traits set to evolve cannot simultaneously be stage-dependent. + +The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. + +Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. + +Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. + +CorrRW traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. + +Dominance values are not applicable for CorrRW traits. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/Demography.Rd b/RangeShiftR/man/Demography.Rd new file mode 100644 index 0000000..dcd69d7 --- /dev/null +++ b/RangeShiftR/man/Demography.Rd @@ -0,0 +1,86 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DemogParams.R +\docType{class} +\name{Demography} +\alias{Demography} +\title{Set Demographic Parameters} +\usage{ +Demography(Rmax, bc = 1.0, StageStruct = FALSE, + ReproductionType = 0, PropMales = 0.5, Harem = 1) +} +\arguments{ +\item{Rmax}{Maximum growth rate. Describes the mean number of offspring per female and reproductive event at very low density. Only required if \code{StageStruct=FALSE}.} + +\item{bc}{Competition coefficient. Describes the type of density regulation, providing the possibility for under-compensatory (\eqn{b_c < 1}), compensatory (\eqn{b_c = 1}) (default) or over-compensatory (\eqn{b_c > 1}) dynamics. Only required if \code{StageStruct=FALSE}.} + +\item{StageStruct}{\code{FALSE} (default) yields a population model with non-overlapping generations.\cr For a stage-structured population, this takes the corresponding parameter object generated by \code{\link[RangeShiftR]{StageStructure}}, which holds all demographic parameters.} + +\item{ReproductionType}{0 = asexual / only female model (default)\cr1 = simple sexual model\cr2 = sexual model with explicit mating system} + +\item{PropMales}{Required if \code{ReproductionType={1,2}}: Proportion of males in the population, between \eqn{0} and \eqn{1}. Defaults to \eqn{0.5}.} + +\item{Harem}{Required if \code{ReproductionType=2}: Maximum harem size. The maximum number of pair bonds that a male can establish. \eqn{Harem = 1} (default) corresponds to monogamy, \eqn{01} to polygyny.} +} +\value{ +a parameter object of class "DemogParams" +} +\description{ +For a simple non-structured population, set its basic demographic parameters here, i.e. the maximum growth rate (\code{Rmax}) and the competition coefficient (\code{bc}). +For a stage-structured population, define its corresponding parameters via \code{\link[RangeShiftR]{StageStructure}} and add it to Demography.\cr +\cr +Choose the Reproduction model that determines if sexes are considered implicitly or explicitly and if a mating system is used. If applicable, set the corresponding parameters, i.e. the proportion of males (\code{PropMales}) and the maximum harem size (\code{Harem}). +} +\details{ +The following information regards the population dynamics of a \strong{non-structured} (\code{StageStruct=FALSE}) population.\cr +For more information on the population dynamics of a \strong{structured} population, see \code{\link[RangeShiftR]{StageStructure}}. + +Populations with non-overlapping generations, i.e. with \strong{no stage-structure} are the appropriate way to model species that have discrete generations. +At each generation the life cycle comprises - in that order - reproduction, death of the adults and offspring dispersal. +Two parameters determine the nature of the demographic density dependence: +the carrying capacity \eqn{K} (given by the argument \code{K_or_DensDep} in the landscape module) and +the competition coefficient \eqn{b_c} (given by the argument \code{bc}). +These discrete generation models can be applied to asexual species, species for which it is assumed that females play the dominant role in spatial dynamics +and for species for which it is considered crucial to model both sexes explicitly. + +\emph{Asexual / only-female models:} (\code{ReproductionType=0})\cr +Recruitment is determined by a stochastic, individual-based formulation of the \insertCite{smith1973;textual}{RangeShiftR} population model, where the number of offspring produced by a single individual in the cell/patch \eqn{i} at time \eqn{t}, is drawn from the following distribution:\cr + +\ifelse{html}{\out{  Njuv(i,t) = Poisson( R(i,t) / (1+|R(i,t) - 1| * (N(i,t) / K(i,t))bc ) ) } }{\deqn{N_juv(i,t) = Poisson( R(i,t) / (1 + |R(i,t) - 1|*( N(i,t) / K(i,t) )^bc ) ) } } + +Here, \eqn{R(i,t)} is the maximum growth rate \code{Rmax} (obtained at very low density only) and \eqn{K(i,t)} is the carrying capacity +at patch \eqn{i} and time \eqn{t}. +Both \eqn{R(i,t)} and \eqn{K(i,t)} can vary in space and time, depending on the model setting. \ifelse{html}{\out{bc}}{\eqn{b_c}} +is the competition coefficient which describes the type of density regulation, providing the possibility for under-compensatory +(\ifelse{html}{\out{bc < 1}}{\eqn{b_c < 1}}), compensatory (\ifelse{html}{\out{bc = 1}}{\eqn{b_c = 1}}) or +over-compensatory (\ifelse{html}{\out{bc > 1}}{\eqn{b_c > 1}}) dynamics.\cr +\cr +\emph{Sexual models}\cr +In this type of models, individuals are explicitly characterized by their sex. The proportion of each sex in the population is controlled by setting the proportion of males (\code{PropMales}). There are two types of possible sexual sub-models:\cr +\cr +\emph{Simple mating system:} (\code{ReproductionType=1})\cr +This is the simplest form of mate limitation. Each female individual is assumed to mate, as long as there is at least one male in the population. As for the asexual case, the Maynard Smith and Slatkin model is used to determine the expected number of +offspring produced by each female. To maintain equivalence between the asexual and sexual versions, the expected value of the Poisson distribution is multiplied by \eqn{2} (Lindström & Kokko 1998):\cr + +\ifelse{html}{\out{  Njuv(i,t) = Poisson( 2 R(i,t) / (1+|R(i,t) - 1| * (N(i,t) / K(i,t) )bc ) ) } }{\deqn{N_juv(i,t) = Poisson( 2 R(i,t) / (1 + |R(i,t) - 1|*( N(i,t) / K(i,t) )^bc ) ) } } + +\emph{Complex mating system:} (\code{ReproductionType=2})\cr +More complex and flexible mating system. Mating is explicitly modelled through a mating function +\insertCite{lindstrom1998,legendre2004,bessa2010}{RangeShiftR}, where the number of mated females \eqn{c} is given by: +\deqn{c = f * min(1, 2hm/(f+hm) )} +where \eqn{f} and \eqn{m} are the numbers of potentially reproductive females and males, respectively, and \eqn{h} is the maximum harem size \code{Harem}, i.e. the maximum number of pair bonds that a male can establish. \eqn{h=1} corresponds to monogamy, \eqn{01} to polygyny. Each potentially reproductive female has a probability of reproducing \ifelse{html}{\out{pr}}{\eqn{p_r}} given by: +\deqn{p_r=c/f} +A Bernoulli trial \eqn{Bern}\ifelse{html}{\out{(pr)}}{\eqn{(p_r)}} determines if the female reproduces or not. For females that reproduce, the number of offspring is determined through the Poisson distribution as stated above. Hence, the specification of the mating system determines the probability for each female to reproduce. However, no explicit pair bonds are formed, and in the cases where traits inheritance is +involved, the father (of all the offspring produced by a single female in a single reproductive event) is selected randomly from the males in the population.\cr +\cr +Populations with overlapping generations, i.e. with \strong{with stage-structure} are the appropriate choice for species in which generations can overlap and individuals can be classified in different stages +(e.g. immature vs. breeding individuals) differing in their demographic parameters. Individuals are characterized by their age and stage. Each stage has a certain fecundity (which will be used as expected value of the Poisson distribution for reproduction), survival +and probability of developing to the next stage. The parameters are provided as classical transition matrices \insertCite{caswell2001}{RangeShiftR} through a \code{\link[RangeShiftR]{StageStructure}} +parameter object. For more information on the population dynamics in this case, see the details there. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/Dispersal.Rd b/RangeShiftR/man/Dispersal.Rd new file mode 100644 index 0000000..2b59133 --- /dev/null +++ b/RangeShiftR/man/Dispersal.Rd @@ -0,0 +1,65 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{Dispersal} +\alias{Dispersal} +\title{Set Dispersal Parameters} +\usage{ +Dispersal(Emigration = Emigration(), + Transfer = DispersalKernel(), + Settlement = Settlement()) +} +\arguments{ +\item{Emigration}{The first phase of dispersal; determines if an individual leaves its natal patch.} + +\item{Transfer}{(or transience) The second phase of dispersal; consists of the movement of an individual departing from its natal patch towards +a potential new patch, ending with settlement or mortality. This movement can be modelled by one of three alternative processes:\cr +- Dispersal kernel: use \code{\link[RangeShiftR]{DispersalKernel}}\cr +- Stochastic movement simulator (SMS): use \code{\link[RangeShiftR]{SMS}}\cr +- Correlated random walk (CRW): use \code{\link[RangeShiftR]{CorrRW}}} + +\item{Settlement}{(or immigration) The last phase of dispersal; determines when the individual stops in a new cell or patch of +breeding habitat.} +} +\value{ +a parameter object of class "DispersalParams" +} +\description{ +Dispersal is defined as movement leading to spatial gene flow. It typically involves three phases, which are all modelled explicitly: +\code{\link[RangeShiftR]{Emigration}}, \code{\link[RangeShiftR]{Transfer}} and \code{\link[RangeShiftR]{Settlement}}.\cr +The specific parameters of each phase are set through their respective functions. For more details, see their documentation.\cr +\cr +The potential evolution of several key dispersal traits is implemented through the possibility of inter-individual variability and heritability. +This option (called \code{IndVar}) can be enabled for each dispersal phase in their respective modules. See the Details below for information on how +to set the associated parameters. Additionally, the \code{\link[RangeShiftR]{Genetics}} module must be defined. +} +\details{ +Dispersal is defined as movement leading to spatial gene flow, and it typically involves three phases: +emigration, transfer and settlement + \insertCite{stenseth1992,clobert2001,clobert2009,clobert2012,bowler2005,ronce2007}{RangeShiftR}.\cr + +The key role of dispersal in species persistence and responses to environmental change is increasingly recognized \insertCite{travis2013dispersal}{RangeShiftR}. +Moreover, the importance of modelling dispersal as a complex process, explicitly considering its three phases, each of which has +´its own mechanisms and costs, has been recently highlighted \insertCite{bonte2012costs,travis2012modelling,travis2013dispersal}{RangeShiftR}. +The implementation of the dispersal process in \emph{RangeShiftR} is based on these recent frameworks and the substantial dispersal +theory that has been developed so far \insertCite{clobert2012}{RangeShiftR}. + +It is possible to model all three phases - emigration, transfer and settlement - with stage- and/or sex-specific parameters via the +switches \code{StageDep} and \code{SexDep} in the respective functions. In the case of sex-dependence, the number of traits is doubled, with +one set coding for the trait in females and the other for the trait in males. As well as being sex-biased, all dispersal phases can be +stage-biased, meaning that parameters can vary for different stage or age classes. + +The options of inter-individual variability in the various dispersal traits can be enabled by setting \code{IndVar=TRUE} for the respective dispersal phase +module and defining the genetic module to simulate heritability and evolution of traits (\code{\link[RangeShiftR]{Genetics}}).\cr +For each such heritable dispersal trait, this requires to set the mean and standard deviation of the distribution of trait values +in the initial population (instead of a constant value each, as in the case of \code{IndVar=FALSE}), +as well as the \code{TraitScaleFactor} for each heritable trait (see \code{\link[RangeShiftR]{Genetics}} documentaion).\cr + +Note, however, that not all combinations of sex-/stage-dependencies with inter-individual variability are implemented.\cr +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/DispersalKernel.Rd b/RangeShiftR/man/DispersalKernel.Rd new file mode 100644 index 0000000..98b3f57 --- /dev/null +++ b/RangeShiftR/man/DispersalKernel.Rd @@ -0,0 +1,164 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{DispersalKernel} +\alias{DispersalKernel} +\title{Set up a Dispersal Kernel} +\usage{ +DispersalKernel(Distances = matrix(c(100),nrow=1), DoubleKernel = FALSE, + SexDep = FALSE, StageDep = FALSE, + IndVar = FALSE, + DistMort = FALSE, + MortProb = 0.0, Slope, InflPoint) +} +\arguments{ +\item{Distances}{Matrix containing all dispersal kernel parameters (#columns) for each stage/sex (#rows) if applicable. Its structure depends on the other parameters, see the Details. +If the mean dispersal distance is constant (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}), \code{Distances} must be a matrix with a single value. Default is to \code{matrix(c(100),nrow=1)}.} + +\item{DoubleKernel}{Use a mixed (i.e. double negative exponential) kernel? (default: \code{FALSE}) Set probability for using Kernel-1 in matrix \code{Distances}.} + +\item{SexDep}{Sex-dependent dispersal kernel? (default: \code{FALSE})} + +\item{StageDep}{Stage-dependent dispersal kernel? (default: \code{FALSE}) Must be \code{FALSE} if \code{IndVar=TRUE}.} + +\item{IndVar}{Individual variability in dispersal kernel traits? (default: \code{FALSE}) Must be \code{FALSE}, if \code{StageDep=TRUE}. If \code{IndVar=TRUE}, specify the trait in \code{\link[RangeShiftR]{KernelTraits}}.} + +\item{TraitScaleFactor}{Required if \code{IndVar=TRUE}: The scaling factor(s) for dispersal kernel traits. A numeric of length \eqn{1} (if \code{DoubleKernel=FALSE}) or \eqn{3} (if \code{DoubleKernel=TRUE}).} + +\item{DistMort}{Distance-dependent mortality probability? (default: \code{FALSE})} + +\item{MortProb}{Constant mortality probability. Required if \code{DistMort=FALSE}, defaults to \eqn{0.0}.} + +\item{InflPoint}{Required if \code{DistMort=TRUE}: Inflection point for the mortality distance dependence function.} + +\item{Slope}{Required if \code{DistMort=TRUE}: Slope at inflection point for the mortality distance dependence function.} +} +\value{ +a parameter object of class "DispersalKernel" +} +\description{ +A method to describe \code{\link[RangeShiftR]{Transfer}}: Dispersal kernels are statistical distributions that are largely used to describe dispersal distances. The main assumption behind them +is that the principal determinant of the probability of an individual dispersing to a particular site is the distance from the starting location.\cr +As for the other dispersal phases, movement abilities and strategies are under multiple selective pressures and can evolve separately. +As a result, the realised dispersal kernels will themselves evolve. +} +\details{ +Two types of dispersal kernels are implemented: negative exponential and a mixed kernel given by two different negative exponentials. +Here, kernels are considered as ‘distance kernels’, i.e. the statistical distribution of the probability that an individual will move a +certain distance \insertCite{hovestadt2012evolution,nathan2012dispersal}{RangeShiftR}. These kernels are specifically used for the \code{\link[RangeShiftR]{Transfer}} phase, meaning that they do +not incorporate information on the \code{\link[RangeShiftR]{Emigration}} or \code{\link[RangeShiftR]{Settlement}} probabilities, which are modelled independently. Therefore, dispersal kernels are +applied only to dispersing individuals and not normally to the entire population. However, the program allows a particular setting where +emigration and transfer are not explicitly separated but are both modelled through the kernel (see the parameter \code{UseFullKern} in +\code{\link[RangeShiftR]{Emigration}} and the Details there). + +There are many possible statistical distributions that have been fitted to dispersal data, which in many cases perform better +than the negative exponential \insertCite{nathan2012dispersal}{RangeShiftR}. However, the negative exponential is still commonly used, has been found useful for +describing dispersal patterns of certain organisms and the combination of two different negative exponentials has been demonstrated to be a +valuable method for discerning between common short-distance and rare long-distance dispersal \insertCite{hovestadt2011all}{RangeShiftR}. + +\emph{Negative exponential} \cr +If the individual disperses, the distance and the movement direction are determined in continuous space. +The distance is drawn from a negative exponential distribution with a given mean \eqn{δ}, and the direction is selected randomly from a uniform +distribution between \eqn{0} and \eqn{2π} radians. + +\ifelse{html}{\out{   p(d;δ) = δ-1 e- d / δ}}{\deqn{ p(d;δ) = 1/δ exp(-d/δ) } } + +If the arrival point lies beyond the boundary of the landscape, distance and direction are re-drawn.\cr +The individual is displaced from a random point (using continuous coordinates) inside the natal cell to the arrival cell where the model +switches back to discrete space \insertCite{bocedi2012projecting}{RangeShiftR}. If the arrival point is inside the natal cell, individual starting position, distance and direction are +re-sampled until the individual leaves the natal cell. In the case of patch-based models, the individual is assumed to disperse from a +random point in the patch and this position, the dispersal distance and direction are drawn until the individual leaves the patch. In order +to separate emigration and transfer explicitly, and to avoid potential infinite re-sampling, the program requires the mean of the kernel +to be greater or equal the cell resolution. This condition is relaxed only in the special case where emigration probability is set to be +density-independent and the kernel is applied to the entire population without re-sampling (the \code{UseFullKern} option in \code{\link[RangeShiftR]{Emigration}}). Individuals +which draw a short movement distance do not leave the natal cell/patch and implicitly become sedentary, and therefore the kernel itself +defines the proportion of individuals which emigrate. When this option is selected, the emigration probability for those stages/sexes +which disperse should be set to \eqn{1.0}; otherwise, only a proportion of such individuals would use the kernel to determine whether or +not they emigrate. + +\emph{Mixed kernel} \cr +The distance an individual moves is sampled from a mixed kernel given by the combination of two negative exponentials +with different means \ifelse{html}{\out{δ1}}{\eqn{δ_1}} and \ifelse{html}{\out{δ2}}{\eqn{δ_2}}, +occurring with probability \ifelse{html}{\out{pI}}{\eqn{p_I}} and \eqn{1-}\ifelse{html}{\out{pI}}{\eqn{p_I}} respectively \insertCite{hovestadt2011all}{RangeShiftR}. +Otherwise, the conditions for the single kernel apply. + +\ifelse{html}{\out{   p(d; δ1,δ2) = pI p(d;δ1) + (1-pI) p(d;δ1)}}{\deqn{ p(d; δ_1,δ_2) = p_I p(d;δ_1) + (1-p_I) p(d;δ_2)}} + +For both types of kernel, inter-individual variability of the kernel traits is possible (set \code{IndVar=TRUE}). Individuals will +carry either one trait for \eqn{δ} or three traits for \ifelse{html}{\out{δ1}}{\eqn{δ_1}}, \ifelse{html}{\out{δ2}}{\eqn{δ_2}} and +\ifelse{html}{\out{pI}}{\eqn{p_I}}, which they inherit from their parents. In this case, you must set the \code{Distances} to \code{NULL} here and specify +them in the \code{\link[RangeShiftR]{KernelTraits}} module to set up the genetics (see \code{\link[RangeShiftR]{Genetics}})\cr +Dispersal kernels can also be sex-dependent (set \code{SexDep=TRUE}). In the case of inter-individual variability, the number of traits is doubled to two trait (female \eqn{δ} +and male δ) or six traits (female and male \ifelse{html}{\out{δ1}}{\eqn{δ_1}}, \ifelse{html}{\out{δ2}}{\eqn{δ_2}} and \ifelse{html}{\out{pI}}{\eqn{p_I}}).\cr +For each trait the initial distribution in the population (as mean and standard variation) must be set in \code{Distances} (instead of only one constant value), +as well as their scaling factors in \code{TraitScaleFactor} (see \code{\link[RangeShiftR]{Genetics}}).\cr + +Further, dispersal kernels can be stage-specific (set \code{StageDep=TRUE}). For this case, inter-individual variability is not implemented. + +All dispersal kernel parameters have to be provided via \code{Distances}, which generally takes a matrix, or - if only a single constant mean distance is +used (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}) - a single numeric. The format of the matrix is defined as follows: The number of columns depend on the options \code{IndVar} and \code{DoubleKernel}. +If \code{DoubleKernel=FALSE}, the mean dispersal distance \eqn{δ} must be specified (in meters). If \code{DoubleKernel=TRUE}, the mean dispersal distances +\ifelse{html}{\out{δ1}}{\eqn{δ_1}} and \ifelse{html}{\out{δ2}}{\eqn{δ_2}} (in meters), as well as the probability \ifelse{html}{\out{pI}}{\eqn{p_I}} of using Kernel-1 must be specified. +If \code{IndVar=TRUE}, \code{Distances} must be \code{NULL} and the dispersal kernel traits must be set in the \code{\link[RangeShiftR]{KernelTraits}} modules. + +All parameters have to be given for each stage/sex if the respective dependence is enabled. If \code{StageDep=TRUE}, state the corresponding stage in the first column. +If \code{SexDep=TRUE}, state the corresponding stage in the next (i.e. first/second) column, with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. The following +table lists the required columns and their correct order for different settings: + +\tabular{ccccc}{IndVar \tab DoubleKernel \tab StageDep \tab SexDep \tab columns \cr + F \tab F \tab F \tab F \tab \eqn{δ} \cr + F \tab F \tab T \tab F \tab stage, \eqn{δ} \cr + F \tab F \tab F \tab T \tab sex, \eqn{δ} \cr + F \tab F \tab T \tab T \tab stage, sex, \eqn{δ} \cr + F \tab T \tab F \tab F \tab \ifelse{html}{\out{δ1, δ2, pI}}{\eqn{δ_1, δ_2, p_I}} \cr + } + +The column headings need not be included, only the numeric matrix is required. The rows require no particular order, but there must be exactly +one row for each stage/sex combination. For example, in the case of a mixed kernel with stage- and sex-dependent distances and no individual variability: +\tabular{ccccc}{ \out{ } 0 \tab \out{ } 0 \tab \out{ } 1000 \tab \out{ } 4500 \tab \out{ } 0.92 \cr + \out{ } 0 \tab \out{ } 1 \tab \out{ } 1400 \tab \out{ } 6000 \tab \out{ } 0.95 \cr + \out{ } 1 \tab \out{ } 0 \tab \out{ } 700 \tab \out{ } 500 \tab \out{ } 0.50 \cr + \out{ } 1 \tab \out{ } 1 \tab \out{ } 500 \tab \out{ } 600 \tab \out{ } 0.55 \cr + \out{ } 2 \tab \out{ } 0 \tab \out{ } 100 \tab \out{ } 0 \tab \out{ } 1.0 \cr + \out{ } 2 \tab \out{ } 1 \tab \out{ } 100 \tab \out{ } 0 \tab \out{ } 1.0 +} + +In the case that the dispersal kernel is applied to the entire +population (i.e. density-independent emigration probability of \eqn{1.0}), the mean dispersal distance can evolve down to zero (i.e. +evolution for no dispersal). In all other cases where emigration and transfer are modelled separately, the mean dispersal distance has a +lower limit which can evolve equal to the landscape resolution. + +\emph{Mortality}\cr +There are two main sources of mortality: First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. When a simple dispersal +kernel is used with no possibility for individuals to search for locally-suitable habitat (see \code{\link[RangeShiftR]{Settlement}}), +mortality occurs to all individuals that arrive in unsuitable habitat. In this first case, dispersal mortality clearly depends upon the +proportion of suitable habitat in the landscape and will increase as the availability of habitat declines.\cr +A second source of dispersal mortality can be specified via the option \code{DistMort}: The probability of mortality is either a constant +(\eqn{m=}\code{MortProb}) or a function of distance \eqn{d} (i.e. individuals that travel further are more likely to die): + +\ifelse{html}{\out{   m(d) = 1 / ( 1 + e-a (d- b) ) } }{\deqn{ m(d) = 1 / ( 1 + exp[-α (d-b) ] ) } } + +with the inflection point \eqn{b=}\code{InflPoint} at which \eqn{m(d=b)=0.5} and the slope \eqn{a=}\code{Slope}.This option may be thought +to represent the increased energetic, time or attritional costs that longer-distance dispersers will experience \insertCite{bonte2012costs}{RangeShiftR}. + +Note that the total dispersal mortality experienced will be the sum of the mortalities due to the two sources identified above and, +in parameterising the model, it will be important to recognize this such that dispersal mortality is not double-accounted. +} +\examples{ +# stage- and sex-dependent mixed kernel +dists_1 <- matrix(c(0,0,1000,4500,0.92,0,1,1400,6000,0.95,1,0,700,500,0.50,1,1,500,600,0.55,2,0,100,0,1.0,2,1,100,0,1.0), byrow = TRUE, ncol = 5) +disp_1 <- DispersalKernel(Distances = dists_1, SexDep = TRUE, StageDep = TRUE, DoubleKernel = TRUE, DistMort = TRUE, Slope = 0.001, InflPoint = 4000) +plotProbs(disp_1, sex = 0, ymax = 0.002) +plotProbs(disp_1, mortality = TRUE) + +# mixed kernel with inter-individual variation +dists_2 <- matrix(c(0,1000,300,2500,500,0.62,0.13,1,3400,860,8000,2800,0.72,0.12), byrow = TRUE, ncol = 7) +disp_2 <- DispersalKernel(Distances = dists_2, SexDep = TRUE, DoubleKernel = TRUE, TraitScaleFactor = c(900,2800,0.14), IndVar = TRUE) +plotProbs(disp_2, xmax = 10000, combinekernels = TRUE) +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/Emigration.Rd b/RangeShiftR/man/Emigration.Rd new file mode 100644 index 0000000..cd9b6a2 --- /dev/null +++ b/RangeShiftR/man/Emigration.Rd @@ -0,0 +1,127 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{Emigration} +\alias{Emigration} +\title{Set Emigration Parameters} +\usage{ +Emigration(EmigProb = 0.0, + SexDep = FALSE, StageDep = FALSE, + DensDep = FALSE, + IndVar = FALSE, + EmigStage, + UseFullKern = FALSE) +} +\arguments{ +\item{EmigProb}{Matrix containing all parameters (#columns) to determine emigration probabilities for each stage/sex (#rows). Its structure depends on the other parameters, see the Details. +If the emigration probability is constant (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}), \code{EmigProb} can take a single numeric. Defaults to \eqn{0.0}.} + +\item{SexDep}{Sex-dependent emigration probability? (default: \code{FALSE})} + +\item{StageDep}{Stage-dependent emigration probability? (default: \code{FALSE}) Must be \code{FALSE} if \code{IndVar=TRUE}.} + +\item{DensDep}{Density-dependent emigration probability? (default: \code{FALSE})} + +\item{IndVar}{Individual variability in emigration traits? (default: \code{FALSE}) Must be \code{FALSE} if \code{StageDep=TRUE}.} + +\item{EmigStage}{Required for stage-structured populations with \code{IndVar=TRUE}: Stage which emigrates. (\code{StageDep} must be \code{FALSE})} + +\item{UseFullKern}{Applicable only if transfer phase is modelled by a \code{\link[RangeShiftR]{DispersalKernel}} and \code{DensDep=FALSE}: Shall the emigration probability be derived from dispersal kernel?} +} +\value{ +a parameter object of class "EmigrationParams" +} +\description{ +Emigration - the first phase of dispersal - is modelled as the probability that an individual leaves its natal patch during the present year (or season). +It is constant by default, but can be set to be density-dependent (\code{DensDep}) and/or to vary for each individual (\code{IndVar}). In case of a stage-structured/sexual +population model, the emigration probabilities can also vary with stage/sex (\code{StageDep/SexDep}). If inter-individual variability is +enabled, the emigration traits can also be allowed to evolve (see \code{\link[RangeShiftR]{EmigrationTraits}}). +} +\details{ +Emigration is modelled as the probability \eqn{d} that an individual leaves its natal patch during the present year or season (every reproductive event +is always followed by dispersal). +Populations with non-overlapping generations have only a single opportunity to emigrate, whereas in a stage-structured population the realised overall emigration +rate can be larger than \eqn{d}, if a stage with \eqn{d>0} lasts for more than one year so that an individual has multiple opportunities to emigrate (each with probability \eqn{d}). + +The emigration probability \eqn{d} can be density-dependent (set \code{DensDep=TRUE}), in which case it is given by the following function, introduced by \insertCite{kun2006evolution;textual}{RangeShiftR}: + +\ifelse{html}{\out{   d(i,t) = D0 / ( 1 + e-αsub>E (N(i,t) / K(i,t) - βsub>E) ) } }{\deqn{ d(i,t) = D_0 / ( 1 + exp[-α_E (N(i,t)/K(i,t) - β_E) ] ) } } + +In the case of stage-structured models this equation is modified to: + +\ifelse{html}{\out{   d(i,t) = D0 / ( 1 + e-αsub>E (b(i,t) * N(i,t) - βsub>E) ) } }{\deqn{ d(i,t) = D_0 / ( 1 + exp[-α_E (b(i,t) N(i,t) - β_E) ] ) } } + +In the first case, \eqn{K(i,t)} is the carrying capacity of the cell/patch \eqn{i} at time \eqn{t} given by \code{K_or_DensDep}. +In the latter case, \eqn{b(i,t)} represents the strength of density dependence and is given by the inverse of \code{K_or_DensDep}.\cr +Further, \ifelse{html}{\out{D0}}{\eqn{D_0}} is the maximum emigration probability, +\eqn{N(i,t)} is the number of individuals in the cell/patch \eqn{i} at time \eqn{t}, +\ifelse{html}{\out{βE}}{\eqn{β_S}} is the inflection point of the function and +\ifelse{html}{\out{αE}}{\eqn{α_S}} is the slope at the inflection point.\cr + +Various functions have been proposed for density dependent emigration \insertCite{hovestadt2010information,poethke2011ability}{RangeShiftR}. +This one was chosen here because it is a flexible function that +allows for modelling a range of different reaction norms, as well as their emergence through evolution. In the case of density-dependent +emigration, we assume individuals to have full knowledge of the population density and carrying capacity (or 1/b, respectively) in their natal patch. +Information acquisition is not explicitly modelled. + +The emigration probability can be allowed to vary between individuals (set \code{IndVar=TRUE}) and to evolve. In the this case, individuals exhibit either one trait +determining the density-independent \eqn{d} (when \code{DensDep=FALSE}), or the three traits \ifelse{html}{\out{D0}}{\eqn{D_0}}, \eqn{α} and +\eqn{β} determining the density-dependent emigration probability (when \code{DensDep=TRUE}).\cr +The traits must be set in \code{\link[RangeShiftR]{EmigrationTraits}} (instead of the constant value(s) in this funciton). +Also, if \code{IndVar=TRUE} is set for a stage-structured population, it is required to specify the stage which emigrates via \code{EmigStage}. + +It is possible to model sex-specific emigration strategies (set \code{SexDep=TRUE}) \insertCite{greenwood1980mating,lawson2007advances}{RangeShiftR}. +In this case the number of traits is doubled; one set coding for the trait(s) in females and the other for the trait(s) in males. +As well as being sex-biased, emigration parameters can be stage-biased (set \code{StageDep=TRUE}) when modelling stage-structured populations. +However, the current version does not accommodate inter-individual variation in emigration strategies when they are stage-dependent. + +If there is no inter-individual variation in emigration, the parameters that determine the emigration probabilities have to be provided via \code{EmigProb}, which generally takes a matrix, or - if only a single constant probability is +used (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}) - a single numeric. If inter-individual variation is enabled, the parameters are set in \code{\link[RangeShiftR]{EmigrationTraits}} and EmigProb is not required. + +The format of the matrix is defined as follows: The number of columns depend on the options \code{DensDep}. If \code{DensDep=FALSE}, the +density-independent probability \eqn{d} must be specified. If \code{DensDep=TRUE}, the functional parameters \ifelse{html}{\out{D0}}{\eqn{D_0}}, \eqn{α} and \eqn{β} (cp. equation above) must be specified. + +All parameters have to be given for each stage/sex if the respective dependence is enabled. If \code{StageDep=TRUE}, state the corresponding stage in the first column. +If \code{SexDep=TRUE}, state the corresponding stage in the next (i.e. first/second) column, with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. The following table lists the required columns and their correct order for different settings: + +\tabular{ccccc}{DensDep \tab IndVar \tab StageDep \tab SexDep \tab columns \cr + F \tab F \tab F \tab F \tab \eqn{d} \cr + F \tab F \tab T \tab F \tab stage, \eqn{d} \cr + F \tab F \tab F \tab T \tab sex, \eqn{d} \cr + F \tab F \tab T \tab T \tab stage, sex, \eqn{d} \cr + T \tab F \tab F \tab F \tab \ifelse{html}{\out{D0}}{\eqn{D_0}}, \eqn{α}, \eqn{β} \cr + } + +The column headings need not be included, only the numeric matrix is required. The rows require no particular order, but there must be exactly one row for each stage/sex combination. For example, in the case of density-, stage- and sex-dependent emigration with no individual variability: +\tabular{ccccc}{ \out{ } 0 \tab \out{ } 0 \tab \out{ } 1.0 \tab \out{ } 20 \tab \out{ } 0.2 \cr + \out{ } 0 \tab \out{ } 1 \tab \out{ } 1.0 \tab \out{ } 20 \tab \out{ } 0.1 \cr + \out{ } 1 \tab \out{ } 0 \tab \out{ } 0.7 \tab \out{ } 25 \tab \out{ } 0.5 \cr + \out{ } 1 \tab \out{ } 1 \tab \out{ } 0.8 \tab \out{ } 50 \tab \out{ } 0.5 \cr + \out{ } 2 \tab \out{ } 0 \tab \out{ } 0.4 \tab \out{ } 10 \tab \out{ } 1.0 \cr + \out{ } 2 \tab \out{ } 1 \tab \out{ } 0.5 \tab \out{ } 20 \tab \out{ } 1.0 +} + +In the special case that \code{DensDep=FALSE} and transfer is realised by \code{\link[RangeShiftR]{DispersalKernel}}, then the option \code{UseFullKern} may be switched on. It +will prevent re-sampling from the kernel if the distance sampled does not move the individual out of its natal cell/patch. Such individuals +are treated as philopatric recruits, and hence the kernel determines the probability of emigration. In this case, the emigration probability +for all stages/sexes which potentially disperse should be set to \eqn{1.0}. +} +\examples{ +# stage- and sex-dependent constant emigration probabilities: +emigmat_1 <- matrix(c(0,0,1,0,1,1,1,0,.7,1,1,.8,2,0,.4,2,1,.5), byrow = TRUE, ncol = 3) +emig_1 <- Emigration(StageDep = TRUE, SexDep = TRUE, EmigProb = emigmat_1) +plotProbs(emig_1) + +# stage- and sex- and density-dependent emigration: +emigmat_2 <- matrix(c(0,0,1,20,.2,0,1,1,20,.1,1,0,.7,25,.5,1,1,.8,50,.5,2,0,.4,10,1,2,1,.5,20,1), byrow = TRUE, ncol = 5) +emig_2 <- Emigration(DensDep = TRUE, StageDep = TRUE, SexDep = TRUE, EmigProb = emigmat_2) +plotProbs(emig_2) + +emig_3 <- Emigration(DensDep = TRUE, IndVar = TRUE, SexDep = TRUE, EmigProb = 0) +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow and Jette Wolff +} diff --git a/RangeShiftR/man/EmigrationTraits.Rd b/RangeShiftR/man/EmigrationTraits.Rd new file mode 100644 index 0000000..788b36a --- /dev/null +++ b/RangeShiftR/man/EmigrationTraits.Rd @@ -0,0 +1,86 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{EmigrationTraits} +\alias{EmigrationTraits} +\title{Set genetic traits structure for emigration traits} +\usage{ +EmigrationTraits(Positions = list("random"), +NbOfPositions = 10, +ExpressionType = "additive", +InitialAlleleDistribution = "normal", +InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), +IsInherited = FALSE, +MutationDistribution = "normal", +MutationParameters = matrix(c(0.5,0.2), nrow=1), +MutationRate = 0.0001, +OutputValues = FALSE) +} +\arguments{ +\item{Positions}{Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{NbOfPositions}{Only specify when the \code{Positions} of the emigration trait is set to \code{"random"}, else must be blank (\code{NULL}). +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{ExpressionType}{Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{InitialAlleleDistribution}{Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{InitialAlleleParameters}{Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{IsInherited}{Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{MutationParameters}{Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between \code{0.0} and \code{1.0}. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{OutputValues}{If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +The length must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} +} +\value{ +a parameter object of class "EmigrationTraitsParams" +} +\description{ +Depending of the settings in \code{\link[RangeShiftR]{Emigration}}, up to three emigration traits evolve: + +- The probability of emigration \ifelse{html}{\out{D0}}{\eqn{D_0}} / \eqn{d} \cr +- The slope of the density dependent emigration function (if \code{DensDep=TRUE}) \ifelse{html}{\out{α}}{\eqn{α}} \cr +- The density threshold of the density dependent emigration function (if \code{DensDep=TRUE}) \ifelse{html}{\out{β}}{\eqn{β}} \cr + +If emigration is sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. + +This results in following number of emigration traits that need to be specifed: + +- 1 entry if emigration is neither density dependent nor sex dependent (\code{DensDep=FALSE} and \code{SexDep=FALSE}): emgiration probability \eqn{d} \cr +- 2 entries if emigration is sex dependent (\code{SexDep=TRUE}): emigration probability of females \eqn{d(f)} and males \eqn{d(m)} \cr +- 3 entries if emigration probability is only density dependent \code{DensDep=TRUE}: \ifelse{html}{\out{D0}}{\eqn{D_0}}, \ifelse{html}{\out{α}}{\eqn{α}} and \ifelse{html}{\out{β}}{\eqn{β}} \cr +- 6 entries if emigration probability is both density dependent (\code{DensDep=TRUE}) and sex dependent (\code{SexDep=TRUE}): \ifelse{html}{\out{D0(f), D0(m)}}{\eqn{D_0(f),D_0(m)}}, \ifelse{html}{\out{α(f), α(m)}}{\eqn{α(f), α(m)}} and \ifelse{html}{\out{β(f), β(m)}}{\eqn{β(f), β(m)}} \cr + +The entries of the trait parameters must be provided in the same order as the emigration traits are listed above. If parameters expect a matrix, the rows must match the order of emigration traits listed above. +} +\details{ +Traits set to evolve cannot simultaneously be stage-dependent. + +The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. + +Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. + +Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. + +Emigration traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. + +Dominance values are not applicable for emigration traits. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/GeneticLoadTraits.Rd b/RangeShiftR/man/GeneticLoadTraits.Rd new file mode 100644 index 0000000..2f7c930 --- /dev/null +++ b/RangeShiftR/man/GeneticLoadTraits.Rd @@ -0,0 +1,106 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{GeneticLoadTraits} +\alias{GeneticLoadTraits} +\title{Set genetic structure for genetic fitness traits} +\usage{ +GeneticLoadTraits(NbGeneticLoads = 1, Positions = list("random"), NbOfPositions = 10, +InitialPositions = list("all"), InitialNbOfPositions = NULL, +InitialAlleleDistribution = "normal", InitialAlleleParameters = matrix(c(0.5,0.1), nrow=1), +InitialDomDistribution = "normal", InitialDomParameters = matrix(c(0.5,0.1), nrow=1), +DominanceDistribution = "normal", DominanceParameters = matrix(c(0.5,0.1), nrow=1), +MutationDistribution = "normal", MutationParameters = matrix(c(0.5,0.2), nrow=1), +MutationRate = 0.0001, OutputValues = FALSE) +} +\arguments{ +\item{NbGeneticLoads}{Number of genetic loads} + +\item{Positions}{Loci positions coding for that trait within genome. Should be provided as a list of strings (if random) and/or vectors of integers (if not random)} + +\item{NbOfPositions}{Number of positions to randomly sample from across the genome for each specified genetic load. Only specify when the \code{Positions} of a genetic load trait are set to \code{"random"}, else must be blank (\code{NULL})} + +\item{InitialPositions}{Specify which positions should be initialised. Should be provided as a list of strings ("random" or "all") and/or vectors of integers (if not random). If enabled, the remaining initial value parameters will only be applied to the selected positions, +and all other positions will be set to 0. Must be in the range of \code{Positions}.} + +\item{InitialNbOfPositions}{Only specify if \code{InitialPositions} for a genetic load is set to \code{"random"}, else must be blank (\code{NULL}). Cannot be greater than \code{NbOfPositions}} + +\item{InitialAlleleDistribution}{Distribution from which to draw initial allele values from. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1}} + +\item{InitialAlleleParameters}{Parameters for the initial distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: +min and max (\code{uniform}), mean and sd (\code{normal}) or shape and scale (\code{gamma}) or one column for \code{negExp}: mean +If genetic loads have different \code{InitialAlleleDistribution} and one requires two columns you need to set the second value to \code{NA} in case of \code{negExp} distribution. +Each row in the matrix corresponds to a genetic load trait.} + +\item{InitialDomDistribution}{Distribution from which to draw initial dominance values. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}, \code{scaled}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1}} + +\item{InitialDomParameters}{Parameters for the initial dominance distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: +min and max (\code{uniform}), mean and sd (\code{normal}) or shape and scale (\code{gamma}) or one column for \code{negExp}: mean +If genetic loads have different \code{InitialDomParameters} and one requires two columns you need to set the second value to \code{NA} in case of \code{negExp} distribution. +Each row in the matrix corresponds to a genetic load trait.} + +\item{DominanceDistribution}{Distribution of dominance values. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}, \code{scaled}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1}} + +\item{DominanceParameters}{Parameters for the dominance distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: + min and max (\code{uniform}), mean and sd (\code{normal}) or shape and scale (\code{gamma}) or one column for \code{negExp}, \code{scaled}: mean +If genetic loads have different \code{DominanceDistribution} and one requires two columns you need to set the second value to \code{NA} in case of \code{negExp} or \code{scaled} distribution. +Each row in the matrix corresponds to a genetic load trait.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be \code{gamma}, \code{uniform}, \code{normal}, \code{negExp}. Should be provided as a vector of strings if \code{NbGeneticLoads > 1}} + +\item{MutationParameters}{Parameters for the mutation distribution: You must provide two colums for \code{uniform}, \code{normal} and \code{gamma} distributions: min and max (\code{uniform}), mean and sd (\code{normal}) + or shape and scale (\code{gamma}) or one column for \code{negExp}: mean +If genetic loads have different \code{DominanceDistribution} and one require two columns you need to set the second value to \code{NA} in case of \code{negExp} distribution.} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between \code{0.0} and \code{1.0}. Should be provided as a vector if multiple genetic loads are specified.} + +\item{OutputValues}{If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +Should be provided as a vector if multiple genetic loads are specified.} +} +\value{ +a parameter object of class "GeneticLoadParams" +} +\description{ +A method to specify genetic fitness traits in the genetic module. You can specify up to 5 genetic loads. +} +\details{ +The alleles of genetic fitness traits represent deleterious mutations which combined expression reduce the viability of juveniles, +i.e. the genetic load. Immediately after birth, all newly born individuals are checked for viability via a Bernoulli trial. +The probability of an individual passing the test and surviving birth is equal to its genetic fitness. +Genetic fitness is 1 by default, but every allele reduces this value by an amount that depends on +its selection coefficient \eqn{s}, and (for diploid systems) the value of its dominance coefficient \eqn{h} relative +to that of the other allele it is paired with. + +More precisely, the genetic fitness \eqn{W} of an individual is the product of the contributions \eqn{w} of each genetic load locus. +The contribution \ifelse{html}{\out{wi}}{\eqn{w_i}} of locus \eqn{i} with alleles \eqn{A} and \eqn{B} is: + +\ifelse{html}{\out{   wi = 1 - hisA - (1 - hi)sB}}{\deqn{w_i = 1 - h_i s_A - (1 - h_i) s_b}} + +\ifelse{html}{\out{   hi = hA / (hA + hB)}}{\deqn{h_i = h_A / ( h_A + h_B )}} + +Selection and dominance coefficients for new alleles (mutations) are drawn from distributions specified by the user: +either a uniform, normal, gamma, or negative exponential, and are not additive. +Dominance coefficients can additionally be sampled from a scaled uniform distribution between zero and a maximum value +that depends on the selection coefficient. This maximum value is equal to \ifelse{html}{\out{e-ksi}}{\deqn{exp(-ks_i)}} where \ifelse{html}{\out{si}}{\eqn{s_i}}is the selection coefficient +for the locus and + +\ifelse{html}{\out{   k = -log (2hD)/sD;*hD}}{\deqn{k = -log(2h_D) / s_D}} + +\ifelse{html}{\out{hD}}{\eqn{h_D}} is the desired mean dominance coefficient; \ifelse{html}{\out{sD}}{\eqn{s_D}} is the mean of the selection coefficient distribution, +calculated after the parameters entered for the (selection coefficients) mutation distribution. + +While selection coefficients should typically be zero or positive, to represent the effect of deleterious mutations, +negative values up to -1 are allowed and may arise if the mutation distribution specified by the user allows it. +In this case, negative values would represent (universally) beneficial mutations that counteract the effect of genetic load. +The total genetic fitness is however bounded to 1. + +To allow more flexibility, there can be up to 5 such genetic load traits, each with a potentially different distribution +of mutations and/or dominance distribution and associated parameters. + +The expression type of genetic load traits is always multiplicative. + +Inheritance is not applicable for genetic load traits. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/Genetics.Rd b/RangeShiftR/man/Genetics.Rd new file mode 100644 index 0000000..2a05323 --- /dev/null +++ b/RangeShiftR/man/Genetics.Rd @@ -0,0 +1,202 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{Genetics} +\alias{Genetics} +\title{Set Genetics parameters} +\usage{ +Genetics(GenomeSize = 10, + ChromosomeEnds = 1, + RecombinationRate = 0.0, + OutputGeneValues = FALSE, + OutputGenesStart = NULL, + OutputGenesInterval = NULL, + OutputGlobalFst = NULL, + OutputGlobalFstStart = NULL, + OutputGlobalFstInterval = NULL, + OutputPairwiseFst = NULL, + OutputPairwiseFstStart = NULL, + OutputPairwiseFstInterval = NULL, + OutputPerLocusFst = NULL, + PatchList = NULL, + NbrPatchesToSample = NULL, + nIndividualsToSample = NULL, + Stages = NULL, + Traits = Traits() + ) +} +\arguments{ +\item{GenomeSize}{Maximum size of genome (number of loci). Should be an integer number.} + +\item{ChromosomeEnds}{Where the genome is split into chromosomes, if empty it is +assumed that one chromosome is equal to GenomeSize. These areas recombine with a +probability of 0.5. Disabled for haploid organisms (no recombination). It should be a vector of integers.} + +\item{RecombinationRate}{Recombination rate (through chromosomal crossover) +across the whole genome (in addition to the chromosomeEnds above). Disabled for haploid organisms (no recombination).} + +\item{OutputGeneValues}{TRUE or FALSE. Output the values of all alleles for all genes of all sampled individuals. +Does not output the resulting trait values: mean and SD of dispersal and genetic fitness traits are +output in the TraitsXPatch, TraitsXCell and/or TraitsXrow output files. Enables the geneValues output files.} + +\item{OutputGenesStart}{Which year should RangeShifter start to produce the output files listed above? Positive integer if any output is \code{TRUE}, otherwise \code{NULL}.} + +\item{OutputGenesInterval}{How frequently to output gene values output. Positive integer if any output is \code{TRUE}, otherwise \code{NULL}.} + +\item{OutputGlobalFst}{Calculate global F-statistics according to Weir & Cockerham (1984)'s method-of-moments approach. Enables the neutralGenetics output file. \code{TRUE} or \code{FALSE}.} + +\item{OutputGlobalFstStart}{Which year should RangeShifter start to produce the global Fst output? Positive integer if \code{OutputGlobalFst} is \code{TRUE}, otherwise \code{NULL}.} + +\item{OutputGlobalFstInterval}{How frequently to output global F-statistics. Positive integer if \code{OutputGlobalFst} is \code{TRUE}, otherwise \code{NULL}.} + +\item{OutputPairwiseFst}{Calculate pairwise F-statistics according to Weir & Cockerham (1984)'s method-of-moments approach. Enables the pairwisePatchNeutralGenetics output files. \code{TRUE} or \code{FALSE}.} + +\item{OutputPairwiseFstStart}{Which year should RangeShifter start to produce the pairwise Fst output? Positive integer if \code{OutputPairwiseFst} is \code{TRUE}, otherwise \code{NULL}.} + +\item{OutputPairwiseFstInterval}{How frequently to output pairwise F-statistics? Positive integer if \code{OutputPairwiseFst} is \code{TRUE}, otherwise \code{NULL}.} + +\item{OutputPerLocusFst}{Calculate F-statistics per-locus estimates according to Weir & Cockerham (1984)'s method-of-moments approach, only if \code{OutputGlobalFst} is \code{TRUE}, for the same interval as the global fst. Enables the perLocusNeutralGenetics output files. \code{TRUE} or \code{FALSE}.} + +\item{PatchList}{Which patches are to be sampled for output. Patches can be +specified according to their patch number, as per the patch layer in a patch-based +model. Or sampled randomly or all patches can be chosen. In a cell-based landscape +random is the only option with number of patches (=cells) specified. Can take "all", "random", "random_occupied" or a vector of integers.} + +\item{NbrPatchesToSample}{If PatchList=random or random_occupied then this specifies +the number of patches to sample randomly. Random: The chosen sample patches remain +the same throughout the simulation, i.e. do not vary between years or replicates +unless artificially generated landscape that is generated afresh between replicates. +Random_occupied: patches are re-sampled every generation among all patches containing at least 1 individual.} + +\item{nIndividualsToSample}{The number of individuals to sample in a patch. If nInds < nIndividualsToSample then sampled individuals = nInds} + +\item{Stages}{The age stages to sample from. Should be a vector of integers. Should be a vector of integers or "all". If NULL, all stages are sampled.} + +\item{Traits}{The genetic traits to be modelled. See \code{\link[RangeShiftR]{Traits}} for more information.} +} +\value{ +a parameter object of class "GeneticsParams" +} +\description{ +Controls heritability and evolution of traits (in case of dispersal traits only if inter-individual variability is enabled (\code{IndVar=TRUE})). +Provides control over the genome size, the number of loci, the recombination rate, output options and the genetic traits to be modelled +} +\details{ +The genome itself is not modelled explicitly, and is instead represented by a genome size, +the set of gene positions and a set of positions for the chromosome breaks (hence determining the number of chromosomes). + +The rate of recombination applies to the entire genome. Genetic linkage does occur, based on the distances between genes controlling different traits. +Multiple traits can use the same position, making the alleles of such genes completely linked, but mutations and expression of different traits are resolved independently, +such that pleiotropy is not possible. +If either option for sexual reproduction is selected, all individuals are diploid. Otherwise, asexual individuals are always haploid (and do not recombine). + +\emph{Output} \cr + +\emph{Sampling} \cr +The volume of genetic output grows quickly with the number of individuals in the simulation, +and it is therefore crucial to first constitute an appropriate sample of the community. +First, a set of patches is sampled from either a random subset of all patches in the landscape, or a pre-specified list of patches. +In either case, the same patches will be sampled through the simulation, and no check is conducted to verify if each patch does contain a +population or is empty. There is an additional option to sample patches from a random subset of occupied patches, +which will change from one generation to the next. +Second, a number of individuals are sampled from the population of each sampled patch. In stage-structured populations, +it is possible to select only certain stages to be sampled. \cr + +\emph{Allele values}\cr + +This output, if enabled (\code{OutputGeneValues = TRUE}), will write all alleles values of the sampled individuals for the selected trait(s) to \emph{Sim_Land_Rep_geneValues}, +along with some contextual information.\cr + +Each row corresponds to a single gene:\cr + + 1. Year\cr + 2. Generation\cr + 3. Individual ID\cr + 4. Trait type (e.g. “kernel_meanDist1”, matching the value given as input)\cr + 5. Position in the genome\cr + 6. Value of the allele on the first chromosome\cr + 7. Dominance coefficient for the allele on the first chromosome (this will be 0 except for genetic fitness traits)\cr + 8. (If diploid) Value of the allele on the second chromosome\cr + 9. (If diploid) Dominance coefficient for the allele on the second chromosome\cr + +\emph{Neutral genetics} \cr + +The standard neutral genetics output, \emph{Sim_Land_neutralGenetics}, writes the following entries (one row per generation): \cr +1. Replicate number \cr +2. Year \cr +3. Generation \cr +4. Number of sampled patches with a non-zero population \cr +5. Total number of sampled individuals \cr +6. Weir & Cockerham’s \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} (if enabled) \cr +7. Weir & Cockerham’s \emph{\ifelse{html}{\out{Fis}}{\eqn{F_is}}} (if enabled) \cr +8. Weir & Cockerham’s \emph{\ifelse{html}{\out{Fit}}{\eqn{F_it}}} (if enabled) \cr +9. Global allelic diversity, calculated as the mean number of alleles per locus for the entire sample. \cr +10. Local allelic diversity, calculated as the mean number of alleles per locus for each sampled patch, then averaged over patches. \cr +11. Number of globally fixed alleles. \cr +12. Mean number of fixed alleles per patch. Note that this may differ from the number of globally fixed alleles, for example if an allele is fixed in one patch but polymorphism exists in other patches. \cr +13. Observed heterozygosity Ho, calculated as the mean number of heterozygous loci per individual per locus. \cr + +RangeShifter estimates standard F-statistics as \insertCite{cockerham1969}{RangeShiftR}’s \ifelse{html}{\out{θ}}{\eqn{θ}} statistics, using the classic method-of-moments estimator +of \insertCite{weir1984}{RangeShiftR}. \cr + +In short, \emph{\ifelse{html}{\out{θ}}{\eqn{θ}}} \emph{(\ifelse{html}{\out{Fst}}{\eqn{F_st}})} measures the correlation between alleles within sub-populations (patches) +relative to the complete sampled population, +\emph{f(\ifelse{html}{\out{Fis}}{\eqn{F_is}})} the correlation between alleles within individuals relative to the sub-population and \emph{F(\ifelse{html}{\out{Fit}}{\eqn{F_it}})} the correlation between alleles +within individuals relative to the complete sampled population (see \insertCite{holsinger2009}{RangeShiftR} for an introduction). \cr + +While the methods are designed for diploid systems, it is possible to compute F-stats for haploid organisms – in this case, +heterozygosity terms evaluate to zero. Reminder: in RangeShifter, asexual species are always haploid, and sexual organisms are always diploid! + +See the RangeShifter manual for more details on the calculation of these statistics. \cr + +\emph{Per-locus neutral genetics} \cr + +If the per locus \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} parameter is enabled \code{OutputPerLocusFst==TRUE}, RangeShifter outputs an additional file +\emph{Sim_Land_perLocusNeutralGenetics} with one entry for each neutral locus: \cr + +1. Year \cr +2. RepSeason \cr +3. Locus, the ID of locus \eqn{l} \cr +4. \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}}, the value of \emph{\ifelse{html}{\out{Fst,l}}{\eqn{F_st,l}}} for locus \emph{l} \cr +5. \emph{\ifelse{html}{\out{Fis}}{\eqn{F_is}}}, the value of \emph{\ifelse{html}{\out{Fis}}{\eqn{F_is,l}}} for locus \emph{l} \cr +6. \emph{\ifelse{html}{\out{Fit}}{\eqn{F_it}}}, the value of \emph{\ifelse{html}{\out{Fit}}{\eqn{F_it,l}}} for locus \emph{l} \cr +7. Het, the sample-level observed heterozygosity (\emph{\ifelse{html}{\out{Ho}}{\eqn{H_o}}}) for locus \eqn{l} \cr +8. One column \emph{patch__het} for each patch \emph{i} in the sample, indicating \emph{\ifelse{html}{\out{Ho}}{\eqn{H_o}}} for patch \emph{i} and locus \emph{l}. +If patches have been sampled with the “random_occupied” option, then the patches number will not correspond to the sampled patches, instead ranging from 1 to the number + of patches sampled. This is because it is not known which patches will be sampled (and they may change) at the time of writing the headers.\cr + +\emph{Pairwise patch neutral genetics}\cr + +If the pariwise \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} parameter is enabled (\code{OutputPairwiseFst=TRUE}), a pairwise \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} matrix is constituted and filled with the corresponding +values of \emph{\ifelse{html}{\out{βii’}}{\eqn{β_ii’}}} for each pair of patches in the sample. Values along the diagonal are set to zero. \cr + +In this case, there is one row of output for each pair: \cr + 1. Year\cr + 2. Generation\cr + 3. Patch ID of the first patch \cr + 4. X coordinate of first patch \cr + 5. Y coordinate of first patch \cr + 6. Patch ID of the second patch (same as 3. along the diagonal of the matrix) \cr + 7. X coordinate of second patch \cr + 8. Y coordinate of second patch \cr + 9. Pairwise \emph{\ifelse{html}{\out{Fst}}{\eqn{F_st}}} \cr + +\emph{Traits} \cr + +In the case of inter-individual variability and evolution of the dispersal traits, +it is possible to output the mean traits of the population. There are two types of traits output:\cr + +1. \emph{Mean traits by cell/patch (Sim0_TraitsXcell.txt or Sim0_TraitsXpatch.txt}). This file reports mean and standard deviation of the varying traits for each cell/patch, +for each replicate and reproductive season at the set year interval. \cr +2. \emph{Mean traits by row (Sim0_TraitsXrow.txt)}. The mean and standard deviation of the varying traits are computed at the row (\emph{y}) level, +pulling together all the populations occupying cells in \emph{y}. Values are reported for each replicate and reproductive season at the specified yearly interval. +This is particularly useful for analysing the structuring of traits along latitudinal gradients. It is possible to compute this output only for cell-based models. \cr + +Data for these outputs are collected at the same time as for the range and population outputs, i.e. before reproduction at each reproductive season at the set year interval and at the end of the simulation. \cr +} +\references{ +\insertAllCited{} +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/ImportedLandscape.Rd b/RangeShiftR/man/ImportedLandscape.Rd new file mode 100644 index 0000000..2785682 --- /dev/null +++ b/RangeShiftR/man/ImportedLandscape.Rd @@ -0,0 +1,174 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_LandParams.R +\docType{class} +\name{ImportedLandscape} +\alias{ImportedLandscape} +\title{Import a Landscape from file} +\usage{ +ImportedLandscape(LandscapeFile, + LandscapeMatrix, + Resolution = 100, + OriginCoords = c(0,0), + HabPercent = FALSE, + Nhabitats, K_or_DensDep = 10, + PatchFile = NULL, + PatchMatrix = list(), + CostsFile = NULL, + CostsMatrix = list(), + DynamicLandYears = 0, + SpDistFile = NULL, + SpDistMatrix = list(), + SpDistResolution, + demogScaleLayersFile, + demogScaleLayersMatrix, nrDemogScaleLayers) +} +\arguments{ +\item{LandscapeFile}{Filename(s) of the landscape habitat map(s) which shall be imported from the Inputs-folder. See the Details for information on the required format.} + +\item{LandscapeMatrix}{List of matrices of the landscape habitat raster(s); contains each cells' habitat suitability or land cover index.} + +\item{Resolution}{Cell size in meters, defaults to \eqn{100}. (integer)} + +\item{OriginCoords}{X- and Y-coordinates of the map origin given in meters as a vector of length 2. Defaults to \eqn{0,0}.} + +\item{HabPercent}{If \code{FALSE} (default), unique integer habitat codes are expected in the imported map to characterise the habitat of each cell. This requires to set \code{Nhabitats}. \cr +If \code{TRUE}, continuous values are expected, ranging from \eqn{0.0} to \eqn{100.0}, that represent percentages of habitat cover or quality.\cr +Make sure your imported landscape file uses the specified standard (see Details below).} + +\item{Nhabitats}{Required if \code{HabPercent=FALSE}: Number of habitats in the imported landscape if unique integer habitat codes are used. (integer)} + +\item{K_or_DensDep}{determines the demographic density dependence of the modelled species and is given in units of the number of individuals per hectare (defaults to \eqn{10}). +Its precise interpretation depends on the structure of the species' \code{\link[RangeShiftR]{Demography}}:\cr +If combined with a \code{\link[RangeShiftR]{StageStructure}}d model, \code{K_or_DensDep} will be used as the \emph{strength of demographic density dependence} \ifelse{html}{\out{b-1}}{\eqn{1/b}}. +If combined with a non-structured model, \code{K_or_DensDep} will be interpreted as \emph{limiting carrying capacity} \eqn{K}.\cr +The expected format:\cr +If \code{HabPercent=FALSE}: a vector of length \code{Nhabitats}, specifying the respective \code{K_or_DensDep} for every habitat code.\cr +If \code{HabPercent=TRUE}: \code{K_or_DensDep} is interpreted as the maximum \code{K_or_DensDep} reached in cells with \eqn{100}\% habitat. All other cells hold the respective fraction of \eqn{K_or_DensDep}.} + +\item{PatchFile}{Filename(s) of the patch map(s) which shall be imported, default is \code{NULL}.} + +\item{PatchMatrix}{List of matrices of the patch raster(s); contains each cells' patch index.} + +\item{CostsFile}{Filename(s) of the SMS cost map(s) which shall be imported, default is \code{NULL}.} + +\item{CostsMatrix}{List of matrices of the SMS cost raster(s); contains each cells' SMS cost.} + +\item{DynamicLandYears}{Integer vector indicating the years of landscape changes. For a non-dynamic landscape its only entry is \eqn{0} (default). +For a dynamic landscape, \code{DynamicLandYears} lists the years in which the corresponding habitat maps in \code{LandscapeFile} and - if applicable - their respective patch and/or costs +maps (in \code{PatchFile},\code{CostsFile}) are loaded and used in the simulation. More details below.} + +\item{SpDistFile}{Filename of the species initial distribution map which shall be imported (*.txt). Default is \code{NULL}.} + +\item{SpDistMatrix}{List of one matrix containing the species' initial distribution raster.} + +\item{SpDistResolution}{Required if \code{SpDistFile} is given: Cell size of the distribution map in meters. (integer) Must be an integer multiple of the landscape resolution.} + +\item{demogScaleLayersFile}{List of vectors with file names of additional landscape layers which can be used to locally scale certain demographic rates and thus allow them to vary spatially. +The list must contain equally sized vectors providing file names, one vector for each element in \code{DynamicLandYears}, which are interpreted as stacked layers. +The files must match the landscape in resolution and dimension. The size of each vector corresponds to the various layers (of which there are \code{nrDemogScaleLayers}). +Can only be used in combination with habitat quality maps, i.e. when \code{HabPercent=TRUE}. It must contain percentage values ranging from \eqn{0.0} to \eqn{100.0}.} + +\item{demogScaleLayersMatrix}{List of arrays that describe additional landscape layers which can be used to locally scale certain demographic rates and thus allow them to vary spatially. +The list must contain equally sized 3D-arrays, one for each element in \code{DynamicLandYears}, which are interpreted as stacked layers. +The arrays' first two dimensions correspond to the x- and y-dimensions of the maps in \code{LandscapeMatrix} and must match in resolution and offset; +the third dimension indexes the various layers (of which there are \code{nrDemogScaleLayers}). +Can only be used in combination with habitat quality maps, i.e. when \code{HabPercent=TRUE}. Contain percentage values ranging from \eqn{0.0} to \eqn{100.0}.} + +\item{nrDemogScaleLayers}{number of additional landscape layers for spatial demographic scaling} +} +\value{ +A parameter object of class ImportedLandscape +} +\description{ +Provide the filename(s) (\code{LandscapeFile}) or the matrices (\code{LandscapeMatrix}) of the map(s) to be imported, their +resolution, origin coordinates in case you use matrices and, if applicable, the number of habitat codes (\code{Nhabitats}) +as well as their respective demographic density dependence (\code{K_or_DensDep}). + +For a dynamic landscape, the year in which each landscape is loaded has to be provided. + +Other, optional input maps are:\cr +- Patch map(s) to define habitat patches - as filenames or matrices,\cr +- SMS cost map(s) to define landscape resistance to - as filenames or matrices,\cr +- a distribution map to define an initial species distribution - as filenames or matrices, \cr +- demographic scaling layers - as filenames or matrices. +} +\details{ +\emph{RangeShiftR} requires all landscape related inputs to be either text files in ESRI ASCII raster format or matrices. + +Text files must have the following six header lines: +\tabular{ll}{\code{ncols} \tab Number of columns \cr +\code{nrows} \tab Number of rows \cr +\code{xllcorner} \tab x-coordinate (longitude) of the lower-left corner \cr +\code{yllcorner} \tab y-coordinate (latitude) of the lower-left corner \cr +\code{cellsize} \tab Resolution (in meters) \cr +\code{NODATA_value} \tab Value for cells having missing data (usually -9999) } + +The rest of the file is a grid containing a value for each cell, one line per row. + +If you want to use matrices for landscape inputs, you must provide the origin coordinates \code{OriginCoords}. +\code{OriginCoords} is the map origin given as a vector of length 2 where the first entry is the x-coordinate (longitude) of the lower-left corner and +the second entry is the y-coordinate (latitude) of the lower-left corner.\cr + +\code{RangeShiftR} can use two different types of habitat maps:\cr +\itemize{ + \item \emph{Raster with habitat codes} (\code{HabPercent=FALSE})\cr In this option each habitat or land-cover type has a unique integer code. Each cell in the file contains a single habitat code and \eqn{100} percent coverage is assumed for the cell. The landscape is therefore composed of discrete habitat cells. The codes are required to be sequential integers starting from \eqn{1} and ranging to \code{Nhabitats}.\cr + \item \emph{Raster with habitat quality} (\code{HabPercent=TRUE})\cr Each cell in the landscape is assigned a continuous percentage value between \eqn{0.0} and \eqn{100.0} of the maximum \code{K_or_DensDep}. There are no explicit habitat or land-cover types. This allows integrating different methods for calculating the habitat suitability for a given species. For example, qualities can result from + different methods of suitability modelling, which incorporate multiple variables like habitat types, elevation, climate, etc. In the current version of the program, a straight-line relationship between the habitat quality and the actual density-dependence of the population dynamics (i.e. \eqn{K} or \eqn{1/b} in a non-structured or structured population, respectively) is assumed. + Therefore, the quality should be scaled accordingly in case of a curvilinear relationship. + } + +\emph{Patch map} \cr +The simulation can be run as a \emph{patch-based model} on the same habitat map described above. An additional file/matrix must be provided through \code{PatchFile} / \code{PatchMatrix}: a raster map of the same landscape, where +each cell contains the ID number of the patch to which it belongs. Each patch must have a unique positive integer ID. The ID of every cell that does not belong to a patch (i.e. non-habitat/matrix) must be zero. +Note that a single patch is the unit at which the density dependence in the population dynamics acts. Therefore, a patch can be discontinuous, i.e. it can contain cells that do not belong to the patch if they +are assumed not to affect the dynamics, or on the other hand, patch cells that are not physically contiguous to the rest of the patch cells. + +\emph{Costs layer} \cr +Only used if the simulation is run with \code{\link[RangeShiftR]{SMS}} as its transfer module and the landscapes resistance to movement is given via a costs raster map (see argument \code{Costs} in \code{SMS()}). +In this case, the specified raster \code{CostsFile} / \code{CostsMatrix} has to match the landscape raster in extent, coordinates and resolution, and each cell contains a cost value, with the minimal possible cost being \eqn{1}. +Importing a cost layer is the only option when the landscape comprises habitat coverage or quality. + +\emph{Initial distribution} \cr +A \emph{species distribution map} can be overlaid on top of the habitat map and can be used to define an initial distribution. The map or raster matrix is provided through \code{SpDistFile} / \code{SpDistMatrix} and must be aligned with the landscape map. The extent of the map does not have to be necessarily +the same as the landscape. The resolution can be the same or coarser, provided that it is a multiple of the landscape resolution. For example, if the landscape cell size is \eqn{250m}, the species distribution can be at the resolution of \eqn{250m}, \eqn{500m}, \eqn{750m}, \eqn{1000m} etc. +Each cell of the species distribution map must contain either \eqn{0} (species absent or not recorded) or \eqn{1} (species present). + + \emph{Demographic scaling layers} \cr +A number of additional landscape layers can be provided in \code{demogScaleLayersMatrix} or \code{demogScaleLayersFiles}, depending on what input type you choose, to locally scale certain demographic rates and thus allow them to vary spatially. +This can only be used in combination with habitat quality maps, i.e. when \code{HabPercent=TRUE}, and with a stage-structured population model. +The additional layers contain percentage values ranging from \eqn{0.0} to \eqn{100.0}. Chosen demographic rates for a specified stage and sex can be mapped to one of these scaling layers using the +parameters \code{FecLayer}, \code{DevLayer}, and \code{SurvLayer} in \code{\link[RangeShiftR]{StageStructure}}. If a demographic rate varies spatially, its value in the transition matrix \code{TransMatrix}) +is now interpreted as a maximum value, while the realised local value in each cell or patch is determined as this maximum value scaled by the percentage given in the respective mapped scaling layer. +For a patch-based landscape, the scaling percentage of a patch is given by the average percentage of its constituent cells. +Potential density-dependence mediated by the strength 1/b still takes effect also for spatially-varying demographic rates. The respective base values φ_0, σ_0 or γ_0 are then replaced by their locally scaled values. + +\emph{Dynamic landscapes} \cr +An imported landscape may be dynamic, i.e. the attributes of cells (either habitat class or quality index) and its patch number (if the model is patch-based) may be changed at specified years during the course of +a simulation. Note that any landscape change occurs at the start of the year, i.e. before the first/only reproductive season. In a patch-based model, the shape of patches may change, patches may +be removed and new patches may be created where there was previously inter-patch matrix. Thus some populations may be extirpated (in a non-structured population, all individuals die; in a stage-structured population, +all individuals either die or have an immediate opportunity to disperse), and new populations may arise from colonisation of newly suitable areas. + +However, there are certain restrictions. Any part of the original landscape which was a ‘no-data’ region (e.g. the sea or land beyond a study area boundary) must remain in that state for the whole simulation. +The identity of patches is not cross-checked between changes, and care must therefore be taken to ensure consistency; otherwise, a patch (and its resident population) can jump to a distant location or be split into +two or more disjunct parts, with unpredictable and possibly weird consequences. It is legitimate for a patch to be split into two or more separate patches (e.g. by construction of a motorway or some other barrier), +but any existing population will remain with the part (if any) which retains the original patch number, and populations within the other parts (having a new patch number) must arise through colonisation. +Possible ways to work around this restriction include: +\itemize{ + \item Assign to all post-change parts of the original patch a new, unique patch number and specify that dispersal is allowed after population destruction (which is possible only for a structured population), in which +case some colonisation of the new patches should occur. Note that the connectivity matrix will be misleading in such cases, as every successful ‘disperser’ will appear to have moved from patch N to patch M (where M +is the new patch number). + \item Instead of a single original patch, define two (or more) distinct but adjacent patches in the original landscape, so that they each retain their own populations when they become separated by the landscape change. +} + +A dynamic landscape can be specified using the slots \code{LandscapeFile} / \code{LandscapeMatrix} (, \code{PatchFile} / \code{PatchMatrix}, \code{CostsFile}) / \code{CostsMatrix} and \code{DynamicLandYears}. +\code{LandscapeFile} (and \code{PatchFile}, \code{CostsFile}) take a character vector with the file names of the maps to be loaded. +\code{LandscapeMatrix} (and \code{PatchMatrix}, \code{CostsMatrix}) take a list with the matrices representing the raster maps to be used. + +Please be aware, that all landscape related input must be either matrices or file names. You cannot mix both types of inputs. + +All provided maps must agree in resolution, extent and origin. \code{DynamicLandYears} is a number vector that contains the years, in which these landscapes shall be loaded; it must have the same ordering so +that years and maps can be matched. If a specific map is used multiple times, it must be listed each time nevertheless. +} +\author{ +Anne-Kathleen Malchow, Jette Wolff +} diff --git a/RangeShiftR/man/Initialise.Rd b/RangeShiftR/man/Initialise.Rd new file mode 100644 index 0000000..34d75b9 --- /dev/null +++ b/RangeShiftR/man/Initialise.Rd @@ -0,0 +1,147 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_InitialisationParams.R +\docType{class} +\name{Initialise} +\alias{Initialise} +\title{Set Initialisation Parameters} +\usage{ +Initialise(InitType = 0, FreeType = 1, SpType = 0, NrCells, InitIndsFile = NULL, InitIndsList = list(), + InitDens = 1, IndsHaCell, PropStages = 0, InitAge = 2, minX, minY, maxX, maxY, + InitFreezeYear = 0, RestrictRows = 0, RestrictFreq = 0, FinalFreezeYear = 0) +} +\arguments{ +\item{InitType}{Type of initialisation:\cr +\code{InitType} = \eqn{0}: Free initialisation according to habitat map (default) (set \code{FreeType}), \cr +\code{InitType} = \eqn{1}: From loaded species distribution map (set \code{SpType}),\cr +\code{InitType} = \eqn{2}: From initial individuals list file (set \code{InitIndsFile} or \code{InitIndsList}, respectively). +\cr Must to be \eqn{0} for an \code{\link[RangeShiftR]{ArtificialLandscape}}.} + +\item{FreeType, NrCells}{Option for \emph{free initialisation}, i.e. required only if \code{InitType}\eqn{ = 0}:\cr +\code{FreeType} = \eqn{0}: Random; provide number of cells/patches to initialise in \code{NrCells}. \cr +\code{FreeType} = \eqn{1}: All suitable cells/patches (default).} + +\item{SpType, NrCells}{Option for \emph{initialisation from species distribution map}, i.e. required only if \code{InitType}\eqn{ = 1}:\cr +\code{SpType} = \eqn{0}: All suitable cells within all distribution presence cells (default), \cr +\code{SpType} = \eqn{1}: All suitable cells within some randomly chosen presence cells; set number of cells to initialise in \code{NrCells}.} + +\item{InitIndsFile}{Name of \emph{initial individuals list file}, required only if \code{InitType}\eqn{ = 2}.\cr +For informaton on the required file format see the Details below.} + +\item{InitIndsList}{The list of initial individuals given as a list of data.frames - one for each replicate simulation (instead of as file name in \code{InitIndsFile}), using the same format (see Details).} + +\item{InitDens, IndsHaCell}{Number of individuals to be seeded in each cell/patch:\cr +\code{InitDens} = \eqn{0}: At \code{K_or_DensDep},\cr +\code{InitDens} = \eqn{1}: At half \code{K_or_DensDep} (default),\cr +\code{InitDens} = \eqn{2}: Set the number of individuals per cell/hectare to initialise in \code{IndsHaCell}.} + +\item{PropStages}{For \code{\link[RangeShiftR]{StageStructure}}d models only: Proportion of individuals initialised in each stage. +Requires a vector of length equal to the number of stages; its entries must be \eqn{\ge 0} and sum to \eqn{1.0}. However, juveniles +can't be initialised and thus stage \eqn{0} (first entry) must have a value of \eqn{0.0}.} + +\item{InitAge}{For \code{StageStructure}d models only: Initial age distribution within each stage:\cr +\code{InitAge} = \eqn{0}: Minimum age for the respective stage.\cr +\code{InitAge} = \eqn{1}: Age randomly sampled between the minimum and the maximum age for the respective stage.\cr +\code{InitAge} = \eqn{2}: According to a quasi-equilibrium distribution (default).} + +\item{minX, maxX, minY, maxY}{Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): Restrict initial range in X- and/or Y- coordinates, given in number of cells. +All must be \eqn{\ge 0} and (\code{maxX,maxY})\eqn{>}(\code{minX,minY}). (Integer)} + +\item{InitFreezeYear}{Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): The year until which species is confined to +its initial range limits.} + +\item{RestrictRows}{Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): The number of rows at northern front to restrict range. +If set to \eqn{0}, the range restriction turned off.} + +\item{RestrictFreq}{Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): Frequency in years at which range is restricted to northern front.} + +\item{FinalFreezeYear}{Option for \emph{free initialisation} (\code{InitType}\eqn{ = 0}): The year after which species is confined to its new, current range limits, after a +period of range expansion. Will be ignored if set to \eqn{0}, otherwise must be \eqn{>} \code{InitFreezeYear}.} +} +\value{ +a parameter object of class "InitialisationParams" +} +\description{ +Initialisation rules define the way in which initial individuals are placed in the landscape at the start of the simulation. +There are three initialisation types:\cr +Free initialisation according to the habitat map (\code{InitType}\eqn{= 0}), +initialisation from a loaded species distribution map (\code{InitType} \eqn{= 1}), +and the initialisation from an initial individuals list (\code{InitType} \eqn{= 2}), +with additional options for each type, see the Details.\cr +Additionally, initial density and, if applicable, initial stage and age distributions can be set. +} +\details{ +\emph{Initialisation Types}\cr +\itemize{ + \item \emph{Free Initialisation.} (\code{InitType}\eqn{ = 0})\cr The population is initialised according to suitable habitat in the landscape. +Either all (\code{FreeType}\eqn{=1}), or a specified number (\code{NrCells}) of randomly selected (\code{FreeType}\eqn{=0}) cells/patches +will be seeded. When using an artificial landscape, this is the only option available. + \item \emph{From loaded species distribution map.} (\code{InitType}\eqn{ = 1})\cr The population is initialised according to a loaded +species distribution map/matrix, which needs to be provided through the module \code{\link[RangeShiftR]{ImportedLandscape}}, option \code{SpDistFile} or \code{SpDistMatrix}. +All habitat cells/patches within either all (\code{SpType}\eqn{=0}), or a specified number (\code{NrCells}) of randomly selected +(\code{SpType}\eqn{=1}) presence cells (which can have a lower resolution) specified by this distribution map will seeded. + \item \emph{From initial individuals list file.} (\code{InitType}\eqn{ = 2})\cr The population is initialised according to a list of specific +individuals (of given sex, age and stage, if appropriate) in specified cells/patches. This option allows simulation of a reintroduction +scenario.\cr The list has to be loaded from a file in the path given by \code{InitIndsFile} or given as a list of dataframes in \code{InitIndsList}. +It must be a tab-separated list with +explicit column headers and one row for each individual to be initialized. The expected column headers depend on the model settings and +must match the following order exactly: 'Year', 'Species' (must \eqn{= 0}), for cell-/patch-based: 'X', 'Y' / 'PatchID', 'Ninds', for sexual model: 'Sex', +for stage-structured population: 'Age', 'Stage'. The sex is specified with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. +} + +\emph{Initialial density, stage, and age}\cr +For \code{InitType}\eqn{ = {0,1}}, the number of individuals that should be seeded in each cell or patch has to be set. +There are three options: +\itemize{ + \item \emph{At} \code{K_or_DensDep}. (\code{InitDens}\eqn{=0})\cr The cell/patch will be saturated at its respective \eqn{K} or \eqn{1/b}. + \item \emph{At half} \code{K_or_DensDep}. (\code{InitDens}\eqn{=1})\cr The cell/patch will be initialised at half its \eqn{K} or \eqn{1/b}. + \item \emph{Set value} \code{IndsHaCell}. (\code{InitDens}\eqn{=2})\cr Set the number of individuals to be seeded in each cell or the density +in each patch (in units of individuals per hectare). +} +(These settings have no effect for \code{InitType}\eqn{ = 2}.) + +In the case of \code{\link[RangeShiftR]{StageStructure}}d models, the initial stage and age distributions must be specified. +If \code{InitType}\eqn{ = 2}, this is done via the \code{InitIndsFile} or \code{InitIndsList}, whereas for \code{InitType}\eqn{ = {0,1}}, +the proportion of individuals that should be initialised at each stage class is set via the numeric vector \code{PropStages}. It needs +to have as many entries as number of stages, starting from the juvenile stage (\eqn{0}). Note that these proportions must sum up to \eqn{1.0}, +however the proportion of juveniles must be \eqn{0.0}. + +Options for initial age distributions: +\itemize{ + \item \emph{Minimal age} of respective stage. (\code{InitAge}=0) + \item \emph{Randomise.} (\code{InitAge}=1)\cr Individuals initialised in each stage will get an age randomly sampled between +the minimum and the maximum age for their respective stage. + \item \emph{Quasi-equilibrium.} (\code{InitAge}=2)\cr Initial age distribution is set approximately in accordance with the number of years +taken to pass through the stage and the (female) survival rate of the respective stage. +} +(These settings have no effect for \code{InitType}\eqn{ = 2}.) + +\emph{Additional options for free initialisation}\cr +In the case of free initialisation, either all or a specified number of randomly selected cells/patches will be seeded. +It is possible to restrict the landscape area available for initialisation by setting limits to the x- and y- coordinates using +\code{minX,maxX,minY} and \code{maxY}). + +Additionally, for all free initialisation methods, it is possible to restrict the available landscape to the initialised range for +a specified period, specifically until year \code{InitFreezeYear}. This option may be particularly useful in an evolutionary model, +to allow a population to reach equilibrium in its original range before being allowed to expand into the remainder of the landscape. + +\emph{Restrict range to northern front} is a further option provided as an additional feature for models of range expansion. Whilst not +strictly an initialisation option, it is provided in this context as it will typically be applied together with restriction of the +initial range in theoretical eco-evolutional models, where the population is firstly allowed to evolve certain traits in a stable range, +then allowed to expand its range during a period of environmental change (when dispersal traits can come under strong selection), and +finally further restricted to a stable range (set \code{FinalFreezeYear}). During the period of range expansion, the population can build up to very large numbers +of individuals in the core of the range, but the area of interest, where strong selection occurs, lies close to the range front. +Therefore, individuals in the core can be discarded, and this is achieved by progressively restricting the suitable range to a number +of rows behind the current range front (set \code{RestrictRows}) so that local populations in the core go extinct. This occurs at +a frequency \code{RestrictFreq} specified in years. The parameter \code{FinalFreezeYear} sets the year after which the range will be +frozen to its new, current limits. It must either be zero, in which case range expansion continues until either the end of the simulation or the northern edge of the +landscape is reached, or set to a year after the year specified in \code{InitFreezeYear}. + +This feature is provided only for expansion in a northerly direction (increasing Y); the initial population should therefore be +established in the southern part of the landscape (low Y values). To turn it off, set \code{RestrictRows = 0}. +} +\examples{ +init <- Initialise() # use all defaults (a stage-structured model requires setting PropStages) +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/KernelTraits.Rd b/RangeShiftR/man/KernelTraits.Rd new file mode 100644 index 0000000..027ead4 --- /dev/null +++ b/RangeShiftR/man/KernelTraits.Rd @@ -0,0 +1,85 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{KernelTraits} +\alias{KernelTraits} +\title{Set genetic traits structure for kernel traits} +\usage{ +KernelTraits(Positions = list("random"), +NbOfPositions = c(10), +ExpressionType = rep("additive",1), +InitialAlleleDistribution = rep("normal",1), +InitialAlleleParameters = matrix(c(rep(0.5,1),(rep(0.1,1), nrow=1), +IsInherited = rep(FALSE,1), +MutationDistribution = rep("normal",1), +MutationParameters = matrix(c(rep(0.5,1),(rep(0.2,1), nrow=1), +MutationRate = rep(0.0001,1), +OutputValues = rep(FALSE,1)) +} +\arguments{ +\item{Positions}{Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{NbOfPositions}{Only specify when the \code{Positions} of the kernel trait is set to ‘random’, else must be blank (\code{NULL}). +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{ExpressionType}{Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{InitialAlleleDistribution}{Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{InitialAlleleParameters}{Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{IsInherited}{Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{MutationParameters}{Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an emigration trait. The number of rows must be equal to the number of required emigration traits (see above) and the sequence must match the sequence of the emigration traits listed above.} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} + +\item{OutputValues}{If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +The length must be equal to the number of required kernel traits (see above) and the sequence must match the sequence of the kernel traits listed above.} +} +\value{ +a parameter object of class "KernelTraitsParams" +} +\description{ +Depending on the settings of \code{\link[RangeShiftR]{DispersalKernel}}, the following traits can be evolvable: + +- The mean parameters(s) of the (two) dispersel kernel(s) \cr +- The probability of using the first kernel, if a double kernel is used (\code{DoubleKernel=TRUE}). \cr + +If dispersal kernels are sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. + +This results in the following number of dispersal kernel traits that need to be specified: + +- 1 if \code{DoubleKernel=FALSE} and \code{SexDep=FALSE}: \ifelse{html}{\out{δ}}{\eqn{δ}} \cr +- 2 if \code{DoubleKernel=FALSE} and \code{SexDep=TRUE}: \ifelse{html}{\out{δ(f)}}{\eqn{δ}(f)}, \ifelse{html}{\out{δ(m)}}{\eqn{δ}(m)}\cr +- 3 if \code{DoubleKernel=TRUE} and \code{SexDep=FALSE}: \ifelse{html}{\out{δ1, δ2, pI}}{\eqn{δ_1, δ_2, p_I}}\cr +- 6 if \code{DoubleKernel=TRUE} and \code{SexDep=TRUE}: \ifelse{html}{\out{δ1(f), δ1(m), δ2(f), δ2(m), pI(f), pI(m)}}{\eqn{δ_1(f), δ_1(m), δ_2(f), δ_2(m), p_I(f), p_I(m)}} \cr + +The entries of the trait parameters must be provided in the same order as the kernel traits are listed above. If parameters expect a matrix, the rows must match the order of kernel traits listed above. +} +\details{ +Traits set to evolve cannot simultaneously be stage-dependent. + +The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. + +Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. + +Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. + +Dispersal kernel traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. + +Dominance values are not applicable for dispersal kernel traits. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/Management.Rd b/RangeShiftR/man/Management.Rd new file mode 100644 index 0000000..3367ffb --- /dev/null +++ b/RangeShiftR/man/Management.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_ManagementParams.R +\docType{class} +\name{Management} +\alias{Management} +\title{Management Parameters} +\usage{ +Management(Translocation = Translocation()) +} +\arguments{ +\item{Translocation}{Set translocation events. See \code{\link{Translocation}} for more details.} +} +\value{ +a parameter object of class "ManagementParams" +} +\description{ +With this function you can set all management strategies you wish to apply to your simulations. +This function includes for now only the translocation of individuals (see details below). +} +\details{ +\strong{Translocation} + +Translocation is a conservation management strategy to reintroduce species in areas where they have been extirpated, +stabilize metapopulations or enhance (genetic) connectivity between fragmented habitats. Translocations are applied +to increase survival probabilities of species, increase genetic diversity or restore ecological balance.The selection of +suitable source and destination sites as well as selection of suitable individuals is crucial for the success of the strategy. +} +\references{ +\insertAllCited{} +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/NeutralTraits.Rd b/RangeShiftR/man/NeutralTraits.Rd new file mode 100644 index 0000000..c130ecf --- /dev/null +++ b/RangeShiftR/man/NeutralTraits.Rd @@ -0,0 +1,80 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{NeutralTraits} +\alias{NeutralTraits} +\title{Set up structure of neutral traits} +\usage{ +NeutralTraits( +Positions = "random", +NbOfPositions = 10, +InitialPositions = "all", +InitialNbOfPositions = NULL, +InitialAlleleDistribution = NULL, +InitialAlleleParameters = 2, +MutationDistribution = "KAM", +MutationParameters = 2, +MutationRate = 0.0, +OutputValues = FALSE) +} +\arguments{ +\item{Positions}{Loci positions coding for trait within genome. Must be in the +range 0-(\code{GenomeSize}-1), specified in \code{\link[RangeShiftR]{Genetics}}. Positions can overlap across +traits - there will be no pleiotropy, but this will influence genetic linkage.,} + +\item{NbOfPositions}{Only specify if \code{Positions} is set to \code{"random"}, else must be blank (\code{NULL})} + +\item{InitialPositions}{Specify which positions should be initialised. Must be "all", "random" or a vector of integers. If enabled, the remaining initial value parameters will only be applied to the selected positions, +and all other positions will be set to 0. Must be in the range of \code{Positions}.} + +\item{InitialNbOfPositions}{Only specify if \code{InitialPositions} is set to \code{"random"}, else must be blank (\code{NULL}). Cannot be greater than \code{NbOfPositions}} + +\item{InitialAlleleDistribution}{Distribution from which to draw initial allele values from. +If \code{uniform}. Initialise with random characters between 0 – \code{max}. Note that possible values start at 0, so \code{max=0} +specifies a monomorphic initial population.} + +\item{InitialAlleleParameters}{Maximal value for the uniform distribution.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be either \code{"KAM"} or \code{"SSM"}. \code{KAM} (k-alleles model) is randomly +draw a value between 0 and \code{max} (see \code{MutationParameters}). +\code{SSM} (single-step mutation) is to move in a stepwise manner, A to B, B to C.} + +\item{MutationParameters}{Parameters for the above distribution: maximal value for \code{KAM} or \code{SSM} (cannot exceed 255)} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0} + +\item{OutputValues}{If OutputGeneValues in \code{\link[RangeShiftR]{Genetics}} is +enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}.} +} +\value{ +a parameter object of class "NeutralTraitsParams" +} +\description{ +A method to specify neutral traits in the genetic module. +} +\details{ +A neutral trait can be specified to track the evolution of population structure and neutral variation. +It is not expressed, and only used to compute neutral statistics. + +For neutral trait you must specify: + +- The number and positions of genes controlling the trait: \code{Positions} and \code{NbOfPositions} \cr +- Which positions should be initialized \code{InitialPositions} and in case of random positions the number of initial positions \code{InitialNbOfPositions}? \cr +- A distribution to sample initial allele values from: \code{InitialAlleleDistribution} and \code{InitialAlleleParameters} \cr +- A mutation rate for all genes controlling the trait. \code{MutationRate} \cr +- A distribution to sample mutations from. \code{MutationDistribution} and \code{MutationParameters} \cr +- Whether or not the allele values should be written to the output \code{OutputValues} \cr + +The user specifies the number of possible alleles for neutral loci (up to 256), via the maximum parameter of the mutation distribution. +Initial values are either identical for all sites (equal to the max value) or sampled in a uniform distribution (between 0 and the maximum value). +Mutations are either sampled in a uniform distribution between 0 and the max parameter (k-allele model, KAM, \insertCite{peng2012}{RangeShiftR}) or +added as increments (random -1 or +1 changes) of the previous value (symmetric stepwise model, SSM, \insertCite{peng2012}{RangeShiftR}). + +Dominance values and inheritance are not applicable for neutral traits. +} +\references{ +\insertAllCited{} +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/RSsim.Rd b/RangeShiftR/man/RSsim.Rd new file mode 100644 index 0000000..bb79727 --- /dev/null +++ b/RangeShiftR/man/RSsim.Rd @@ -0,0 +1,104 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RSsim.R +\name{RSsim} +\alias{RSsim} +\title{Define a RangeShiftR parameter master object} +\usage{ +RSsim(batchnum = 1L, + simul = Simulation(), + land = ArtificialLandscape(), + demog = Demography(Rmax = 1.5), + dispersal = Dispersal(), + gene = Genetics(), + management = Management(), + init = Initialise(), + seed = 0, + fixreplicateseed = FALSE) +} +\arguments{ +\item{batchnum}{Batch ID is part of output files names and can be used to prevent overwriting.} + +\item{simul}{Set \code{\link[RangeShiftR]{Simulation}} parameters} + +\item{land}{Set landscape parameters. Can be either \code{\link[RangeShiftR]{ArtificialLandscape}} or \code{\link[RangeShiftR]{ImportedLandscape}}.} + +\item{demog}{Set \code{\link[RangeShiftR]{Demography}} parameters} + +\item{dispersal}{Set \code{\link[RangeShiftR]{Dispersal}} parameters} + +\item{gene}{Set \code{\link[RangeShiftR]{Genetics}} parameters} + +\item{management}{Set \code{\link[RangeShiftR]{Management}} parameters} + +\item{init}{Set \code{\link[RangeShiftR]{Initialise}} parameters} + +\item{seed}{Set seed for random number generator. If non-positive, a random seed will be generated.} + +\item{fixreplicateseed}{Use the same seed for all replicates.} +} +\value{ +returns a \emph{RangeShiftR} parameter master object (class 'RSparams') + +if given parameters pass validity check, returns a RangeShiftR parameter master object of class "RSparams", otherwise NULL +} +\description{ +Set up a parameter master that can be used in \code{\link[RangeShiftR]{RunRS}}() to run a simulation.\cr +All parameter modules can be added to an existing parameter master via the "+"-functions. However, note that the entire respective module will be overwritten.\cr +} +\details{ +\emph{Demographic stochasticity} \cr Demographic stochasticity is fundamentally important for the dynamics of populations that are naturally small or have declined to low abundances owing to +anthropogenic pressures. Additionally, inter-individual variability within populations can have a major influence on dynamics. Modelling stochastic events +that happen to individuals is crucial for avoiding systematic overestimation of population viability or rate of spread +\insertCite{clark2001invasion,kendall2003unstructured,robert2003variation,grimm2005individual,jongejans2008dispersal,travis2011improving}{RangeShiftR}. +Thus, population dynamics in \emph{RangeShiftR} were constructed to be +fully individual-based and stochastic. Each reproductive individual produces a discrete number of offspring sampled from a Poisson distribution with a mean +that is influenced by the species’ demographic parameters and the local population density. As \emph{RangeShiftR} has been designed for modelling a variety of +species with different life-history traits, a range of different population models can be chosen, depending on the species being modelled and on the +available information (see \code{\link[RangeShiftR]{Demography}}). In all cases demographic stochasticity is implemented. + +\emph{Cell-based vs. patch-based model} \cr +\emph{RangeShiftR} can be run as a cell-based or patch-based model \insertCite{bian2003representation}{RangeShiftR}. It should be noted +that the selection between cell-based or patch-based model is of fundamental importance for population dynamics calculations because +it influences the spatial extent at which density dependence operates. In both cases, the landscape is represented as a grid with cells +belonging to a particular habitat type, holding a percentage of habitat cover or being assigned a habitat quality index. However, +when \emph{RangeShiftR} is run using the cell-based setting, the cell is the scale at which processes such as population dynamics and dispersal +act. The individuals present in a cell define a distinct population, and density-dependencies for reproduction, emigration and settlement +all operate at this scale. Even in the case where two habitat cells are adjacent, they still hold separate populations. In contrast, in +the patch-based model, population dynamics happen at the patch level, a patch being an assemblage of landscape cells of potentially +different habitat types. Patches are not defined automatically by \emph{RangeShiftR} (see \code{\link[RangeShiftR]{ImportedLandscape}}). +Rather, the user is required to define which cells belong +to which patch, taking into account the ecological understanding of the study species. Density-dependencies regarding reproduction, +development, survival, emigration and settlement will depend on the density of individuals in a patch. However, discrete step-wise +movements during the transfer phase will always use the cell as the resolution at which steps occur, thus retaining important information +about the landscape heterogeneity.\cr +The choice between cell- and patch-based modelling can be of crucial importance. While a cell-based model provides an excellent abstraction +of space for many theoretical studies, for some applied studies it may be insufficient. This is because the misrepresentation of population +dynamics and dispersal (in terms of the scale at which they operate) can lead to substantial biases in projections regarding, for example, +rate of range expansion and population persistence \insertCite{bocedi2012projecting}{RangeShiftR}. Ideally, the scales at which population dynamics and dispersal +processes are modelled (by choosing the cell resolution or by defining the patches) should be those that are relevant for the species. +Importantly, the patch-based implementation allows separating the scales used for population dynamics and movements. In this case, the +landscape can be modelled at very fine resolution in order to capture the features that are likely to influence movements (e.g. narrow linear +features) without constraining the local population dynamics to operate at too small a scale. + +\emph{Temporal and spatial scales} \cr +It is important to note an essential difference in spatial scale between +the cell-based and the patch-based version. In the cell-based model, the cell resolution represents the spatial scale at which the two fundamental +processes of population dynamics and dispersal happen. This means that all the density-dependencies in the model (reproduction, survival, +emigration, settlement, etc...) act at the cell scale and the same scale is used as a single step unit for discrete movement models. In +the patch-based version, two spatial scales are simultaneously present: the cell scale, which in this case is used just for the transfer phase +of dispersal (movements) and the patch scale, at which the density-dependences are acting. The choice of type of model and cell resolution (as +well as the definition/scale of patches) is of fundamental importance because, depending on the system and on the question being tackled, it can +systematically bias the outcomes of the model.\cr +The user also defines the temporal scales. There are three distinct temporal scales. The highest-level one has years as units and represents the +scale at which variations in the abiotic environment are modelled (\emph{RangeShiftR} does not explicitly model within-year variability in conditions). +The intermediate scale is the species’ reproductive season. The model can be used to simulate the case where there is only one reproductive +season per year but it is also possible to simulate situations where there more than one per year or only one every \eqn{N} years. A single +reproductive event is always followed by dispersal. Finally, the smallest time scale is represented by the number of steps that emigrants take +during the movement phase of dispersal. This can be determined by a maximum number of steps, per-step mortality or both. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/RangeShiftR-package.Rd b/RangeShiftR/man/RangeShiftR-package.Rd new file mode 100644 index 0000000..286270c --- /dev/null +++ b/RangeShiftR/man/RangeShiftR-package.Rd @@ -0,0 +1,50 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RangeShiftR.R +\docType{package} +\name{RangeShiftR-package} +\alias{RangeShiftR} +\alias{RangeShiftR-package} +\title{RangeShiftR: An R package for individual-based simulation of spatial eco-evolutionary dynamics and species' responses to environmental changes} +\description{ +RangeShiftR provides individual-based simulations of spatial eco-evolutionary dynamics. It is based on the C++ software RangeShifter, making it flexible and fast. RangeShiftR models the processes of demography, dispersal and evolution in an inter-dependent way, offering substantial complexity in the corresponding modelling choices. It is entirely open-source and aims to facilitate the application of individual-based and mechanistic modelling to eco-evolutionary questions. +} +\details{ +\code{RangeShiftR} provides flexible and fast simulations of spatial eco-evolutionary dynamics. +It implements the individual-based simulation software \emph{RangeShifter}, +\insertCite{bocedi2014,bocedi2020}{RangeShiftR}, +making it available for all machines that can build and run \emph{R}. + +\code{RangeShiftR} models the processes of demography, dispersal and evolution in an +inter-dependent way, offering substantial complexity in the corresponding modelling choices. +It is entirely open-source and aims to facilitate the application +of individual-based and mechanistic modelling to eco-evolutionary questions. + +The \emph{RangeShifter} project is presented on our website +\url{https://rangeshifter.github.io/}. + +To get started with the package, please find an overview and a range of tutorials here: +\url{https://rangeshifter.github.io/RangeshiftR-tutorials/}. +} +\references{ +\insertAllCited{} +} +\seealso{ +Useful links: +\itemize{ + \item \url{https://rangeshifter.github.io/RangeshiftR-tutorials/} +} + +} +\author{ +\strong{Maintainer}: Anne-Kathleen Malchow \email{rangeshiftr@uni-potsdam.de} + +Authors: +\itemize{ + \item Greta Bocedi + \item Stephen C.F. Palmer + \item Justin M.J. Travis + \item Damaris Zurell +} + +} +\keyword{internal} diff --git a/RangeShiftR/man/RangeShiftR_citation.Rd b/RangeShiftR/man/RangeShiftR_citation.Rd new file mode 100644 index 0000000..84951ee --- /dev/null +++ b/RangeShiftR/man/RangeShiftR_citation.Rd @@ -0,0 +1,11 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RangeShiftR.R +\name{RangeShiftR_citation} +\alias{RangeShiftR_citation} +\title{Display citation} +\usage{ +RangeShiftR_citation() +} +\description{ +Display citation +} diff --git a/RangeShiftR/man/RangeShiftR_license.Rd b/RangeShiftR/man/RangeShiftR_license.Rd new file mode 100644 index 0000000..d9575c4 --- /dev/null +++ b/RangeShiftR/man/RangeShiftR_license.Rd @@ -0,0 +1,11 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RangeShiftR.R +\name{RangeShiftR_license} +\alias{RangeShiftR_license} +\title{Display RangeShiftR license information} +\usage{ +RangeShiftR_license() +} +\description{ +Display RangeShiftR license information +} diff --git a/RangeShiftR/man/RunRS.Rd b/RangeShiftR/man/RunRS.Rd new file mode 100644 index 0000000..6a2bd43 --- /dev/null +++ b/RangeShiftR/man/RunRS.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RunRS.R +\name{RunRS} +\alias{RunRS} +\title{Run the Simulation} +\usage{ +RunRS(RSparams, dirpath = getwd()) +} +\arguments{ +\item{RSparams}{A parameter master object (class 'RSparams'), contains all parameters to specify the simulation settings. +Can be generated using the function \code{\link[RangeShiftR]{RSsim}}.} + +\item{dirpath}{File path to RS working directory; must contain the folders 'Inputs', 'Outputs', 'Output_Maps'.\cr +If NULL, the current \code{R} working directory will be used.} +} +\value{ +returns an error code +} +\description{ +Run the Simulation +} diff --git a/RangeShiftR/man/SMS.Rd b/RangeShiftR/man/SMS.Rd new file mode 100644 index 0000000..07c7a9e --- /dev/null +++ b/RangeShiftR/man/SMS.Rd @@ -0,0 +1,146 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{SMS} +\alias{SMS} +\title{Set up a Stochastic Movement Simulator} +\usage{ +SMS(PR = 1, PRMethod = 1, MemSize = 1, + DP = 1.0, + GoalType = 0, + GoalBias = 1.0, AlphaDB, BetaDB, + IndVar = FALSE, + Costs, StepMort = 0.0, + StraightenPath = TRUE) +} +\arguments{ +\item{PR}{Perceptual range. Given in number of cells, defaults to \eqn{1}. (integer)} + +\item{PRMethod}{Method to evaluate the effective cost of a particular step from the landscape within the perceptual range:\cr \eqn{1 = }Arithmetic mean (default)\cr \eqn{2 = }Harmonic +mean\cr \eqn{3 = }Weighted arithmetic mean} + +\item{MemSize}{Size of memory, given as the number of previous steps over which to calculate current direction to apply directional persistence +(\code{DP}). A maximum of \eqn{14} steps is supported, default is \eqn{1}. (integer)} + +\item{DP}{Directional persistence. Corresponds to the tendency to follow a correlated random walk, must be \eqn{\ge 1.0}, defaults to \eqn{1.0}.\cr +If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}.} + +\item{GoalType}{Goal bias type: \eqn{0 = } None (default), \eqn{2 = } Dispersal bias.} + +\item{GoalBias}{Only if \code{GoalType=2}: Goal bias strength. Must be must be \eqn{\ge 1.0}, defaults to \eqn{1.0}. \cr If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}.} + +\item{AlphaDB}{Required if \code{GoalType=2}: Dispersal bias decay rate. Must be must be \eqn{> 0.0}.\cr If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}.} + +\item{BetaDB}{Required if \code{GoalType=2}: Dispersal bias decay inflection point (given in number of steps). Must be must be \eqn{> 0.0}.\cr If \code{IndVar=TRUE}, set to NULL and specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}.} + +\item{IndVar}{Individual variability in SMS traits (i.e. \code{DP}, \code{GoalBias}, \code{AlphaDB} and \code{BetaDB})? Defaults to \code{FALSE}. If \code{TRUE}, specify the SMSTraits in \code{\link[RangeShiftR]{SMSTraits}}.} + +\item{Costs}{Describes the landscapes resistance to movement. Set either: \cr + - \emph{habitat-specific} costs for each habitat type, or\cr + - \code{"file" or "matrix"}, to indicate to use the \emph{cost raster} map(s) specified in the landscape module and import the cost values from them.\cr +In the first case of \emph{habitat-specific} costs a numeric vector is expected with, respectively, length \code{Nhabitats} for an \code{\link[RangeShiftR]{ImportedLandscape}} +with habitat codes (i.e. \code{HabPercent=FALSE})) or length \eqn{2} for an \code{\link[RangeShiftR]{ArtificialLandscape}} (matrix and habitat costs).\cr +In the second case of importing a \emph{cost raster} file or matrix, specify the file name(s) or matrices in the \code{\link[RangeShiftR]{ImportedLandscape}} module. +The specified map or matrix has to match the landscape raster/matrix in extent, coordinates and resolution, and each cell contains a cost value (\eqn{\ge 1}). +This is the only option for an imported landscape with habitat qualities / cover percentage (i.e. \code{HabPercent=TRUE}).} + +\item{StepMort}{Per-step mortality probability. Can be either \emph{constant}, in which case a single numeric is expected (the default, with +value \eqn{0.0}) or \emph{habitat-specific}, in which case a numeric vector (with a length as described above for \code{Costs}) is expected. +All values must be within the half-open interval \eqn{[0,1)}. \cr +For an imported habitat quality landscape (\code{HabPercent=TRUE}), only constant per-step mortality is allowed.} + +\item{StraightenPath}{Straighten path after decision not to settle in a patch? Defaults to \code{TRUE}, see Details below.} +} +\value{ +a parameter object of class "StochMove" +} +\description{ +A method to describe \code{\link[RangeShiftR]{Transfer}}: +SMS is a stochastic individual-based movement model where organisms move through grid-based, heterogeneous landscapes. The model uses similar +cost surfaces as the least cost path (LCP) method, but it relaxes two of its main assumptions: Firstly, individuals are not assumed to be +omniscient, but move according to what they can perceive of the landscape within their perceptual range (\code{PR}). Secondly, individuals +do not know a priori their final destination, which is a reasonable assumption for dispersing individuals. For a complete description of the +method, see the Details below or refer to \insertCite{palmer2011introducing;textual}{RangeShiftR}. +} +\details{ +SMS is a stochastic individual-based model where organisms move through grid-based, heterogeneous landscapes. The model uses similar cost +surfaces as the least cost path (LCP) \insertCite{adriaensen2003application,chardon2003incorporating,stevens2006gene,driezen2007evaluating}{RangeShiftR}, +but it relaxes two of the main assumptions/limitations of the latter. Firstly, individuals are not assumed to be omniscient, but move according to what they +can perceive of the landscape within their perceptual range. Secondly, individuals do not know a priori their final destination, which is a +reasonable assumption for dispersing individuals. Here, the core components of SMS are briefly described; +see \insertCite{palmer2011introducing;textual}{RangeShiftR} for a complete description of the method. + +SMS uses cost maps where a relative cost to movement is assigned to each habitat type. Costs are integer numbers and represent the cost of +moving through a particular land cover relative to the cost of moving through breeding habitat (which is conventionally set to a cost of \eqn{1}). +Individuals take single cell steps basing their decisions on three parameters: their perceptual range (\code{PR}) (given in number of cells), +the method used to evaluate the landscape within their perceptual range (\code{PRMethod}), and their directional persistence (\code{DP}), which corresponds to +their tendency to follow a correlated random walk. At each step, the individual evaluates the surrounding habitat in order to determine +the effective cost of taking a particular step to each of the eight neighbouring cells. The effective cost is a mean of the cost of the +neighbouring cell and the surrounding cells beyond it within the \code{PR}, and is calculated by one of three possible methods:\cr +- \emph{Arithmetic mean}\cr +- \emph{Harmonic mean} - The reciprocal of the arithmetic mean of the reciprocals of the observations (cell costs). This method increases the +detectability of low cost cells but performs less well than the arithmetic mean in detecting high cost cells. Therefore, the choice between +the two depends on whether the main driver of the animal movement is selecting for good habitat or avoiding costly habitat.\cr +- \emph{Weighted arithmetic mean} - The cost of each cell is weighted by its inverse distance from the individual (which is assumed to be in +the centre of the current cell). + +The effective cost of each neighbouring cell is weighted by the \code{DP}, which is lowest in the direction of travel. \code{DP} can be +calculated over more steps than just the previous one (up to a maximum of \eqn{14}), which is controlled by the memory size parameter (\code{MemSize}) +\insertCite{palmer2014inter,aben2014simple}{RangeShiftR}. Increasing the memory size means that an individual retains for longer its tendency to move in a +certain direction, and hence paths tend to become somewhat smoother. + +There is an option to include goal bias, i.e. a tendency to move towards a particular destination \insertCite{aben2014simple}{RangeShiftR}, +which is implemented in a similar way to \code{DP}. However, as dispersers in \emph{RangeShiftR} are naïve and have no goal, it may be applied only in the ‘negative’ +sense of moving away from the natal location (\code{GoalType=2}), i.e. as a dispersal bias, which is subject to a decay in strength as a +function of the total number of steps taken (set the decay rate \code{AlphaDB} and inflection point \code{BetaDB}). +This enables a dispersal path to follow a straighter trajectory initially, and later become more responsive to perceived landscape costs. + +The product of the reciprocals of effective cost, \code{DP} and dispersal bias, scaled to sum to one, +give the probabilities that the individual will move to each neighbouring cell. All the dispersing individuals move simultaneously, i.e. at +each time-step they all make one move. In the case of patch-based models, the individual is forced to leave the natal patch by increasing its +\code{DP} ten-fold until it has taken a number of steps (\eqn{=2*}\code{PR}) outside the natal patch. + +When an individual arrives in a non-natal patch and decides not to settle there (as a result of a density-dependent or mate-finding settlement +rule; see \code{\link[RangeShiftR]{Settlement}}), then there is the option that its path is straightened (\code{StraightenPath=TRUE}). This means +that it leaves the patch as soon as possible in order to search for another patch. This is achieved by increasing its \code{DP} ten-fold. However, in +certain types of model, e.g. when arbitrary contiguous patches have been defined for what is basically a continuous population, this can lead +to the path always being straightened, as an individual enters a new patch as soon as it has left the one it has rejected. In such cases, it is +advisable to disable the feature (\code{StraightenPath=FALSE}), although care must be taken that individuals do not become trapped in patches +surrounded by very high cost matrix. + +When inter-individual variability is activated (set \code{IndVar=TRUE}), the four SMS movement traits \code{DP}, as well as - if dispersal goal bias +is enabled - \code{GB}, \code{AlphaDB} and \code{BetaDB} can evolve. In this case, you must set the corresponding traits to \code{NULL} here and must specify them in the \code{\link[RangeShiftR]{SMSTraits}} module and set up the genetics +(see \code{\link[RangeShiftR]{Genetics}}).\cr + +As currently implemented, there is no sex- or stage- dependence of SMS traits. + +The production of the output ‘dispersal heat maps’, which show the total number of times each cell is visited by dispersing individuals within a +single replicate simulation, can be enabled with the option \code{SMSHeatMap} in \code{\link[RangeShiftR]{Simulation}}. + +\emph{Costs layer} \cr +Critical for the outcomes of SMS are the relative costs assigned to the different habitats (as it is also the case for +the LCP approach). Habitat costs or resistance to movement can be set manually for each habitat code or imported as a raster map, which +allows for costs to be a function of multiple variables instead of a simple value associated to the habitat type. +In the latter case, the file names/matrices are provided in the \code{\link[RangeShiftR]{ImportedLandscape}} module. +The specified map has to match the landscape raster/matrix in extent, coordinates and resolution, and each cell contains a cost value, with the minimal possible cost being \eqn{1}. +Importing a cost layer is the only option when the landscape comprises habitat coverage or quality. + +\emph{Mortality} \cr +There are two main sources of mortality: First, dispersal mortality can arise as a result of individuals failing to reach suitable habitat. Some individuals may fail +to find suitable habitat before they use up their maximum number of movement steps (\code{MaxSteps} in \code{\link[RangeShiftR]{Settlement}}). +In this first case, dispersal mortality clearly depends upon the proportion of suitable habitat in the landscape and will increase as the +availability of habitat declines.\cr +A second source of dispersal mortality can be specified by the user in form of a per-step probability of mortality (\code{StepMort}. +This can be useful for representing mortality risks that increase with distance or time spent travelling \insertCite{bonte2012costs}{RangeShiftR}. +Additionally, it is possible that the per-step mortality varies according to the nature of the local environment by providing the \code{CostMap}. + +Note that the total dispersal mortality +experienced will be the sum of the mortalities due to the two sources identified above and, in parameterising the model, it will be important +to recognize this such that dispersal mortality is not double-accounted. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/SMSTraits.Rd b/RangeShiftR/man/SMSTraits.Rd new file mode 100644 index 0000000..b08fb72 --- /dev/null +++ b/RangeShiftR/man/SMSTraits.Rd @@ -0,0 +1,87 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{SMSTraits} +\alias{SMSTraits} +\title{Set genetic traits structure for SMS traits} +\usage{ +SMSTraits(Positions = list("random"), +NbOfPositions = c(10), +ExpressionType = rep("additive",1), +InitialAlleleDistribution = rep("normal",1), +InitialAlleleParameters = matrix(c(rep(0.5,1),(rep(0.1,1), nrow=1), +IsInherited = rep(FALSE,1), +MutationDistribution = rep("normal",1), +MutationParameters = matrix(c(rep(0.5,1),(rep(0.2,1), nrow=1), +MutationRate = rep(0.0001,1), +OutputValues = rep(FALSE,1)) +} +\arguments{ +\item{Positions}{Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{NbOfPositions}{Only specify when the \code{Positions} of the SMS trait is set to ‘random’, else must be blank (\code{NULL}). +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{ExpressionType}{Type of expression for the emigration trait. Can be either \code{additive} or \code{average}. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{InitialAlleleDistribution}{Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{InitialAlleleParameters}{Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an SMS trait. +The number of rows must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{IsInherited}{Should the emigration trait be inherited? Can be either \code{TRUE} or \code{FALSE}. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{MutationParameters}{Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an SMS trait. +The number of rows must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} + +\item{OutputValues}{If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +The length must be 1 (\code{GoalType=0}) or 4 (\code{GoalType=2}) for the required SMS traits \code{DP} and, if \code{GoalType=2} \code{GoalBias}, , \code{AlphaDB} and , \code{BetaDB}.} +} +\value{ +a parameter object of class "SMSTraitsParams" +} +\description{ +Depending on the settings of \code{\link[RangeShiftR]{SMS}}, the following traits can be evolvable: + +- The directional persistence of the individual \code{DP} \cr +- The \code{GoalBias}, that is the tendency for an individual to move away from its natal patch \cr +- The slope of the distance dependent decay of the goal bias \code{AlphaDB} \cr +- The distance threshold of the distance dependent devay of the goal bias \code{BetaDB} \cr + +If dispersal kernels are sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. + +This results in the following number of SMS traits that need to be specified: + +- 1 if \code{GoalType = 0}: directional persistence \code{DP} \cr +- 4 if \code{GoalType = 2}: \code{DP}, \code{GoalBias}, \code{AlphaDB}, \code{BetaDB} \cr + +The entries of the trait parameters must be provided in the same order as the SMS traits are listed above. If parameters expect a matrix, the rows must match the order of SMS traits listed above. +} +\details{ +Traits set to evolve cannot simultaneously be stage-dependent. + +The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. + +Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. + +Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. + +SMS traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. + +Dominance values are not applicable for SMS traits. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/SMSpathLengths.Rd b/RangeShiftR/man/SMSpathLengths.Rd new file mode 100644 index 0000000..39be4c0 --- /dev/null +++ b/RangeShiftR/man/SMSpathLengths.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{SMSpathLengths} +\alias{SMSpathLengths} +\title{Get the distribution of SMS Path Lengths} +\usage{ +SMSpathLengths(s, dirpath, ...) +} +\arguments{ +\item{s}{RSmaster parameter object} + +\item{dirpath}{RS directory path} +} +\value{ +a data.frame that contains the mean (over replicates) number of SNS paths of a given length (rows) per simulated map (columns) +} +\description{ +Reads the RangeShiftR output files 'MovePaths' (if they were generated) to get the distribution of lengths of SMS +paths taken in all recorded years. +} diff --git a/RangeShiftR/man/Settlement.Rd b/RangeShiftR/man/Settlement.Rd new file mode 100644 index 0000000..6c078a6 --- /dev/null +++ b/RangeShiftR/man/Settlement.Rd @@ -0,0 +1,192 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{Settlement} +\alias{Settlement} +\title{Set Settlement Parameters} +\usage{ +Settlement(StageDep = FALSE, SexDep = FALSE, + Settle = 0, FindMate = FALSE, + DensDep = FALSE, + IndVar = FALSE, TraitScaleFactor, + MinSteps = 0, MaxSteps = 0, MaxStepsYear = 0) +} +\arguments{ +\item{StageDep}{Stage-dependent settlement requirements? (default: \code{FALSE})} + +\item{SexDep}{Sex-dependent settlement requirements? (default: \code{FALSE})} + +\item{Settle}{Settlement codes (for \code{DispersalKernel}) or settlement probability parameters (for \emph{Movement process} if \code{DensDep=TRUE}) for all +stages/sexes, defaults to \eqn{0} (i.e. 'die when unsuitable' for \emph{DispersalKernel} and +'always settle when suitable' for \emph{Movement process}). See the Details below.} + +\item{FindMate}{Mating requirements to settle? Set for all stages/sexes. Must be \code{FALSE} (default) in a female-only model.} + +\item{DensDep}{Movement process only: Density-dependent settlement probability? (default: \code{FALSE})} + +\item{IndVar}{Movement process only: Individual variability in settlement probability traits? Must be \code{FALSE} (default), +if \code{DensDep=FALSE} or \code{StageDep=TRUE}. If \code{TRUE} settlement traits are defined in \code{\link[RangeShiftR]{SettlementTraits}}.} + +\item{MinSteps}{Movement process only: Minimum number of steps. Defaults to \eqn{0}.} + +\item{MaxSteps}{Movement process only: Maximum number of steps. Must be \eqn{0} or more; set to \eqn{0} (default) for “per-step mortality only”.} + +\item{MaxStepsYear}{Movement process and stage-structured population only: Maximum number of steps per year, if there are more than \eqn{1} reproductive seasons (option \code{RepSeasons} in \code{\link[RangeShiftR]{StageStructure}}). +Must be \eqn{0} or more. If \eqn{0}, every individual completes the dispersal phase in one year, i.e. between two successive reproduction phases.} +} +\value{ +a parameter object of class "SettlementParams" +} +\description{ +Settlement, or immigration, is the last phase of dispersal, when the organism stops in a new cell or patch of breeding habitat. The +available settlement conditions vary depending on the used \code{\link[RangeShiftR]{Transfer}} type. In any case, dispersing individuals +are not allowed to settle in their natal cell or patch and can only settle in suitable habitat.\cr +\emph{RangeShiftR} incorporates some basic settlement rules that can be stage- or sex-specific or both (set \code{StageDep}, \code{SexDep}). +If a movement process is used, density-dependence (\code{DensDep}) and/or inter-individual variability (\code{IndVar}) are available. +} +\details{ +The settlement phase is determined by a suite of strategies, behaviours and reaction norms that lead individuals to the decision to stop +in a particular place. Habitat selection, mate finding and density dependence are probably three of the main processes involved, +but not the only ones. Like emigration, settlement is a complex process affected by multiple criteria including inter-individual +variability and context dependencies. + +The type of implemented settlement rules depends on the movement model utilized for the \code{\link[RangeShiftR]{Transfer}}. +In any case, dispersing individuals are not allowed to settle in their natal cell or patch.\cr +\emph{RangeShiftR} incorporates some basic settlement rules that can be stage- or sex-specific or both (set \code{StageDep}, \code{SexDep}). +Inter-individual variability (\code{IndVar}) is implemented only for movement processes and then for the three traits +determining density-dependent settlement (\ifelse{html}{\out{S0}}{\eqn{S_0}}, \ifelse{html}{\out{αS}}{\eqn{α_S}}, +\ifelse{html}{\out{βS}}{\eqn{β_S}}; see below). In this case, settlement may not be stage-dependent.\cr + +\emph{Settlement with dispersal kernels}\cr +When using a \code{\link[RangeShiftR]{DispersalKernel}}, individuals are displaced directly from the starting location to the arrival location. The suitability +of the arrival cell or patch determines whether the disperser is successful or not.\cr For species with \emph{non-overlapping generations}, +where individuals have only one chance to disperse and reproduce, the model has two options if the arrival cell is unsuitable: the +individual either dies (\code{Settle} code \eqn{0}) or it can move to one of the eight neighbouring cells in the case that at least one +of them is suitable (\code{Settle} code \eqn{2}). In +the latter case, if more than one of the neighbouring cells is suitable, the individual is placed in one of them chosen randomly. +For patch-based models, if the arrival patch is unsuitable, the individual either dies or can move to a randomly chosen neighbouring +suitable patch, provided that the new patch is only one cell apart from the arrival patch.\cr For species with \emph{overlapping generations} +(i.e. a \code{\link[RangeShiftR]{StageStructure}}d population), +where individuals can disperse over multiple seasons, there are two additional options: First, if the arrival cell/patch is unsuitable, +the individual can stay there waiting until the next dispersal event when it will disperse again according to the set kernel (\code{Settle} code \eqn{1}). Second, +if both the arrival cell/patch and all eight neighbouring cells, or all eventual neighbouring patches, are unsuitable the individual +can wait in the arrival cell/patch before moving again at the next dispersal event (\code{Settle} code \eqn{3}). The arrival cell/patch is considered suitable if +it contains breeding habitat. + +If the settlement condition is the same for the entire population (\code{StageDep=FALSE} and \code{SexDep=FALSE}), then the parameter +\code{Settle} takes a single integer, specifying the corresponding settlement condition code (\eqn{0,1,2} or \eqn{3}). +In case of stage- and/or sex-specific settlement conditions, \code{Settle} must be an integer matrix with the first one/two columns +stating 'stage' and/or 'sex' (\eqn{0} for \emph{female} and \eqn{1} for \emph{male}), and the last column giving the respective settlement condition. +Exactly one row for each stage/sex-combination is required, in no particular order. + +Settlement condition codes: If the individuals current step ends in unsuitable habitat, it:\cr +\eqn{0} = die (default),\cr +\eqn{1} = wait (stage-structured models only),\cr +\eqn{2} = randomly choose a suitable neighbouring cell or die,\cr +\eqn{3} = randomly choose a suitable neighbouring cell or wait (stage-structured models only).\cr + +Simple example for sex-dependence only: Females choose a neighbouring cell or wait, males wait: \tabular{cc}{\out{ } 0 \tab \out{ } 3 \cr \out{ } 1 \tab \out{ } 0 } + +\emph{Settlement with movement processes}\cr +If individuals are dispersing by one of the two movement processes implemented (\code{\link[RangeShiftR]{SMS}} or +\code{\link[RangeShiftR]{CorrRW}}), at each step (made simultaneously) they each evaluate their current cell or patch for the +possibility of settling. This allows for the implementation of more complex settlement rules. The simplest one is that the individual +decides to stop if there is suitable habitat; this is in any case a necessary condition (set \code{DensDep=FALSE}).\cr +If a Settlement module with a constant \eqn{S_0=0} (the default) is used in a model with \emph{movement process} and \code{IndVar=FALSE}, +it gets converted to \eqn{S_0=1.0}, i.e. 'always settle when habitat is suitable'. \cr +\cr +Furthermore, the settlement decision can be density-dependent (set \code{DensDep=TRUE}). In this case, the individual has a probability \ifelse{html}{\out{pS}}{\eqn{p_S}} +of settling in the cell or patch \eqn{i}, given by: + +\ifelse{html}{\out{   pS(i,t) = S0 / ( 1 + e-αS (N(i,t) / K(i,t) - βS) ) } }{\deqn{ p_S(i,t) = S_0 / ( 1 + exp[-α_S (N(i,t)/K(i,t) - β_S) ] ) } } + +In the case of stage-structured models the above equation is modified to: + +\ifelse{html}{\out{   pS(i,t) = S0 / ( 1 + e-αS (b(i,t) * N(i,t) - βS) ) } }{\deqn{ p_S(i,t) = S_0 / ( 1 + exp[-α_S (b(i,t) N(i,t) - β_S) ] ) } } + +In the first case, \eqn{K(i,t)} is the carrying capacity of the cell/patch \eqn{i} at time \eqn{t} given by \code{K_or_DensDep}. +In the latter case, \eqn{b(i,t)} represents the strength of density dependence that is given by the inverse of \code{K_or_DensDep}.\cr +Further, \ifelse{html}{\out{S0}}{\eqn{S_0}} is the maximum settlement probability, +\eqn{N(i,t)} is the number of individuals in the cell/patch \eqn{i} at time \eqn{t}, +\ifelse{html}{\out{βS}}{\eqn{β_S}} is the inflection point of the function and +\ifelse{html}{\out{αS}}{\eqn{α_S}} is the slope at the inflection point.\cr + +Inter-individual variability \code{IndVar=TRUE} and thus evolution is implemented only for the three traits determining density-dependent settlement +(\code{DensDep=TRUE}), and if so, it may not be stage-dependent (\code{StageDep=FALSE}). +Settlement traits must be set in \code{\link[RangeShiftR]{SettlementTraits}} and \code{Settle} must be 0. For details see also \code{\link[RangeShiftR]{Genetics}} and \code{\link[RangeShiftR]{Traits}} + +The parameters that determine the settlement probabilities have to be provided via the parameter \code{Settle}, which generally takes a numeric matrix, or - if only a single constant probability is +used (i.e. \code{DensDep, IndVar, StageDep, SexDep = FALSE}) - a single numeric. If individual variability is enabled, \code{Settle} must be \code{0}. +The format of the matrix is defined as follows: The number of required parameter depend on the option \code{DensDep}. If \code{DensDep=FALSE}, the +density-independent probability \ifelse{html}{\out{pS}}{\eqn{p_S}} must be specified. If \code{DensDep=TRUE}, the functional parameters \ifelse{html}{\out{S0}}{\eqn{S_0}}, +\ifelse{html}{\out{αS}}{\eqn{α_S}} and \ifelse{html}{\out{βS}}{\eqn{β_S}} (cf. equation above) must be specified. + +All parameters have to be given for each stage/sex if the respective dependency is enabled. If \code{StageDep=TRUE}, state the corresponding stage in the first column. +If \code{SexDep=TRUE}, state the corresponding stage in the next (i.e. first/second) column, with \eqn{0} for \emph{female} and \eqn{1} for \emph{male}. + + +The following table lists the required columns and their correct order for different settings: + +\tabular{ccccc}{DensDep \tab IndVar \tab StageDep \tab SexDep \tab columns \cr + F \tab F \tab F \tab F \tab - not applicable - \cr + F \tab F \tab T \tab F \tab stage, \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr + F \tab F \tab F \tab T \tab sex, \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr + F \tab F \tab T \tab T \tab stage, sex, \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr + T \tab F \tab F \tab F \tab \ifelse{html}{\out{S0}}{\eqn{S_0}}, \ifelse{html}{\out{αS}}{\eqn{α_S}}, \ifelse{html}{\out{βS}}{\eqn{β_S}} \cr + \out{⋮} \tab \out{⋮} \tab \out{⋮} \tab \out{⋮} \tab \out{⋮} \cr + T \tab F \tab T \tab T \tab stage, sex, \ifelse{html}{\out{S0}}{\eqn{S_0}}, \ifelse{html}{\out{αS}}{\eqn{α_S}}, \ifelse{html}{\out{βS}}{\eqn{β_S}} \cr + } + +The column headings need not be included, only the numeric matrix is required. The rows require no particular order, but they must match with the matrices provided for \code{FindMate, MaxSteps, MinSteps, MaxStepsYr}. There must be exactly one row for each stage/sex combination. + +For example, in the case of density-, stage- and sex-dependent settlement with no individual variability: +\tabular{ccccc}{ \out{ } 0 \tab \out{ } 0 \tab \out{ } 1.0 \tab \out{ } 0.2 \tab \out{ } 4.0 \cr + \out{ } 0 \tab \out{ } 1 \tab \out{ } 1.0 \tab \out{ } 0.1 \tab \out{ } 6.0 \cr + \out{ } 1 \tab \out{ } 0 \tab \out{ } 0.7 \tab \out{ } 0.5 \tab \out{ } 2.0 \cr + \out{ } 1 \tab \out{ } 1 \tab \out{ } 0.5 \tab \out{ } 0.5 \tab \out{ } 2.0 \cr + \out{ } 2 \tab \out{ } 0 \tab \out{ } 0.05 \tab \out{ } 1.0 \tab \out{ } 1.0 \cr + \out{ } 2 \tab \out{ } 1 \tab \out{ } 0.05 \tab \out{ } 1.0 \tab \out{ } 1.0 +} + +To avoid having individuals moving perpetually because they cannot find suitable conditions to settle, the model requires a maximum number +of steps (\code{MaxSteps}) or a per-step mortality (within the \code{Transfer} object), or both, to be set. +The maximum number of steps defines the maximum time length of the transfer period. +When an individual reaches the maximum number of steps, it stops where it is regardless of the suitability of the location. In +the case of \emph{non-overlapping generations} this results in automatic death if the individual stops in unsuitable habitat. For species that can disperse +over multiple seasons, i.e. a \emph{stage-structured population}, the model additionally requires a maximum number of steps per dispersal event (\code{MaxStepsYear}); on reaching that limit, the individual will +stop where it is and the next season, if still alive, it will move again. + +An additional rule that can be set constitutes a minimum number of steps (\code{MinSteps}) that each individual must take before settlement can take +place. This is useful for simulating situations where animals, in a ‘dispersal mode’, will keep moving and not consider settling even +if suitable conditions are available \insertCite{@e.g. @barton2012risky}{RangeShiftR}. + +Each of the three parameters \code{MinSteps, MaxSteps, MaxStepsYear} need to be provided as single integer (if \code{StageDep=FALSE} and \code{SexDep=FALSE}) or numeric matrix, providing the stage (if \code{StageDep=TRUE}) and sex (if \code{SexDep=TRUE}). +The rows require the same order as in \code{Settle}.There must be exactly one row for each stage/sex combination. + +\tabular{ccccc}{StageDep \tab SexDep \tab columns \cr +F \tab F \tab - not applicable only provide single numeric value - \cr +T \tab F \tab stage, \code{MinSteps/MaxSteps/MaxStepsYear} \cr +F \tab T \tab sex, \code{MinSteps/MaxSteps/MaxStepsYear}\cr +T \tab T \tab stage, sex, \code{MinSteps/MaxSteps/MaxStepsYear} \cr + } + +\emph{Mating requirements}\cr +Sexual species may be required to find a mate, i.e. there has to be at least one individual of the opposite sex present for the cell/patch to be considered suitable for settlement. +Density-dependence and mating requirements can also be combined together to determine the settlement decision. + +The application of this mating condition can be switched on or off using the parameter \code{FindMate}, which takes either a single +logical if \code{StageDep=FALSE} and \code{SexDep=FALSE} or, otherwise, a matrix of the similar structure as for \code{Settle, MinSteps, MaxSteps} and \code{MaxStepsYear}. + +#' \tabular{ccccc}{StageDep \tab SexDep \tab columns \cr +F \tab F \tab - not applicable only provide single logical value - \cr +T \tab F \tab stage, \code{FindMate} as logical value \cr +F \tab T \tab sex, \code{FindMate} as logical value\cr +T \tab T \tab stage, sex, \code{FindMate} as logical value \cr + } +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/SettlementTraits.Rd b/RangeShiftR/man/SettlementTraits.Rd new file mode 100644 index 0000000..794eea6 --- /dev/null +++ b/RangeShiftR/man/SettlementTraits.Rd @@ -0,0 +1,86 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{SettlementTraits} +\alias{SettlementTraits} +\title{Set genetic traits structure for settlement traits} +\usage{ +SettlementTraits(Positions = list("random","random","random"), +NbOfPositions = c(10, 10, 10), +ExpressionType = rep("additive",3), +InitialAlleleDistribution = rep("normal",3), +InitialAlleleParameters = matrix(c(rep(0.5,3),(rep(0.1,3), nrow=3), +IsInherited = rep(FALSE,3), +MutationDistribution = rep("normal",3), +MutationParameters = matrix(c(rep(0.5,3),(rep(0.2,3), nrow=3), +MutationRate = rep(0.0001,3), +OutputValues = rep(FALSE,3)) +} +\arguments{ +\item{Positions}{Loci positions coding for the trait within genome. Should be provided as a list. Entries can either be a string (\code{"random"}) and/or vectors of integers. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{NbOfPositions}{Only specify when the \code{Positions} of the settlement trait is set to \code{"random"}, else must be blank (\code{NULL}). +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{ExpressionType}{Type of expression for the settlement trait. Can be either \code{additive} or \code{average}. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{InitialAlleleDistribution}{Distribution of the initial values. Can be \code{uniform} or \code{normal}. Should be provided as a vector of strings. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{InitialAlleleParameters}{Parameters for the initial distribution: You must provide two colums min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an settlement trait. The number of rows must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{IsInherited}{Should the settlement trait be inherited? Can be either TRUE or FALSE. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{MutationDistribution}{Distribution for mutations to draw from. Can be \code{uniform} or \code{normal}. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{MutationParameters}{Parameters for the mutation distribution: You must provide two colums: min and max for \code{uniform} distribution and mean and sd for \code{normal} distribution. +Each row in the matrix corresponds to an settlement trait. The number of rows must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{MutationRate}{Mutation rate applicable to this type of loci. Must be between 0.0 and 1.0. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} + +\item{OutputValues}{If OutputGeneValues in GeneticsFile is enabled, should allele values for this gene be written to output? Ignored if OutputGeneValues is set to \code{FALSE}. +The length must be equal to the number of required settlement traits (see above) and the sequence must match the sequence of the settlement traits listed above.} +} +\value{ +a parameter object of class "SettlementTraitsParams" +} +\description{ +Only if settlement is density-dependent (\code{DensDep = TRUE}) in \code{\link[RangeShiftR]{Settlement}}, settlement traits can be evolvable. + +Three settlement traits can evolve: + + - The probability of settlement \ifelse{html}{\out{S0}}{\eqn{S_0}} \cr + - The slope of the density-dependent settlement function \ifelse{html}{\out{α}}{\eqn{α}} \cr + - The density threshold of the density-dependent settlement function \ifelse{html}{\out{β}}{\eqn{β}} \cr + +If settlement is sex dependent, \code{SexDep=TRUE}, you must provide details for both sexes. + +This results in following number of settlement traits that need to be specifed: + +- 3 entries/rows if settlement probability is not sex dependent \code{SexDep=FALSE}: \ifelse{html}{\out{S0}}{\eqn{S_0}}, \eqn{α} and \eqn{β} \cr +- 6 entries/rows if settlement probability is sex dependent (\code{SexDep=TRUE}): \ifelse{html}{\out{S0(f), S0(m)}}{\eqn{S_0(f),S_0(m)}}, \ifelse{html}{\out{α(f), α(m)}}{\eqn{α(f), α(m)}} and \ifelse{html}{\out{β(f), β(m)}}{\eqn{β(f), β(m)}} \cr + +The entries of the trait parameters must be provided in the same order as the kernel traits are listed above. If parameters expect a matrix, the rows must match the order of settlement traits listed above. +} +\details{ +Traits set to evolve cannot simultaneously be stage-dependent. + +The alleles of each trait can be expressed according to an additive model (allele values across all loci are summed) or be averaged. + +Mutations are additive and can be sampled in either a \code{normal} or \code{uniform} distribution. + +Initial allele values are sampled in a \code{normal} or \code{uniform} distribution. + +Settlement traits can also be **not** inherited, that is, allele values are resampled from the initial distribution for every new individual. + +Dominance values are not applicable for settlement traits. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/Simulation.Rd b/RangeShiftR/man/Simulation.Rd new file mode 100644 index 0000000..2602404 --- /dev/null +++ b/RangeShiftR/man/Simulation.Rd @@ -0,0 +1,307 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_SimulationParams.R +\docType{class} +\name{Simulation} +\alias{Simulation} +\title{Set Simulation parameters} +\usage{ +Simulation(Simulation = 1, Replicates = 2, Years = 50, Absorbing = FALSE, + Gradient = 0, GradSteep, Optimum, f, ExtinctOptim, + Shifting = FALSE, ShiftRate, ShiftStart, ShiftEnd, + LocalExt = FALSE, LocalExtProb, + EnvStoch = 0, EnvStochType, std, ac, minR, maxR, minK, maxK, + OutIntRange = 1, OutIntOcc = 0, + OutIntPop = 1, OutIntInd = 0, + OutIntTraitCell = 0, OutIntTraitRow = 0, + OutIntConn = 0, OutIntPaths = 0, + OutStartPop = 0, OutStartInd = 0, + OutStartTraitCell = 0, OutStartTraitRow = 0, + OutStartConn = 0, OutStartPaths = 0, + ReturnPopMatrix = FALSE, ReturnPopDataFrame = FALSE, ReturnStages = FALSE, + CreatePopFile = TRUE, + ReturnStages = FALSE, + SMSHeatMap = FALSE) +} +\arguments{ +\item{Simulation}{ID number of current simulation, defaults to \eqn{1}. (integer)} + +\item{Replicates}{Number of simulation iterations, defaults to \eqn{2}. (integer)} + +\item{Years}{The number of simulated years, defaults to \eqn{50}. (integer)} + +\item{Absorbing}{If \code{FALSE} (default), every move in the \code{\link[RangeShiftR]{Transfer}} process will be +repeated until a valid cell is met.\cr +If \code{TRUE}, an individual which hits a non-valid cell or +transgresses the landscape boundary during the dispersal act is eliminated from the simulation.} + +\item{Gradient}{Whether to apply north-south gradient: +\eqn{0} = None (default), \cr +\eqn{1} = decreasing \code{K_or_DensDep}\cr +\eqn{2} = decreasing growth rate \eqn{r} or, for a \code{\link[RangeShiftR]{StageStructure}}d population, +fecundity \ifelse{html}{\out{φ}}{\eqn{\phi}}, \cr +\eqn{3} = increasing local extinction probability \eqn{e}. \cr +If activated, a gradient will be imposed along the north-south (\eqn{y}-) axis in which the selected parameter varies linearly with distance from the +optimum \eqn{y}-value \code{Optimum}. Note that a \code{Gradient} can not be applied in for patch-based models (must be \code{Gradient}\eqn{=0}).} + +\item{GradSteep}{Required if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: gradient steepness in units of (fraction of local value) per cell. Must be \eqn{\ge 0}.} + +\item{Optimum}{Required if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: \eqn{y}-value at which the extremum is obtained. Must be \eqn{\ge 0}.} + +\item{f}{Required if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: local scaling factor that determines the magnitude of stochastic local heterogeneity relative to the optimal value. Must be \eqn{\ge 0}.} + +\item{ExtinctOptim}{Required if \code{Gradient} \eqn{= 3}: optimum (i.e. minimal) local extinction probability at \code{Optimum}. Must be between \eqn{0} and \eqn{1}.} + +\item{Shifting}{Only applicable if \code{Gradient} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}:\cr +If \code{FALSE} (default), the gradient is stationary.\cr +If \code{TRUE}, the \code{Gradient} shifts along the \eqn{y}-axis towards increasing \eqn{y} (northwards). Requires to set \code{ShiftRate}, \code{ShiftStart} and \code{ShiftEnd},} + +\item{ShiftRate}{Required if \code{Shifting=TRUE}: shift rate of the gradient in units of rows per year. (integer)} + +\item{ShiftStart}{Required if \code{Shifting=TRUE}: year in which the gradient shifting starts (integer)} + +\item{ShiftEnd}{Required if \code{Shifting=TRUE}: year in which the gradient shifting stops. (integer)} + +\item{LocalExt}{If \code{FALSE} (default), no additional extinction probability is applied.\cr +If \code{TRUE}, an independent constant extinction probability \code{LocalExtProb} is applied, defined as +the probability that each population goes extinct at each year. +Note that \code{LocalExt} must be \code{FALSE} for a patch-based model or if \code{Gradient}\eqn{=3}.} + +\item{LocalExtProb}{Required if \code{LocalExt=TRUE}: independent yearly extinction probability of populations.} + +\item{EnvStoch}{Scale of environmental stochasticity:\cr +\eqn{0} = none (default),\cr +\eqn{1} = global (a single time series for entire landscape),\cr +\eqn{2} = local (each cell fluctuates independently, only permitted for cell-based model).\cr +Environmental stochasticity is always applied on a yearly basis.} + +\item{EnvStochType}{Required if \code{EnvStoch} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: Parameter to which environmental stochasticity is applied:\cr +\eqn{0} = growth rate \eqn{r} or, for a \code{\link[RangeShiftR]{StageStructure}}d population, fecundity (\eqn{\phi}).\cr +\eqn{1} = demographic density dependence \code{K_or_DensDep} (carrying capacity or 1/b) (allowed for artificial landscapes only!).} + +\item{std}{Required if \code{EnvStoch} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: magnitude of stochastic fluctuations. Must be \eqn{> 0.0} and \eqn{\le 1.0}.} + +\item{ac}{Required if \code{EnvStoch} \ifelse{html}{\out{≠ 0}}{\eqn{> 0}}: temporal autocorrelation coefficient. Must be \eqn{\ge 0.0} and \eqn{<1.0}.} + +\item{minR, maxR}{Required if \code{EnvStochType}\eqn{=0}: minimum and maximum growth rates.} + +\item{minK, maxK}{Required if \code{EnvStochType}\eqn{=1}: minimum and maximum value of \eqn{K} or \eqn{1/b}, respectively.} + +\item{OutIntRange, OutIntOcc, OutIntPop, OutIntInd, OutIntTraitCell, OutIntTraitRow, OutIntConn, OutIntPaths}{Control the various types +of Output files, i.e. range, occupancy, populations, individuals, traits (by cell or by row), connectivity and SMS paths:\cr + \eqn{=0 }: Output disabled.\cr + \eqn{>0 }: Output enabled; sets interval (in years) in which output is generated.\cr +If the output is enabled, start values are required. By default, only the output of Range and Population are enabled.\cr +Occupancy output is only applicable if \code{Replicates>1}. +Traits output is only applicable for a cell-based model with inter-individual variability. +Connectivity output is only applicable for a patch-based model. +SMS paths is only applicable for a model with SMS transfer method. + +Please note that with RangeShiftR version 2.0, the output of genetic data is no longer controlled within this function. +Instead, genetic data output is controlled within the \code{\link[RangeShiftR]{Genetics}}.} + +\item{OutStartPop, OutStartInd, OutStartTraitCell, OutStartTraitRow, OutStartConn, OutStartPaths}{Starting years for output generation. Note that the first year is year \eqn{0}. Defaults to \eqn{0} for all output types. (integer)} + +\item{SMSHeatMap}{Produce SMS heat map raster as output? Defaults to \code{FALSE}.} + +\item{ReturnPopMatrix}{Return population data to R as matrix (only for cell-based models)? Defaults to \code{FALSE}.} + +\item{ReturnPopDataFrame}{Return population data to R as data frame (most suitable for patch based models)? Defaults to \code{FALSE}.} + +\item{ReturnStages}{Return also stage-specific population data? Only applicable for stage-structured models if \code{ReturnPopMatrix = TRUE} or \code{ReturnPopDataFrame = TRUE}. If \code{FALSE} only total abundance is recorded.} + +\item{CreatePopFile}{Create population output file? Defaults to \code{TRUE}.} +} +\description{ +Set basic simulation parameters and control output types.\cr +Furthermore, optionally define a (\code{Shifting}) Environmental \code{Gradient}, Environmental Stochasticity (\code{EnvStoch}) and/or Local extinction (\code{LocalExt}). +(These options are to be moved to separate classes in future versions.) +} +\details{ +\emph{Environmental Gradient}\cr +In \emph{RangeShiftR}, it is possible to superimpose an artificial gradient on top of the landscape map (real or artificial). +Gradients are implemented for cell-based models only.\cr +An environmental gradient can be superimposed on the habitat map to describe gradual change in abiotic factors through space. Use the option \code{Gradient} +and choose one of three implemented parameter gradients. These are, respectively for non-structured / stage-structured population models:\cr +\itemize{ + \item{Decreasing values of \code{K_or_DensDep}, that mediates demographic density dependence (stronger with lower values) and is interpreted as + the \emph{carrying capacity} \eqn{K} / the \emph{strength of density dependence} \ifelse{html}{\out{b-1}}{\eqn{1/b}} (set \code{Gradient=1});} + \item{Decreasing growth rate \eqn{r} / fecundity (\eqn{\phi}) (set \code{Gradient=2});} + \item {Increasing local extinction probability \eqn{e} (set \code{Gradient=3}).} +} +The gradient is restrictively implemented along the north-south (\eqn{y})-axis and the selected parameter declines linearly with (\eqn{y})-distance from +an optimum location (\code{Optimum}). + +Gradients are implemented following the method of \insertCite{travis2004;textual}{RangeShiftR}, which combines linear variability with local heterogeneity. +If \eqn{Z} is one of the gradient variables listed above, \eqn{Z={K, 1/b, r, \phi, e}}, the value of \eqn{Z(x,y)} for a cell with \eqn{x} and \eqn{y}-coordinates +is given by the following equation: + +\ifelse{html}{\out{    Z(x,y) = Z0 * z(x,y)       for K and r,}}{\deqn{Z(x,y)=Z_0 * z(x,y)} for K and r,} +or\cr +\ifelse{html}{\out{    Z(x,y) = 1 - z(x,y) + eopt     for e}}{\deqn{Z(x,y)= 1 - z(x,y) + e_{opt}} for e} +\cr + +with \cr +\ifelse{html}{\out{    z(x,y) = 1 - |y - yopt| G + U(-1,1) f }}{\deqn{z(x,y) = 1 - |y - y_{opt}| G + U(-1,1) f }} +, constrained to \eqn{\ge 0} + +where \ifelse{html}{\out{Z0}}{Z_0} is the original parameter value at \eqn{(x,y)}, +\ifelse{html}{\out{eopt}}{e_{opt}} (\code{ExtinctOptim}) the minimum extinction probability. +The linear variability is specified by +\ifelse{html}{\out{yopt}}{y_{opt}} (\code{Optimum}), the \eqn{y}-value at which the extremum (i.e. \ifelse{html}{\out{Z0}}{Z_0} or \ifelse{html}{\out{eopt}}{e_{opt}}) is obtained, +and \eqn{G} (\code{GradSteep}), the gradient steepness in units of fraction of the local value per cell. +The local heterogeneity is determined by a random number drawn from a uniform distribution between \eqn{-1} and \eqn{1} for each cell +and \code{f}, the local scaling factor that determines the magnitude of this stochastic local variation relative to the extremal value. + +The gradient in fecundity φ applies to the fecundity of each stage. Negative local values in \eqn{z(x,y)} are set to \eqn{0}. + +It is also possible to simulate the shifting of the gradient by setting the option \code{Shifting}. Here the position \eqn{y} of the species’ +optimum is shifted northwards (increasing \eqn{y}) at a given rate \code{ShiftRate} (in units of rows per year), +starting from year \code{ShiftStart} to year \code{ShiftEnd}. + +Environmental gradients are available for cell-based models only, due to the cell-based character of operations and therefore \code{Gradient} +has to be \eqn{0} for patch-based models. + +\emph{Local Extinctions}\cr +An additional, independent extinction probability can be added using the option \code{LocalExt}. If set, +in each year, every population has an identical probability \code{LocalExtProb} of going extinct. +This does not affect any demographic parameters but simply kills off the local population. + +\emph{Environmental Stochasticity}\cr +It is possible to model environmental stochasticity via the option \code{EnvStoch} acting at a global or local scale +and can be applied to \code{K_or_DensDep}, the demographic density dependence (\code{EnvStoch=1}), or to growth rate / fecundity (\code{EnvStoch=0}). +It is implemented using a first order autoregressive process to generate time series of the noise value \eqn{ε} +\insertCite{ruokolainen2009}{RangeShiftR}: + +\deqn{ε(t+1) = κ ε(t) + \omega(t) \sqrt(1-\kappa^2)} + +where κ is the autocorrelation coefficient (\code{ac}) and ω is a random normal variable drawn from \eqn{N(0,σ)}. +Changing σ (\code{std}) changes the magnitude of the fluctuations. The spatial scale of the variation can either be global (a single time series +for the entire landscape) or local (each cell fluctuates independently), and is always applied on a yearly basis. +Different degrees of spatial autocorrelation are not implemented in the current version. + +The noise affects the species' selected parameter \eqn{Z} as follows: +\deqn{Z(x,y,t) = Z(x,y,0) + Z ε(t)} +where \eqn{x} and \eqn{y} are the cell coordinates and \eqn{Z} is the original parameter value in absence of stochasticity and gradients. +In the presence of an environmental gradient, \eqn{Z(x,y,0)} is the gradient value at the cell location, otherwise its equal to \eqn{Z}. +The resulting values \eqn{Z(x,y,t)} are limited to the maximum and minimum values \code{minR,maxR} or \code{minK,maxK}, respectively. + +\emph{Output files}\cr +Seven different types of outputs can be produced, plus one more for patch-based models. +All the output files will be named with a standard name reporting the simulation ID number and +the type of output. The file name will start with the batch number, and also indicate the number +of the landscape to which the output refers. Additionally, for each simulation all the set parameters +will be automatically written to a text file named \"Sim0_Parameters.txt\" in the case of simulation\eqn{#=0}. + +- \emph{Species range} (\code{Sim0_Range.txt}) \cr +contains the following general information regarding the species’ range:\cr +Replicate number (Rep), Year (Year), Reproductive season within the year (RepSeason), Total number of individuals (NInds), +Total number of individuals in each stage (NInd_stageX; only in case of stage-structured models), +Total number of juveniles born (NJuvs; only in case of stage-structured models), +Total number of occupied cells (NOccupCells) or total number of occupied patches (NOccupPatches), +Ratio between occupied and suitable cells or patches (OccupSuit), +Species’ range, in terms of maximum and minimum coordinates (min_X, max_X, min_Y, max_Y).\cr +Data are written before reproduction at each reproductive season at the specified yearly interval. An extra line is written +at the end of the simulation. + +- \emph{Occupancy} \cr +reports the cell/patch probability of occupancy. This is only possible if the number of replicates is greater than \eqn{1}. +Two files will be produced:\cr + + 1) \code{Sim0_Occupancy.txt}: contains a list of all the cells in the landscape (\eqn{x-} and \eqn{y-}coordinates) or +of all the patches (PatchID). The remaining columns give the occupancy probability of the cell/patch at defined time steps. +The occupancy probability is obtained by dividing the number of times (replicates) that the cell/patch has been occupied in +a given year, by the total number of replicates. + + 2) \code{Sim0_Occupancy_Stats.txt}: Summary occupancy statistics, i.e. the mean ratio between occupied and suitable cells +(Mean_OccupSuit) and its standard error (Std_error) at the set time interval. + + Data will be recorded at the beginning of the year before any other process (and only once a year no matter the number +of reproductive seasons per year). + +- \emph{Populations} (\code{Sim0_Pop.txt}) \cr +contains statistics regarding each population present in the landscape at a given time interval:\cr +Replicate number (Rep), Year (Year), Reproductive season within the year (RepSeason), Cell location (\eqn{x-} and \eqn{y-}coordinates) or +patch ID (PatchID), Species number (Species; not yet used, always \eqn{0}), Number of individuals in the population (NInd), +Number of individuals in each stage (NInd_stageX; only in case of stage-structured models). If the reproduction is sexual, +these columns will be replaced by the number of females (Nfemales_stageX) and of males (Nmales_stageX) in each stage. In the case +of sexual model without stage structure, two columns will indicate the number of females (Nfemales) and of males (Nmales) in +the population. In the case of a stage-structured population, the number of juveniles born (NJuvs). If the reproduction is sexual, +these columns will be replaced by the number of females juveniles (NJuvFemales) and males (NJuvMales).\cr +As for the species’ range output, data are collected before reproduction at each reproductive +season at the specified yearly interval and at the end of the simulation. + +- \emph{Individuals} (\code{Sim0_Rep0_Inds.txt}) \cr +contains information regarding each individual at a given time step. To avoid the production of huge files, a separate file is +saved for each replicate. Data are recorded after settlement and before aging (in the case of overlapping generations). For each +individual the following data are saved: \cr +Replicate number (Rep), Year, Reproductive season within the year (RepSeason), Species ID (always \eqn{0}), +Individual ID (IndID), the individual’s Status (Status), Natal cell (Natal_X and Natal_Y) and current cell (\eqn{x} and +\eqn{y}) coordinates or natal and current patch IDs (Natal_patch and PatchID), Sex (0 = female, 1 = male), Age in years +(in case of overlapping generations), Stage (in case of stage structure), Emigration traits, Transfer traits (depending on +transfer method). + +- \emph{Genetics} \cr +From RangeShiftR 2.0, the output of the genetic data is controlled within \code{\link[RangeShiftR]{Genetics}}. You can find a detailed describtion of available oputput files there. + +- \emph{Traits} \cr +In the case of inter-individual variability and evolution of the dispersal traits, it is possible to output the mean traits of +the population. There are two types of traits output:\cr + + 1) \code{Sim0_TraitsXcell.txt / Sim0_TraitsXpatch.txt} reports mean and standard deviation of the varying/evolving traits for each +cell/patch, for each replicate and reproductive season at the set year interval.\cr + + 2) \code{Sim0_TraitsXrow.txt} mean and standard deviation of the varying/evolving traits computed at the row (\eqn{y}) level, +pulling together all the populations occupying cells in \eqn{y}. Values are reported for each replicate and reproductive season +at the specified yearly interval. This is particularly useful for analyzing the structuring of traits along latitudinal gradients. +It is possible to compute this output only for cell-based models. \cr + + Data for these outputs are collected at the same time as for the +range and population outputs, i.e. before reproduction at each reproductive season at the set year interval and at the end of the +simulation. For sexual models, the standard deviation relates to the variation between all alleles in the local population (which +is greater than the variation in phenotypic expression; if the phenotypic s.d. is required, it must be calculated from +individual-level output data). + +- \emph{Connectivity matrix} (\code{Sim0_Connect.txt}) \cr +is available for a patch-based model only. It presents counts of the number of individuals successfully dispersing from each patch +to each other patch for each year specified by \code{OutIntConn}, starting from \code{OutStartConn}. If there is more than one +reproductive season during the year, cumulative year-end totals are reported. Although the file contains the data required for +true \eqn{NxN} matrices, the data are presented in list format:\cr +Replicate number (Rep), Year (Year), ID number of natal patch (StartPatch), ID number of settlement patch (EndPatch), Number of +individuals dispersing from StartPatch to EndPatch (NInds). + +- \emph{SMS paths} (\code{Sim0_Rep0_SMSpaths.txt}) \cr +is available for a model with transfer method SMS only. It lists the cell-based trajectories of all (successfully or unsuccessfully) +dispersed individuals from the natal to the final (settlement or fatal) patch for each year specified by \code{OutIntPaths}, starting +from \code{OutStartPaths}. The data are presented in list format with the columns:\cr +Year (Year), Individual ID (IndID), consecutive step number (Step), coordinates of cell at this step (\eqn{x} and \eqn{y}), +status of individual (Status). +The status is an integer number that codes for the following possible states:\cr + 0 = natal patch,\cr + 1 = disperser,\cr + 2 = disperser awaiting settlement in possible suitable patch,\cr + 3 = waiting between dispersal events,\cr + 4 = completed settlement,\cr + 5 = completed settlement in a suitable neighbouring cell,\cr + 6 = died during transfer by failing to find a suitable patch (includes exceeding maximum number of steps or crossing absorbing boundary),\cr + 7 = died during transfer by constant, step-dependent, habitat-dependent or distance-dependent mortality,\cr + 8 = failed to survive annual (demographic) mortality,\cr + 9 = exceeded maximum age.\cr\cr + +- \emph{SMS Heat map} (\code{OutputMaps/Sim0_Land0_Rep0_Visits.txt}) \cr +When the transfer model is \emph{SMS}, an additional optional output is a series of maps in ASCII raster format, showing how many times each +cell has been visited by a dispersing individual across the whole time period of the simulation. These heat maps may be useful, for example, +for identifying corridors which are heavily used during the dispersal phase. One raster map is created in the \emph{Output_Maps} folder for +each replicate simulation, and is in the same format as the input habitat file. + +- \emph{Log file} (\code{Batch1_RS_log.csv}) \cr +An additional log file will be created automatically. In it is listed the time taken (in seconds) to run the simulation. +It may also possibly include error codes, which can occur in rare occasions when the batch input files are in themselves valid, +but there is an inconsistency between files or an invalid habitat code or patch number occurs in an input map file. +Error codes are listed in the \emph{Batch_error_codes.xlsx} file. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/StageStructure.Rd b/RangeShiftR/man/StageStructure.Rd new file mode 100644 index 0000000..aef512d --- /dev/null +++ b/RangeShiftR/man/StageStructure.Rd @@ -0,0 +1,168 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DemogParams.R +\docType{class} +\name{StageStructure} +\alias{StageStructure} +\title{Define a Stage-structure} +\usage{ +StageStructure(Stages, TransMatrix, MaxAge = 100, MinAge = 0, + RepSeasons = 1, PRep = 1.0, RepInterval = 0, SurvSched = 0, + FecDensDep = FALSE, DevDensDep = FALSE, SurvDensDep = FALSE, + FecStageWtsMatrix, DevStageWtsMatrix, SurvStageWtsMatrix, + FecLayer, DevLayer, SurvLayer, + PostDestructn = FALSE) +} +\arguments{ +\item{Stages}{Number of life-stages (integer). Requires a minimum of \eqn{2}, for "juvenile" (stage 0) and "adult". Maximum is 10.} + +\item{TransMatrix}{Transition matrix. Defines the development probabilities from each stage into the next, as well as the respective survival probabilities and fecundities. See Details for matrix structure and notation.} + +\item{MaxAge}{Maximum age in years, defaults to \eqn{100}. (integer)} + +\item{MinAge}{Integer vector containing the ages which an individual in stage \eqn{i-1} (with sex \eqn{m/f}, if applicable) must already have reached before it can develop into the next stage \eqn{(i)}. The defaults are \eqn{0} for all stages and sexes. The required format is described in the Details.} + +\item{RepSeasons}{Number of potential reproduction events per year. Defaults to \eqn{1}. (integer)} + +\item{RepInterval}{Number of reproductive seasons which must be missed following a reproduction attempt, before another reproduction attempt may occur. Defaults to \eqn{0}. (integer)} + +\item{PRep}{Probability of reproducing in subsequent reproductive seasons. Defaults to \eqn{1.0}.} + +\item{SurvSched}{Scheduling of Survival. When should survival and development occur?\cr 0 = At reproduction\cr 1 = Between reproductive events (default)\cr 2 = Annually (only for \code{RepSeasons>1})} + +\item{FecDensDep, DevDensDep, SurvDensDep}{Density-dependent fecundity / development / survival probabilities? Defaults to \code{FALSE}. See Details for functional form of density-dependence.} + +\item{DevDensCoeff, SurvDensCoeff}{Relative density dependence coefficient for development / survival. Defaults to \eqn{1.0}.} + +\item{FecStageWtsMatrix, DevStageWtsMatrix, SurvStageWtsMatrix}{Stage-dependent weights in density dependence of fecundity / development / survival. Takes a quadratic matrix with (#sexes * #stages) rows/columns indicating the weight of the abundance of each stage/sex on the fecundity/development/survival of each other stage/sex. If not set, all stages are weighted equally.} + +\item{FecLayer, DevLayer, SurvLayer}{A matrix of layer indices for the three demographic rates (fecundity/development/survival) if they are spatially varying. The indices match the +scaling layers given in the \code{\link[RangeShiftR]{ImportedLandscape}} module to each demographic rate. The value NA denotes a spatially constant rate. The row number corresponds +to the stage; the first/second column contains the layer index for females/males. In case of a female-only or simple sexual model (\code{ReproductionType={0,1}}) only the first +column is needed and a vector is accepted to represent it. In any case, values will be coerced to integer.} + +\item{PostDestructn}{In a dynamic landscape, determine if all individuals of a population should die (\code{FALSE}, default) or disperse (\code{TRUE}) if its patch gets destroyed.} +} +\value{ +a parameter object of class "StagesParams" +} +\description{ +Set all demographic parameters for a stage-structured population. All elements of the transition matrix, i.e. Fecundity, Development, and Survival can be subjected to a density-dependent scaling. +In this case, the base probabilities given via the transition matrix will be reduced exponentially with the strength of density dependence \eqn{b(i,t)} times abundance \eqn{N(i,t)}, in patch \eqn{i} at time \eqn{t}. +Additionally, the effect of the abundances of each stage/sex on these parameters can be weighted. For more information, see the details. +} +\details{ +In stage-structured populations, generations can overlap and individuals can be classified in different stages (e.g. immature vs. breeding individuals) differing in their +demographic parameters. Individuals are characterized by their age and stage. Each stage has a certain fecundity, survival probability and probability of developing to the next stage. + +These parameters are provided through classical transition matrices \insertCite{caswell2001}{RangeShiftR}. +\ifelse{html}{\out{φi}}{\eqn{φ_i}} is the fecundity of stage \eqn{i} ; +\ifelse{html}{\out{σi}}{\eqn{σ_i}} is the survival probability of an individual in stage \eqn{i} ; +and \ifelse{html}{\out{γi-j}}{\eqn{γ_(i-j)}} is the probability of developing from stage \eqn{i} to stage \eqn{j}. +In this way, the transition matrix describes the effect of each individuals current stage (column) on all stages at the next timestep (rows). +Since all offspring is born into the juvenile stage (stage 0), all fecundities are always located in the first row of the matrix. + +However, in \emph{RangeShiftR}, these parameters are not used deterministically as \emph{rates} (like it is typical for matrix models) but, instead, as \emph{probabilities} which are +applied stochastically at the individual level. Hence, each female at stage \eqn{i}, if it reproduces, produces a number of offspring given by \eqn{Poisson}(\ifelse{html}{\out{φi}}{\eqn{φ_i}}), +while Bernoulli trials \eqn{Bern}(\ifelse{html}{\out{σi}}{\eqn{σ_i}}) and \eqn{Bern}(\ifelse{html}{\out{γi,i+1}}{\eqn{γ_(i,i+1)}}) determine if an individual/female survives or not +and - if it survives - if it develops to the next stage or not. + +An example transition matrix for a 3-staged only-female or simple sexual (\code{ReproductionType={0,1}}) population model: +\tabular{ccccc}{0 \tab | \tab 0 \tab | \tab \ifelse{html}{\out{φ2}}{\eqn{φ_2}} \cr +\eqn{1.0} \tab | \tab \ifelse{html}{\out{σ1 (1-γ1-2)}}{\eqn{σ_1 (1 − γ_(1-2))}} \tab | \tab \eqn{0} \cr +\eqn{0} \tab | \tab \ifelse{html}{\out{σ1 γ1-2}}{\eqn{σ_1 γ_(1-2)}} \tab | \tab \ifelse{html}{\out{σ2}}{\eqn{σ_2}} \cr} + +In a female-only model (\code{ReproductionType=0}), \ifelse{html}{\out{φ}}{\eqn{φ}} represents the number of female offspring per female and reproductive event. \cr +Note that for an implicit (simple) sexual model (\code{ReproductionType=1}), the demographic parameters are not sex-specific. However, individuals are defined by their sex, which is acknowledged for example in the dispersal +process and transmission of alleles. The fecundities \ifelse{html}{\out{φ}}{\eqn{φ}} refer to the number of all offspring (males and females) per female and reproductive event. + +In case of an explicit (complex) sexual model (\code{ReproductionType=2}), in contrast, each stage must be represented by two columns and rows to distinguish male and female demographic parameters. +Note, however, that in any case the juvenile stage has only one row; it contains the fecundities. Male fecundities should have one of two possible values: set \ifelse{html}{\out{φm}}{\eqn{φ_m}} \eqn{=1.0} for reproductive males or \ifelse{html}{\out{φm}}{\eqn{φ_m}} \eqn{=0.0} for non-reproductive males.\cr +An example transition matrix for a 3-staged explicit sexual population model \insertCite{weeks1986,lindstrom1998}{RangeShiftR}: +\tabular{ccccccccccc}{\eqn{0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{φ1m}}{\eqn{φ_1m}} \tab | \tab \ifelse{html}{\out{φ1f}}{\eqn{φ_1f}} \tab | \tab \ifelse{html}{\out{φ2m}}{\eqn{φ_2m}} \tab | \tab \ifelse{html}{\out{φ2f}}{\eqn{φ_2f}} \cr +\eqn{1.0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1m (1-γ1-2,m)}}{\eqn{σ_1m (1 − γ_(1-2,m))}} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \cr +\eqn{0} \tab | \tab \eqn{1.0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1f γ1-2,f}}{\eqn{σ_1f γ_(1-2,f)}} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \cr +\eqn{0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1m γ1-2,m}}{\eqn{σ_1m γ_(1-2,m)}} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ2m}}{\eqn{σ_2m}} \tab | \tab \eqn{0} \cr +\eqn{0} \tab | \tab \eqn{0} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ1f γ1-2,f}}{\eqn{σ_1f γ_(1-2,f)}} \tab | \tab \eqn{0} \tab | \tab \ifelse{html}{\out{σ2f}}{\eqn{σ_2f}} \cr}#' The mating system is explicitly modelled and a female’s probability of reproducing is determined as described in \code{\link[RangeShiftR]{Demography}} \insertCite{weeks1986,caswell2001}{RangeShiftR}. + +A common mistake in building a transition matrix is made when offspring produced at year \eqn{t} develop to the next stage in the same year \insertCite{@ @caswell2001 pg. 60-62}{RangeShiftR}. To avoid this problem without losing the offspring stage, and hence the chance for simulating post-natal dispersal, +we require an additional explicit juvenile stage (stage 0). Juveniles have to develop to stage 1 in the same year they are born. Hence the minimum number of stages of a stage-structured model is always \eqn{2}. It is important to note that juvenile mortality can be accounted for in +two ways. Either, as in the examples above, it is included in adult fecundity \ifelse{html}{\out{φ}}{\eqn{φ}} (by appropriately reducing its value), and \ifelse{html}{\out{σ0 γ(0-1)}}{\eqn{σ_0 γ_(0-1)}} is equal to \eqn{1.0}. This is how it is typically accounted for in matrix models. Or, alternatively, +φ is equal to the true maximum fecundity and \ifelse{html}{\out{σ0 γ(0-1)}}{\eqn{σ_0 γ_(0-1)}} is less than \eqn{1.0}. +Only the first approach allows straightforward direct comparison with standard analytical matrix models. + +\emph{Minimum ages:} For every row in the transition matrix, a minimum age must be provided through a vector in argument \code{MinAge}. It specifies the age which an individual in stage \eqn{i-1} (with sex \eqn{m/f}, if applicable) must already have reached before it can develop into the next stage \eqn{(i)}. The vector must be in +the order of increasing stage, stating first male then female values; i.e. \eqn{0,1m,1f,2m,2f,...}. Note that (analogous to the transition matrix) the juvenile stage (\eqn{i=0}) has only one entry for male and female. The defaults are \eqn{0} for all stages and sexes. +Note that the minimum age for juveniles (stage \eqn{0}) is by definition zero, and that the minimum age for stage \eqn{1} is required to also be zero because individuals may not persist as juveniles beyond the breeding season in which they are born. + +It is possible to have one or more reproductive seasons per year (\code{RepSeasons}), or a reproductive event once every few years (controlled by \code{RepInterval}). At each reproductive season, two parameters +control the likelihood that each individual / female reproduces: +\enumerate{ +\item First, it is determined whether a reproductively mature female is a potential reproducer. The user specifies a minimum interval (\code{RepInterval}) before an individual, that has +already reproduced, is able to reproduce again. Only those mature individuals that are either yet to reproduce, or last reproduced more than this number of reproductive seasons previously, are potential breeders. +\item Potential breeders all reproduce with a set probability (\code{PRep}). Note that this probability is different from the probability of reproducing \ifelse{html}{\out{pr}}{\eqn{p_r}} described in \code{\link[RangeShiftR]{Demography}}. +The latter will be additionally applied only in the case of more complex modelling of the mating system (\code{ReproductionType=2}) and it is determined by the number of reproductive males and females present in the cell/patch. +} +Note that in the current implementation, reproductive attempts that result in zero offspring still count in terms of an individual having to wait for the chance to reproduce again. + +A major difference between transition matrices and this individual-based model is that in the first, the three processes of reproduction, survival and development happen simultaneously while, in the second, they are explicitly modelled in sequence. +The sequence of these events and the time of the dispersal phase in relation to them can change the actual dynamics and density-dependencies in both population growth and dispersal. At the beginning of each year, reproduction is always the first +process to be modelled. However, there can be multiple reproductive seasons per year (default is one); in this case the year starts with a succession of all reproductive seasons. There are three choices for the scheduling of reproduction, survival, development and dispersal: +\itemize{ +\item \code{SurvSched=0}: For each reproductive season: reproduction; survival and development of all stages (apart from stage 0); dispersal; survival and development of stage 0. Then: aging; end of the year. +\item \code{SurvSched=1}: For each reproductive season: reproduction; dispersal; survival and successive development of all stages. Then: aging; end of the year. +\item \code{SurvSched=2}: For each reproductive season: reproduction; dispersal. Then: survival and development of all stages; aging; end of the year. This option applies only for species having multiple reproductive seasons in a year, otherwise it is equivalent to \code{SurvSched=1}. +} +Option \code{SurvSched=0} gives results that are comparable with the deterministic solution of the matrix. The choice will depend on the biology of the species. If the main mortality happens overwinter, option \code{SurvSched=1} might be more appropriate. + +Note that \code{SurvSched=1} in combination with multiple reproductive seasons (\code{RepSeasons>1}) implies several evaluations of the fecundity and the survival and development probabilities, so that the transition matrix should be set accordingly. +If the transition matrix contains the annual survival and development rates, \code{SurvSched=2} is the appropriate option (fecundity, however, is still given per reproductive event). + +\emph{Density dependence} can act on each of the three demographic phases (i.e. reproduction, survival and development) and is controlled by \code{FecDensDep,DevDensDep,SurvDensDep}. +It is implemented as an exponential decay \insertCite{neubert2000}{RangeShiftR}: + +\ifelse{html}{\out{   φi(r,t) = φ0,i * e - b(r) N(t) }}{\deqn{φ_i(r,t)=φ_(0,i) * exp(- b(r) N(t) ) }} + +\ifelse{html}{\out{   σi(r,t) = σ0,i * e - Cσ b(r) N(t) }}{\deqn{σ_i(r,t)=σ_(0,i) * exp(- C_\sigma b(r) N(t) ) }} + +\ifelse{html}{\out{   γi(r,t) = γ0,i * e - Cγ b(r) N(t) }}{\deqn{γ_i(r,t)=γ_(0,i) * exp(- C_γ b(r) N(t) ) }} + +where \eqn{b(r)} is the strength of density dependence in fecundity at site \eqn{r}, which is given by the argument \code{K_or_DensDep} in the landscape module. +Furthermore, \ifelse{html}{\out{Cσ}}{\eqn{C_\sigma}} and \ifelse{html}{\out{Cγ}}{\eqn{C_γ}} (\code{DevDensCoeff,SurvDensCoeff}) +scale the strength of density dependence in survival and development relative to that in fecundity. + +Moreover, the strength of density-dependence can be uniform for all stages or stage-dependent. Even greater complexity can be incorporated with +different stages contributing differently to density-dependence \insertCite{caswell2004}{RangeShiftR}: + +\ifelse{html}{\out{  φi(r,t) = φ0,i * e - b(r) ΣjS ωφ,ij N(j,t)}}{\deqn{φ_i(r,t)=φ_(0,i) * exp(- b(r) \Sigma_j^S ω_{φ,ij} N_j(t) ) }} + +\ifelse{html}{\out{  σi(r,t) = σ0,i * e - Cσ b(r) ΣjS ωσ,ij N(j,t) }}{\deqn{σ_i(r,t)=σ_(0,i) * exp(- C_\sigma b(r) \Sigma_j^S ω_{σ,ij} N_j(t) )}} + +\ifelse{html}{\out{  γi(r,t) = γ0,i * e - Cγ b(r) ΣjS ωγ,ij N(j,t)}}{\deqn{γ_i(r,t)=γ_(0,i) * exp(- C_γ b(r) \Sigma_j^S ω_{γ,ij} N_j(t) )}} + +where \ifelse{html}{\out{ωφ}}{\eqn{ω_φ}}, \ifelse{html}{\out{ωσ}}{\eqn{ω_σ}}, \ifelse{html}{\out{ωγ}}{\eqn{ω_γ}} are weight matrices given by \code{FecStageWtsMatrix, DevStageWtsMatrix, SurvStageWtsMatrix}. Their elements \ifelse{html}{\out{ωij}}{\eqn{ω_ij}} +represent the contributions of the abundance of stage \eqn{j} to the density dependence in the fecundity / survival / development of stage \eqn{i}, thus they are quadratic matrices of size \code{Stages}\eqn{^2}. Note that the row sums are not required to be normalized, therefore they can be used +to scale the density-dependence for the different stages. In fact, any real value will be accepted for the single weights, so care should be taken when setting them. + +The demographic rates (fecundity, development probability and survival probability) can be allowed to vary spatially, if the landscape is an imported habitat quality map. In this case, additional maps with the same resolution and extent as the habitat quality map(s) need to be given +in \code{\link[RangeShiftR]{ImportedLandscape}()}. These additional layers contain percentage values between 0 and 100 and the matrices \code{FecLayer}, \code{DevLayer}, and \code{SurvLayer} indicate the mapping of each demographic rate to these layers. The local value +of a given demographic rate for a certain stage and sex in a cell or patch is then determined as the maximum value (the value given in the transition matrix \code{TransMatrix}) scaled with the percentage in the respective mapped layer. +For a patch-based landscape, the scaling percentage of a patch is given by the average percentage of its constituent cells. +Potential density-dependence mediated by the strength 1/b still takes effect also for spatially-varying demographic rates. The respective base values φ_0, σ_0 or γ_0 are then replaced by their locally scaled values. +} +\examples{ + # Stage-structure for simple sexual model +transmat <- matrix(c(0,1,0,0,0,0.3,0.4,0,1.5,0,0.6,0.3,2.5,0,0,0.8), ncol = 4) +stg <- StageStructure(Stages = 4, TransMatrix = transmat, FecDensDep = TRUE, SurvDensDep = TRUE, SurvDensCoeff = 1.5) +plotProbs(stg, stage=1:3) + + # Stage-structure for explicit sexual model +transmat_2 <- matrix(c(0,0.5,0,0,0,0,0,0.5,0,0,1.0,0.4,0,0.3,0,3.0,0,0.3,0,0.4,1.0,0,0,0.85,0,5,0,0,0,0.8), ncol = 6) +stg_2 <- StageStructure(Stages = 3, TransMatrix = transmat_2, FecDensDep = TRUE, DevDensDep = TRUE, DevDensCoeff = 1.2) +plotProbs(stg_2, stage=c(1,2), sex = 1) +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/Traits.Rd b/RangeShiftR/man/Traits.Rd new file mode 100644 index 0000000..ae470ef --- /dev/null +++ b/RangeShiftR/man/Traits.Rd @@ -0,0 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_GeneticsParams.R +\docType{class} +\name{Traits} +\alias{Traits} +\title{Set genetic traits structure} +\usage{ +Traits(Neutral = FALSE, +GeneticLoad = FALSE, +EmigrationGenes = FALSE, +SettlementGenes = FALSE, +CorrRWGenes = FALSE, +SMSGenes = FALSE, +KernelGenes = FALSE) +} +\arguments{ +\item{Neutral}{If neutral traits should be modelled, define \code{\link[RangeShiftR]{NeutralTraits}}. If \code{FALSE} (default), the neutral traits are not modelled.} + +\item{GeneticLoad}{If genetic load should be modelled, define \code{\link[RangeShiftR]{GeneticLoadTraits}}. There can be up to 5 genetic loads. If \code{FALSE} (default), the genetic load is not modelled.} + +\item{EmigrationGenes}{If evolvable emigration traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{Emigration}}), define \code{\link[RangeShiftR]{EmigrationTraits}}. If \code{FALSE} (default), the emigration traits are not modelled/evolvable.} + +\item{SettlementGenes}{If evolvable settlement traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{Settlement}}), define \code{\link[RangeShiftR]{SettlementTraits}}. If \code{FALSE} (default), the settlement traits are not modelled/evolvable.} + +\item{CorrRWGenes}{If evolvable CorrRW traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{CorrRW}}), define \code{\link[RangeShiftR]{CorrRWTraits}}. If \code{FALSE} (default), the CorrRW traits are not modelled/evolvable.} + +\item{SMSGenes}{If evolvable SMS traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{SMS}}), define \code{\link[RangeShiftR]{SMSTraits}}. If \code{FALSE} (default), the SMS traits are not modelled/evolvable.} + +\item{KernelGenes}{If evolvable Kernel traits should be modelled (\code{IndVar = TRUE} in \code{\link[RangeShiftR]{Kernel}}), define \code{\link[RangeShiftR]{KernelTraits}}. If \code{FALSE} (default), the Kernel traits are not modelled/evolvable.} +} +\value{ +a parameter object of class "TraitsParams" +} +\description{ +Three types of traits can be made evolvable and parameterised with their own genetic architecture: + +- Dispersal traits correspond to the main parameters controlling each phase of dispersal (emigration, transfer and settlement). \cr +- Genetic fitness traits represent genetic load, the accumulation of deleterious mutations and their effect on the viability of newborn offspring. \cr +- Neutral trait does not have any phenotypic effect during the simulation. It is used to compute F-statistics and other measures of neutral variation. \cr +} +\details{ +The parameterisation structure for each type of trait is defined in the corresponding subclasses: + +- Dispersal traits: \code{\link[RangeShiftR]{EmigrationTraits}}, \code{\link[RangeShiftR]{SettlementTraits}}, \code{\link[RangeShiftR]{CorrRWTraits}}, \code{\link[RangeShiftR]{SMSTraits}} and \code{\link[RangeShiftR]{KernelTraits}} \cr +- Genetic fitness traits: \code{\link[RangeShiftR]{GeneticLoadTraits}} \cr +- Neutral traits: \code{\link[RangeShiftR]{NeutralTraits}} \cr + +They follow a similar structure, but some parameters and their specific options are specific to the type of trait. + +Parameters that need to be defined: + +- The number and positions of genes controlling the trait. \cr +- A rule for expression (restricted to dispersal traits, for genetic load it is fixed to 'multiplicative') \cr +- Initialized positions (restricted to neutral traits and genetic fitness traits, for dispersal traits it is fixed to 'all') \cr +- Option for inter-individual variability in without inheritance (restricted to dispersal traits) \cr +- A mutation rate for all genes controlling the trait. \cr +- A distribution to sample mutations from. \cr +- A distribution to sample initial allele values and dominance coefficients (the latter is restricted to genetic fitness traits) from. \cr +- A distribution to sample dominance coefficients from (restricted to genetic fitness traits). \cr +- Whether allele values should be written to output. +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/Transfer.Rd b/RangeShiftR/man/Transfer.Rd new file mode 100644 index 0000000..4d5f973 --- /dev/null +++ b/RangeShiftR/man/Transfer.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_DispersalParams.R +\docType{class} +\name{Transfer} +\alias{Transfer} +\alias{TransferParams} +\title{Set a Transfer method} +\description{ +Transfer (or transience) is the second phase of dispersal. It consists of the movement of an individual departing from its natal patch towards +a potential new patch, ending with settlement or mortality. This movement can be modelled by one of three alternative processes:\cr +- Dispersal kernel: use \code{\link[RangeShiftR]{DispersalKernel}}\cr +- Stochastic movement simulator (SMS): use \code{\link[RangeShiftR]{SMS}}\cr +- Correlated random walk (CRW): use \code{\link[RangeShiftR]{CorrRW}} +} +\details{ +The choice between the two main methods to model the transfer phase, i.e. phenomenological dispersal kernels or mechanistic movement processes +(SMS and CRW) depends on the information available for a given species and on the level of detail that is considered important to represent in +the model (which will depend on its aim and the scale). +\cr +Dispersal is often a costly process for an organism \insertCite{bonte2012costs}{RangeShiftR} and, in some cases, a dispersing individual may +suffer mortality. Obtaining a sensible +representation of dispersal requires that these mortality costs are described appropriately. The total dispersal mortality experienced will +be the sum of two main sources of mortality: First, as the result of individuals failing to reach suitable habitat, and second, as the result +of increased energetic, time or attritional costs that longer-distance dispersers will experience. +For more details, refer also to the respective Details sections of the different transfer methods. +In parameterising the model, it will be important to recognise this such that dispersal mortality is not double-accounted. +} +\references{ +\insertAllCited{} +} +\author{ +Anne-Kathleen Malchow +} diff --git a/RangeShiftR/man/Translocation.Rd b/RangeShiftR/man/Translocation.Rd new file mode 100644 index 0000000..3526e37 --- /dev/null +++ b/RangeShiftR/man/Translocation.Rd @@ -0,0 +1,96 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class_ManagementParams.R +\docType{class} +\name{Translocation} +\alias{Translocation} +\title{Translocation Parameters} +\usage{ +Translocation(years = 1, + TransLocMat = 0, + catching_rate = 0.5 + ) +} +\arguments{ +\item{years}{Vector of years in which translocation events should take place} + +\item{TransLocMat}{Matrix of translocation events. Each row represents a translocation event. Columns represent: + + - the year of the event,\cr + - the source location (\code{Patch_ID} in case of cell-based models or \code{X} and \code{Y} location in case of cell-based models),\cr + - the destination location (\code{Patch_ID} in case of cell-based models or \code{X} and \code{Y} location in case of cell-based models),\cr + - the number of individuals which are tried to be caught,\cr + - minimal age of each individual,\cr + - maximal age of the individual,\cr + - stage of the individual,\cr + - sex of the individual\cr} + +\item{catching_rate}{Catching success rate} +} +\value{ +a parameter object of class "ManagementParams" +} +\description{ +Translocation is a conservation management strategy to reintroduce species in areas where they have been extirpated, +stabilize metapopulations or enhance (genetic) connectivity between fragmented habitats. +Translocations aim to increase the survival probabilities of species, boost genetic diversity, +and restore ecological balance. Success depends on careful selection of suitable source and destination sites, as well as +appropriate selection of individuals to be relocated. +} +\details{ +\strong{General information} + +This function translocates a specified number of individuals with given characteristics from a source site +to a destination site in a specified year representing a translocation event. +In other words, a translocation event is defined by a unique combination of the year, source and +destination site, and the number and characteristics of selected individuals. + +You must set at least one translocation event, but there is no upper limit. Multiple translocation events can occur +per year (differing in either the characteristics of the individuals selected or +the source and destination sites), or across different years. + +Individuals can be selected according to their age, stage and sex, depending on the type of demographic model applied. +Only individuals which are currently not in the transfer phase are eligible for translocation. +After being translocated, individuals are assumed to not disperse further. + +Additionally, you can define a constant catching success rate to determine the likelihood of successfully capturing a selected individual. + +\strong{Setting translocation parameters} + +You need to create a Translocation Matrix \code{TransLocMat} which hold the information for each translocation event in each row. + +In the columns of the \code{TransLocMat} the year, source and destination site as well as the number of individuals and the characteristics are +defined in the following order: + +- \code{year} of the translocation event \cr +- \code{Patch_ID} or \code{X} and \code{Y} location of the source site from which individuals are caught. \cr +- \code{Patch_ID} or \code{X} and \code{Y} location of the destintation site to which individuals are relocated. \cr +- \code{nb_catch} how many individuals of the given set of characteristics are tried to be caught \cr +- \code{min_age} minimal age of the individual in the interval of 0-MaxAge. Set to -9 to ignore. \cr +- \code{max_age} maximal age of the individual in the interval of \code{min_age}-MaxAge. Set to -9 to ignore.\cr +- \code{stage} of the individual. Set to -9 to ignore. \cr +- \code{sex} of the individual: Only for sexual models, otherwise set to -9 to ignore \cr + +\code{min_age}, \code{max_age} and \code{stage} can only be defined for stage structured models. +For non stage structured models, or to ignore the characteristic, set the value to -9. + +\code{sex} can only be defined for sexual models. For non sexual models, or to ignore the characteristic, set the value to -9. + +To avoid unsuccessful translocation events, you should set the range of allowed characteristics as broad as possible. + +Each row of the translocation matrix \code{TransLocMat} should hold a unique combination of a source and a destination location, +the number of individuals to catch as well as characteristics of these individuals. +You may add more than one translocation event per year, i.e. there may be multiple source and destination sites for each year of a translocation +event or multiple individual characteristics for a certain pair of source and destination site. + +In each \code{year} of a translocation event, individuals matching the given criteria in the source site are collected and a given number of individuals \code{nb_catch} +are sampled from this subset. The success of catching one of these sampled individuals in the source location is defined by the \code{catching_rate}. +Successfully caught individuals are then translocated to the destination site and the individual will be assigned the status 10 (translocated) and will not further disperse. + +The source as well as the destination sites are required to be habitat patches or cells of the landscape. Otherwise the translocation event will be skipped. +} +\references{ +\insertAllCited{} +} +\author{ +Jette Wolff +} diff --git a/RangeShiftR/man/createODD.Rd b/RangeShiftR/man/createODD.Rd new file mode 100644 index 0000000..24804ba --- /dev/null +++ b/RangeShiftR/man/createODD.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{createODD} +\alias{createODD} +\title{Creating ODD template file for a specific RangeShiftR parameter master object} +\usage{ +createODD(filename, s, type, title) +} +\arguments{ +\item{filename}{Name of the R markdown file and document to be created, must have ending ".Rmd", e.g. 'ODD_protocol.Rmd'} + +\item{s}{RangeShiftR parameter object} + +\item{type}{file type of the rendering process output. Can currently only be "pdf_document"} + +\item{title}{Title of the study if possible including authors, e.g. "'Study title ABC' by author ABC} +} +\description{ +This function creates an ODD template file for a specific RangeShiftR parameter master object \code{s}. +It only creates a new file, if the \code{filename} doesn't exist in the folder. +If the \code{filename} already exists, it only renders the document to the given type. +} diff --git a/RangeShiftR/man/createParameterTables.Rd b/RangeShiftR/man/createParameterTables.Rd new file mode 100644 index 0000000..4bd6ca5 --- /dev/null +++ b/RangeShiftR/man/createParameterTables.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{createParameterTables} +\alias{createParameterTables} +\title{Creating parameter table file for a specific RangeShiftR parameter master object} +\usage{ +createParameterTables(filename, s, type, title) +} +\arguments{ +\item{filename}{Name of the R markdown file and document to be created, e.g. 'Parameter_table.rmd'} + +\item{s}{RangeShiftR parameter object} + +\item{type}{file type of the rendering process output. Can be either "pdf_document", "word_document" or "md_document" We recommend using "word_document" to refine the layout.} + +\item{title}{Title of the study if possible including authors, e.g. "'Study title ABC' by author ABC} +} +\description{ +This function creates a file with tables of the parameter set for a specific RangeShiftR parameter master object \code{s}. +It only creates a new file, if the \code{filename} doesn't exist in the folder. +If the \code{filename} already exists, it only renders the document to either pdf, word or md. +} diff --git a/RangeShiftR/man/figures/RSRlogo.png b/RangeShiftR/man/figures/RSRlogo.png new file mode 100644 index 0000000..ae378b7 Binary files /dev/null and b/RangeShiftR/man/figures/RSRlogo.png differ diff --git a/RS_repos.png b/RangeShiftR/man/figures/RS_repos.png similarity index 100% rename from RS_repos.png rename to RangeShiftR/man/figures/RS_repos.png diff --git a/branches.png b/RangeShiftR/man/figures/branches.png similarity index 100% rename from branches.png rename to RangeShiftR/man/figures/branches.png diff --git a/RangeShiftR/man/getLocalisedEquilPop.Rd b/RangeShiftR/man/getLocalisedEquilPop.Rd new file mode 100644 index 0000000..06b08f9 --- /dev/null +++ b/RangeShiftR/man/getLocalisedEquilPop.Rd @@ -0,0 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{getLocalisedEquilPop} +\alias{getLocalisedEquilPop} +\title{Calculates the equilibrium density and stage distribution for a localised (i.e. non-spatial) closed population} +\usage{ +getLocalisedEquilPop(demog, ...) +} +\arguments{ +\item{demog}{DemogParams object with a \code{StageStructure}} + +\item{DensDep_values}{values of \eqn{1/b} to run the matrix model for} + +\item{plot}{plot the equilibrium densities? (default is \code{TRUE})} + +\item{stages_out}{which stages to plot? (defaults to all)} + +\item{juv.stage}{use explicit juvenile (zeroth) stage? (default is \code{TRUE})} + +\item{t_rec}{number of time steps to record at the end (defaults to \eqn{1}); if \code{t_rec}\eqn{>1}, the mean over all recorded time steps is returned} + +\item{N_0}{initial condition, i.e. population density at time zero; must include stage zero regardless of the value of \code{juv.stage}} + +\item{t_max}{allowed number of time steps to reach equilibrium (default is \eqn{1000})} + +\item{delta}{tolerance to check for equilibrium (default is \eqn{.1}); the utilised measure is euclidian distance of current to previous time steps} + +\item{diagnostics}{in addition to recorded population vectors, returns the number of steps taken as well as the transition matrix and the value if delta at the last step (default is \code{FALSE})} +} +\value{ +a matrix of population densities with a named row for each stage and a column for each given value of \eqn{1/b} +} +\description{ +Uses the \emph{RangeShiftR} Demography module to create the corresponding matrix model and runs it until equilibrium is reached. +This corresponds to a localised population in a single cell without dispersal (i.e. no immigration or emigration). +Since the matrix model representation is used, some options (e.g. maximum age) of the \code{\link[RangeShiftR]{Demography}} module can not be taken into account. +} +\details{ +\emph{RangeShiftR} requires an additional juvenile stage to be added to the common transition matrix as stage \eqn{0} (in order +to allow for juvenile dispersal). For the simulation with \code{RunMatrixModel()}, this stage can be kept (\code{juv.stage=TRUE}) +or removed to yield the corresponding Lefkovitch matrix (\code{juv.stage=FALSE}).\cr +The default initial state \code{N_0} is a population at its respective density \eqn{1/b} with unpopulated juvenile stage and +all higher stages equally populated.\cr +} diff --git a/RangeShiftR/man/plotAbundance.Rd b/RangeShiftR/man/plotAbundance.Rd new file mode 100644 index 0000000..f0ba235 --- /dev/null +++ b/RangeShiftR/man/plotAbundance.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{plotAbundance} +\alias{plotAbundance} +\title{Plot Abundance} +\usage{ +plotAbundance(s, ...) +} +\arguments{ +\item{s}{RSparams object or a data.frame in the 'range' file format} + +\item{dirpath}{RS directory path; required if \code{s} is a \code{RSparams}} + +\item{sd}{plot standard deviation? (default is \code{FALSE})} + +\item{replicates}{plot the replicates? (default is \code{TRUE})} + +\item{ylim}{upper limit to the y-axis} +} +\description{ +Uses the RangeShiftR output data 'range' to generate abundance time series. +Plots the mean abundance over all replicates, and optionally the standard deviation and/or the single replicates. +} diff --git a/RangeShiftR/man/plotOccupancy.Rd b/RangeShiftR/man/plotOccupancy.Rd new file mode 100644 index 0000000..4cd4d91 --- /dev/null +++ b/RangeShiftR/man/plotOccupancy.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{plotOccupancy} +\alias{plotOccupancy} +\title{Plot Occupancy} +\usage{ +plotOccupancy(s, ...) +} +\arguments{ +\item{s}{RSparams object or a data.frame in the 'range' file format} + +\item{dirpath}{RS directory path; required if \code{s} is a \code{RSparams}} + +\item{sd}{plot standard deviation? (default is \code{FALSE})} + +\item{replicates}{plot the replicates? (default is \code{TRUE})} + +\item{ylim}{upper limit to the y-axis} +} +\description{ +Uses the RangeShiftR output data 'range' to generate occupancy time series. +Plots the mean occupancy over all replicates, and optionally the standard deviation and/or the single replicates. +} diff --git a/RangeShiftR/man/plotProbs.Rd b/RangeShiftR/man/plotProbs.Rd new file mode 100644 index 0000000..29d6497 --- /dev/null +++ b/RangeShiftR/man/plotProbs.Rd @@ -0,0 +1,50 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plotProbs.R +\name{plotProbs} +\alias{plotProbs} +\title{Plot parameterised probabilities} +\usage{ +plotProbs(x, ...) +} +\arguments{ +\item{x}{a RangeShiftR parameter object} + +\item{...}{various options, depend on the given parameter module type} + +\item{xmax, ymax}{upper plotting limits (lower limits are fixed to \eqn{0})} + +\item{stage, sex}{stage(s) and sexe(s) to plot, default: all} +} +\description{ +Visualise the dependencies or distributions of probabilities of the various processes that are defined by the different parameter modules, +like e.g. fecundity or mortality. +} +\details{ +Available methods and their options: +\itemize{ + \item \code{\link[RangeShiftR]{Emigration}}: plot emigration probability + \item \code{\link[RangeShiftR]{DispersalKernel}}: + \itemize{ + \item \code{mortality=FALSE} - plot dispersal distance probability density (default) + \item \code{mortality= TRUE} - plot mortality probability + } + If a mixed kernel was defined (i.e. \code{DoubleKernel=TRUE}), plot the resulting dispersal probability by... + \itemize{ + \item \code{combinekernels=FALSE} - ...plotting both kernels separately (default) + \item \code{combinekernels= TRUE} - ...combining both kernels, i.e. \ifelse{html}{ \out{p(d; δ1,δ2) = pI p(d;δ1) + (1-pI) p(d;δ1) } }{\deqn{ p(d; δ_1,δ_2) = p_I p(d;δ_1) + (1-p_I) p(d;δ_2)} } + } + \item \code{\link[RangeShiftR]{StageStructure}}: plot fecundity as well as survival and development probabilities. + + Survival and development are calculated based on the transition matrix. Consider e.g. a 3 stage matrix with a transition matrix of + + \tabular{ccccc}{0 \tab | \tab 0 \tab | \tab \ifelse{html}{\out{φ2}}{\eqn{φ_2}} \cr + \eqn{1.0} \tab | \tab \ifelse{html}{\out{σ1 (1-γ1-2)}}{\eqn{σ_1 (1 − γ_(1-2))}} \tab | \tab \eqn{0} \cr + \eqn{0} \tab | \tab \ifelse{html}{\out{σ1 γ1-2}}{\eqn{σ_1 γ_(1-2)}} \tab | \tab \ifelse{html}{\out{σ2}}{\eqn{σ_2}} \cr} + + The survival probability is calculated as the sum of the probability to stay in the same stage and the probability to reach the next stage. + E.g. for stage 1: \ifelse{html}{\out{σ1 = sum( σ1 (1-γ1-2), σ1 γ1-2}}{\eqn{σ_1 = sum(σ_1 (1 − γ_(1-2)), σ_1 γ_(1-2))}} + + The development probability of stage 1 to stage 2 is the ratio of the probability to reach stage 2 and the previously calculated survival probability. + E.g. for stage 1: \ifelse{html}{\out{γ1-2 = σ1 γ1-2 / σ1}}{\eqn{γ_(1-2) = σ_1 / (σ_1 γ_(1-2) )}} +} +} diff --git a/RangeShiftR/man/readPop.Rd b/RangeShiftR/man/readPop.Rd new file mode 100644 index 0000000..ceed504 --- /dev/null +++ b/RangeShiftR/man/readPop.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{readPop} +\alias{readPop} +\title{Read 'pop' file} +\usage{ +readPop(s, dirpath, ...) +} +\arguments{ +\item{s}{RSmaster parameter object} + +\item{dirpath}{RS directory path} + +\item{center}{In a cell-based model, the x- and y- coordinates will be converted from *nrow* and *ncol* (as in the 'pop' output file) +to true coordinates of the center of the cell measured in metres.} +} +\value{ +a data.frame +} +\description{ +Read the RangeShiftR output file 'pop' into a data.frame, if it was generated. +} diff --git a/RangeShiftR/man/readRange.Rd b/RangeShiftR/man/readRange.Rd new file mode 100644 index 0000000..2f5000a --- /dev/null +++ b/RangeShiftR/man/readRange.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/output_handling.R +\name{readRange} +\alias{readRange} +\title{Read 'range' file} +\usage{ +readRange(s, dirpath) +} +\arguments{ +\item{s}{RSmaster parameter object} + +\item{dirpath}{RS directory path} +} +\value{ +a data.frame +} +\description{ +Read the RangeShiftR output file 'range' into a data.frame, if it was generated. +} diff --git a/RangeShiftR/man/validateRSparams.Rd b/RangeShiftR/man/validateRSparams.Rd new file mode 100644 index 0000000..16840d5 --- /dev/null +++ b/RangeShiftR/man/validateRSparams.Rd @@ -0,0 +1,11 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Rfunctions.R +\name{validateRSparams} +\alias{validateRSparams} +\title{Validate a given RS parameter object} +\usage{ +validateRSparams(x) +} +\description{ +Validate a given RS parameter object +} diff --git a/RangeShiftR/src/Makevars b/RangeShiftR/src/Makevars new file mode 100644 index 0000000..aa66b8c --- /dev/null +++ b/RangeShiftR/src/Makevars @@ -0,0 +1,17 @@ +# all except RScore/main.cpp +SOURCES = RScore/Cell.cpp RScore/Community.cpp RScore/FractalGenerator.cpp \ + RScore/Genome.cpp RScore/Individual.cpp RScore/Landscape.cpp \ + RScore/Model.cpp RScore/Parameters.cpp RScore/Patch.cpp \ + RScore/Population.cpp RScore/RandomCheck.cpp RScore/RSrandom.cpp \ + RScore/Species.cpp RScore/SubCommunity.cpp RScore/Utils.cpp \ + RScore/Management.cpp + +OBJECTS = Rinterface.o RcppExports.o $(SOURCES:.cpp=.o) + +CXX_STD = CXX20 +PKG_CXXFLAGS = -O2 -DRS_RCPP -DBATCH +#PKG_CXXFLAGS = -DRSDEBUG +# PKG_CXXFLAGS = -Wall -pedantic +#Optional for activating OpenMP +#PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS) +#PKG_LIBS = $(SHLIB_OPENMP_CXXFLAGS) \ No newline at end of file diff --git a/RangeShiftR/src/Makevars.win b/RangeShiftR/src/Makevars.win new file mode 100644 index 0000000..46e3453 --- /dev/null +++ b/RangeShiftR/src/Makevars.win @@ -0,0 +1,19 @@ +# all except RScore/main.cpp +SOURCES = RScore/Cell.cpp RScore/Community.cpp RScore/FractalGenerator.cpp \ + RScore/Individual.cpp RScore/Landscape.cpp \ + RScore/Model.cpp RScore/Parameters.cpp RScore/Patch.cpp \ + RScore/Population.cpp RScore/RSrandom.cpp \ + RScore/Species.cpp RScore/SubCommunity.cpp RScore/Utils.cpp \ + RScore/Management.cpp RScore/DispersalTrait.cpp RScore/NeutralStatsManager.cpp \ + RScore/NeutralTrait.cpp RScore/SpeciesTrait.cpp RScore/GeneticFitnessTrait.cpp + +OBJECTS = Rinterface.o RcppExports.o $(SOURCES:.cpp=.o) + + +CXX_STD = CXX20 +PKG_CXXFLAGS = -DRSWIN64 -DRS_RCPP -DBATCH -w +#PKG_CXXFLAGS = -DRSDEBUG +#PKG_CXXFLAGS = -H +#Optional for activating OpenMP +#PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS) +#PKG_LIBS = $(SHLIB_OPENMP_CXXFLAGS) \ No newline at end of file diff --git a/.github/workflows/check.yml b/RangeShiftR/src/RScore/.github/workflows/check.yml similarity index 100% rename from .github/workflows/check.yml rename to RangeShiftR/src/RScore/.github/workflows/check.yml diff --git a/RangeShiftR/src/RScore/.gitignore b/RangeShiftR/src/RScore/.gitignore new file mode 100644 index 0000000..c4a4ac5 --- /dev/null +++ b/RangeShiftR/src/RScore/.gitignore @@ -0,0 +1,88 @@ +.gitignore +#README.md + +# CodeLite +/.build-debug/ +/Debug/ +/Release/ +/RNG_test/ +.codelite/ +compile_commands.json +Makefile +.build-release/ +build-Release/ +*.project +*.workspace +*.mk +*.tags +/build/ + +# Hidden source +/RangeShiftR/src/.* + +# Windows files +/RangeShiftR/src/*.dll + +# History files +.Rhistory +.Rapp.history + +# RStudio files +.Rproj.user/ +/RangeShiftR/.Rproj.user/ +#/RangeShiftR/RangeShiftR.Rproj +/RangeShiftR/Read-and-delete-me +/RangeShiftR/.Rhistory +#/RangeShiftR/.Rbuildignore + +# Session Data files +.RData +tags + +# User-specific files +.Ruserdata + +# Example code in package build process +*-Ex.R + +# Output files from R CMD build +*.tar.gz +/RangeShiftR/src/*.o +/RangeShiftR/src/RangeShiftR.so + + +# Windows files +/RangeShiftR/src/*.dll + +# Output files from R CMD check +/*.Rcheck/ + +# Output from Rcpp compile.attributes() +#/RangeShiftR/R/RcppExports.R +#/RangeShiftR/src/RcppExports.cpp + +# RStudio files +.Rproj.user/ + +# produced vignettes +vignettes/*.html +vignettes/*.pdf +#/RangeShiftR/man/ + +# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3 +.httr-oauth + +# knitr and R markdown default cache directories +/*_cache/ +/cache/ + +# Temporary files created by R markdown +*.utf8.md +*.knit.md + +# compilation files +*.o + +# Visual Studio files +.vs/ +out/ diff --git a/RangeShiftR/src/RScore/Allele.h b/RangeShiftR/src/RScore/Allele.h new file mode 100644 index 0000000..9acfc97 --- /dev/null +++ b/RangeShiftR/src/RScore/Allele.h @@ -0,0 +1,36 @@ +#ifndef ALLELEH +#define ALLELEH + +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + + +class Allele { + const float value; + const float dominance; +public: + Allele(float alleleValue, float alleleDominance) : value(alleleValue), dominance(alleleDominance) { } + ~Allele() {} + float getAlleleValue() const { return value; }; + float getDominanceCoef() const { return dominance; }; +}; +#endif diff --git a/RangeShiftR/src/RScore/CMakeLists.txt b/RangeShiftR/src/RScore/CMakeLists.txt new file mode 100644 index 0000000..06869ac --- /dev/null +++ b/RangeShiftR/src/RScore/CMakeLists.txt @@ -0,0 +1,35 @@ +# Config file for compilation with CMake + +if(NOT batchmode) # that is, RScore as a standalone + cmake_minimum_required(VERSION 3.10) + # set the project name and version + project(RScore VERSION 3.0.0) + # specify the C++ standard + set(CMAKE_CXX_STANDARD 20) + set(CMAKE_CXX_STANDARD_REQUIRED True) + + add_executable(RScore Main.cpp Species.cpp Cell.cpp Community.cpp FractalGenerator.cpp GeneticFitnessTrait.cpp Individual.cpp Landscape.cpp Management.cpp Model.cpp NeutralStatsManager.cpp Parameters.cpp Patch.cpp Population.cpp DispersalTrait.cpp RSrandom.cpp NeutralTrait.cpp SpeciesTrait.cpp SubCommunity.cpp Utils.cpp "unit_tests/testIndividual.cpp" "unit_tests/testNeutralStats.cpp" "unit_tests/testPopulation.cpp") + + # turn on unit tests + add_compile_definitions("UNIT_TESTS") +else() # that is, RScore compiled as library within RangeShifter_batch + + add_library(RScore Species.cpp Cell.cpp Community.cpp FractalGenerator.cpp GeneticFitnessTrait.cpp Individual.cpp Landscape.cpp Management.cpp Model.cpp NeutralStatsManager.cpp Parameters.cpp Patch.cpp Population.cpp DispersalTrait.cpp RSrandom.cpp NeutralTrait.cpp SpeciesTrait.cpp SubCommunity.cpp Utils.cpp) +endif() + +if(OMP) + find_package(OpenMP COMPONENTS CXX) + if(OpenMP_CXX_FOUND) + target_link_libraries(RScore PUBLIC OpenMP::OpenMP_CXX) + endif() +endif() + +# enable LINUX_CLUSTER macro on Linux + macOS +if(CMAKE_SYSTEM_NAME STREQUAL "Linux" OR CMAKE_SYSTEM_NAME STREQUAL "Darwin") + add_compile_definitions("LINUX_CLUSTER") +endif() + + +if(NOT batchmode) + target_include_directories(RScore PUBLIC "${PROJECT_BINARY_DIR}") +endif() diff --git a/RangeShiftR/src/RScore/CONTRIBUTING.md b/RangeShiftR/src/RScore/CONTRIBUTING.md new file mode 100644 index 0000000..fa25488 --- /dev/null +++ b/RangeShiftR/src/RScore/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# The RangeShifter platform - An eco-evolutionary modelling framework + +## How to contribute + +Thank you for your interest in contributing to the RangeShifter platform. +In this document we will give you guidance on how to contribute to the RangeShifter project regarding issues, bug fixing and adding new features. + +## Repo structure + +![Rangeshifter repo structure](RS_repos.png) + +RangeShifter is distributed with three user interfaces, each living in their own repo: + +- the RangeShifter GUI (clickable Windows interface)* +- RangeShifter Batch Mode (command line interface) +- the RangeShiftR package (R interface) + +All three share the same source code for the core simulation (i.e., the actual model), which lives in this repo (RScore). Each of the interfaces keeps a copy of this core code in a subfolder called RScore, kept in sync with the RScore repo via a git subtree (see Git subtree usage section). + +⚠ If you wish to propose a change to one of the interfaces, please do so in the corresponding repo: [RangeShifter batch mode](https://github.com/RangeShifter/RangeShifter_batch_dev), [RangeShiftR package](https://github.com/RangeShifter/RangeShiftR-package-dev). + +*The RangeShifter GUI is currently being rewritten, and is not open source yet. + +## Roles + +#### Maintainers + +- [@JetteReeg](https://github.com/JetteReeg): RScore repo and lead in R package + + +Maintainers are responsible for coordinating development efforts and ensuring that RangeShifter keeps building continuously. + +#### Developers + +Regular contributors and members of the [RangeShifter development team](https://github.com/orgs/RangeShifter/people), including maintainers. + +#### Contributors + +Anyone who whishes to make changes to RangeShifter's code, including regular developers. + +## Branching policy + +![](branches.png) + +*Check out the [Git cheatsheet](https://github.com/RangeShifter/RScore/blob/main/git_cheatsheet.md) for a reminder on the main git commands* + +This policy applies to RScore and all three RangeShifter interfaces. +RangeShifter uses the following branching structure: + +- `main` is the default branch, where stable releases live. Because it contains the version of RangeShifter that users normally interact with, it must be stable and build at all times. +Only maintainers should make significant changes to `main`, normally by merging `develop` into `main` to make newly developed features available to users, and marking a release while doing so. +- `develop` is the development branch containing new, in-development features. It is the reference branch for all developers. Contributors may make small changes directly to `develop` but should ensure that new changes do not break the build. If one happens to break `develop`, it should be their top priority to fix it as this will disrupt the work of all other contributors. +Larger changes should instead be developed on feature branches. +- Larger changes should be first developed on feature (e.g. `cmake`, `mutualism`, etc.) or contributor (e.g., `theo`) branches. Contributors are welcome to experiment and break such branches at any time, as this will not impact users or other contributors. + +When progress is deemed satisfactory, changes can be brought to `develop`. Please open a pull request on GitHub, and assign at least one maintainer as a reviewer. As a pre-requisite, RangeShifter must build on the branch before merging. Please enter a descriptive title and use the description field to describe what you have changed. + +In the meantime, we encourage contributors to work in small and frequent commits, and to merge `develop` into their branch often to update their branch with newest changes. + +### Contributing to RangeShifter core code + +Any changes regarding the RangeShifter core code should be done in this repository and can afterwards be synced with all interfaces using the git subtree feature (see [Git subtree](https://github.com/RangeShifter/RScore/tree/main?tab=readme-ov-file#usage-git-subtree) section in the README). + + +#### Bugs + +To report a bug, please [open an issue](https://github.com/RangeShifter/RangeShiftR-package/issues/new), using the Bug Report template. +Please do check if a related issue has already open on one of the other interfaces ([here](https://github.com/RangeShifter/RangeShifter_batch/issues) for the batch interface or [here](https://github.com/RangeShifter/RangeShiftR-package) for the R package interface). + +To propose a bug fix (thank you!!), please create and work on your own branch or fork, from either `main` or `develop` (preferred), and open a pull request when your fix is ready to be merged into the original branch. + +As a prerequisite for merging, please ensure that your version passes status check (that is, RScore can still build, and all unit tests are still satisfied). +This can be seen in the Actions panel for every commit and at the bottom of the pull request. + +Maintainers will review the pull request, possibly request changes, and eventually integrate the bug fix into RScore, and update the subtrees to bring the fix to all interfaces. + +#### New features + +Do you have an idea of a new feature in the RangeShifter platform that should be integrated and is of use for other RangeShifter users? +Please get in touch with the RangeShifter development team (rangeshiftr@uni-potsdam.de) to discuss a collaboration. + +⚠️ We advise to contact the developer team as early as possible if you plan on implementing a new feature. This could prevent simultaneous development of the same feature and coordinate potential joint development. + +Alternatively, proceed as with the bug fix above: create your own branch or fork _from `develop`_ and work from there, and submit a pull request when your new features are ready to join the core code. +We recommend that you update your branch regularly to new changes on `develop` (using `git merge develop`) to reduce the risk of merge conflicts or your version getting out-of-touch in the late stages of development. +We also recommend that you work in small commits, as this makes the code easier to debug, and makes it easier for maintainers to understand your contributions when reviewing a pull request. diff --git a/RangeShiftR/src/RScore/Cell.cpp b/RangeShiftR/src/RScore/Cell.cpp new file mode 100644 index 0000000..73eda84 --- /dev/null +++ b/RangeShiftR/src/RScore/Cell.cpp @@ -0,0 +1,246 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + +//--------------------------------------------------------------------------- + +#include "Cell.h" + +//--------------------------------------------------------------------------- + +//--------------------------------------------------------------------------- + +// Cell functions + +Cell::Cell(int xx,int yy,Patch *patch,int hab) +{ + x = xx; y = yy; + pPatch = patch; + envVal = 1.0; // default - no effect of any gradient + envDev = eps = 0.0; + habIxx.push_back(hab); + visits = 0; + smsData = 0; +} + +Cell::Cell(int xx,int yy,Patch *patch,float hab) +{ + x = xx; y = yy; + pPatch = patch; + envVal = 1.0; // default - no effect of any gradient + envDev = eps = 0.0; + habitats.push_back(hab); + visits = 0; + smsData = 0; +} + +Cell::~Cell() { + habIxx.clear(); + habitats.clear(); + if (smsData != 0) { + if (smsData->effcosts != 0) delete smsData->effcosts; + delete smsData; + } +demoScalings.clear(); + +#if RSDEBUG +//DEBUGLOG << "Cell::~Cell(): deleted" << endl; +#endif +} + +void Cell::setHabIndex(short hx) { + if (hx < 0) habIxx.push_back(0); + else habIxx.push_back(hx); +} + +void Cell::changeHabIndex(short ix,short hx) { + if (ix >= 0 && ix < (short)habIxx.size() && hx >= 0) habIxx[ix] = hx; + else habIxx[ix] = 0; +} + +int Cell::getHabIndex(int ix) { + if (ix < 0 || ix >= (int)habIxx.size()) + // nodata cell OR should not occur, but treat as such + return -1; + else return habIxx[ix]; +} +int Cell::nHabitats(void) { + int nh = (int)habIxx.size(); + if ((int)habitats.size() > nh) nh = (int)habitats.size(); + return nh; +} + +void Cell::setHabitat(float q) { + if (q >= 0.0 && q <= 100.0) habitats.push_back(q); + else habitats.push_back(0.0); +} + +float Cell::getHabitat(int ix) { + if (ix < 0 || ix >= (int)habitats.size()) + // nodata cell OR should not occur, but treat as such + return -1.0; + else return habitats[ix]; +} + +void Cell::setPatch(Patch *p) { + pPatch = p; +} +Patch *Cell::getPatch(void) +{ + return pPatch; +} + +locn Cell::getLocn(void) { locn q; q.x = x; q.y = y; return q; } + +void Cell::setEnvDev(float d) { envDev = d; } + +float Cell::getEnvDev(void) { return envDev; } + +void Cell::setEnvVal(float e) { + if (e >= 0.0) envVal = e; +} + +float Cell::getEnvVal(void) { return envVal; } + +void Cell::updateEps(float ac,float randpart) { + eps = eps * ac + randpart; +} + +float Cell::getEps(void) { return eps; } + +// Functions to handle costs for SMS + +#ifdef _OPENMP +std::unique_lock Cell::lockCost() { + return std::unique_lock(cost_mutex); +} +#endif + +int Cell::getCost(void) { + int c; + if (smsData == 0) c = 0; // costs not yet set up + else c = smsData->cost; + return c; +} + +void Cell::setCost(int c) { + if (smsData == 0) { + smsData = new smscosts; + smsData->effcosts = 0; + } + smsData->cost = c; +} + +// Reset the cost and the effective cost of the cell +void Cell::resetCost(void) { + if (smsData != 0) { resetEffCosts(); delete smsData; } + smsData = 0; +} + +array3x3f Cell::getEffCosts(void) { + array3x3f a; + if (smsData == 0 || smsData->effcosts == 0) { // effective costs have not been calculated + for (int i = 0; i < 3; i++) { + for (int j = 0; j < 3; j++) { + a.cell[i][j] = -1.0; + } + } + } + else + a = *smsData->effcosts; + return a; +} + +void Cell::setEffCosts(array3x3f a) { + if (smsData->effcosts == 0) smsData->effcosts = new array3x3f; + *smsData->effcosts = a; +} + +// Reset the effective cost, but not the cost, of the cell +void Cell::resetEffCosts(void) { + if (smsData != 0) { + if (smsData->effcosts != 0) { + delete smsData->effcosts; + smsData->effcosts = 0; + } + } +} + +void Cell::resetVisits(void) { visits = 0; } +void Cell::incrVisits(void) { visits++; } +unsigned long int Cell::getVisits(void) { return visits; } + + +void Cell::addchgDemoScaling(std::vector ds) { + std::for_each(ds.begin(), ds.end(), [](float& perc){ if(perc < 0.0 || perc > 100.0) perc=100; }); + demoScalings.push_back(ds); + return; +} + +std::vector Cell::getDemoScaling(short chgyear) { + if (chgyear < 0 || chgyear >= (int)demoScalings.size()) { + std::vector ret(1, -1); + return ret; + } + else return demoScalings[chgyear]; +} + + + +//--------------------------------------------------------------------------- + +// Initial species distribution cell functions + +DistCell::DistCell(int xx,int yy) { + x = xx; + y = yy; + initialise = false; +} + +DistCell::~DistCell() { + +} + +void DistCell::setCell(bool init) { + initialise = init; +} + +bool DistCell::toInitialise(locn loc) { + if (loc.x == x && loc.y == y) return initialise; + else return false; +} + +bool DistCell::selected(void) { return initialise; } + +locn DistCell::getLocn(void) { + locn loc; + loc.x = x; + loc.y = y; + return loc; +} + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + + + + diff --git a/Cell.h b/RangeShiftR/src/RScore/Cell.h similarity index 63% rename from Cell.h rename to RangeShiftR/src/RScore/Cell.h index 5382a1e..2dc28f8 100644 --- a/Cell.h +++ b/RangeShiftR/src/RScore/Cell.h @@ -1,74 +1,84 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * + * --------------------------------------------------------------------------*/ - - -/*------------------------------------------------------------------------------ -RangeShifter v2.0 Cell -Implements the following classes: + /*------------------------------------------------------------------------------ -Cell - Landscape cell + RangeShifter v2.0 Cell -DistCell - Initial species distribution cell + Implements the following classes: -For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. -and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. -Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + Cell - Landscape cell -Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + DistCell - Initial species distribution cell -Last updated: 14 January 2021 by Steve Palmer + For full details of RangeShifter, please see: + Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. + and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial + eco-evolutionary dynamics and species’ responses to environmental changes. + Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 -------------------------------------------------------------------------------*/ + Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + + Last updated: 14 January 2021 by Steve Palmer + + ------------------------------------------------------------------------------*/ #ifndef CellH #define CellH + +#include + #include using namespace std; #include "Parameters.h" +#ifdef _OPENMP +#include +#include +#endif + //--------------------------------------------------------------------------- +class Patch; // Forward-declaration of the Patch class + struct array3x3f { float cell[3][3]; }; // neighbourhood cell array (SMS) -struct smscosts { int cost; array3x3f *effcosts; }; // cell costs for SMS +struct smscosts { int cost; array3x3f* effcosts; }; // cell costs for SMS // Landscape cell -class Cell{ +class Cell { public: Cell( // Constructor for habitat codes int, // x co-ordinate int, // y co-ordinate - intptr, // pointer (cast as integer) to the Patch to which Cell belongs + Patch *, // pointer to the Patch to which Cell belongs int // habitat index number ); Cell( // Constructor for habitat % cover or habitat quality int, // x co-ordinate int, // y co-ordinate - intptr, // pointer (cast as integer) to the Patch to which Cell belongs + Patch *, // pointer to the Patch to which Cell belongs float // habitat proportion or cell quality score ); ~Cell(); @@ -90,9 +100,9 @@ class Cell{ int // habitat index number / landscape change number ); void setPatch( - intptr // pointer (cast as integer) to the Patch to which Cell belongs + Patch * // pointer to the Patch to which Cell belongs ); - intptr getPatch(void); + Patch *getPatch(void); locn getLocn(void); void setEnvDev( float // local environmental deviation @@ -110,6 +120,9 @@ class Cell{ void setCost( int // cost value for SMS ); +#ifdef _OPENMP + std::unique_lock lockCost(void); +#endif int getCost(void); void resetCost(void); array3x3f getEffCosts(void); @@ -121,29 +134,44 @@ class Cell{ void incrVisits(void); unsigned long int getVisits(void); + void addchgDemoScaling(std::vector); + void setDemoScaling(std::vector, short); + std::vector getDemoScaling(short); + + private: - int x,y; // cell co-ordinates - intptr pPatch; // pointer (cast as integer) to the Patch to which cell belongs + int x, y; // cell co-ordinates + Patch *pPatch; // pointer to the Patch to which cell belongs // NOTE: THE FOLLOWING ENVIRONMENTAL VARIABLES COULD BE COMBINED IN A STRUCTURE // AND ACCESSED BY A POINTER ... float envVal; // environmental value, representing one of: - // gradient in K, r or extinction probability + // gradient in K, r or extinction probability float envDev; // local environmental deviation (static, in range -1.0 to +1.0) float eps; // local environmental stochasticity (epsilon) (dynamic, from N(0,std)) +#ifdef _OPENMP + std::atomic visits; // no. of times square is visited by dispersers +#else unsigned long int visits; // no. of times square is visited by dispersers - smscosts *smsData; +#endif + smscosts* smsData; vector habIxx; // habitat indices (rasterType=0) - // NB initially, habitat codes are loaded, then converted to index nos. - // once landscape is fully loaded + // NB initially, habitat codes are loaded, then converted to index nos. + // once landscape is fully loaded vector habitats; // habitat proportions (rasterType=1) or quality (rasterType=2) + + std::vector> demoScalings; // demographic scaling layers (only if rasterType==2) + +#ifdef _OPENMP + std::mutex cost_mutex; +#endif }; //--------------------------------------------------------------------------- // Initial species distribution cell -class DistCell{ +class DistCell { public: DistCell( int, // x co-ordinate @@ -160,15 +188,11 @@ class DistCell{ locn getLocn(void); private: - int x,y; // cell co-ordinates + int x, y; // cell co-ordinates bool initialise; // cell is to be initialised }; -#if RSDEBUG -extern void DebugGUI(string); -#endif - //--------------------------------------------------------------------------- #endif diff --git a/Community.cpp b/RangeShiftR/src/RScore/Community.cpp similarity index 60% rename from Community.cpp rename to RangeShiftR/src/RScore/Community.cpp index 286dc6a..46c8970 100644 --- a/Community.cpp +++ b/RangeShiftR/src/RScore/Community.cpp @@ -1,6 +1,7 @@ +#include "Community.h" /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -24,18 +25,41 @@ #include "Community.h" +#ifdef _OPENMP +#ifdef __has_include +#if __has_include() +#include +#endif +#endif +#include +#if __cpp_lib_barrier >= 201907L && __cpp_lib_optional >= 201606L +#define HAS_BARRIER_LIB +#include +#include +#else +#include +#include +#endif +#include +#endif // _OPENMP + //--------------------------------------------------------------------------- ofstream outrange; ofstream outoccup, outsuit; ofstream outtraitsrows; +ofstream ofsGenes; +ofstream outwcfstat; +ofstream outperlocusfstat; +ofstream outpairwisefst; //--------------------------------------------------------------------------- Community::Community(Landscape* pLand) { pLandscape = pLand; indIx = 0; + pNeutralStatistics = 0; } Community::~Community(void) { @@ -54,13 +78,11 @@ SubCommunity* Community::addSubComm(Patch* pPch, int num) { void Community::initialise(Species* pSpecies, int year) { - int nsubcomms, npatches, ndistcells, spratio, patchnum, rr = 0; locn distloc; patchData pch; patchLimits limits; - intptr ppatch, subcomm; - std::vector subcomms; + std::vector subcomms; std::vector selected; SubCommunity* pSubComm; Patch* pPatch; @@ -72,16 +94,6 @@ void Community::initialise(Species* pSpecies, int year) spratio = ppLand.spResol / ppLand.resol; -#if RSDEBUG - DEBUGLOG << endl << "Community::initialise(): this=" << this - << " seedType=" << init.seedType << " freeType=" << init.freeType - << " minSeedX=" << init.minSeedX << " minSeedY=" << init.minSeedY - << " maxSeedX=" << init.maxSeedX << " maxSeedY=" << init.maxSeedY - << " indsFile=" << init.indsFile - << " nsubcomms=" << nsubcomms << " spratio=" << spratio - << endl; -#endif - switch (init.seedType) { case 0: // free initialisation @@ -138,7 +150,7 @@ void Community::initialise(Species* pSpecies, int year) } for (int i = 0; i < npatches; i++) { if (selected[i]) { - pSubComm = (SubCommunity*)subcomms[i]; + pSubComm = subcomms[i]; pSubComm->setInitial(true); } } @@ -155,14 +167,11 @@ void Community::initialise(Species* pSpecies, int year) if (patchnum != 0) { if (pch.pPatch->getK() > 0.0) { // patch is suitable - subcomm = pch.pPatch->getSubComm(); - if (subcomm == 0) { + pSubComm = pch.pPatch->getSubComm(); + if (pSubComm == nullptr) { // create a sub-community in the patch pSubComm = addSubComm(pch.pPatch, patchnum); } - else { - pSubComm = (SubCommunity*)subcomm; - } pSubComm->setInitial(true); } } @@ -211,13 +220,11 @@ void Community::initialise(Species* pSpecies, int year) for (int y = 0; y < spratio; y++) { pCell = pLandscape->findCell(distloc.x * spratio + x, distloc.y * spratio + y); if (pCell != 0) { // not a no-data cell - ppatch = pCell->getPatch(); - if (ppatch != 0) { - pPatch = (Patch*)ppatch; + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { if (pPatch->getSeqNum() != 0) { // not the matrix patch - subcomm = pPatch->getSubComm(); - if (subcomm != 0) { - pSubComm = (SubCommunity*)subcomm; + pSubComm = pPatch->getSubComm(); + if (pSubComm != nullptr) { pSubComm->setInitial(true); } } @@ -246,7 +253,8 @@ void Community::initialise(Species* pSpecies, int year) indIx = 0; // reset index for initial individuals } else { // add any initial individuals for the current year - initInd iind; iind.year = 0; + initInd iind = initInd(); + iind.year = 0; int ninds = paramsInit->numInitInds(); while (indIx < ninds && iind.year <= year) { iind = paramsInit->getInitInd(indIx); @@ -256,14 +264,11 @@ void Community::initialise(Species* pSpecies, int year) pPatch = pLandscape->findPatch(iind.patchID); if (pPatch->getK() > 0.0) { // patch is suitable - subcomm = pPatch->getSubComm(); - if (subcomm == 0) { + pSubComm = pPatch->getSubComm(); + if (pSubComm == nullptr) { // create a sub-community in the patch pSubComm = addSubComm(pPatch, iind.patchID); } - else { - pSubComm = (SubCommunity*)subcomm; - } pSubComm->initialInd(pLandscape, pSpecies, pPatch, pPatch->getRandomCell(), indIx); } } @@ -271,19 +276,15 @@ void Community::initialise(Species* pSpecies, int year) else { // cell-based model pCell = pLandscape->findCell(iind.x, iind.y); if (pCell != 0) { - intptr ppatch = pCell->getPatch(); - if (ppatch != 0) { - pPatch = (Patch*)ppatch; + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { if (pPatch->getK() > 0.0) { // patch is suitable - subcomm = pPatch->getSubComm(); - if (subcomm == 0) { + pSubComm = pPatch->getSubComm(); + if (pSubComm == nullptr) { // create a sub-community in the patch pSubComm = addSubComm(pPatch, iind.patchID); } - else { - pSubComm = (SubCommunity*)subcomm; - } pSubComm->initialInd(pLandscape, pSpecies, pPatch, pCell, indIx); } } @@ -308,18 +309,11 @@ void Community::initialise(Species* pSpecies, int year) } // end of switch (init.seedType) -#if RSDEBUG - DEBUGLOG << "Community::initialise(): this=" << this - << " nsubcomms=" << nsubcomms - << endl; -#endif - } // Add manually selected patches/cells to the selected set for initialisation void Community::addManuallySelected(void) { int npatches; - intptr subcomm, patch; locn initloc; Cell* pCell; Patch* pPatch; @@ -328,19 +322,14 @@ void Community::addManuallySelected(void) { landParams ppLand = pLandscape->getLandParams(); npatches = pLandscape->initCellCount(); // no. of patches/cells specified -#if RSDEBUG - DEBUGLOG << "Community::addManuallySelected(): this = " << this - << " npatches = " << npatches << endl; -#endif // identify sub-communities to be initialised if (ppLand.patchModel) { for (int i = 0; i < npatches; i++) { initloc = pLandscape->getInitCell(i); // patch number held in x-coord of list pPatch = pLandscape->findPatch(initloc.x); if (pPatch != 0) { - subcomm = pPatch->getSubComm(); - if (subcomm != 0) { - pSubComm = (SubCommunity*)subcomm; + pSubComm = pPatch->getSubComm(); + if (pSubComm != nullptr) { pSubComm->setInitial(true); } } @@ -353,29 +342,11 @@ void Community::addManuallySelected(void) { && initloc.y >= 0 && initloc.y < ppLand.dimY) { pCell = pLandscape->findCell(initloc.x, initloc.y); if (pCell != 0) { // not no-data cell - patch = pCell->getPatch(); -#if RSDEBUG - DEBUGLOG << "Community::initialise(): i = " << i - << " x = " << initloc.x << " y = " << initloc.y - << " pCell = " << pCell << " patch = " << patch - << endl; -#endif - if (patch != 0) { - pPatch = (Patch*)patch; - subcomm = pPatch->getSubComm(); -#if RSDEBUG - DEBUGLOG << "Community::initialise(): i = " << i - << " pPatch = " << pPatch << " subcomm = " << subcomm - << endl; -#endif - if (subcomm != 0) { - pSubComm = (SubCommunity*)subcomm; + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { + pSubComm = pPatch->getSubComm(); + if (pSubComm != nullptr) { pSubComm->setInitial(true); -#if RSDEBUG - DEBUGLOG << "Community::initialise(): i = " << i - << " pSubComm = " << pSubComm - << endl; -#endif } } } @@ -386,6 +357,7 @@ void Community::addManuallySelected(void) { void Community::resetPopns(void) { int nsubcomms = (int)subComms.size(); + #pragma omp parallel for schedule(static,128) for (int i = 0; i < nsubcomms; i++) { // all sub-communities subComms[i]->resetPopns(); } @@ -413,49 +385,93 @@ void Community::patchChanges(void) { void Community::reproduction(int yr) { - float eps = 0.0; // epsilon for environmental stochasticity landParams land = pLandscape->getLandParams(); envStochParams env = paramsStoch->getStoch(); + float eps = 0.0; // epsilon for environmental stochasticity + if (env.stoch && !env.local) { // global stochasticty + eps = pLandscape->getGlobalStoch(yr); + } int nsubcomms = (int)subComms.size(); -#if RSDEBUG - DEBUGLOG << "Community::reproduction(): this=" << this - << " nsubcomms=" << nsubcomms << endl; -#endif + #pragma omp parallel for schedule(static,128) for (int i = 0; i < nsubcomms; i++) { // all sub-communities - if (env.stoch) { - if (!env.local) { // global stochasticty - eps = pLandscape->getGlobalStoch(yr); - } - } subComms[i]->reproduction(land.resol, eps, land.rasterType, land.patchModel); } -#if RSDEBUG - DEBUGLOG << "Community::reproduction(): finished" << endl; -#endif } void Community::emigration(void) { - int nsubcomms = (int)subComms.size(); -#if RSDEBUG - DEBUGLOG << "Community::emigration(): this=" << this - << " nsubcomms=" << nsubcomms << endl; -#endif + int nsubcomms = static_cast(subComms.size()); + #pragma omp parallel for schedule(static, 128) for (int i = 0; i < nsubcomms; i++) { // all sub-communities subComms[i]->emigration(); } -#if RSDEBUG - DEBUGLOG << "Community::emigration(): finished" << endl; -#endif } -#if RS_RCPP // included also SEASONAL +#ifdef _OPENMP +#ifdef HAS_BARRIER_LIB +typedef std::optional> split_barrier; +#else +class split_barrier { +private: + std::mutex m; + std::condition_variable cv; + int threads_in_section; + int total_threads; + bool may_enter; + bool may_leave; + +public: + split_barrier(): + threads_in_section(0), + may_enter(false), + may_leave(false) + {} + + void emplace(int threads) { + std::lock_guard lock(m); + total_threads = threads; + may_enter = true; + } + + void enter() { + std::unique_lock lock(m); + cv.wait(lock, [this]{return may_enter;}); + if (++threads_in_section == total_threads) { + may_enter = false; + may_leave = true; + lock.unlock(); + cv.notify_all(); + } + } + + void leave() { + std::unique_lock lock(m); + cv.wait(lock, [this]{return may_leave;}); + if (--threads_in_section == 0) { + may_leave = false; + may_enter = true; + lock.unlock(); + cv.notify_all(); + } + } +}; +#endif // HAS_BARRIER_LIB +#endif // _OPENMP + +#if RS_RCPP void Community::dispersal(short landIx, short nextseason) #else void Community::dispersal(short landIx) -#endif // SEASONAL || RS_RCPP +#endif // RS_RCPP { +#ifdef _OPENMP + std::atomic nbStillDispersing; + split_barrier barrier; +#else + int nbStillDispersing; +#endif // _OPENMP + #if RSDEBUG int t0, t1, t2; t0 = time(0); @@ -466,43 +482,89 @@ void Community::dispersal(short landIx) int nsubcomms = (int)subComms.size(); // initiate dispersal - all emigrants leave their natal community and join matrix community SubCommunity* matrix = subComms[0]; // matrix community is always the first - for (int i = 0; i < nsubcomms; i++) { // all populations - subComms[i]->initiateDispersal(matrix); - } -#if RSDEBUG - t1 = time(0); - DEBUGLOG << "Community::dispersal(): this=" << this - << " nsubcomms=" << nsubcomms << " initiation time=" << t1 - t0 << endl; -#endif +#pragma omp parallel + { + std::map> disperserPool; - // dispersal is undertaken by all individuals now in the matrix patch - // (even if not physically in the matrix) - int ndispersers = 0; - do { - for (int i = 0; i < nsubcomms; i++) { // all populations - subComms[i]->resetPossSettlers(); + // All individuals in the matrix disperse again + // (= unsettled dispersers from previous generation) + matrix->disperseMatrix(disperserPool); + + // Recruit new emigrants +#pragma omp for schedule(static,128) nowait + for (int i = 0; i < nsubcomms; i++) { + subComms[i]->recruitDispersers(disperserPool); } -#if RS_RCPP // included also SEASONAL - ndispersers = matrix->transfer(pLandscape, landIx, nextseason); + +#ifdef _OPENMP +#pragma omp single + barrier.emplace(omp_get_num_threads()); +#endif // _OPENMP + + + // + do { +#pragma omp for schedule(guided) + for (int i = 0; i < nsubcomms; i++) { + subComms[i]->resetPossSettlers(); + } + int localNbDispersers = matrix->resolveTransfer(disperserPool, pLandscape, landIx); +#pragma omp single nowait + nbStillDispersing = 0; +#pragma omp barrier +#if RS_RCPP + localNbDispersers += matrix->resolveSettlement(disperserPool, pLandscape, nextseason); #else - ndispersers = matrix->transfer(pLandscape, landIx); -#endif // SEASONAL || RS_RCPP - matrix->completeDispersal(pLandscape, sim.outConnect); - } while (ndispersers > 0); + localNbDispersers += matrix->resolveSettlement(disperserPool, pLandscape); +#endif // RS_RCPP + nbStillDispersing += localNbDispersers; + +#ifdef _OPENMP +#ifdef HAS_BARRIER_LIB + std::barrier<>::arrival_token token = barrier->arrive(); +#else + barrier.enter(); +#endif // HAS_BARRIER_LIB +#endif // _OPENMP + + matrix->completeDispersal(disperserPool, pLandscape, sim.outConnect); + +#ifdef _OPENMP +#ifdef HAS_BARRIER_LIB + barrier->wait(std::move(token)); +#else + barrier.leave(); +#endif // HAS_BARRIER_LIB +#endif // _OPENMP + + } while (nbStillDispersing > 0); + + // All unsettled dispersers are stored in matrix until next generation + for (auto & it : disperserPool) { + Species* const& pSpecies = it.first; + vector& inds = it.second; + matrix->recruitMany(inds, pSpecies); + } + } -#if RSDEBUG - DEBUGLOG << "Community::dispersal(): matrix=" << matrix << endl; - t2 = time(0); - DEBUGLOG << "Community::dispersal(): transfer time=" << t2 - t1 << endl; -#endif } -void Community::survival(short part, short option0, short option1) +void Community::survival0(short option0, short option1) { int nsubcomms = (int)subComms.size(); + #pragma omp parallel for schedule(static,128) for (int i = 0; i < nsubcomms; i++) { // all communities (including in matrix) - subComms[i]->survival(part, option0, option1); + subComms[i]->survival0(option0, option1); + } +} + +void Community::survival1() +{ + int nsubcomms = (int)subComms.size(); + #pragma omp parallel for schedule(static,128) + for (int i = 0; i < nsubcomms; i++) { // all communities (including in matrix) + subComms[i]->survival1(); } } @@ -553,17 +615,12 @@ void Community::createOccupancy(int nrows, int reps) { void Community::updateOccupancy(int row, int rep) { -#if RSDEBUG - DEBUGLOG << "Community::updateOccupancy(): row=" << row << endl; -#endif int nsubcomms = (int)subComms.size(); for (int i = 0; i < nsubcomms; i++) { subComms[i]->updateOccupancy(row); } - commStats s = getStats(); occSuit[row][rep] = (float)s.occupied / (float)s.suitable; - } void Community::deleteOccupancy(int nrows) { @@ -583,7 +640,7 @@ void Community::deleteOccupancy(int nrows) { // Determine range margins commStats Community::getStats(void) { - commStats s; + commStats s = commStats(); landParams ppLand = pLandscape->getLandParams(); s.ninds = s.nnonjuvs = s.suitable = s.occupied = 0; s.minX = ppLand.maxX; s.minY = ppLand.maxY; s.maxX = s.maxY = 0; @@ -616,9 +673,14 @@ commStats Community::getStats(void) // Functions to control production of output files +// Close population file +bool Community::outPopFinishLandscape() { + return subComms[0]->outPopFinishLandscape(); +} + // Open population file and write header record -bool Community::outPopHeaders(Species* pSpecies, int option) { - return subComms[0]->outPopHeaders(pLandscape, pSpecies, option); +bool Community::outPopStartLandscape(Species* pSpecies) { + return subComms[0]->outPopStartLandscape(pLandscape, pSpecies); } // Write records to population file @@ -632,53 +694,36 @@ void Community::outPop(int rep, int yr, int gen) } +// Close individuals file +void Community::outIndsFinishReplicate() { + subComms[0]->outIndsFinishReplicate(); +} -// Write records to individuals file -void Community::outInds(int rep, int yr, int gen, int landNr) { +// Open individuals file and write header record +void Community::outIndsStartReplicate(int rep, int landNr) { + subComms[0]->outIndsStartReplicate(pLandscape, rep, landNr); +} - if (landNr >= 0) { // open the file - subComms[0]->outInds(pLandscape, rep, yr, gen, landNr); - return; - } - if (landNr == -999) { // close the file - subComms[0]->outInds(pLandscape, rep, yr, gen, -999); - return; - } +// Write records to individuals file +void Community::outIndividuals(int rep, int yr, int gen) { // generate output for each sub-community (patch) in the community int nsubcomms = (int)subComms.size(); for (int i = 0; i < nsubcomms; i++) { // all sub-communities - subComms[i]->outInds(pLandscape, rep, yr, gen, landNr); + subComms[i]->outIndividuals(pLandscape, rep, yr, gen); } } -// Write records to genetics file -void Community::outGenetics(int rep, int yr, int gen, int landNr) { - //landParams ppLand = pLandscape->getLandParams(); - if (landNr >= 0) { // open the file - subComms[0]->outGenetics(rep, yr, gen, landNr); - return; - } - if (landNr == -999) { // close the file - subComms[0]->outGenetics(rep, yr, gen, landNr); - return; - } - // generate output for each sub-community (patch) in the community - int nsubcomms = (int)subComms.size(); - for (int i = 0; i < nsubcomms; i++) { // all sub-communities - subComms[i]->outGenetics(rep, yr, gen, landNr); - } +// Close range file +bool Community::outRangeFinishLandscape() +{ + if (outrange.is_open()) outrange.close(); + outrange.clear(); + return true; } // Open range file and write header record -bool Community::outRangeHeaders(Species* pSpecies, int landNr) +bool Community::outRangeStartLandscape(Species* pSpecies, int landNr) { - - if (landNr == -999) { // close the file - if (outrange.is_open()) outrange.close(); - outrange.clear(); - return true; - } - string name; landParams ppLand = pLandscape->getLandParams(); envStochParams env = paramsStoch->getStoch(); @@ -686,33 +731,21 @@ bool Community::outRangeHeaders(Species* pSpecies, int landNr) // NEED TO REPLACE CONDITIONAL COLUMNS BASED ON ATTRIBUTES OF ONE SPECIES TO COVER // ATTRIBUTES OF *ALL* SPECIES AS DETECTED AT MODEL LEVEL - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); -#if RSDEBUG - DEBUGLOG << "Community::outRangeHeaders(): simulation=" << sim.simulation - << " sim.batchMode=" << sim.batchMode - << " landNr=" << landNr << endl; -#endif - if (sim.batchMode) { name = paramsSim->getDir(2) -#if RS_RCPP - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) + "_Land" - + Int2Str(landNr) -#else - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) + "_Land" - + Int2Str(landNr) -#endif + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + + to_string(landNr) + "_Range.txt"; } else { - name = paramsSim->getDir(2) + "Sim" + Int2Str(sim.simulation) + "_Range.txt"; + name = paramsSim->getDir(2) + "Sim" + to_string(sim.simulation) + "_Range.txt"; } outrange.open(name.c_str()); outrange << "Rep\tYear\tRepSeason"; @@ -749,7 +782,7 @@ bool Community::outRangeHeaders(Species* pSpecies, int landNr) } } if (trfr.indVar) { - if (trfr.moveModel) { + if (trfr.usesMovtProc) { if (trfr.moveType == 1) { outrange << "\tmeanDP\tstdDP\tmeanGB\tstdGB"; outrange << "\tmeanAlphaDB\tstdAlphaDB\tmeanBetaDB\tstdBetaDB"; @@ -787,31 +820,21 @@ bool Community::outRangeHeaders(Species* pSpecies, int landNr) } } outrange << endl; - -#if RSDEBUG - DEBUGLOG << "Community::outRangeHeaders(): finished" << endl; -#endif - return outrange.is_open(); } // Write record to range file void Community::outRange(Species* pSpecies, int rep, int yr, int gen) { -#if RSDEBUG - DEBUGLOG << "Community::outRange(): rep=" << rep - << " yr=" << yr << " gen=" << gen << endl; -#endif - landParams ppLand = pLandscape->getLandParams(); envStochParams env = paramsStoch->getStoch(); // NEED TO REPLACE CONDITIONAL COLUMNS BASED ON ATTRIBUTES OF ONE SPECIES TO COVER // ATTRIBUTES OF *ALL* SPECIES AS DETECTED AT MODEL LEVEL - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); outrange << rep << "\t" << yr << "\t" << gen; @@ -828,14 +851,14 @@ void Community::outRange(Species* pSpecies, int rep, int yr, int gen) for (int stg = 1; stg < sstruct.nStages; stg++) { stagepop = 0; for (int i = 0; i < nsubcomms; i++) { // all sub-communities - stagepop += subComms[i]->stagePop(stg); + stagepop += subComms[i]->getNbInds(stg); } outrange << "\t" << stagepop; } // juveniles born in current reproductive season stagepop = 0; for (int i = 0; i < nsubcomms; i++) { // all sub-communities - stagepop += subComms[i]->stagePop(0); + stagepop += subComms[i]->getNbInds(0); } outrange << "\t" << stagepop; } @@ -858,14 +881,11 @@ void Community::outRange(Species* pSpecies, int rep, int yr, int gen) outrange << "\t0\t0\t0\t0"; if (emig.indVar || trfr.indVar || sett.indVar) { // output trait means - traitsums ts; + traitsums ts = traitsums(); traitsums scts; // sub-community traits - traitCanvas tcanv; int ngenes, popsize; - tcanv.pcanvas[0] = NULL; - - for (int i = 0; i < NSEXES; i++) { + for (int i = 0; i < gMaxNbSexes; i++) { ts.ninds[i] = 0; ts.sumD0[i] = ts.ssqD0[i] = 0.0; ts.sumAlpha[i] = ts.ssqAlpha[i] = 0.0; ts.sumBeta[i] = ts.ssqBeta[i] = 0.0; @@ -882,8 +902,8 @@ void Community::outRange(Species* pSpecies, int rep, int yr, int gen) int nsubcomms = (int)subComms.size(); for (int i = 0; i < nsubcomms; i++) { // all sub-communities (incl. matrix) - scts = subComms[i]->outTraits(tcanv, pLandscape, rep, yr, gen, true); - for (int j = 0; j < NSEXES; j++) { + scts = subComms[i]->outTraits(pLandscape, rep, yr, gen, true); + for (int j = 0; j < gMaxNbSexes; j++) { ts.ninds[j] += scts.ninds[j]; ts.sumD0[j] += scts.sumD0[j]; ts.ssqD0[j] += scts.ssqD0[j]; ts.sumAlpha[j] += scts.sumAlpha[j]; ts.ssqAlpha[j] += scts.ssqAlpha[j]; @@ -959,7 +979,7 @@ void Community::outRange(Species* pSpecies, int rep, int yr, int gen) } if (trfr.indVar) { - if (trfr.moveModel) { + if (trfr.usesMovtProc) { // CURRENTLY INDIVIDUAL VARIATION CANNOT BE SEX-DEPENDENT ngenes = 1; } @@ -1016,7 +1036,7 @@ void Community::outRange(Species* pSpecies, int rep, int yr, int gen) } } } - if (trfr.moveModel) { + if (trfr.usesMovtProc) { if (trfr.moveType == 1) { outrange << "\t" << mnDP[0] << "\t" << sdDP[0]; outrange << "\t" << mnGB[0] << "\t" << sdGB[0]; @@ -1108,16 +1128,18 @@ void Community::outRange(Species* pSpecies, int rep, int yr, int gen) outrange << endl; } -// Open occupancy file, write header record and set up occupancy array -bool Community::outOccupancyHeaders(int option) +// Close occupancy file +bool Community::outOccupancyFinishLandscape() { - if (option == -999) { // close the files - if (outsuit.is_open()) outsuit.close(); - if (outoccup.is_open()) outoccup.close(); - outsuit.clear(); outoccup.clear(); - return true; - } + if (outsuit.is_open()) outsuit.close(); + if (outoccup.is_open()) outoccup.close(); + outsuit.clear(); outoccup.clear(); + return true; +} +// Open occupancy file, write header record and set up occupancy array +bool Community::outOccupancyStartLandscape() +{ string name, nameI; simParams sim = paramsSim->getSim(); landParams ppLand = pLandscape->getLandParams(); @@ -1125,22 +1147,22 @@ bool Community::outOccupancyHeaders(int option) name = paramsSim->getDir(2); if (sim.batchMode) { - name += "Batch" + Int2Str(sim.batchNum) + "_"; - name += "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(ppLand.landNum); + name += "Batch" + to_string(sim.batchNum) + "_"; + name += "Sim" + to_string(sim.simulation) + "_Land" + to_string(ppLand.landNum); } else - name += "Sim" + Int2Str(sim.simulation); + name += "Sim" + to_string(sim.simulation); name += "_Occupancy_Stats.txt"; outsuit.open(name.c_str()); outsuit << "Year\tMean_OccupSuit\tStd_error" << endl; name = paramsSim->getDir(2); if (sim.batchMode) { - name += "Batch" + Int2Str(sim.batchNum) + "_"; - name += "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(ppLand.landNum); + name += "Batch" + to_string(sim.batchNum) + "_"; + name += "Sim" + to_string(sim.simulation) + "_Land" + to_string(ppLand.landNum); } else - name += "Sim" + Int2Str(sim.simulation); + name += "Sim" + to_string(sim.simulation); name += "_Occupancy.txt"; outoccup.open(name.c_str()); if (ppLand.patchModel) { @@ -1181,9 +1203,10 @@ void Community::outOccupancy(void) { } } -void Community::outOccSuit(bool view) { +void Community::outOccSuit() { double sum, ss, mean, sd, se; simParams sim = paramsSim->getSim(); + for (int i = 0; i < (sim.years / sim.outIntOcc) + 1; i++) { sum = ss = 0.0; for (int rep = 0; rep < sim.reps; rep++) { @@ -1195,15 +1218,20 @@ void Community::outOccSuit(bool view) { if (sd > 0.0) sd = sqrt(sd); else sd = 0.0; se = sd / sqrt((double)(sim.reps)); + outsuit << i * sim.outIntOcc << "\t" << mean << "\t" << se << endl; - if (view) viewOccSuit(i * sim.outIntOcc, mean, se); } } +// Close traits file +bool Community::outTraitsFinishLandscape() { + return subComms[0]->outTraitsFinishLandscape(); +} + // Open traits file and write header record -bool Community::outTraitsHeaders(Species* pSpecies, int landNr) { - return subComms[0]->outTraitsHeaders(pLandscape, pSpecies, landNr); +bool Community::outTraitsStartLandscape(Species* pSpecies, int landNr) { + return subComms[0]->outTraitsStartLandscape(pLandscape, pSpecies, landNr); } // Write records to traits file @@ -1212,11 +1240,9 @@ only, this function relies on the fact that subcommunities are created in the sa sequence as patches, which is in asecending order of x nested within descending order of y */ -void Community::outTraits(traitCanvas tcanv, Species* pSpecies, - int rep, int yr, int gen) +void Community::outTraits(Species* pSpecies, int rep, int yr, int gen) { simParams sim = paramsSim->getSim(); - simView v = paramsSim->getViews(); landParams land = pLandscape->getLandParams(); traitsums* ts = 0; traitsums sctraits; @@ -1224,7 +1250,7 @@ void Community::outTraits(traitCanvas tcanv, Species* pSpecies, // create array of traits means, etc., one for each row ts = new traitsums[land.dimY]; for (int y = 0; y < land.dimY; y++) { - for (int i = 0; i < NSEXES; i++) { + for (int i = 0; i < gMaxNbSexes; i++) { ts[y].ninds[i] = 0; ts[y].sumD0[i] = ts[y].ssqD0[i] = 0.0; ts[y].sumAlpha[i] = ts[y].ssqAlpha[i] = 0.0; @@ -1237,22 +1263,22 @@ void Community::outTraits(traitCanvas tcanv, Species* pSpecies, ts[y].sumS0[i] = ts[y].ssqS0[i] = 0.0; ts[y].sumAlphaS[i] = ts[y].ssqAlphaS[i] = 0.0; ts[y].sumBetaS[i] = ts[y].ssqBetaS[i] = 0.0; + ts[y].sumGeneticFitness[i] = ts[y].ssqGeneticFitness[i] = 0.0; } } } - if (v.viewTraits - || ((sim.outTraitsCells && yr >= sim.outStartTraitCell && yr % sim.outIntTraitCell == 0) || - (sim.outTraitsRows && yr >= sim.outStartTraitRow && yr % sim.outIntTraitRow == 0))) + if ((sim.outTraitsCells && yr >= sim.outStartTraitCell && yr % sim.outIntTraitCell == 0) || + (sim.outTraitsRows && yr >= sim.outStartTraitRow && yr % sim.outIntTraitRow == 0)) { // generate output for each sub-community (patch) in the community int nsubcomms = (int)subComms.size(); for (int i = 1; i < nsubcomms; i++) { // // all except matrix sub-community - sctraits = subComms[i]->outTraits(tcanv, pLandscape, rep, yr, gen, false); + sctraits = subComms[i]->outTraits(pLandscape, rep, yr, gen, false); locn loc = subComms[i]->getLocn(); int y = loc.y; if (sim.outTraitsRows && yr >= sim.outStartTraitRow && yr % sim.outIntTraitRow == 0) { - for (int s = 0; s < NSEXES; s++) { + for (int s = 0; s < gMaxNbSexes; s++) { ts[y].ninds[s] += sctraits.ninds[s]; ts[y].sumD0[s] += sctraits.sumD0[s]; ts[y].ssqD0[s] += sctraits.ssqD0[s]; ts[y].sumAlpha[s] += sctraits.sumAlpha[s]; ts[y].ssqAlpha[s] += sctraits.ssqAlpha[s]; @@ -1265,6 +1291,7 @@ void Community::outTraits(traitCanvas tcanv, Species* pSpecies, ts[y].sumS0[s] += sctraits.sumS0[s]; ts[y].ssqS0[s] += sctraits.ssqS0[s]; ts[y].sumAlphaS[s] += sctraits.sumAlphaS[s]; ts[y].ssqAlphaS[s] += sctraits.ssqAlphaS[s]; ts[y].sumBetaS[s] += sctraits.sumBetaS[s]; ts[y].ssqBetaS[s] += sctraits.ssqBetaS[s]; + ts[y].sumGeneticFitness[s] += sctraits.sumGeneticFitness[s]; ts[y].ssqGeneticFitness[s] += sctraits.ssqGeneticFitness[s]; } } } @@ -1284,8 +1311,8 @@ void Community::outTraits(traitCanvas tcanv, Species* pSpecies, void Community::writeTraitsRows(Species* pSpecies, int rep, int yr, int gen, int y, traitsums ts) { - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); double mn, sd; @@ -1347,7 +1374,7 @@ void Community::writeTraitsRows(Species* pSpecies, int rep, int yr, int gen, int } if (trfr.indVar) { - if (trfr.moveModel) { + if (trfr.usesMovtProc) { if (trfr.moveType == 2) { // CRW // NB - CURRENTLY CANNOT BE SEX-DEPENDENT... if (popsize > 0) mn = ts.sumStepL[0] / (double)popsize; else mn = 0.0; @@ -1423,35 +1450,52 @@ void Community::writeTraitsRows(Species* pSpecies, int rep, int yr, int gen, int if (popsize > 1) sd = ts.ssqBetaS[0] / (double)popsize - mn * mn; else sd = 0.0; if (sd > 0.0) sd = sqrt(sd); else sd = 0.0; outtraitsrows << "\t" << mn << "\t" << sd; - // } } + if (pSpecies->getNbGenLoadTraits() > 0) { + if (gMaxNbSexes > 1) { + if (ts.ninds[0] > 0) mn = ts.sumGeneticFitness[0] / (double)ts.ninds[0]; else mn = 0.0; + if (ts.ninds[0] > 1) sd = ts.ssqGeneticFitness[0] / (double)ts.ninds[0] - mn * mn; else sd = 0.0; + if (sd > 0.0) sd = sqrt(sd); else sd = 0.0; + outtraitsrows << "\t" << mn << "\t" << sd; + if (ts.ninds[1] > 0) mn = ts.sumGeneticFitness[1] / (double)ts.ninds[1]; else mn = 0.0; + if (ts.ninds[1] > 1) sd = ts.ssqGeneticFitness[1] / (double)ts.ninds[1] - mn * mn; else sd = 0.0; + if (sd > 0.0) sd = sqrt(sd); else sd = 0.0; + outtraitsrows << "\t" << mn << "\t" << sd; + } + else { + if (ts.ninds[0] > 0) mn = ts.sumGeneticFitness[0] / (double)ts.ninds[0]; else mn = 0.0; + if (ts.ninds[0] > 1) sd = ts.ssqGeneticFitness[0] / (double)ts.ninds[0] - mn * mn; else sd = 0.0; + if (sd > 0.0) sd = sqrt(sd); else sd = 0.0; + outtraitsrows << "\t" << mn << "\t" << sd; + } + } outtraitsrows << endl; } -// Open trait rows file and write header record -bool Community::outTraitsRowsHeaders(Species* pSpecies, int landNr) { - - if (landNr == -999) { // close file - if (outtraitsrows.is_open()) outtraitsrows.close(); - outtraitsrows.clear(); - return true; - } +// Close trait rows file +bool Community::outTraitsRowsFinishLandscape() { + if (outtraitsrows.is_open()) outtraitsrows.close(); + outtraitsrows.clear(); + return true; +} +// Open trait rows file and write header record +bool Community::outTraitsRowsStartLandscape(Species* pSpecies, int landNr) { string name; - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); simParams sim = paramsSim->getSim(); string DirOut = paramsSim->getDir(2); if (sim.batchMode) { name = DirOut - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(landNr) + "_TraitsXrow.txt"; + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + to_string(landNr) + "_TraitsXrow.txt"; } else { - name = DirOut + "Sim" + Int2Str(sim.simulation) + "_TraitsXrow.txt"; + name = DirOut + "Sim" + to_string(sim.simulation) + "_TraitsXrow.txt"; } outtraitsrows.open(name.c_str()); @@ -1483,7 +1527,7 @@ bool Community::outTraitsRowsHeaders(Species* pSpecies, int landNr) { } } if (trfr.indVar) { - if (trfr.moveModel) { + if (trfr.usesMovtProc) { if (trfr.moveType == 2) { outtraitsrows << "\tmeanStepLength\tstdStepLength\tmeanRho\tstdRho"; } @@ -1505,10 +1549,26 @@ bool Community::outTraitsRowsHeaders(Species* pSpecies, int landNr) { } if (sett.indVar) { + // if (sett.sexDep) { + // outtraitsrows << "\tF_meanS0\tF_stdS0\tM_meanS0\tM_stdS0"; + // outtraitsrows << "\tF_meanAlphaS\tF_stdAlphaS\tM_meanAlphaS\tM_stdAlphaS"; + // outtraitsrows << "\tF_meanBetaS\tF_stdBetaS\tM_meanBetaS\tM_stdBetaS"; + // } + // else { outtraitsrows << "\tmeanS0\tstdS0"; outtraitsrows << "\tmeanAlphaS\tstdAlphaS"; outtraitsrows << "\tmeanBetaS\tstdBetaS"; + // } } + + if (pSpecies->getNbGenLoadTraits() > 0) { + if (gMaxNbSexes > 1) { + outtraitsrows << "\tF_meanProbViable\tF_stdProbViable\tM_meanProbViable\tM_stdProbViable"; + } + else + outtraitsrows << "\tmeanProbViable\tstdProbViable"; + } + outtraitsrows << endl; return outtraitsrows.is_open(); @@ -1516,47 +1576,535 @@ bool Community::outTraitsRowsHeaders(Species* pSpecies, int landNr) { } #if RS_RCPP && !R_CMD -Rcpp::IntegerMatrix Community::addYearToPopList(int rep, int yr) { // TODO: define new simparams to control start and interval of output - +Rcpp::IntegerMatrix Community::addYearToPopList(int rep, int yr, PopOutType type, int stage) { // TODO: define new simparams to control start and interval of output + /* Rcpp::Rcout << "Calling addYearToPopList: " + << "rep=" << rep + << " yr=" << yr + << " type=" << (int)type + << " stage=" << stage << endl; +*/ landParams ppLand = pLandscape->getLandParams(); Rcpp::IntegerMatrix pop_map_year(ppLand.dimY, ppLand.dimX); - intptr patch = 0; Patch* pPatch = 0; - intptr subcomm = 0; - SubCommunity* pSubComm = 0; + SubCommunity* pSubComm = nullptr; popStats pop; pop.nInds = pop.nAdults = pop.nNonJuvs = 0; for (int y = 0; y < ppLand.dimY; y++) { for (int x = 0; x < ppLand.dimX; x++) { - Cell* pCell = pLandscape->findCell(x, y); + Cell* pCell = pLandscape->findCell(x, y); //if (pLandscape->cells[y][x] == 0) { if (pCell == 0) { // no-data cell pop_map_year(ppLand.dimY - 1 - y, x) = NA_INTEGER; } else { - patch = pCell->getPatch(); - if (patch == 0) { // matrix cell + pPatch = pCell->getPatch(); + if (pPatch == nullptr) { // matrix cell pop_map_year(ppLand.dimY - 1 - y, x) = 0; } else { - pPatch = (Patch*)patch; - subcomm = pPatch->getSubComm(); - if (subcomm == 0) { // check if sub-community exists + pSubComm = pPatch->getSubComm(); + if (pSubComm == nullptr) { // check if sub-community exists pop_map_year(ppLand.dimY - 1 - y, x) = 0; } else { - pSubComm = (SubCommunity*)subcomm; pop = pSubComm->getPopStats(); - pop_map_year(ppLand.dimY - 1 - y, x) = pop.nInds; // use indices like this because matrix gets transposed upon casting it into a raster on R-level + + switch (type) { + case PopOutType::NInd: + pop_map_year(ppLand.dimY - 1 - y, x) = pop.nInds; + break; + + case PopOutType::Stage: + pop_map_year(ppLand.dimY - 1 - y, x) = pSubComm->getNbInds(stage); // check if function is correct? + break; + + case PopOutType::Juvs: + pop_map_year(ppLand.dimY - 1 - y, x) = pSubComm->getNbInds(0); + break; + } + // pop_map_year(ppLand.dimY - 1 - y, x) = pop.nInds; // use indices like this because matrix gets transposed upon casting it into a raster on R-level + //pop_map_year(ppLand.dimY-1-y,x) = pop.nAdults; } } } } } + //list_outPop.push_back(pop_map_year, "rep" + std::to_string(rep) + "_year" + std::to_string(yr)); + return pop_map_year; +} + +// write a similar function for patch-based models; +// Instead of a spatial x,y raster, the output should also be a Rcpp::IntegerMatrix with PatchID and population size (or stage-specific population size) for each patch. +// The number of columns is determined by what the user specified in ReturnStages: +// As default its 2 columns: 1st column is the patch ID, 2nd column is the total abundance. +// Depending on the user specification the columns 3 to maximal (number of stages + 2) +// can contain the abundance of each stage (e.g. column 3 is abundance of juveniles (stage 0), column 4 is abundance of stage 1 etc). +// But only selected stages are included, so if the user only wants to output juveniles and adults, +// then column 3 is abundance of juveniles (stage 0) and column 4 is abundance of adults (stage 1), and no other stages are included in the output. +// After the runtime, the user can create a spatial raster in R by joining it with the patch coordinates. +// be aware: the output is then not a spatial raster, but a table +Rcpp::IntegerMatrix Community::addYearToPopListPatchBased(int rep, int yr, Rcpp::LogicalVector stages) { + /* Rcpp::Rcout << "Calling addYearToPopListPatchBased: " + << "rep=" << rep + << " yr=" << yr << endl;*/ + int nrows=pLandscape->getPatchNbs().size(); + int ncols = 2; // for patchID + total abundance + std::vector stageIndices; + + for (int i = 0; i < stages.length(); i++) { + if (stages[i]) { + stageIndices.push_back(i); + } + } + ncols += stageIndices.size(); + + + Rcpp::IntegerMatrix pop_map_year(nrows, ncols); // 2 columns: 1st column is the patch ID, 2nd column is the total abundance (or stage-specific abundance depending on user specification) + Patch* pPatch = nullptr; + SubCommunity* pSubComm = nullptr; + int currentRow = 0; + + for (auto patchId : pLandscape->getPatchNbs()) { + // pPatch = pLandscape->findPatch(patchId); + // if (pPatch == nullptr) { // check if patch exists + // continue; // skip to next patch + // } else{ + // pSubComm = pPatch->getSubComm(); + // if (pSubComm == nullptr) { // check if sub-community exists + // pop = pSubComm->getPopStats(); + // pop_map_year(patchId, 0) = patchId; // 1st column is patch ID + // pop_map_year(patchId, 1) = 0; // 2nd column is total abundance + // // additional columns for stage-specific abundances depending on user specification + // for(int i = 0; i < stages.length(); i++) { + // int ncol = 0; + // if(stages[i]) { + // pop_map_year(patchId, 2 + ncol) = 0; // all following columns are stage specific columns depending on the users specifications + // ncol++; + // } + // } + // } else { + // pop = pSubComm->getPopStats(); + // pop_map_year(patchId, 0) = patchId; // 1st column is patch ID + // pop_map_year(patchId, 1) = pop.nInds; // 2nd column is total abundance + // // additional columns for stage-specific abundances depending on user specification + // for (int i = 0; i < stages.length(); i++) { + // int ncol = 0; + // if(stages[i]) { + // pop_map_year(patchId, 2 + ncol) = pSubComm->getNbInds(stages[i]); // all following columns are stage specific columns depending on the users specifications + // ncol++; + // } + // } + // } + // } + pop_map_year(currentRow, 0) = patchId; // 1st column: patch ID + // loop over ncols to fill default to 0 + for(int i = 1; i < ncols; i++) { + pop_map_year(currentRow, i) = 0; // 2nd column: default total abundance + } + + pPatch = pLandscape->findPatch(patchId); + if (pPatch != nullptr) { // Valid patch + pSubComm = pPatch->getSubComm(); + if (pSubComm != nullptr) { // Valid sub-community + popStats pop = pSubComm->getPopStats(); + pop_map_year(currentRow, 1) = pop.nInds; // Actual total abundance + + for (int idx = 0; idx < stageIndices.size(); ++idx) { + int stage = stageIndices[idx]; + pop_map_year(currentRow, 2 + idx) = pSubComm->getNbInds(stage); + } + } + } + currentRow++; + } + return pop_map_year; + // } + // return pop_map_year; } + #endif +bool Community::openOutGenesFile(const bool& isDiploid, const int landNr, const int rep) +{ + if (landNr == -999) { // close the file + if (ofsGenes.is_open()) { + ofsGenes.close(); + ofsGenes.clear(); + } + return true; + } + string name; + simParams sim = paramsSim->getSim(); + + if (sim.batchMode) { + name = paramsSim->getDir(2) + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + + to_string(landNr) + "_Rep" + to_string(rep) + + "_geneValues.txt"; + } + else { + name = paramsSim->getDir(2) + + "Sim" + to_string(sim.simulation) + "_Land" + + to_string(landNr) + "_Rep" + to_string(rep) + + "_geneValues.txt"; + } + + ofsGenes.open(name.c_str()); + ofsGenes << "Year\tGeneration\tIndID\ttraitType\tlocusPosition" + << "\talleleValueA\tdomCoefA"; + if (isDiploid) ofsGenes << "\talleleValueB\tdomCoefB"; + ofsGenes << endl; + + return ofsGenes.is_open(); +} + +void Community::outputGeneValues(const int& year, const int& gen, Species* pSpecies) { + if (!ofsGenes.is_open()) + throw runtime_error("Could not open output gene values file."); + + const set patchList = pSpecies->getSamplePatches(); + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + if (patch == 0) { + throw runtime_error("Sampled patch does not exist"); + } + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + pPop->outputGeneValues(ofsGenes, year, gen); + } + } +} + +// ---------------------------------------------------------------------------------------- +// Sample individuals from sample patches +// ---------------------------------------------------------------------------------------- + +void Community::sampleIndividuals(Species* pSpecies) { + + const set patchList = pSpecies->getSamplePatches(); + string nbIndsToSample = pSpecies->getNIndsToSample(); + const set stagesToSampleFrom = pSpecies->getStagesToSample(); + + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + if (patch == 0) { + throw runtime_error("Can't sample individuals: patch" + to_string(patchId) + "doesn't exist."); + } + auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + pPop->sampleIndsWithoutReplacement(nbIndsToSample, stagesToSampleFrom); + } + } +} + +// ---------------------------------------------------------------------------------------- +// Open population level Fstat output file +// ---------------------------------------------------------------------------------------- + +bool Community::openNeutralOutputFile(Species* pSpecies, int landNr) +{ + if (landNr == -999) { // close the file + if (outwcfstat.is_open()) outwcfstat.close(); + outwcfstat.clear(); + return true; + } + + string name; + simParams sim = paramsSim->getSim(); + + if (sim.batchMode) { + name = paramsSim->getDir(2) + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + + to_string(landNr) + + "_neutralGenetics.txt"; + } + else { + name = paramsSim->getDir(2) + "Sim" + to_string(sim.simulation) + "_neutralGenetics.txt"; + } + outwcfstat.open(name.c_str()); + outwcfstat << "Rep\tYear\tRepSeason\tnExtantPatches\tnIndividuals\tFstWC\tFisWC\tFitWC\tmeanAllelePerLocus\tmeanAllelePerLocusPatches\tmeanFixedLoci\tmeanFixedLociPatches\tmeanObHeterozygosity"; + outwcfstat << endl; + + return outwcfstat.is_open(); +} + +// ---------------------------------------------------------------------------------------- +// open per locus WC fstat using MS approach, this will output MS calculated FIS, FIT, FST +// in general population neutral genetics output file +// ---------------------------------------------------------------------------------------- + +bool Community::openPerLocusFstFile(Species* pSpecies, Landscape* pLandscape, const int landNr, const int rep) +{ + set patchList; + string samplingOpt = paramsSim->getSim().patchSamplingOption; + if (samplingOpt == "list" + || samplingOpt == "random" + || (samplingOpt == "all" && !pLandscape->getLandParams().dynamic) + ) // list of patches always the same + patchList = pSpecies->getSamplePatches(); + else { // random_occupied or all with dynamic landscape + // then sampled patches may change every year, + // so produce an entry for all patches + patchList = pLandscape->getPatchNbs(); + } + + if (landNr == -999) { // close the file + if (outperlocusfstat.is_open()) outperlocusfstat.close(); + outperlocusfstat.clear(); + return true; + } + + string name; + simParams sim = paramsSim->getSim(); + + if (sim.batchMode) { + name = paramsSim->getDir(2) + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + + to_string(landNr) + "_Rep" + + to_string(rep) + + "_perLocusNeutralGenetics.txt"; + } + else { + name = paramsSim->getDir(2) + "Sim" + to_string(sim.simulation) + "_Rep" + to_string(rep) + "_perLocusNeutralGenetics.txt"; + } + + outperlocusfstat.open(name.c_str()); + outperlocusfstat << "Year\tRepSeason\tLocus\tFst\tFis\tFit\tHet"; + for (int patchId : patchList) { + outperlocusfstat << "\tpatch_" + to_string(patchId) + "_Het"; + } + outperlocusfstat << endl; + + return outperlocusfstat.is_open(); +} + +// ---------------------------------------------------------------------------------------- +// open pairwise fst file +// ---------------------------------------------------------------------------------------- + +bool Community::openPairwiseFstFile(Species* pSpecies, Landscape* pLandscape, const int landNr, const int rep) { + + const set patchList = pSpecies->getSamplePatches(); + + if (landNr == -999) { // close the file + if (outpairwisefst.is_open()) outpairwisefst.close(); + outpairwisefst.clear(); + return true; + } + + string name; + simParams sim = paramsSim->getSim(); + + if (sim.batchMode) { + name = paramsSim->getDir(2) + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + + to_string(landNr) + "_Rep" + + to_string(rep) + + "_pairwisePatchNeutralGenetics.txt"; + } + else { + name = paramsSim->getDir(2) + "Sim" + to_string(sim.simulation) + "_Rep" + to_string(rep) + "_pairwisePatchNeutralGenetics.txt"; + } + outpairwisefst.open(name.c_str()); + outpairwisefst << "Year\tRepSeason\tpatchA\tpatchA_x\tpatchA_y\tpatchB\tpatchB_x\tpatchB_y\tFst"; + outpairwisefst << endl; + + return outpairwisefst.is_open(); +} + +// ---------------------------------------------------------------------------------------- +// Write population level FST results file +// ---------------------------------------------------------------------------------------- + +void Community::writeNeutralOutputFile(int rep, int yr, int gen) { + + outwcfstat << rep << "\t" << yr << "\t" << gen << "\t"; + outwcfstat << pNeutralStatistics->getNbPopulatedSampledPatches() + << "\t" << pNeutralStatistics->getTotalNbSampledInds() << "\t"; + + + outwcfstat << pNeutralStatistics->getFstWC() << "\t" + << pNeutralStatistics->getFisWC() << "\t" + << pNeutralStatistics->getFitWC() << "\t"; + + + + outwcfstat << pNeutralStatistics->getMeanNbAllPerLocus() << "\t" + << pNeutralStatistics->getMeanNbAllPerLocusPerPatch() << "\t" + << pNeutralStatistics->getTotalFixdAlleles() << "\t" + << pNeutralStatistics->getMeanFixdAllelesPerPatch() << "\t" + << pNeutralStatistics->getHo(); + + outwcfstat << endl; +} + +// ---------------------------------------------------------------------------------------- +// Write per locus FST results file +// ---------------------------------------------------------------------------------------- + +void Community::writePerLocusFstatFile(Species* pSpecies, const int yr, const int gen, const int nLoci, set const& patchList) +{ + string samplingOpt = paramsSim->getSim().patchSamplingOption; + bool samplingFixed = samplingOpt == "list" + || samplingOpt == "random" + || (samplingOpt == "all" && !pLandscape->getLandParams().dynamic); + + const set positions = pSpecies->getSpTrait(NEUTRAL)->getGenePositions(); + + int thisLocus = 0; + for (int position : positions) { + + outperlocusfstat << yr << "\t" + << gen << "\t" + << position << "\t"; + outperlocusfstat << pNeutralStatistics->getPerLocusFst(thisLocus) << "\t" + << pNeutralStatistics->getPerLocusFis(thisLocus) << "\t" + << pNeutralStatistics->getPerLocusFit(thisLocus) << "\t" + << pNeutralStatistics->getPerLocusHo(thisLocus); + + if (samplingFixed) { // then safe to output sampled patches in order + for (int patchId : patchList) { + float het = getPatchHet(pSpecies, patchId, thisLocus); + if (het < 0) // patch empty + outperlocusfstat << "\t" << "NA"; + else outperlocusfstat << "\t" << het; + } + } + else { // sampling may change between generations, must produce output for all patches in Landscape + for (auto patchId : pLandscape->getPatchNbs()) { + if (patchList.find(patchId) != patchList.end()) { + float het = getPatchHet(pSpecies, patchId, thisLocus); + if (het < 0) // patch empty + outperlocusfstat << "\t" << "NA"; + else outperlocusfstat << "\t" << het; + } + else { // patch not sampled + outperlocusfstat << "\t" << "NA"; + } + } + } + ++thisLocus; + outperlocusfstat << endl; + } +} + +// Calculate the observed heterozygosity (Ho) for a patch +// = number of heterozygous individuals at this locus / nb individuals in patch +float Community::getPatchHet(Species* pSpecies, int patchId, int whichLocus) const { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + int nAlleles = pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); + int popSize = 0; + float het = 0; + if (pPop != 0) { + popSize = pPop->sampleSize(); + if (popSize == 0) return -1.0; + else { + for (int a = 0; a < nAlleles; ++a) { + het += static_cast(pPop->getHeteroTally(whichLocus, a)); + } + het /= popSize; + return het; + } + } + else return -1.0; +} + + +// ---------------------------------------------------------------------------------------- +// Write pairwise FST results file +// ---------------------------------------------------------------------------------------- +void Community::writePairwiseFstFile(Species* pSpecies, const int yr, const int gen, set const& patchList) { + + const int nPatches = static_cast(patchList.size()); + // Convert set to vector for index-based access + vector patchVect; + copy(patchList.begin(), patchList.end(), back_inserter(patchVect)); + + for (int i = 0; i < nPatches; ++i) + { + const auto patchA = pLandscape->findPatch(patchVect[i]); + + for (int j = i; j < nPatches; ++j) + { + + const auto patchB = pLandscape->findPatch(patchVect[j]); + + outpairwisefst << yr << "\t" + << gen << "\t" + << patchVect[i] << "\t" + << patchA->getSubComm()->getLocn().x << "\t" + << patchA->getSubComm()->getLocn().y << "\t" + << patchVect[j] << "\t" + << patchB->getSubComm()->getLocn().x << "\t" + << patchB->getSubComm()->getLocn().y << "\t" + << pNeutralStatistics->getPairwiseFst(i, j) + << "\n"; + } + } + + +} + + +// ---------------------------------------------------------------------------------------- +// Output and calculate neutral statistics +// ---------------------------------------------------------------------------------------- + + +void Community::calculateNeutralGenetics(Species* pSpecies, int rep, int yr, int gen, bool outPairwiseFst, int outputPairwiseFstStart, int outputPairwiseFstInterval, + bool outputGlobalFst, int outputGlobalFstStart, int outputGlobalFstInterval, bool outputPerLocusFst) { + + const int maxNbNeutralAlleles = pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); + const int nLoci = (int)pSpecies->getNPositionsForTrait(NEUTRAL); + const set patchList = pSpecies->getSamplePatches(); + int nInds = 0, nbPops = 0; + + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + if (patch == 0) { + throw runtime_error("Sampled patch does not exist"); + } + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { // empty patches do not contribute + nInds += pPop->sampleSize(); + nbPops++; + } + } + + if (pNeutralStatistics == 0) + pNeutralStatistics = make_unique(patchList.size(), nLoci); + + pNeutralStatistics->updateAllNeutralTables(pSpecies, pLandscape, patchList); + pNeutralStatistics->calculateHo(patchList, nInds, nLoci, pSpecies, pLandscape); + pNeutralStatistics->calculatePerLocusHo(patchList, nInds, nLoci, pSpecies, pLandscape); + pNeutralStatistics->calcAllelicDiversityMetrics(patchList, nInds, pSpecies, pLandscape); + + if (outPairwiseFst) { + pNeutralStatistics->calculatePairwiseFst(patchList, nLoci, maxNbNeutralAlleles, pSpecies, pLandscape); + + if (yr >= outputPairwiseFstStart && yr % outputPairwiseFstInterval == 0) { + writePairwiseFstFile(pSpecies, yr, gen, patchList); + } + } + if (outputGlobalFst) { + pNeutralStatistics->calculateFstatWC(patchList, nInds, nLoci, maxNbNeutralAlleles, pSpecies, pLandscape, false); + + if (yr >= outputGlobalFstStart && yr % outputGlobalFstInterval == 0) { + writeNeutralOutputFile(rep, yr, gen); + if (outputPerLocusFst) + writePerLocusFstatFile(pSpecies, yr, gen, nLoci, patchList); + } + } + +} + + //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- diff --git a/Community.h b/RangeShiftR/src/RScore/Community.h similarity index 61% rename from Community.h rename to RangeShiftR/src/RScore/Community.h index c55b333..f102fd1 100644 --- a/Community.h +++ b/RangeShiftR/src/RScore/Community.h @@ -1,25 +1,25 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * + * --------------------------------------------------------------------------*/ - - + + /*------------------------------------------------------------------------------ RangeShifter v2.0 Community @@ -35,9 +35,9 @@ Optionally, the Community maintains a record of the occupancy of suitable cells or patches during the course of simulation of multiple replicates. For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. + eco-evolutionary dynamics and species’ responses to environmental changes. Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 Authors: Greta Bocedi & Steve Palmer, University of Aberdeen @@ -51,6 +51,8 @@ Last updated: 25 June 2021 by Anne-Kathleen Malchow #include #include +#include +#include using namespace std; #include "SubCommunity.h" @@ -58,6 +60,7 @@ using namespace std; #include "Patch.h" #include "Cell.h" #include "Species.h" +#include "NeutralStatsManager.h" //--------------------------------------------------------------------------- struct commStats { @@ -65,6 +68,14 @@ int ninds,nnonjuvs,suitable,occupied; int minX,maxX,minY,maxY; }; +#if RS_RCPP// For raster output only: which type of population output should be stored? +enum class PopOutType { + NInd, // total abundance + Stage, // specific stages + Juvs // juvenile stage +}; +#endif + class Community { public: @@ -95,15 +106,14 @@ class Community { ); #endif // SEASONAL || RS_RCPP - void survival( - short, // part: 0 = determine survival & development, - // 1 = apply survival changes to the population + void survival0( // Determine survival & development short, // option0: 0 = stage 0 (juveniles) only ) // 1 = all stages ) used by part 0 only // 2 = stage 1 and above (all non-juvs) ) short // option1: 0 - development only (when survival is annual) // 1 - development and survival ); + void survival1(); // Apply survival changes to the population void ageIncrement(void); int totalInds(void); Population* findPop( // Find the population of a given species in a given patch @@ -123,9 +133,10 @@ class Community { int // no. of rows (as above) ); - bool outRangeHeaders( // Open range file and write header record + bool outRangeFinishLandscape(); // Close range file + bool outRangeStartLandscape( // Open range file and write header record Species*, // pointer to Species - int // Landscape number (-999 to close the file) + int // Landscape number ); void outRange( // Write record to range file Species*, // pointer to Species @@ -133,9 +144,9 @@ class Community { int, // year int // generation ); - bool outPopHeaders( // Open population file and write header record - Species*, // pointer to Species - int // option: -999 to close the file + bool outPopFinishLandscape(); // Close population file + bool outPopStartLandscape( // Open population file and write header record + Species* // pointer to Species ); void outPop( // Write records to population file int, // replicate @@ -143,46 +154,33 @@ class Community { int // generation ); - void outInds( // Write records to individuals file + void outIndsFinishReplicate(); // Close individuals file + void outIndsStartReplicate( // Open individuals file and write header record int, // replicate - int, // year - int, // generation - int // Landscape number (>= 0 to open the file, -999 to close the file - // -1 to write data records) + int // Landscape number ); - void outGenetics( // Write records to genetics file + void outIndividuals( // Write records to individuals file int, // replicate int, // year - int, // generation - int // Landscape number (>= 0 to open the file, -999 to close the file - // -1 to write data records) + int // generation ); + // Close occupancy file + bool outOccupancyFinishLandscape(); // Open occupancy file, write header record and set up occupancy array - bool outOccupancyHeaders( - int // option: -999 to close the file - ); + bool outOccupancyStartLandscape(); void outOccupancy(void); - void outOccSuit( - bool // TRUE if occupancy graph is to be viewed on screen - ); - void viewOccSuit( // Update the occupancy graph on the screen - // NULL for the batch version - int, // year - double, // mean occupancy - double // standard error of occupancy - ); - bool outTraitsHeaders( // Open traits file and write header record + void outOccSuit(); + bool outTraitsFinishLandscape(); // Close traits file + bool outTraitsStartLandscape( // Open traits file and write header record Species*, // pointer to Species - int // Landscape number (-999 to close the file) + int // Landscape number ); - bool outTraitsRowsHeaders( // Open trait rows file and write header record + bool outTraitsRowsFinishLandscape(); // Close trait rows file + bool outTraitsRowsStartLandscape( // Open trait rows file and write header record Species*, // pointer to Species - int // Landscape number (-999 to close the file) + int // Landscape number ); void outTraits( // Write records to traits file - traitCanvas,// pointers to canvases for drawing variable traits - // see SubCommunity.h - // in the batch version, these are replaced by integers set to zero Species*, // pointer to Species int, // replicate int, // year @@ -196,23 +194,42 @@ class Community { int, // row number (Y cell co-ordinate) traitsums // structure holding sums of trait genes for dispersal (see Population.h) ); - void draw( // Draw the Community on the landscape map and optionally save the map - // NULL for the batch version - int, // replicate - int, // year - int, // generation - int // Landscape number - ); #if RS_RCPP && !R_CMD - Rcpp::IntegerMatrix addYearToPopList(int,int); + Rcpp::IntegerMatrix addYearToPopList(int,int,PopOutType,int); + + Rcpp::IntegerMatrix addYearToPopListPatchBased(int,int,Rcpp::LogicalVector); #endif + //sample individuals for genetics (or could be used for anything) + void sampleIndividuals(Species* pSpecies); + + bool openOutGenesFile(const bool& isDiploid, const int landNr, const int rep); + void outputGeneValues(const int& year, const int& gen, Species* pSpecies); + + //control neutral stat output + + void calculateNeutralGenetics(Species* pSpecies, int rep, int yr, int gen, bool outPairwiseFst, int outputPairwiseFstStart, int outputPairwiseFstInterval, + bool outputGlobalFst, int outputGlobalFstStart, int outputGlobalFstInterval, bool outputPerLocusFst); + + + //file openers + bool openNeutralOutputFile(Species* pSpecies, const int landNr); + bool openPerLocusFstFile(Species* pSpecies, Landscape* pLandscape, const int landNr, const int rep); + bool openPairwiseFstFile(Species* pSpecies, Landscape* pLandscape, const int landNr, const int rep); + + //file writers + void writeNeutralOutputFile(int rep, int yr, int gen); + void writePerLocusFstatFile(Species* pSpecies, const int yr, const int gen, const int nLoci, set const& patchList); + void writePairwiseFstFile(Species* pSpecies, const int yr, const int gen, set const& patchList); + float getPatchHet(Species* pSpecies, int patchId, int whichLocus) const; private: Landscape *pLandscape; int indIx; // index used to apply initial individuals float **occSuit; // occupancy of suitable cells / patches std::vector subComms; + //below won't work for multispecies + unique_ptr pNeutralStatistics; }; extern paramSim *paramsSim; diff --git a/RangeShiftR/src/RScore/DispersalTrait.cpp b/RangeShiftR/src/RScore/DispersalTrait.cpp new file mode 100644 index 0000000..f0a805d --- /dev/null +++ b/RangeShiftR/src/RScore/DispersalTrait.cpp @@ -0,0 +1,489 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#include "DispersalTrait.h" + +// ---------------------------------------------------------------------------------------- +// Initialisation constructor +// Called when initialising community +// Sets up initial values, and immutable attributes (distributions and parameters) +// that are defined at the species-level +// ---------------------------------------------------------------------------------------- +DispersalTrait::DispersalTrait(SpeciesTrait* P) +{ + pSpeciesTrait = P; + ExpressionType expressionType = pSpeciesTrait->getExpressionType(); + + if (!pSpeciesTrait->isInherited()) // there is a trait for individual variation but this isn't inherited variation it's sampled from initial distribution + _inherit_func_ptr = &DispersalTrait::reInitialiseGenes; + else { + _inherit_func_ptr = (pSpeciesTrait->getPloidy() == 1) ? &DispersalTrait::inheritHaploid : &DispersalTrait::inheritDiploid; //this could be changed if we wanted some alternative form of inheritance + + DistributionType mutationDistribution = pSpeciesTrait->getMutationDistribution(); + map mutationParameters = pSpeciesTrait->getMutationParameters(); + + // Set mutation parameters + switch (mutationDistribution) { + case UNIFORM: + { + if (mutationParameters.count(MAX) != 1) + throw logic_error("mutation uniform distribution parameter must contain max value (e.g. max= ) \n"); + if (mutationParameters.count(MIN) != 1) + throw logic_error("mutation uniform distribution parameter must contain min value (e.g. min= ) \n"); + _mutate_func_ptr = &DispersalTrait::mutateUniform; + break; + } + case NORMAL: + { + if (mutationParameters.count(MEAN) != 1) + throw logic_error("mutation distribution set to normal so parameters must contain mean value (e.g. mean= ) \n"); + if (mutationParameters.count(SD) != 1) + throw logic_error("mutation distribution set to normal so parameters must contain sdev value (e.g. sdev= ) \n"); + _mutate_func_ptr = &DispersalTrait::mutateNormal; + break; + } + default: + { + throw logic_error("wrong parameter value for mutation model, must be uniform/normal \n"); //unless want to add gamma or negative exp + break; + } + } + } + + // Set initialisation parameters + DistributionType initialDistribution = pSpeciesTrait->getInitialDistribution(); + map initialParameters = pSpeciesTrait->getInitialParameters(); + switch (initialDistribution) { + case UNIFORM: + { + if (initialParameters.count(MAX) != 1) + throw logic_error("initial uniform distribution parameter must contain max value (e.g. max= ) \n"); + if (initialParameters.count(MIN) != 1) + throw logic_error("initial uniform distribution parameter must contain min value (e.g. min= ) \n"); + float maxD = initialParameters.find(MAX)->second; + float minD = initialParameters.find(MIN)->second; + initialiseUniform(minD, maxD); + break; + } + case NORMAL: + { + if (initialParameters.count(MEAN) != 1) + throw logic_error("initial normal distribution parameter must contain mean value (e.g. mean= ) \n"); + if (initialParameters.count(SD) != 1) + throw logic_error("initial normal distribution parameter must contain sdev value (e.g. sdev= ) \n"); + float mean = initialParameters.find(MEAN)->second; + float sd = initialParameters.find(SD)->second; + initialiseNormal(mean, sd); + break; + } + default: + { + throw logic_error("wrong parameter value for parameter \"initialisation of dispersal traits\", must be uniform/normal \n"); + break; + } + } + + // Set expression mode parameters + switch (expressionType) { + case AVERAGE: + { + _express_func_ptr = &DispersalTrait::expressAverage; + break; + } + case ADDITIVE: + { + _express_func_ptr = &DispersalTrait::expressAdditive; + break; + } + default: + { + throw logic_error("wrong parameter value for parameter \"expression of dispersal trait\", must be average/additive \n"); + break; + } + } +} + +// ---------------------------------------------------------------------------------------- +// Inheritance constructor +// Copies immutable features from a parent trait +// Only called via clone() +// ---------------------------------------------------------------------------------------- +DispersalTrait::DispersalTrait(const DispersalTrait& T) : + pSpeciesTrait(T.pSpeciesTrait), + _mutate_func_ptr(T._mutate_func_ptr), + _inherit_func_ptr(T._inherit_func_ptr), + _express_func_ptr(T._express_func_ptr) {} + +// ---------------------------------------------------------------------------------------- +// Sample and apply mutations from a uniform distribution +// +// Mutations drawn only for existing positions, +// that is no new genes are created during simulation +// ---------------------------------------------------------------------------------------- +void DispersalTrait::mutateUniform() +{ + const int positionsSize = pSpeciesTrait->getPositionsSize(); + const auto& genePositions = pSpeciesTrait->getGenePositions(); + const short ploidy = pSpeciesTrait->getPloidy(); + const float mutationRate = pSpeciesTrait->getMutationRate(); + float newAlleleVal; + + auto rng = pRandom->getRNG(); + + map mutationParameters = pSpeciesTrait->getMutationParameters(); + float maxD = mutationParameters.find(MAX)->second; + float minD = mutationParameters.find(MIN)->second; + + for (int p = 0; p < ploidy; p++) { + + unsigned int NbMut = pRandom->Binomial(positionsSize, mutationRate); + + if (NbMut > 0) { + vector mutationPositions; + sample(genePositions.begin(), genePositions.end(), std::back_inserter(mutationPositions), + NbMut, rng); + + for (int m : mutationPositions) { + auto it = genes.find(m); + if (it == genes.end()) + throw runtime_error("Locus sampled for mutation doesn't exist."); + float currentAlleleVal = it->second[p].get()->getAlleleValue();//current + newAlleleVal = pRandom->FRandom(minD, maxD) + currentAlleleVal; + it->second[p] = make_shared(newAlleleVal, dispDominanceFactor); + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// Sample and apply mutations from a normal distribution +// Mutations drawn only for existing positions, +// that is no new genes are created during simulation +// ---------------------------------------------------------------------------------------- +void DispersalTrait::mutateNormal() +{ + const int positionsSize = pSpeciesTrait->getPositionsSize(); + const auto& genePositions = pSpeciesTrait->getGenePositions(); + const short ploidy = pSpeciesTrait->getPloidy(); + const float mutationRate = pSpeciesTrait->getMutationRate(); + + auto rng = pRandom->getRNG(); + + const map mutationParameters = pSpeciesTrait->getMutationParameters(); + const float mean = mutationParameters.find(MEAN)->second; + const float sd = mutationParameters.find(SD)->second; + float newAlleleVal; + + for (int p = 0; p < ploidy; p++) { + + unsigned int NbMut = pRandom->Binomial(positionsSize, mutationRate); + + if (NbMut > 0) { + vector mutationPositions; + sample(genePositions.begin(), genePositions.end(), std::back_inserter(mutationPositions), + NbMut, rng); + + for (int m : mutationPositions) { + auto it = genes.find(m); + if (it == genes.end()) + throw runtime_error("Locus sampled for mutation doesn't exist."); + float currentAlleleVal = it->second[p].get()->getAlleleValue(); //current + newAlleleVal = pRandom->Normal(mean, sd) + currentAlleleVal; + it->second[p] = make_shared(newAlleleVal, dispDominanceFactor); + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// Wrapper to inheritance function +// ---------------------------------------------------------------------------------------- +void DispersalTrait::inheritGenes(const bool& fromMother, QuantitativeTrait* parentTrait, set const& recomPositions, int startingChromosome) +{ + auto parentCast = dynamic_cast(parentTrait); // must convert QuantitativeTrait to DispersalTrait + const auto& parent_seq = parentCast->getGenes(); + (this->*_inherit_func_ptr)(fromMother, parent_seq, recomPositions, startingChromosome); +} + +// ---------------------------------------------------------------------------------------- +// Inheritance for diploid, sexual species +// Called once for each parent. +// Pass the correct parental strand, resolving crossing-overs +// after each recombinant site e.g. if parent genotype is +// 0000 +// 1111 +// and position 2 is selected to recombine, then offspring inherits +// 0001 +// Assumes mother genes are inherited first. +// ---------------------------------------------------------------------------------------- +void DispersalTrait::inheritDiploid(const bool& fromMother, map>> const& parentGenes, set const& recomPositions, int parentChromosome) { + + const int lastPosition = parentGenes.rbegin()->first; + auto recomIt = recomPositions.lower_bound(parentGenes.begin()->first); + // If no recombination sites, only breakpoint is last position + // i.e., no recombination occurs + int nextBreakpoint = recomIt == recomPositions.end() ? lastPosition : *recomIt; + + // Is the first parent gene position already recombinant? + auto distance = std::distance(recomPositions.begin(), recomIt); + if (distance % 2 != 0) // odd positions = switch, even = switch back + parentChromosome = 1 - parentChromosome; //switch chromosome + + for (auto const& [locus, allelePair] : parentGenes) { + + // Switch chromosome if locus is past recombination site + while (locus > nextBreakpoint) { + parentChromosome = 1 - parentChromosome; + std::advance(recomIt, 1); // go to next recombination site + nextBreakpoint = recomIt == recomPositions.end() ? lastPosition : *recomIt; + } + + if (locus <= nextBreakpoint) { + auto& parentAllele = allelePair[parentChromosome]; + auto itGene = genes.find(locus); + if (itGene == genes.end()) { + // locus does not exist yet, create and initialise it + if (!fromMother) throw runtime_error("Father-inherited locus does not exist."); + vector> newAllelePair(2); + newAllelePair[sex_t::FEM] = parentAllele; + genes.insert(make_pair(locus, newAllelePair)); + } + else { // father, locus already exists + if (fromMother) throw runtime_error("Mother-inherited locus already exists."); + itGene->second[sex_t::MAL] = parentAllele; + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// Inheritance for haploid, asexual species +// Simply pass down parent genes +// Arguments are still needed to match overloaded function in base class +// ---------------------------------------------------------------------------------------- +void DispersalTrait::inheritHaploid(const bool& fromMother, map>> const& parentGenes, set const& recomPositions, int parentChromosome) +{ + genes = parentGenes; +} + +// ---------------------------------------------------------------------------------------- +// Non-inheritance +// For cases where isInherited option is turned off +// In this case, offspring alleles are populated using the initialise functions +// Arguments are still needed to match overloaded function in base class +// ---------------------------------------------------------------------------------------- +void DispersalTrait::reInitialiseGenes(const bool& fromMother, map>> const& parentGenes, set const& recomPositions, int parentChromosome) +{ + DistributionType initialDistribution = pSpeciesTrait->getInitialDistribution(); + map initialParameters = pSpeciesTrait->getInitialParameters(); + + switch (initialDistribution) { + case UNIFORM: + { + if (initialParameters.count(MAX) != 1) + throw logic_error("initial uniform distribution parameter must contain max value (e.g. max= ) \n"); + if (initialParameters.count(MIN) != 1) + throw logic_error("initial uniform distribution parameter must contain min value (e.g. min= ) \n"); + float maxD = initialParameters.find(MAX)->second; + float minD = initialParameters.find(MIN)->second; + initialiseUniform(minD, maxD); + break; + } + case NORMAL: + { + if (initialParameters.count(MEAN) != 1) + throw logic_error("initial normal distribution parameter must contain mean value (e.g. mean= ) \n"); + if (initialParameters.count(SD) != 1) + throw logic_error("initial normal distribution parameter must contain sdev value (e.g. sdev= ) \n"); + float mean = initialParameters.find(MEAN)->second; + float sd = initialParameters.find(SD)->second; + initialiseNormal(mean, sd); + break; + } + default: + { + throw logic_error("wrong parameter value for parameter \"initialisation of dispersal trait\", must be uniform/normal \n"); + break; //should return false + } + } +} + +// ---------------------------------------------------------------------------------------- +// Dispersal initialisation options +// ---------------------------------------------------------------------------------------- +void DispersalTrait::initialiseNormal(float mean, float sd) { + + const set genePositions = pSpeciesTrait->getGenePositions(); + short ploidy = pSpeciesTrait->getPloidy(); + + for (auto position : genePositions) { + vector> newAllelePair; + for (int i = 0; i < ploidy; i++) { + float alleleVal = pRandom->Normal(mean, sd); + newAllelePair.emplace_back(make_shared(alleleVal, dispDominanceFactor)); + } + genes.insert(make_pair(position, newAllelePair)); + } +} + +void DispersalTrait::initialiseUniform(float min, float max) { + + const set genePositions = pSpeciesTrait->getGenePositions(); + short ploidy = pSpeciesTrait->getPloidy(); + + for (auto position : genePositions) { + vector> newAllelePair; + for (int i = 0; i < ploidy; i++) { + float alleleVal = pRandom->FRandom(min, max); + newAllelePair.emplace_back(make_shared(alleleVal, dispDominanceFactor)); + } + genes.insert(make_pair(position, newAllelePair)); + } +} + +// ---------------------------------------------------------------------------------------- +// Dispersal gene expression options +// ---------------------------------------------------------------------------------------- +float DispersalTrait::expressAdditive() { + + float phenotype = 0.0; + + for (auto const& [locus, allelePair] : genes) + { + for (const std::shared_ptr m : allelePair) + phenotype += m->getAlleleValue(); + } + trimPhenotype(phenotype); + return phenotype; +} + +float DispersalTrait::expressAverage() { + + int positionsSize = pSpeciesTrait->getPositionsSize(); + short ploidy = pSpeciesTrait->getPloidy(); + float phenotype = 0.0; + + for (auto const& [locus, allelePair] : genes) + { + for (auto& m : allelePair) + phenotype += m->getAlleleValue(); + } + phenotype /= positionsSize * ploidy; + trimPhenotype(phenotype); + return phenotype; +} + +void DispersalTrait::trimPhenotype(float& val) { + const float minPositiveVal = 1e-06; + switch (pSpeciesTrait->getTraitType()) + { + // Values bound between 0 and 1 + case E_D0_F: case E_D0_M: case E_D0: + case S_S0_F: case S_S0_M: case S_S0: + case KERNEL_PROBABILITY_F: case KERNEL_PROBABILITY_M: case KERNEL_PROBABILITY: + case CRW_STEPCORRELATION: + { + if (val < 0.0) val = 0; + else if (val > 1.0) val = 1.0; + break; + } + // Positive values + case KERNEL_MEANDIST_1_F: case KERNEL_MEANDIST_1_M: case KERNEL_MEANDIST_1: + case KERNEL_MEANDIST_2_F: case KERNEL_MEANDIST_2_M: case KERNEL_MEANDIST_2: + case CRW_STEPLENGTH: + { + if (val < 0.0) val = 0; + break; + } + // Strictly positive values + case E_ALPHA_F: case E_ALPHA_M: case E_ALPHA: + case S_ALPHA_F: case S_ALPHA_M: case S_ALPHA: + case SMS_ALPHADB: + { + if (val <= 0.0) val = minPositiveVal; + break; + } + // Minimum 1 + case SMS_DP: + case SMS_GB: + { + if (val <= 1.0) val = 1.0; + break; + } + // Not bound + case E_BETA_F: case E_BETA_M: case E_BETA: + case S_BETA_F: case S_BETA_M: case S_BETA: + case SMS_BETADB: + { + break; + } + default: + break; + } +} + +// ---------------------------------------------------------------------------------------- +// Get allele value at locus +// ---------------------------------------------------------------------------------------- +float DispersalTrait::getAlleleValueAtLocus(short whichChromosome, int position) const { + + auto it = genes.find(position); + if (it == genes.end()) + throw runtime_error("The Dispersal locus queried for its allele value does not exist."); + return it->second[whichChromosome].get()->getAlleleValue(); +} + +float DispersalTrait::getDomCoefAtLocus(short whichChromosome, int position) const { + auto it = genes.find(position); + if (it == genes.end()) + throw runtime_error("The genetic load locus queried for its dominance coefficient does not exist."); + return it->second[whichChromosome]->getDominanceCoef(); +} + +#ifdef UNIT_TESTS + +// Create a default set of alleles for testing +// +// Shorthand function to manually set genotypes for dispersal and +// genetic fitness traits, instead of having to manipulate mutations. +map>> createTestGenotype( + const int genomeSz, const bool isDiploid, + const float valAlleleA, + const float valAlleleB, + const float domCoeffA, + const float domCoeffB +) { + vector> gene(isDiploid ? 2 : 1); + if (isDiploid) { + gene[0] = make_shared(valAlleleA, domCoeffA); + gene[1] = make_shared(valAlleleB, domCoeffB); + } + else { + gene[0] = make_shared(valAlleleA, domCoeffA); + } + map>> genotype; + for (int i = 0; i < genomeSz; i++) { + genotype.emplace(i, gene); + } + return genotype; +} +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/DispersalTrait.h b/RangeShiftR/src/RScore/DispersalTrait.h new file mode 100644 index 0000000..fc5a4cc --- /dev/null +++ b/RangeShiftR/src/RScore/DispersalTrait.h @@ -0,0 +1,129 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#ifndef DISPTRAITH +#define DISPTRAITH + +#include +#include +#include +#include + +#include "QuantitativeTrait.h" + +using namespace std; + +// Dispersal trait +// +// That is, all evolvable that control emigration, transfer and settlement +class DispersalTrait : public QuantitativeTrait { + +public: + + // Initialisation constructor, set initial values and immutable features + DispersalTrait(SpeciesTrait* P); + + // Inheritance constructor, copies pointers to immutable features when cloning from parent + DispersalTrait(const DispersalTrait& T); + + // Make a shallow copy to pass to offspring trait + // Return new pointer to new trait created by inheritance c'tor + // This avoids copying shared attributes: distributions and parameters + virtual unique_ptr clone() const override { return std::make_unique(*this); } + + virtual ~DispersalTrait() { } + + // Getters + int getNLoci() const override { return pSpeciesTrait->getPositionsSize(); } + float getMutationRate() const override { return pSpeciesTrait->getMutationRate(); } + bool isInherited() const override { return pSpeciesTrait->isInherited(); } + + map>>& getGenes() { return genes; } // returning reference, receiver must be const + + void mutate() override { (this->*_mutate_func_ptr) (); } + float express() override { return (this->*_express_func_ptr) (); } + void inheritGenes(const bool& fromMother, QuantitativeTrait* parent, set const& recomPositions, int startingChromosome) override; + + float getAlleleValueAtLocus(short chromosome, int i) const override; + float getDomCoefAtLocus(short chromosome, int position) const override; + +#ifdef UNIT_TESTS // for testing only + void overwriteGenes(map>> genSeq) { + genes = genSeq; + } + void triggerInherit( + // inheritGenes requires passing a QuantitativeTrait, unfeasible in tests + const bool& fromMother, + map>> const& parentGenes, + set const& recomPositions, + int startChr) { + (this->*_inherit_func_ptr)(fromMother, parentGenes, recomPositions, startChr); + } +#endif + +private: + + const double dispDominanceFactor = 1.0; // no dominance for Dispersal traits (yet?) + + // > + map>> genes; + + // Initialisation + void initialiseUniform(float min, float max); + void initialiseNormal(float mean, float sd); + + // Immutable features, set at initialisation + // and passed down to every subsequent trait copy + //// Species-level trait attributes, invariant across individuals + SpeciesTrait* pSpeciesTrait; + //// Species-level trait functions + void (DispersalTrait::* _mutate_func_ptr) (void); + void (DispersalTrait::* _inherit_func_ptr) (const bool& fromMother, map>> const& parent, set const& recomPositions, int parentChromosome); + float (DispersalTrait::* _express_func_ptr) (void); + + // Possible values for immutable functions + //// Inheritance + void inheritDiploid(const bool& fromMother, map>> const& parent, set const& recomPositions, int parentChromosome); + void inheritHaploid(const bool& fromMother, map>> const& parent, set const& recomPositions, int parentChromosome); + void reInitialiseGenes(const bool& fromMother, map>> const& parentMutations, set const& recomPositions, int parentChromosome); + //// Mutation + void mutateUniform(); + void mutateNormal(); + void trimPhenotype(float& phenotype); + //// Gene expression + float expressAverage(); + float expressAdditive(); +}; + +#ifdef UNIT_TESTS +// Test utilities + +map>> createTestGenotype( + const int genomeSz, const bool isDiploid, + const float valAlleleA, + const float valAlleleB = -99.9, // allow no value for haploids + const float domCoeffA = 1.0, // default for dispersal traits + const float domCoeffB = 1.0 +); +#endif // UNIT_TESTS + +#endif // DISPTRAITH diff --git a/RangeShiftR/src/RScore/FractalGenerator.cpp b/RangeShiftR/src/RScore/FractalGenerator.cpp new file mode 100644 index 0000000..8650ef4 --- /dev/null +++ b/RangeShiftR/src/RScore/FractalGenerator.cpp @@ -0,0 +1,227 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + --------------------------------------------------------------------------*/ + + + + //--------------------------------------------------------------------------- + +#include "FractalGenerator.h" +//--------------------------------------------------------------------------- + +vector patches; + +//----- Landscape creation -------------------------------------------------- + +land::land() : x_coord(0), y_coord(0), value(0.0), avail(0) {} + +bool compare(const land& z, const land& zz) //compares only the values of the cells +{ + return z.value < zz.value; +} + +vector& fractal_landscape(int X, int Y, double Hurst, double prop, + double maxValue, double minValue) +{ + + int ii, jj, x, y; + int ix, iy; + //int x0, y0, size, kx, kx2, ky, ky2; + int kx, kx2, ky, ky2; + + double range; //range to draw random numbers at each iteration + double nx, ny; + double i, j; + int Nx = X; + int Ny = Y; + + double ran[5]; // to store each time the 5 random numbers for the random displacement + + int Nno; // number of cells NON suitable as habitat + + // exponents used to obtain the landscape dimensions + double pow2x = log(((double)X - 1.0)) / log(2.0); + double pow2y = log(((double)Y - 1.0)) / log(2.0); + + double** arena = new double* [X]; + for (ii = 0; ii < X; ii++) { + arena[ii] = new double[Y]; + } + + patches.clear(); + // initialise all the landscape with zeroes + for (jj = 0; jj < X; jj++) { + for (ii = 0; ii < Y; ii++) { + arena[jj][ii] = 0; + } + } + + // initialisation of the four corners + arena[0][0] = 1.0 + pRandom->Random() * (maxValue - 1.0); + arena[0][Y - 1] = 1.0 + pRandom->Random() * (maxValue - 1.0); + arena[X - 1][0] = 1.0 + pRandom->Random() * (maxValue - 1.0); + arena[X - 1][Y - 1] = 1.0 + pRandom->Random() * (maxValue - 1.0); + + /////////////MIDPOINT DISPLACEMENT ALGORITHM////////////////////////////////// + kx = (Nx - 1) / 2; + kx2 = 2 * kx; + ky = (Ny - 1) / 2; + ky2 = 2 * ky; + + for (ii = 0; ii < 5; ii++) //random displacement + { + ran[ii] = 1.0 + pRandom->Random() * (maxValue - 1.0); + } + + //The diamond step: + arena[kx][ky] = ((arena[0][0] + arena[0][ky2] + arena[kx2][0] + arena[kx2][ky2]) / 4) + ran[0]; + + //The square step: + //left + arena[0][ky] = ((arena[0][0] + arena[0][ky2] + arena[kx][ky]) / 3) + ran[1]; + //top + arena[kx][0] = ((arena[0][0] + arena[kx][ky] + arena[kx2][0]) / 3) + ran[2]; + //right + arena[kx2][ky] = ((arena[kx2][0] + arena[kx][ky] + arena[kx2][ky2]) / 3) + ran[3]; + //bottom + arena[kx][ky2] = ((arena[0][ky2] + arena[kx][ky] + arena[kx2][ky2]) / 3) + ran[4]; + + range = maxValue * pow(2, -Hurst); + + i = pow2x - 1; + j = pow2y - 1; + + while (i > 0) { + nx = pow(2, i) + 1; + kx = (int)((nx - 1) / 2); + kx2 = 2 * kx; + + ny = pow(2, j) + 1; + ky = (int)((ny - 1) / 2); + ky2 = 2 * ky; + + ix = 0; + while (ix <= (Nx - nx)) { + iy = 0; + while (iy <= (Ny - ny)) { + for (ii = 0; ii < 5; ii++) //random displacement + { + ran[ii] = (int)(pRandom->Random() * 2.0 * range - range); + } + //The diamond step: + + arena[ix + kx][iy + ky] = ((arena[ix][iy] + arena[ix][iy + ky2] + arena[ix + ky2][iy] + + arena[ix + kx2][iy + ky2]) / 4) + ran[0]; + if (arena[ix + kx][iy + ky] < 1) arena[ix + kx][iy + ky] = 1; + + //The square step: + //left + arena[ix][iy + ky] = ((arena[ix][iy] + arena[ix][iy + ky2] + arena[ix + kx][iy + ky]) / 3) + + ran[1]; + if (arena[ix][iy + ky] < 1) arena[ix][iy + ky] = 1; + //top + arena[ix + kx][iy] = ((arena[ix][iy] + arena[ix + kx][iy + ky] + arena[ix + kx2][iy]) / 3) + + ran[2]; + if (arena[ix + kx][iy] < 1) arena[ix + kx][iy] = 1; + //right + arena[ix + kx2][iy + ky] = ((arena[ix + kx2][iy] + arena[ix + kx][iy + ky] + + arena[ix + kx2][iy + ky2]) / 3) + ran[3]; + if (arena[ix + kx2][iy + ky] < 1) arena[ix + kx2][iy + ky] = 1; + //bottom + arena[ix + kx][iy + ky2] = ((arena[ix][iy + ky2] + arena[ix + kx][iy + ky] + + arena[ix + kx2][iy + ky2]) / 3) + ran[4]; + if (arena[ix + kx][iy + ky2] < 1) arena[ix + kx][iy + ky2] = 1; + + iy += ((int)ny - 1); + } + ix += ((int)nx - 1); + } + if (i == j) j--; + i--; + + range = range * pow(2, -Hurst); //reduce the random number range + } + + // Now all the cells will be sorted and the Nno cells with the lower carrying + // capacity will be set as matrix, i.e. with K = 0 + + land* patch; + + for (x = 0; x < X; x++) // put all the cells with their values in a vector + { + for (y = 0; y < Y; y++) + { + patch = new land; + patch->x_coord = x; + patch->y_coord = y; + patch->value = (float)arena[x][y]; + patch->avail = 1; + + patches.push_back(*patch); + + delete patch; + } + } + + + sort(patches.begin(), patches.end(), compare); // sorts the vector + + Nno = (int)(prop * X * Y); + for (ii = 0; ii < Nno; ii++) + { + patches[ii].value = 0.0; + patches[ii].avail = 0; + } + + double min = (double)patches[Nno].value; // variables for the rescaling + double max = (double)patches[X * Y - 1].value; + + double diff = max - min; + double diffK = maxValue - minValue; + double new_value; + + vector::iterator iter = patches.begin(); + while (iter != patches.end()) + { + if (iter->value > 0) // rescale to a range of K between Kmin and Kmax + { + new_value = maxValue - diffK * (max - (double)iter->value) / diff; + + iter->value = (float)new_value; + } + else iter->value = 0; + + iter++; + } + + if (arena != NULL) { + for (ii = 0; ii < X; ii++) { + delete[] arena[ii]; + } + delete[] arena; + } + + return patches; + +} + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + diff --git a/FractalGenerator.h b/RangeShiftR/src/RScore/FractalGenerator.h similarity index 58% rename from FractalGenerator.h rename to RangeShiftR/src/RScore/FractalGenerator.h index 24acbc7..3a2e216 100644 --- a/FractalGenerator.h +++ b/RangeShiftR/src/RScore/FractalGenerator.h @@ -1,66 +1,66 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Tho Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * --------------------------------------------------------------------------*/ - - -/*------------------------------------------------------------------------------ -RangeShifter v2.0 FractalGenerator -Implements the midpoint displacement algorithm for generating a fractal Landscape, -following: -Saupe, D. (1988). Algorithms for random fractals. In: The Science of Fractal Images -(eds. Pietgen, H.O. & Saupe, D.). Springer, New York, pp. 71113. + /*------------------------------------------------------------------------------ + RangeShifter v2.0 FractalGenerator -For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. -and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. -Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + Implements the midpoint displacement algorithm for generating a fractal Landscape, + following: -Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + Saupe, D. (1988). Algorithms for random fractals. In: The Science of Fractal Images + (eds. Pietgen, H.O. & Saupe, D.). Springer, New York, pp. 71113. -Last updated: 15 July 2021 by Anne-Kathleen Malchow -------------------------------------------------------------------------------*/ + For full details of RangeShifter, please see: + Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial + eco-evolutionary dynamics and species responses to environmental changes. + Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + + Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + + Last updated: 15 July 2021 by Anne-Kathleen Malchow + + ------------------------------------------------------------------------------*/ #ifndef FractalGeneratorH #define FractalGeneratorH #include #include -//using namespace std; + //using namespace std; #include "Parameters.h" class land { - public: +public: land(); int x_coord; int y_coord; float value; int avail; // if 0 the patch is not available as habitat, if 1 it is - private: +private: }; // IMPORTANT NOTE: X AND Y ARE TRANSPOSED, i.e. X IS THE VERTICAL CO-ORDINATE @@ -76,10 +76,7 @@ vector& fractal_landscape( ); bool compare(const land&, const land&); -extern RSrandom *pRandom; -#if RSDEBUG -extern void DebugGUI(string); -#endif +extern RSrandom* pRandom; //--------------------------------------------------------------------------- #endif diff --git a/RangeShiftR/src/RScore/GeneticFitnessTrait.cpp b/RangeShiftR/src/RScore/GeneticFitnessTrait.cpp new file mode 100644 index 0000000..fa1bb55 --- /dev/null +++ b/RangeShiftR/src/RScore/GeneticFitnessTrait.cpp @@ -0,0 +1,558 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#include "GeneticFitnessTrait.h" + +// ---------------------------------------------------------------------------------------- +// Initialisation constructor +// Called when initialising community +// Sets up initial values, and immutable attributes (distributions and parameters) +// that are defined at the species-level +// ---------------------------------------------------------------------------------------- +GeneticFitnessTrait::GeneticFitnessTrait(SpeciesTrait* P) +{ + pSpeciesTrait = P; + ExpressionType expressionType = pSpeciesTrait->getExpressionType(); + + _inherit_func_ptr = (pSpeciesTrait->getPloidy() == 1) ? &GeneticFitnessTrait::inheritHaploid : &GeneticFitnessTrait::inheritDiploid; //this could be changed if we wanted some alternative form of inheritance + + // Set initialisation parameters + DistributionType initialDistribution = pSpeciesTrait->getInitialDistribution(); + map initialParameters = pSpeciesTrait->getInitialParameters(); + switch (initialDistribution) { + case UNIFORM: + { + if (initialParameters.count(MAX) != 1) + throw logic_error("initial uniform distribution parameter must contain max value (e.g. max= ) \n"); + if (initialParameters.count(MIN) != 1) + throw logic_error("initial uniform distribution parameter must contain min value (e.g. min= ) \n"); + break; + } + case NORMAL: + { + if (initialParameters.count(MEAN) != 1) + throw logic_error("initial normal distribution parameter must contain mean value (e.g. mean= ) \n"); + if (initialParameters.count(SD) != 1) + throw logic_error("initial normal distribution parameter must contain sdev value (e.g. sdev= ) \n"); + break; + } + case GAMMA: + { + if (initialParameters.count(SHAPE) != 1) + throw logic_error("genetic load dominance distribution set to gamma so parameters must contain one shape value (e.g. shape= ) \n"); + if (initialParameters.count(SCALE) != 1) + throw logic_error("genetic load dominance distribution set to gamma so parameters must contain one scale value (e.g. scale= ) \n"); + break; + } + case NEGEXP: + { + if (initialParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to negative exponential (negative decay) so parameters must contain mean value (e.g. mean= ) \n"); + break; + } + case NONE: // initialise with default (i.e. zero) values + break; + default: + { + throw logic_error("wrong parameter value for parameter \"initialisation of dispersal traits\", must be uniform/normal \n"); + break; + } + } + + DistributionType initDomDistribution = pSpeciesTrait->getInitDomDistribution(); + map initDomParameters = pSpeciesTrait->getInitDomParameters(); + switch (initDomDistribution) { + case UNIFORM: + { + if (initDomParameters.count(MAX) != 1) + throw logic_error("genetic load dominance uniform distribution parameter must contain one max value (e.g. max= ) \n"); + if (initDomParameters.count(MIN) != 1) + throw logic_error("genetic load dominance uniform distribution parameter must contain one min value (e.g. min= ) \n"); + break; + } + case NORMAL: + { + if (initDomParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to normal so parameters must contain one mean value (e.g. mean= ) \n"); + if (initDomParameters.count(SD) != 1) + throw logic_error("genetic load dominance distribution set to normal so parameters must contain one sdev value (e.g. sdev= ) \n"); + break; + } + case GAMMA: + { + if (initDomParameters.count(SHAPE) != 1) + throw logic_error("genetic load dominance distribution set to gamma so parameters must contain one shape value (e.g. shape= ) \n"); + if (initDomParameters.count(SCALE) != 1) + throw logic_error("genetic load dominance distribution set to gamma so parameters must contain one scale value (e.g. scale= ) \n"); + break; + } + case NEGEXP: + { + if (initDomParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to negative exponential (negative decay) so parameters must contain mean value (e.g. mean= ) \n"); + break; + } + case SCALED: + { + if (initDomParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to scaled, so parameters must contain mean dominance value (e.g. mean= ) \n"); + // Set for drawing initial values + setScaledCoeff(initialDistribution, initialParameters); + break; + } + case NONE: // default values, zero-dominance coefficients + break; + default: + { + throw logic_error("wrong parameter value for genetic load dominance model, must be uniform/normal/gamma/negExp/scaled \n"); + break; + } + } + + // Draw initial values + initialise(); + + DistributionType mutationDistribution = pSpeciesTrait->getMutationDistribution(); + map mutationParameters = pSpeciesTrait->getMutationParameters(); + switch (mutationDistribution) { + case UNIFORM: + { + if (mutationParameters.count(MAX) != 1) + throw logic_error("genetic load mutation uniform distribution parameter must contain one max value (e.g. max= ) \n"); + if (mutationParameters.count(MIN) != 1) + throw logic_error("genetic load mutation uniform distribution parameter must contain one min value (e.g. min= ) \n"); + break; + } + case NORMAL: + { + if (mutationParameters.count(MEAN) != 1) + throw logic_error("genetic load mutation distribution set to normal so parameters must contain one mean value (e.g. mean= ) \n"); + if (mutationParameters.count(SD) != 1) + throw logic_error("genetic load mutation distribution set to normal so parameters must contain one sdev value (e.g. sdev= ) \n"); + break; + } + case GAMMA: + { + if (mutationParameters.count(SHAPE) != 1) + throw logic_error("genetic load mutation distribution set to gamma so parameters must contain one shape value (e.g. shape= ) \n"); + if (mutationParameters.count(SCALE) != 1) + throw logic_error("genetic load mutation distribution set to gamma so parameters must contain one scale value (e.g. scale= ) \n"); + break; + } + case NEGEXP: + { + if (mutationParameters.count(MEAN) != 1) + throw logic_error("genetic load mutation distribution set to negative exponential (negative decay) so parameters must contain one mean value (e.g. mean= ) \n"); + break; + } + default: + throw logic_error("wrong parameter value for genetic load mutation model, must be uniform/normal/gamma/negExp \n"); + } + + DistributionType dominanceDistribution = pSpeciesTrait->getDominanceDistribution(); + map dominanceParameters = pSpeciesTrait->getDominanceParameters(); + + switch (dominanceDistribution) { + case UNIFORM: + { + if (dominanceParameters.count(MAX) != 1) + throw logic_error("genetic load dominance uniform distribution parameter must contain one max value (e.g. max= ) \n"); + if (dominanceParameters.count(MIN) != 1) + throw logic_error("genetic load dominance uniform distribution parameter must contain one min value (e.g. min= ) \n"); + break; + } + case NORMAL: + { + if (dominanceParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to normal so parameters must contain one mean value (e.g. mean= ) \n"); + if (dominanceParameters.count(SD) != 1) + throw logic_error("genetic load dominance distribution set to normal so parameters must contain one sdev value (e.g. sdev= ) \n"); + break; + } + case GAMMA: + { + if (dominanceParameters.count(SHAPE) != 1) + throw logic_error("genetic load dominance distribution set to gamma so parameters must contain one shape value (e.g. shape= ) \n"); + if (dominanceParameters.count(SCALE) != 1) + throw logic_error("genetic load dominance distribution set to gamma so parameters must contain one scale value (e.g. scale= ) \n"); + break; + } + case NEGEXP: + { + if (dominanceParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to negative exponential (negative decay) so parameters must contain mean value (e.g. mean= ) \n"); + break; + } + case SCALED: + { + if (dominanceParameters.count(MEAN) != 1) + throw logic_error("genetic load dominance distribution set to scaled, so parameters must contain mean dominance value (e.g. mean= ) \n"); + + // Set for drawing mutations (overwrite initial value) + setScaledCoeff(mutationDistribution, mutationParameters); + break; + } + default: + { + throw logic_error("wrong parameter value for genetic load dominance model, must be uniform/normal/gamma/negExp/scaled \n"); + break; + } + } +} + +// Calculate mean selection coeff s_d for calculation of k +void GeneticFitnessTrait::setScaledCoeff(const DistributionType& selCoeffDist, const map& selCoeffParams) +{ + switch (selCoeffDist) + { + case UNIFORM: + scaledDomMeanSelCoeff = (selCoeffParams.find(MIN)->second + selCoeffParams.find(MAX)->second) / 2; + break; + case NORMAL: + scaledDomMeanSelCoeff = selCoeffParams.find(MEAN)->second; + break; + case GAMMA: + scaledDomMeanSelCoeff = selCoeffParams.find(SHAPE)->second * selCoeffParams.find(SCALE)->second; + break; + case NEGEXP: + scaledDomMeanSelCoeff = 1 / selCoeffParams.find(MEAN)->second; + break; + case NONE: + throw logic_error("Scaled dominance distribution cannot be used with default allele distribution."); + default: break; + } +} + +// ---------------------------------------------------------------------------------------- +// Inheritance constructor +// Copies immutable features from a parent trait +// Only called via clone() +// ---------------------------------------------------------------------------------------- +GeneticFitnessTrait::GeneticFitnessTrait(const GeneticFitnessTrait& T) : + pSpeciesTrait(T.pSpeciesTrait), + _inherit_func_ptr(T._inherit_func_ptr), + scaledDomMeanSelCoeff(T.scaledDomMeanSelCoeff) +{ + // nothing +} + +void GeneticFitnessTrait::initialise() { + float initSelCoeff; + float initDomCoeff; + short ploidy = pSpeciesTrait->getPloidy(); + auto initDist = pSpeciesTrait->getInitialDistribution(); + auto initParams = pSpeciesTrait->getInitialParameters(); + auto initDomDist = pSpeciesTrait->getInitDomDistribution(); + auto initDomParams = pSpeciesTrait->getInitDomParameters(); + + const set genePositions = pSpeciesTrait->getGenePositions(); + const set initPositions = pSpeciesTrait->getInitPositions(); + + for (auto position : genePositions) { + vector> initialGene(ploidy); + for (int p = 0; p < ploidy; p++) { + initSelCoeff = initDomCoeff = 0.0; + if (initPositions.contains(position)) { + initSelCoeff = drawSelectionCoef(initDist, initParams); + initDomCoeff = drawDominance(initSelCoeff, initDomDist, initDomParams); + } + initialGene[p] = make_shared(initSelCoeff, initDomCoeff); + } + genes.insert(make_pair(position, initialGene)); + } +} + +// ---------------------------------------------------------------------------------------- +// Mutate uniform +// ---------------------------------------------------------------------------------------- +void GeneticFitnessTrait::mutate() +{ + const int positionsSize = pSpeciesTrait->getPositionsSize(); + const auto& genePositions = pSpeciesTrait->getGenePositions(); + const short ploidy = pSpeciesTrait->getPloidy(); + const float mutationRate = pSpeciesTrait->getMutationRate(); + float newSelectionCoef; + float newDominanceCoef; + + auto rng = pRandom->getRNG(); + + for (int p = 0; p < ploidy; p++) { + // Determine nb of mutations + unsigned int NbMut = pRandom->Binomial(positionsSize, mutationRate); + + if (NbMut > 0) { + vector mutationPositions; + // Draw which positions mutate + sample(genePositions.begin(), genePositions.end(), std::back_inserter(mutationPositions), + NbMut, rng); + + for (int m : mutationPositions) { + auto it = genes.find(m); + if (it == genes.end()) + throw runtime_error("Locus sampled for mutation doesn't exist."); + newSelectionCoef = drawSelectionCoef( + pSpeciesTrait->getMutationDistribution(), + pSpeciesTrait->getMutationParameters() + ); + newDominanceCoef = drawDominance( + newSelectionCoef, + pSpeciesTrait->getDominanceDistribution(), + pSpeciesTrait->getDominanceParameters() + ); + it->second[p] = make_shared(newSelectionCoef, newDominanceCoef); + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// get dominance value for new mutation +// ---------------------------------------------------------------------------------------- +float GeneticFitnessTrait::drawDominance(float selCoef, const DistributionType& domDist, const map& domParams) { + + float h = 0.0; + switch (domDist) { + case UNIFORM: + { + float maxD = domParams.find(MAX)->second; + float minD = domParams.find(MIN)->second; + h = pRandom->FRandom(minD, maxD); + break; + } + case NORMAL: + { + const float mean = domParams.find(MEAN)->second; + const float sd = domParams.find(SD)->second; + do { + h = static_cast(pRandom->Normal(mean, sd)); + } while (h <= 0.0); + break; + } + case GAMMA: + { + const float shape = domParams.find(SHAPE)->second; + const float scale = domParams.find(SCALE)->second; + h = static_cast(pRandom->Gamma(shape, scale)); + break; + } + case NEGEXP: + { + const float mean = domParams.find(MEAN)->second; + h = static_cast(pRandom->NegExp(mean)); + break; + } + case SCALED: + { + const float h_d = domParams.find(MEAN)->second; + const float k = -log(2 * h_d) / scaledDomMeanSelCoeff; + const float max = exp(-k * selCoef); + h = pRandom->FRandom(0, max); + break; + } + case NONE: + { + // nothing, s remains 0.0 + break; + } + default: + { + throw logic_error("wrong parameter value for genetic load dominance model, must be uniform/normal/gamma/negExp/scaled/none \n"); + break; + } + } + return h; +} + +// ---------------------------------------------------------------------------------------- +// Get selection coefficient for new mutation +// +// Selection coefficients will usually be between 0 and 1, but may, +// if the mutation distribution enable it, take a negative value +// down to -1 representing the effect of beneficial mutations +// ---------------------------------------------------------------------------------------- +float GeneticFitnessTrait::drawSelectionCoef(const DistributionType& mutationDistribution, const map& mutationParameters) { + + float s = 0.0; // default selection coefficient is 0 + + switch (mutationDistribution) { + case UNIFORM: + { + float maxD = mutationParameters.find(MAX)->second; + float minD = mutationParameters.find(MIN)->second; + s = pRandom->FRandom(minD, maxD); // no check here, min and max should already be constrained to valid values + break; + } + case NORMAL: + { + const float mean = mutationParameters.find(MEAN)->second; + const float sd = mutationParameters.find(SD)->second; + do { + s = static_cast(pRandom->Normal(mean, sd)); + } while (!pSpeciesTrait->isValidTraitVal(s)); + break; + } + case GAMMA: + { + const float shape = mutationParameters.find(SHAPE)->second; + const float scale = mutationParameters.find(SCALE)->second; + do { + s = static_cast(pRandom->Gamma(shape, scale)); + } while (!pSpeciesTrait->isValidTraitVal(s)); + break; + } + case NEGEXP: + { + const float mean = mutationParameters.find(MEAN)->second; + do { + s = static_cast(pRandom->NegExp(mean)); + } while (!pSpeciesTrait->isValidTraitVal(s)); + break; + } + case NONE: + { + // nothing, s remains 0.0 + break; + } + default: + { + throw logic_error("wrong parameter value for genetic load mutation model, must be uniform/normal/gamma/negExp/scaled/none \n"); + break; + } + } + return s; +} + + +// ---------------------------------------------------------------------------------------- +// Wrapper to inheritance function +// ---------------------------------------------------------------------------------------- +void GeneticFitnessTrait::inheritGenes(const bool& fromMother, QuantitativeTrait* parentTrait, set const& recomPositions, int startingChromosome) +{ + auto parentCast = dynamic_cast (parentTrait); // must convert QuantitativeTrait to GeneticFitnessTrait + const auto& parent_seq = parentCast->getGenes(); + (this->*_inherit_func_ptr) (fromMother, parent_seq, recomPositions, startingChromosome); +} + +// ---------------------------------------------------------------------------------------- +// Inheritance for diploid, sexual species +// Called once for each parent. Given a list of recombinant sites, +// populates offspring genes with appropriate parent alleles +// Assumes mother genes are inherited first +// ---------------------------------------------------------------------------------------- +void GeneticFitnessTrait::inheritDiploid(const bool& fromMother, map>> const& parentGenes, set const& recomPositions, int parentChromosome) { + + const int lastPosition = parentGenes.rbegin()->first; + auto recomIt = recomPositions.lower_bound(parentGenes.begin()->first); + // If no recombination sites, only breakpoint is last position + // i.e., no recombination occurs + int nextBreakpoint = recomIt == recomPositions.end() ? lastPosition : *recomIt; + + // Is the first parent gene position already recombinant? + auto distance = std::distance(recomPositions.begin(), recomIt); + if (distance % 2 != 0) + parentChromosome = 1 - parentChromosome; // switch chromosome + + for (auto const& [locus, allelePair] : parentGenes) { + + // Switch chromosome if locus is past recombination site + while (locus > nextBreakpoint) { + parentChromosome = 1 - parentChromosome; + std::advance(recomIt, 1); // go to next recombination site + nextBreakpoint = recomIt == recomPositions.end() ? lastPosition : *recomIt; + } + + if (locus <= nextBreakpoint) { + auto& parentAllele = allelePair[parentChromosome]; + auto itGene = genes.find(locus); + if (itGene == genes.end()) { + // locus does not exist yet, create and initialise it + if (!fromMother) throw runtime_error("Father-inherited locus does not exist."); + vector> newAllelePair(2); // always diploid + newAllelePair[sex_t::FEM] = parentAllele; + genes.insert(make_pair(locus, newAllelePair)); + } + else { // father, locus already exists + if (fromMother) throw runtime_error("Mother-inherited locus already exists."); + itGene->second[sex_t::MAL] = parentAllele; + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// Inheritance for haploid, asexual species +// Simply pass down parent genes +// Arguments are still needed to match overloaded function in base class +// ---------------------------------------------------------------------------------------- +void GeneticFitnessTrait::inheritHaploid(const bool& fromMother, map>> const& parentGenes, set const& recomPositions, int parentChromosome) +{ + genes = parentGenes; +} + +// ---------------------------------------------------------------------------------------- +// Expression genetic load +// ---------------------------------------------------------------------------------------- +float GeneticFitnessTrait::express() { + + float phenotype = 1.0; // base chance of viability + float sA, sB, hA, hB, sumDomCoeffs, hLocus; + + for (auto const& [locus, pAllelePair] : genes) + { + shared_ptr pAlleleA = pAllelePair[0] == 0 ? wildType : pAllelePair[0]; + + sA = pAlleleA->getAlleleValue(); + hA = pAlleleA->getDominanceCoef(); + + if (pSpeciesTrait->getPloidy() == 2) { + shared_ptr pAlleleB = pAllelePair[1] == 0 ? wildType : pAllelePair[1]; + sB = pAlleleB->getAlleleValue(); + hB = pAlleleB->getDominanceCoef(); + + sumDomCoeffs = hA + hB; + hLocus = sumDomCoeffs == 0.0 ? 0.5 : hA / sumDomCoeffs; + phenotype *= 1 - hLocus * sA - (1 - hLocus) * sB; + } + else { + phenotype *= 1 - sA; + } + } + return phenotype; +} + +// ---------------------------------------------------------------------------------------- +// Get allele value at locus +// ---------------------------------------------------------------------------------------- +float GeneticFitnessTrait::getAlleleValueAtLocus(short whichChromosome, int position) const { + + auto it = genes.find(position); + if (it == genes.end()) + throw runtime_error("The genetic load locus queried for its allele value does not exist."); + return it->second[whichChromosome] == 0 ? wildType->getAlleleValue() : it->second[whichChromosome]->getAlleleValue(); +} + +float GeneticFitnessTrait::getDomCoefAtLocus(short whichChromosome, int position) const { + auto it = genes.find(position); + if (it == genes.end()) + throw runtime_error("The genetic load locus queried for its dominance coefficient does not exist."); + return it->second[whichChromosome] == 0 ? wildType->getDominanceCoef() : it->second[whichChromosome]->getDominanceCoef(); +} diff --git a/RangeShiftR/src/RScore/GeneticFitnessTrait.h b/RangeShiftR/src/RScore/GeneticFitnessTrait.h new file mode 100644 index 0000000..cb81eff --- /dev/null +++ b/RangeShiftR/src/RScore/GeneticFitnessTrait.h @@ -0,0 +1,111 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#ifndef GENETICFITNESSH +#define GENETICFITNESSH + +#include +#include +#include +#include +#include + +#include "QuantitativeTrait.h" + +using namespace std; + +// Genetic Load trait +// +// Alleles contribute to their value to reducing +// offspring viability. Alleles start with value +// zero but increase through simulation via mutations. +// There can be up to five genetic load traits. +class GeneticFitnessTrait : public QuantitativeTrait { + +public: + + // Initialisation constructor, set initial values and immutable features + GeneticFitnessTrait(SpeciesTrait* P); + + // Inheritance constructor, copies pointers to immutable features when cloning from parent + GeneticFitnessTrait(const GeneticFitnessTrait& T); + + // Make a shallow copy to pass to offspring trait + // Return new pointer to new trait created by inheritance c'tor + // This avoids copying shared attributes: distributions and parameters + virtual unique_ptr clone() const override { return std::make_unique(*this); } + + virtual ~GeneticFitnessTrait() { } + + // Getters + virtual int getNLoci() const override { return pSpeciesTrait->getPositionsSize(); } + float getMutationRate() const override { return pSpeciesTrait->getMutationRate(); } + bool isInherited() const override { return pSpeciesTrait->isInherited(); } + + map>>& getGenes() { return genes; } // returning reference, reciever must be const + + virtual void mutate() override; + virtual float express(); + virtual void inheritGenes(const bool& fromMother, QuantitativeTrait* parent, set const& recomPositions, int startingChromosome) override; + + virtual float getAlleleValueAtLocus(short chromosome, int position) const override; + virtual float getDomCoefAtLocus(short chromosome, int position) const override; + +private: + + // Default allele has value 0 and dominance 0 + inline static shared_ptr wildType = make_shared(0.0, 0.0); + + // > + map>> genes; // position > + + // Initialisation + void initialise(); + + void setScaledCoeff(const DistributionType& selCoeffDist, const map& selCoeffParams); + + // Mutation + float scaledDomMeanSelCoeff = 0; // s_d, only for scaled dominance distribution + float drawDominance( + float selCoef, + const DistributionType& domDist, + const map& domParams + ); + float drawSelectionCoef( + const DistributionType& mutationDistribution, + const map& mutationParameters + ); + + // Immutable features, set at initialisation + // and passed down to every subsequent trait copy + //// Species-level trait attributes, invariant across individuals + SpeciesTrait* pSpeciesTrait; + //// Species-level trait functions + void (GeneticFitnessTrait::* _inherit_func_ptr) (const bool& fromMother, map>> const& parent, set const& recomPositions, int parentChromosome); + + // Possible values for immutable functions + //// Inheritance + void inheritDiploid(const bool& fromMother, map>> const& parent, set const& recomPositions, int parentChromosome); + void inheritHaploid(const bool& fromMother, map>> const& parent, set const& recomPositions, int parentChromosome); + +}; +#endif // GENETICFITNESSH diff --git a/Individual.cpp b/RangeShiftR/src/RScore/Individual.cpp similarity index 55% rename from Individual.cpp rename to RangeShiftR/src/RScore/Individual.cpp index 73f6f6f..b24d249 100644 --- a/Individual.cpp +++ b/RangeShiftR/src/RScore/Individual.cpp @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -16,29 +16,105 @@ * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * --------------------------------------------------------------------------*/ + //--------------------------------------------------------------------------- #include "Individual.h" + +#ifdef _OPENMP +#include +#endif + +//--------------------------------------------------------------------------- + +template +MemoryQueue::MemoryQueue(std::size_t size): + space(size), + data(new T[size]), + begin_idx(0), + nb_elts(0) +{ } + +template +T &MemoryQueue::front() { + return data[begin_idx]; +} + +template +T const &MemoryQueue::front() const { + return data[begin_idx]; +} + +template +T &MemoryQueue::back() { + return data[(begin_idx + nb_elts - 1) % space]; +} + +template +T const &MemoryQueue::back() const { + return data[(begin_idx + nb_elts - 1) % space]; +} + +template +void MemoryQueue::push(const T& value) { + size_t end_idx = (begin_idx + nb_elts) % space; + data[end_idx] = value; + nb_elts++; +} + +template +void MemoryQueue::push(T&& value) { + size_t end_idx = (begin_idx + nb_elts) % space; + data[end_idx] = std::move(value); + nb_elts++; +} + +template +void MemoryQueue::pop() { + begin_idx++; + begin_idx %= space; + nb_elts--; +} + +template +std::size_t MemoryQueue::size() const { + return nb_elts; +} + +template +bool MemoryQueue::empty() const { + return nb_elts == 0; +} + +template +bool MemoryQueue::full() const { + return nb_elts == space; +} + //--------------------------------------------------------------------------- +#ifdef _OPENMP +std::atomic Individual::indCounter = 0; +#else // _OPENMP int Individual::indCounter = 0; +#endif // _OPENMP +TraitFactory Individual::traitFactory = TraitFactory(); //--------------------------------------------------------------------------- // Individual constructor -Individual::Individual(Cell* pCell, Patch* pPatch, short stg, short a, short repInt, - float probmale, bool movt, short moveType) +Individual::Individual(Species* pSpecies, Cell* pCell, Patch* pPatch, short stg, short a, short repInt, + float probmale, bool movt, short moveType): + memory(pSpecies->getSpSMSTraits().memSize) { - indId = indCounter; - indCounter++; // unique identifier for each individual - + indId = indCounter; indCounter++; // unique identifier for each individual + geneticFitness = 1.0; stage = stg; - if (probmale <= 0.0) sex = 0; - else sex = pRandom->Bernoulli(probmale); + if (probmale <= 0.0) sex = FEM; + else sex = pRandom->Bernoulli(probmale) ? MAL : FEM; age = a; status = 0; @@ -49,6 +125,7 @@ Individual::Individual(Cell* pCell, Patch* pPatch, short stg, short a, short rep isDeveloping = false; pPrevCell = pCurrCell = pCell; pNatalPatch = pPatch; + pTrfrData = nullptr; //set to null as default if (movt) { locn loc = pCell->getLocn(); path = new pathData; @@ -59,354 +136,257 @@ Individual::Individual(Cell* pCell, Patch* pPatch, short stg, short a, short rep #endif if (moveType == 1) { // SMS // set up location data for SMS - smsData = new smsdata; - smsData->dp = smsData->gb = smsData->alphaDB = 1.0; - smsData->betaDB = 1; - smsData->prev.x = loc.x; - smsData->prev.y = loc.y; // previous location - smsData->goal.x = loc.x; - smsData->goal.y = loc.y; // goal location - initialised for dispersal bias + pTrfrData = make_unique(loc, loc); + } - else smsData = 0; if (moveType == 2) { // CRW // set up continuous co-ordinates etc. for CRW movement - crw = new crwParams; - crw->xc = ((float)pRandom->Random() * 0.999f) + (float)loc.x; - crw->yc = (float)(pRandom->Random() * 0.999f) + (float)loc.y; - crw->prevdrn = (float)(pRandom->Random() * 2.0 * PI); - crw->stepL = crw->rho = 0.0; + float xc = ((float)pRandom->Random() * 0.999f) + (float)loc.x; + float yc = (float)(pRandom->Random() * 0.999f) + (float)loc.y; + float prevdrn = (float)(pRandom->Random() * 2.0 * PI); + pTrfrData = make_unique(prevdrn, xc, yc); } - else crw = 0; } else { - path = 0; crw = 0; smsData = 0; + path = 0; + pTrfrData = make_unique(0.0, 0.0, 0.0); } - emigtraits = 0; - kerntraits = 0; - setttraits = 0; - pGenome = 0; } Individual::~Individual(void) { if (path != 0) delete path; - if (crw != 0) delete crw; - if (smsData != 0) delete smsData; - if (emigtraits != 0) delete emigtraits; - if (kerntraits != 0) delete kerntraits; - if (setttraits != 0) delete setttraits; +} - if (pGenome != 0) delete pGenome; +void Individual::setEmigTraits(const emigTraits& emig) { + pEmigTraits = make_unique(emig); + } +void Individual::setSettleTraits(const settleTraits& settle) { + pSettleTraits = make_unique(settle); } -//--------------------------------------------------------------------------- +QuantitativeTrait* Individual::getTrait(TraitType trait) const { + auto p = this->spTraitTable.find(trait); + if (p == spTraitTable.end()) + throw runtime_error("Trait does not exist in trait table."); + else return p->second.get(); + } +set Individual::getTraitTypes() { + auto kv = std::views::keys(this->spTraitTable); + set< TraitType > keys{ kv.begin(), kv.end() }; + return keys; + } + +//--------------------------------------------------------------------------- +// Inheritance for diploid, sexual species //--------------------------------------------------------------------------- +void Individual::inherit(Species* pSpecies, const Individual* mother, const Individual* father) { -// Set genes for individual variation from species initialisation parameters -void Individual::setGenes(Species* pSpecies, int resol) { - demogrParams dem = pSpecies->getDemogr(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); - settleType sett = pSpecies->getSettle(); - genomeData gen = pSpecies->getGenomeData(); - simParams sim = paramsSim->getSim(); - int ntraits; // first trait for all/female expression, second for male expression + int events = 0; + const set chromosomeEnds = pSpecies->getChromosomeEnds(); + const int genomeSize = pSpecies->getGenomeSize(); - if (gen.trait1Chromosome) { - pGenome = new Genome(pSpecies->getNChromosomes(), pSpecies->getNLoci(0), - pSpecies->isDiploid()); - } - else { - pGenome = new Genome(pSpecies); - } + int maternalStartingChromosome = pRandom->Bernoulli(0.5); + int paternalStartingChromosome = pRandom->Bernoulli(0.5); - int gposn = 0; // current position on genome - int expr = 0; // gene expression type - NOT CURRENTLY USED + set maternalRecomPositions; + set paternalRecomPositions; - if (emig.indVar) { // set emigration genes - int emigposn = gposn; - double d0, alpha, beta; - emigParams eparams; - if (emig.sexDep) { // must be a sexual species - ntraits = 2; - } - else { - if (dem.repType == 0) { // asexual reproduction (haploid) - ntraits = 1; - } - else { // sexual reproduction - ntraits = 1; + // Determine which parental chromosomes are inherited + for (int pos : chromosomeEnds) { + if (pRandom->Bernoulli(0.5)) // switch strand for next chromosome + maternalRecomPositions.insert(pos); + if (pRandom->Bernoulli(0.5)) + paternalRecomPositions.insert(pos); } - } - for (int g = 0; g < ntraits; g++) { // first trait for females/all, second for males - eparams = pSpecies->getEmigParams(0, g); - d0 = pRandom->Normal(0.0, eparams.d0SD) / eparams.d0Scale; - if (emig.densDep) { - alpha = pRandom->Normal(0.0, eparams.alphaSD) / eparams.alphaScale; - beta = pRandom->Normal(0.0, eparams.betaSD) / eparams.betaScale; - } - if (gen.trait1Chromosome) { - pGenome->setGene(gposn++, expr, d0, gen.alleleSD); - if (emig.densDep) { - pGenome->setGene(gposn++, expr, alpha, gen.alleleSD); - pGenome->setGene(gposn++, expr, beta, gen.alleleSD); - } - } - else { - pGenome->setTrait(pSpecies, gposn++, d0, gen.alleleSD); - if (emig.densDep) { - pGenome->setTrait(pSpecies, gposn++, alpha, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, beta, gen.alleleSD); - } - } - } - // record phenotypic traits - if (emig.densDep) { - setEmigTraits(pSpecies, emigposn, 3, emig.sexDep); - } - else { - setEmigTraits(pSpecies, emigposn, 1, emig.sexDep); - } - } - if (trfr.indVar) { // set transfer genes - int trfrposn = gposn; - if (trfr.sexDep) { // must be a sexual species - ntraits = 2; - } - else { - if (dem.repType == 0) { // asexual reproduction - ntraits = 1; - } - else { // sexual reproduction - ntraits = 1; - } + // Draw recombination events for maternal genome + if (pSpecies->getRecombinationRate() > 0.0) + events = pRandom->Binomial(genomeSize, pSpecies->getRecombinationRate()); + // if poisson exceeds genomeSize, bound to genomeSize + int nbrCrossOvers = events + maternalRecomPositions.size(); + if (nbrCrossOvers > genomeSize) { + nbrCrossOvers = genomeSize; } - if (trfr.moveModel) { - if (trfr.moveType == 1) { // set SMS genes - double dp, gb, alphaDB, betaDB; - trfrSMSParams smsparams = pSpecies->getSMSParams(0, 0); // only traits for females/all - trfrSMSTraits smstraits = pSpecies->getSMSTraits(); - dp = pRandom->Normal(0.0, smsparams.dpSD) / smsparams.dpScale; - gb = pRandom->Normal(0.0, smsparams.gbSD) / smsparams.gbScale; - if (smstraits.goalType == 2) { - alphaDB = pRandom->Normal(0.0, smsparams.alphaDBSD) / smsparams.alphaDBScale; - betaDB = pRandom->Normal(0.0, smsparams.betaDBSD) / smsparams.betaDBScale; - } - if (gen.trait1Chromosome) { - pGenome->setGene(gposn++, expr, dp, gen.alleleSD); - pGenome->setGene(gposn++, expr, gb, gen.alleleSD); - if (smstraits.goalType == 2) { - pGenome->setGene(gposn++, expr, alphaDB, gen.alleleSD); - pGenome->setGene(gposn++, expr, betaDB, gen.alleleSD); - } - } - else { - pGenome->setTrait(pSpecies, gposn++, dp, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, gb, gen.alleleSD); - if (smstraits.goalType == 2) { - pGenome->setTrait(pSpecies, gposn++, alphaDB, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, betaDB, gen.alleleSD); - } - } - // record phenotypic traits - if (smstraits.goalType == 2) - setSMSTraits(pSpecies, trfrposn, 4, false); - else - setSMSTraits(pSpecies, trfrposn, 2, false); + while (maternalRecomPositions.size() < nbrCrossOvers) { + // Sample recombination sites + maternalRecomPositions.insert(pRandom->IRandom(0, genomeSize)); } - if (trfr.moveType == 2) { // set CRW genes - double stepL, rho; - trfrCRWParams m = pSpecies->getCRWParams(0, 0); // only traits for females/all - stepL = pRandom->Normal(0.0, m.stepLgthSD) / m.stepLScale; - rho = pRandom->Normal(0.0, m.rhoSD) / m.rhoScale; - if (gen.trait1Chromosome) { - pGenome->setGene(gposn++, expr, stepL, gen.alleleSD); - pGenome->setGene(gposn++, expr, rho, gen.alleleSD); - } - else { - pGenome->setTrait(pSpecies, gposn++, stepL, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, rho, gen.alleleSD); + + // Draw recombination events for paternal genome + if (pSpecies->getRecombinationRate() > 0.0) + events = pRandom->Binomial(genomeSize, pSpecies->getRecombinationRate()); + nbrCrossOvers = events + paternalRecomPositions.size(); + if (nbrCrossOvers > genomeSize) { + nbrCrossOvers = genomeSize; } - // record phenotypic traits - setCRWTraits(pSpecies, trfrposn, 2, false); + while (paternalRecomPositions.size() < nbrCrossOvers) { + paternalRecomPositions.insert(pRandom->IRandom(0, genomeSize)); } - } - else { // set kernel genes - double dist1, dist2, prob1; - trfrKernParams k; - for (int g = 0; g < ntraits; g++) { // first traits for females/all, second for males - k = pSpecies->getKernParams(0, g); - dist1 = pRandom->Normal(0.0, k.dist1SD) / k.dist1Scale; - if (trfr.twinKern) + + // Inherit genes for each trait + const auto& spTraits = pSpecies->getTraitTypes(); + for (auto const& trait : spTraits) { - dist2 = pRandom->Normal(0.0, k.dist2SD) / k.dist2Scale; - prob1 = pRandom->Normal(0.0, k.PKern1SD) / k.PKern1Scale; + const auto motherTrait = mother->getTrait(trait); + const auto fatherTrait = father->getTrait(trait); + auto newTrait = motherTrait->clone(); // shallow copy pointer to species-level attributes + + // Inherit from mother first + newTrait->inheritGenes(true, motherTrait, maternalRecomPositions, maternalStartingChromosome); + if (newTrait->isInherited()) { + // Inherit father trait values + newTrait->inheritGenes(false, fatherTrait, paternalRecomPositions, paternalStartingChromosome); + if (newTrait->getMutationRate() > 0 && pSpecies->areMutationsOn()) + newTrait->mutate(); } - if (gen.trait1Chromosome) { - pGenome->setGene(gposn++, expr, dist1, gen.alleleSD); - if (trfr.twinKern) - { - pGenome->setGene(gposn++, expr, dist2, gen.alleleSD); - pGenome->setGene(gposn++, expr, prob1, gen.alleleSD); + if (trait == GENETIC_LOAD1 || trait == GENETIC_LOAD2 || trait == GENETIC_LOAD3 || trait == GENETIC_LOAD4 || trait == GENETIC_LOAD5) + geneticFitness *= newTrait->express(); + + // Add the inherited trait and genes to the newborn's list + spTraitTable.insert(make_pair(trait, move(newTrait))); } } - else { - pGenome->setTrait(pSpecies, gposn++, dist1, gen.alleleSD); - if (trfr.twinKern) + +//--------------------------------------------------------------------------- +// Inheritance for haploid, asexual species +//--------------------------------------------------------------------------- +void Individual::inherit(Species* pSpecies, const Individual* mother) { + set recomPositions; //not used here cos haploid but need it for inherit function, not ideal + int startingChromosome = 0; + + const auto& spTraits = pSpecies->getTraitTypes(); + + for (auto const& trait : spTraits) { - pGenome->setTrait(pSpecies, gposn++, dist2, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, prob1, gen.alleleSD); + const auto motherTrait = mother->getTrait(trait); + auto newTrait = motherTrait->clone(); // shallow copy, pointer to species trait initialised and empty sequence + + newTrait->inheritGenes(true, motherTrait, recomPositions, startingChromosome); + if (newTrait->isInherited()) { + if (newTrait->getMutationRate() > 0 && pSpecies->areMutationsOn()) + newTrait->mutate(); } + + if (trait == GENETIC_LOAD1 || trait == GENETIC_LOAD2 || trait == GENETIC_LOAD3 || trait == GENETIC_LOAD4 || trait == GENETIC_LOAD5) + geneticFitness *= newTrait->express(); + + // Add the inherited trait and genes to the newborn's list + spTraitTable.insert(make_pair(trait, move(newTrait))); } } - // record phenotypic traits - if (trfr.twinKern) + +// Initialise individual trait genes from species-level traits +void Individual::setUpGenes(Species* pSpecies, int resol) { + + // this way to keep spp trait table immutable i.e. not able to call getTraitTable, + // could pass it back by value (copy) instead but could be heavy if large map + const auto& traitTypes = pSpecies->getTraitTypes(); + for (auto const& traitType : traitTypes) { - setKernTraits(pSpecies, trfrposn, 3, resol, trfr.sexDep); + const auto spTrait = pSpecies->getSpTrait(traitType); + this->spTraitTable.emplace(traitType, traitFactory.Create(traitType, spTrait)); } - else { - setKernTraits(pSpecies, trfrposn, 1, resol, trfr.sexDep); + expressDispersalPhenotypes(pSpecies, resol); + expressGeneticLoad(pSpecies); } - } - } - if (sett.indVar) { - int settposn = gposn; - double s0, alpha, beta; - settParams sparams; - if (sett.sexDep) { // must be a sexual species - ntraits = 2; - } - else { - if (dem.repType == 0) { // asexual reproduction - ntraits = 1; - } - else { // sexual reproduction - ntraits = 1; - } - } - for (int g = 0; g < ntraits; g++) { // first trait for females/all, second for males - if (sim.batchMode) { - sparams = pSpecies->getSettParams(0, g); - } - else { // individual variability not (yet) implemented as sex-dependent in GUI - sparams = pSpecies->getSettParams(0, 0); - } - s0 = pRandom->Normal(0.0, sparams.s0SD) / sparams.s0Scale; - alpha = pRandom->Normal(0.0, sparams.alphaSSD) / sparams.alphaSScale; - beta = pRandom->Normal(0.0, sparams.betaSSD) / sparams.betaSScale; - - if (gen.trait1Chromosome) { - pGenome->setGene(gposn++, expr, s0, gen.alleleSD); - pGenome->setGene(gposn++, expr, alpha, gen.alleleSD); - pGenome->setGene(gposn++, expr, beta, gen.alleleSD); - } - else { - pGenome->setTrait(pSpecies, gposn++, s0, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, alpha, gen.alleleSD); - pGenome->setTrait(pSpecies, gposn++, beta, gen.alleleSD); - } - } +void Individual::expressDispersalPhenotypes(Species* pSpecies, int resol) { + + const emigRules emig = pSpecies->getEmigRules(); + const transferRules trfr = pSpecies->getTransferRules(); + const settleType sett = pSpecies->getSettle(); + const settleRules settRules = pSpecies->getSettRules(stage, sex); + // record phenotypic traits - setSettTraits(pSpecies, settposn, 3, sett.sexDep); + if (emig.indVar) setEmigTraits(pSpecies, emig.sexDep, emig.densDep); + if (trfr.indVar) setTransferTraits(pSpecies, trfr, resol); + if (sett.indVar) setSettlementTraits(pSpecies, sett.sexDep, settRules.densDep); } - if (!gen.trait1Chromosome) { - if (gen.neutralMarkers || pSpecies->getNNeutralLoci() > 0) { - pGenome->setNeutralLoci(pSpecies, gen.alleleSD); - } +// Set the fitness attribute of individuals +// Only called at initialisation, otherwise probably faster to compute directly during inheritance +void Individual::expressGeneticLoad(Species* pSpecies) { + const int nbGenLoadTraits = pSpecies->getNbGenLoadTraits(); + const vector whichTrait = { GENETIC_LOAD1 , GENETIC_LOAD2, GENETIC_LOAD3, GENETIC_LOAD4, GENETIC_LOAD5 }; + for (int i = 0; i < nbGenLoadTraits; i++) { + if (spTraitTable.contains(whichTrait[i])) + geneticFitness *= getTrait(whichTrait[i])->express(); } } -// Inherit genome from parent(s) -void Individual::setGenes(Species* pSpecies, Individual* mother, Individual* father, - int resol) -{ - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); - settleType sett = pSpecies->getSettle(); - - Genome* pFatherGenome; - if (father == 0) pFatherGenome = 0; else pFatherGenome = father->pGenome; +void Individual::setTransferTraits(Species* pSpecies, transferRules trfr, int resol) { + if (trfr.usesMovtProc) { + if (trfr.moveType == 1) { + setIndSMSTraits(pSpecies); + } + else setIndCRWTraits(pSpecies); + } + else setIndKernelTraits(pSpecies, trfr.sexDep, trfr.twinKern, resol); +} - pGenome = new Genome(pSpecies, mother->pGenome, pFatherGenome); +void Individual::setSettlementTraits(Species* pSpecies, bool sexDep, bool densDep) { - if (emig.indVar) { - // record emigration traits - if (father == 0) { // haploid - if (emig.densDep) { - setEmigTraits(pSpecies, 0, 3, 0); - } - else { - setEmigTraits(pSpecies, 0, 1, 0); + settleTraits s; s.s0 = s.alpha = s.beta = 0.0; + if (sexDep) { + if (this->getSex() == MAL) { + s.s0 = getTrait(S_S0_M)->express(); + if (densDep) { + s.alpha = getTrait(S_ALPHA_M)->express(); + s.beta = getTrait(S_BETA_M)->express(); } } - else { // diploid - if (emig.densDep) { - setEmigTraits(pSpecies, 0, 3, emig.sexDep); - } - else { - setEmigTraits(pSpecies, 0, 1, emig.sexDep); + else if (this->getSex() == FEM) { + s.s0 = getTrait(S_S0_F)->express(); + if (densDep) { + s.alpha = getTrait(S_ALPHA_F)->express(); + s.beta = getTrait(S_BETA_F)->express(); } } + else { + throw runtime_error("Attempt to express invalid emigration trait sex."); + } + } + else { + s.s0 = getTrait(S_S0)->express(); + if (densDep) { + s.alpha = getTrait(S_ALPHA)->express(); + s.beta = getTrait(S_BETA)->express(); + } } - if (trfr.indVar) { - // record movement model traits - if (trfr.moveModel) { - if (trfr.moveType == 1) { // SMS - trfrSMSTraits s = pSpecies->getSMSTraits(); - if (s.goalType == 2) - setSMSTraits(pSpecies, trfr.movtTrait[0], 4, 0); - else - setSMSTraits(pSpecies, trfr.movtTrait[0], 2, 0); - } - if (trfr.moveType == 2) { // CRW - setCRWTraits(pSpecies, trfr.movtTrait[0], 2, 0); - } + pSettleTraits = make_unique(); + pSettleTraits->s0 = (float)(s.s0); + pSettleTraits->alpha = (float)(s.alpha); + pSettleTraits->beta = (float)(s.beta); + if (pSettleTraits->s0 < 0.0) pSettleTraits->s0 = 0.0; + if (pSettleTraits->s0 > 1.0) pSettleTraits->s0 = 1.0; + return; } - else { // kernel - if (father == 0) { // haploid - if (trfr.twinKern) + + +// Inherit genome from parent(s), diploid +void Individual::inheritTraits(Species* pSpecies, Individual* mother, Individual* father, int resol) { - setKernTraits(pSpecies, trfr.movtTrait[0], 3, resol, 0); + inherit(pSpecies, mother, father); + expressDispersalPhenotypes(pSpecies, resol); } - else { - setKernTraits(pSpecies, trfr.movtTrait[0], 1, resol, 0); - } - } - else { // diploid - if (trfr.twinKern) + +// Inherit genome from mother, haploid +void Individual::inheritTraits(Species* pSpecies, Individual* mother, int resol) { - setKernTraits(pSpecies, trfr.movtTrait[0], 3, resol, trfr.sexDep); + inherit(pSpecies, mother); + expressDispersalPhenotypes(pSpecies, resol); } - else { - setKernTraits(pSpecies, trfr.movtTrait[0], 1, resol, trfr.sexDep); - } - } - } - } - - if (sett.indVar) { - // record settlement traits - if (father == 0) { // haploid - setSettTraits(pSpecies, sett.settTrait[0], 3, 0); - } - else { // diploid - setSettTraits(pSpecies, sett.settTrait[0], 3, sett.sexDep); - } - } -} //--------------------------------------------------------------------------- // Identify whether an individual is a potentially breeding female - // if so, return her stage, otherwise return 0 int Individual::breedingFem(void) { - if (sex == 0) { - if (status == 0 || status == 4 || status == 5) return stage; + if (sex == FEM) { + if (status == 0 || status == 4 || status == 5 || status == 10) return stage; else return 0; } else return 0; @@ -414,10 +394,17 @@ int Individual::breedingFem(void) { int Individual::getId(void) { return indId; } -int Individual::getSex(void) { return sex; } +sex_t Individual::getSex(void) { return sex; } int Individual::getStatus(void) { return status; } +float Individual::getGeneticFitness(void) { return geneticFitness; } + +bool Individual::isViable() const { + float probViability = geneticFitness > 1.0 ? 1.0 : geneticFitness; + return probViability >= pRandom->Random(); +} + indStats Individual::getStats(void) { indStats s; s.stage = stage; s.sex = sex; s.age = age; s.status = status; s.fallow = fallow; @@ -425,13 +412,12 @@ indStats Individual::getStats(void) { return s; } -Cell* Individual::getLocn(const short option) { - if (option == 0) { // return previous location - return pPrevCell; - } - else { // return current location - return pCurrCell; - } +Cell* Individual::getPrevCell() { + return pPrevCell; +} + +Cell* Individual::getCurrCell() { + return pCurrCell; } Patch* Individual::getNatalPatch(void) { return pNatalPatch; } @@ -477,340 +463,218 @@ void Individual::setSettPatch(const settlePatch s) { path->pSettPatch = s.pSettPatch; } -// Set phenotypic emigration traits -void Individual::setEmigTraits(Species* pSpecies, short emiggenelocn, short nemigtraits, - bool sexdep) { - emigTraits e; e.d0 = e.alpha = e.beta = 0.0; - if (pGenome != 0) { - if (pSpecies->has1ChromPerTrait()) { - if (sexdep) { - if (nemigtraits == 3) { // emigration is density-dependent - e.d0 = (float)pGenome->express(emiggenelocn + 3 * sex, 0, 0); - e.alpha = (float)pGenome->express(emiggenelocn + 3 * sex + 1, 0, 0); - e.beta = (float)pGenome->express(emiggenelocn + 3 * sex + 2, 0, 0); +void Individual::setEmigTraits(Species* pSpecies, bool sexDep, bool densityDep) { + emigTraits e; + e.d0 = e.alpha = e.beta = 0.0; + if (sexDep) { + if (this->getSex() == MAL) { + e.d0 = this->getTrait(E_D0_M)->express(); + if (densityDep) { + e.alpha = getTrait(E_ALPHA_M)->express(); + e.beta = getTrait(E_BETA_M)->express(); } - else { - e.d0 = (float)pGenome->express(emiggenelocn + sex, 0, 0); } + else if (this->getSex() == FEM) { + e.d0 = this->getTrait(E_D0_F)->express(); + if (densityDep) { + e.alpha = getTrait(E_ALPHA_F)->express(); + e.beta = getTrait(E_BETA_F)->express(); } - else { - e.d0 = (float)pGenome->express(emiggenelocn, 0, 0); - if (nemigtraits == 3) { // emigration is density-dependent - e.alpha = (float)pGenome->express(emiggenelocn + 1, 0, 0); - e.beta = (float)pGenome->express(emiggenelocn + 2, 0, 0); } - } - } else { - if (sexdep) { - if (nemigtraits == 3) { // emigration is density-dependent - e.d0 = (float)pGenome->express(pSpecies, emiggenelocn + 3 * sex); - e.alpha = (float)pGenome->express(pSpecies, emiggenelocn + 3 * sex + 1); - e.beta = (float)pGenome->express(pSpecies, emiggenelocn + 3 * sex + 2); + throw runtime_error("Attempt to express invalid emigration trait sex."); } - else { - e.d0 = (float)pGenome->express(pSpecies, emiggenelocn + sex); } - } else { - e.d0 = (float)pGenome->express(pSpecies, emiggenelocn); - if (nemigtraits == 3) { // emigration is density-dependent - e.alpha = (float)pGenome->express(pSpecies, emiggenelocn + 1); - e.beta = (float)pGenome->express(pSpecies, emiggenelocn + 2); + e.d0 = this->getTrait(E_D0)->express(); + if (densityDep) { + e.alpha = getTrait(E_ALPHA)->express(); + e.beta = getTrait(E_BETA)->express(); } } - } - } - emigParams eparams; - if (sexdep) { - eparams = pSpecies->getEmigParams(0, sex); - } - else { - eparams = pSpecies->getEmigParams(0, 0); - } - emigtraits = new emigTraits; - emigtraits->d0 = (float)(e.d0 * eparams.d0Scale + eparams.d0Mean); - emigtraits->alpha = (float)(e.alpha * eparams.alphaScale + eparams.alphaMean); - emigtraits->beta = (float)(e.beta * eparams.betaScale + eparams.betaMean); - if (emigtraits->d0 < 0.0) emigtraits->d0 = 0.0; - if (emigtraits->d0 > 1.0) emigtraits->d0 = 1.0; + pEmigTraits = make_unique(); + pEmigTraits->d0 = e.d0; + pEmigTraits->alpha = e.alpha; + pEmigTraits->beta = e.beta; + + // Below must never trigger, phenotype is bounded in express() + if (pEmigTraits->d0 < 0.0) throw runtime_error("d0 value has become negative."); + if (pEmigTraits->d0 > 1.0) throw runtime_error("d0 value has exceeded 1."); return; } // Get phenotypic emigration traits -emigTraits Individual::getEmigTraits(void) { - emigTraits e; e.d0 = e.alpha = e.beta = 0.0; - if (emigtraits != 0) { - e.d0 = emigtraits->d0; - e.alpha = emigtraits->alpha; - e.beta = emigtraits->beta; +emigTraits Individual::getIndEmigTraits(void) { + emigTraits e; + e.d0 = e.alpha = e.beta = 0.0; + if (pEmigTraits != 0) { + e.d0 = pEmigTraits->d0; + e.alpha = pEmigTraits->alpha; + e.beta = pEmigTraits->beta; } return e; } - // Set phenotypic transfer by kernel traits -void Individual::setKernTraits(Species* pSpecies, short kerngenelocn, short nkerntraits, - int resol, bool sexdep) { - trfrKernTraits k; k.meanDist1 = k.meanDist2 = k.probKern1 = 0.0; - if (pGenome != 0) { - if (pSpecies->has1ChromPerTrait()) { - if (sexdep) { - if (nkerntraits == 3) { // twin kernel - k.meanDist1 = (float)pGenome->express(kerngenelocn + 3 * sex, 0, sex); - k.meanDist2 = (float)pGenome->express(kerngenelocn + 3 * sex + 1, 0, sex); - k.probKern1 = (float)pGenome->express(kerngenelocn + 3 * sex + 2, 0, sex); +void Individual::setIndKernelTraits(Species* pSpecies, bool sexDep, bool twinKernel, int resol) { + + trfrKernelParams k; + k.meanDist1 = k.meanDist2 = k.probKern1 = 0.0; + + if (sexDep) { + if (this->sex == MAL) { + k.meanDist1 = getTrait(KERNEL_MEANDIST_1_M)->express(); + + if (twinKernel) { // twin kernel + k.meanDist2 = getTrait(KERNEL_MEANDIST_2_M)->express(); + k.probKern1 = getTrait(KERNEL_PROBABILITY_M)->express(); } - else { - k.meanDist1 = (float)pGenome->express(kerngenelocn + sex, 0, sex); } + else if (this->sex == FEM) { + k.meanDist1 = getTrait(KERNEL_MEANDIST_1_F)->express(); + + if (twinKernel) { // twin kernel + k.meanDist2 = getTrait(KERNEL_MEANDIST_2_F)->express(); + k.probKern1 = getTrait(KERNEL_PROBABILITY_F)->express(); } - else { - k.meanDist1 = (float)pGenome->express(kerngenelocn, 0, 0); - if (nkerntraits == 3) { // twin kernel - k.meanDist2 = (float)pGenome->express(kerngenelocn + 1, 0, 0); - k.probKern1 = (float)pGenome->express(kerngenelocn + 2, 0, 0); } - } - } else { - if (sexdep) { - if (nkerntraits == 3) { // twin kernel - k.meanDist1 = (float)pGenome->express(pSpecies, kerngenelocn + 3 * sex); - k.meanDist2 = (float)pGenome->express(pSpecies, kerngenelocn + 3 * sex + 1); - k.probKern1 = (float)pGenome->express(pSpecies, kerngenelocn + 3 * sex + 2); + throw runtime_error("Attempt to express invalid kernel transfer trait sex."); } - else { - k.meanDist1 = (float)pGenome->express(pSpecies, kerngenelocn + sex); } - } else { - k.meanDist1 = (float)pGenome->express(pSpecies, kerngenelocn); - if (nkerntraits == 3) { // twin kernel - k.meanDist2 = (float)pGenome->express(pSpecies, kerngenelocn + 1); - k.probKern1 = (float)pGenome->express(pSpecies, kerngenelocn + 2); + k.meanDist1 = getTrait(KERNEL_MEANDIST_1)->express(); + + if (twinKernel) { // twin kernel + k.meanDist2 = getTrait(KERNEL_MEANDIST_2)->express(); + k.probKern1 = getTrait(KERNEL_PROBABILITY)->express(); } } - } - } - trfrKernParams kparams; - if (sexdep) { - kparams = pSpecies->getKernParams(0, sex); - } - else { - kparams = pSpecies->getKernParams(0, 0); - } - kerntraits = new trfrKernTraits; - kerntraits->meanDist1 = (float)(k.meanDist1 * kparams.dist1Scale + kparams.dist1Mean); - kerntraits->meanDist2 = (float)(k.meanDist2 * kparams.dist2Scale + kparams.dist2Mean); - kerntraits->probKern1 = (float)(k.probKern1 * kparams.PKern1Scale + kparams.PKern1Mean); + float meanDist1 = (float)(k.meanDist1); + float meanDist2 = (float)(k.meanDist2); + float probKern1 = (float)(k.probKern1); + if (!pSpecies->useFullKernel()) { // kernel mean(s) may not be less than landscape resolution - if (kerntraits->meanDist1 < resol) kerntraits->meanDist1 = (float)resol; - if (kerntraits->meanDist2 < resol) kerntraits->meanDist2 = (float)resol; + if (meanDist1 < resol) meanDist1 = (float)resol; + if (meanDist2 < resol) meanDist2 = (float)resol; } - if (kerntraits->probKern1 < 0.0) kerntraits->probKern1 = 0.0; - if (kerntraits->probKern1 > 1.0) kerntraits->probKern1 = 1.0; + if (probKern1 < 0.0) probKern1 = 0.0; + if (probKern1 > 1.0) probKern1 = 1.0; + auto& pKernel = dynamic_cast(*pTrfrData); + pKernel.meanDist1 = meanDist1; + pKernel.meanDist2 = meanDist2; + pKernel.probKern1 = probKern1; + return; } + + // Get phenotypic emigration traits -trfrKernTraits Individual::getKernTraits(void) { - trfrKernTraits k; k.meanDist1 = k.meanDist2 = k.probKern1 = 0.0; - if (kerntraits != 0) { - k.meanDist1 = kerntraits->meanDist1; - k.meanDist2 = kerntraits->meanDist2; - k.probKern1 = kerntraits->probKern1; +trfrKernelParams Individual::getIndKernTraits(void) { + trfrKernelParams k; k.meanDist1 = k.meanDist2 = k.probKern1 = 0.0; + if (pTrfrData != 0) { + + auto& pKernel = dynamic_cast(*pTrfrData); + + k.meanDist1 = pKernel.meanDist1; + k.meanDist2 = pKernel.meanDist2; + k.probKern1 = pKernel.probKern1; } + return k; } -// Set phenotypic transfer by SMS traits -void Individual::setSMSTraits(Species* pSpecies, short SMSgenelocn, short nSMStraits, - bool sexdep) { - trfrSMSTraits s = pSpecies->getSMSTraits(); +void Individual::setIndSMSTraits(Species* pSpecies) { + + trfrSMSTraits s = pSpecies->getSpSMSTraits(); + double dp, gb, alphaDB, betaDB; dp = gb = alphaDB = betaDB = 0.0; - if (pGenome != 0) { - if (pSpecies->has1ChromPerTrait()) { - if (sexdep) { - dp = pGenome->express(SMSgenelocn, 0, 0); - gb = pGenome->express(SMSgenelocn + 1, 0, 0); - if (nSMStraits == 4) { - alphaDB = pGenome->express(SMSgenelocn + 2, 0, 0); - betaDB = pGenome->express(SMSgenelocn + 3, 0, 0); - } - } - else { - dp = pGenome->express(SMSgenelocn, 0, 0); - gb = pGenome->express(SMSgenelocn + 1, 0, 0); - if (nSMStraits == 4) { - alphaDB = pGenome->express(SMSgenelocn + 2, 0, 0); - betaDB = pGenome->express(SMSgenelocn + 3, 0, 0); - } - } - } - else { - if (sexdep) { - dp = pGenome->express(pSpecies, SMSgenelocn); - gb = pGenome->express(pSpecies, SMSgenelocn + 1); - if (nSMStraits == 4) { - alphaDB = pGenome->express(pSpecies, SMSgenelocn + 2); - betaDB = pGenome->express(pSpecies, SMSgenelocn + 3); - } - } - else { - dp = pGenome->express(pSpecies, SMSgenelocn); - gb = pGenome->express(pSpecies, SMSgenelocn + 1); - if (nSMStraits == 4) { - alphaDB = pGenome->express(pSpecies, SMSgenelocn + 2); - betaDB = pGenome->express(pSpecies, SMSgenelocn + 3); + dp = getTrait(SMS_DP)->express(); + if (s.goalType == 2) { + gb = getTrait(SMS_GB)->express(); + alphaDB = getTrait(SMS_ALPHADB)->express(); + betaDB = getTrait(SMS_BETADB)->express(); } - } - } - } - trfrSMSParams smsparams; - if (sexdep) { - smsparams = pSpecies->getSMSParams(0, 0); - } - else { - smsparams = pSpecies->getSMSParams(0, 0); - } - smsData->dp = (float)(dp * smsparams.dpScale + smsparams.dpMean); - smsData->gb = (float)(gb * smsparams.gbScale + smsparams.gbMean); + + auto& pSMS = dynamic_cast(*pTrfrData); + pSMS.dp = (float)(dp); + pSMS.gb = (float)(gb); if (s.goalType == 2) { - smsData->alphaDB = (float)(alphaDB * smsparams.alphaDBScale + smsparams.alphaDBMean); - smsData->betaDB = (int)(betaDB * smsparams.betaDBScale + smsparams.betaDBMean + 0.5); + pSMS.alphaDB = (float)(alphaDB); + pSMS.betaDB = (int)(betaDB); } else { - smsData->alphaDB = s.alphaDB; - smsData->betaDB = s.betaDB; + pSMS.alphaDB = s.alphaDB; + pSMS.betaDB = s.betaDB; } - if (smsData->dp < 1.0) smsData->dp = 1.0; - if (smsData->gb < 1.0) smsData->gb = 1.0; - if (smsData->alphaDB <= 0.0) smsData->alphaDB = 0.000001f; - if (smsData->betaDB < 1) smsData->betaDB = 1; + if (pSMS.dp < 1.0) pSMS.dp = 1.0; + if (pSMS.gb < 1.0) pSMS.gb = 1.0; + if (pSMS.alphaDB <= 0.0) pSMS.alphaDB = 0.000001f; + if (pSMS.betaDB < 1) pSMS.betaDB = 1; return; } +trfrData* Individual::getTrfrData(void) { + return pTrfrData.get(); +} + // Get phenotypic transfer by SMS traits -trfrSMSTraits Individual::getSMSTraits(void) { +trfrSMSTraits Individual::getIndSMSTraits(void) { + trfrSMSTraits s; s.dp = s.gb = s.alphaDB = 1.0; s.betaDB = 1; - if (smsData != 0) { - s.dp = smsData->dp; s.gb = smsData->gb; - s.alphaDB = smsData->alphaDB; s.betaDB = smsData->betaDB; + if (pTrfrData != 0) { + + auto& pSMS = dynamic_cast(*pTrfrData); + + s.dp = pSMS.dp; s.gb = pSMS.gb; + s.alphaDB = pSMS.alphaDB; s.betaDB = pSMS.betaDB; } + return s; } + // Set phenotypic transfer by CRW traits -void Individual::setCRWTraits(Species* pSpecies, short CRWgenelocn, short nCRWtraits, - bool sexdep) { +void Individual::setIndCRWTraits(Species* pSpecies) { trfrCRWTraits c; c.stepLength = c.rho = 0.0; - if (pGenome != 0) { - if (pSpecies->has1ChromPerTrait()) { - if (sexdep) { - c.stepLength = (float)pGenome->express(CRWgenelocn + sex, 0, sex); - c.rho = (float)pGenome->express(CRWgenelocn + 2 + sex, 0, sex); - } - else { - c.stepLength = (float)pGenome->express(CRWgenelocn, 0, 0); - c.rho = (float)pGenome->express(CRWgenelocn + 1, 0, 0); - } - } - else { - if (sexdep) { - c.stepLength = (float)pGenome->express(pSpecies, CRWgenelocn + sex); - c.rho = (float)pGenome->express(pSpecies, CRWgenelocn + 2 + sex); - } - else { - c.stepLength = (float)pGenome->express(pSpecies, CRWgenelocn); - c.rho = (float)pGenome->express(pSpecies, CRWgenelocn + 1); - } - } - } - trfrCRWParams cparams; - if (sexdep) { - cparams = pSpecies->getCRWParams(0, sex); - } - else { - cparams = pSpecies->getCRWParams(0, 0); - } - crw->stepL = (float)(c.stepLength * cparams.stepLScale + cparams.stepLgthMean); - crw->rho = (float)(c.rho * cparams.rhoScale + cparams.rhoMean); - if (crw->stepL < 1.0) crw->stepL = 1.0; - if (crw->rho < 0.0) crw->rho = 0.0; - if (crw->rho > 0.999) crw->rho = 0.999f; + c.stepLength = getTrait(CRW_STEPLENGTH)->express(); + c.rho = getTrait(CRW_STEPCORRELATION)->express(); + + auto& pCRW = dynamic_cast(*pTrfrData); + pCRW.stepLength = (float)(c.stepLength); + pCRW.rho = (float)(c.rho); + if (pCRW.stepLength < 1.0) pCRW.stepLength = 1.0; + if (pCRW.rho < 0.0) pCRW.rho = 0.0; + if (pCRW.rho > 0.999) pCRW.rho = 0.999f; return; } // Get phenotypic transfer by CRW traits -trfrCRWTraits Individual::getCRWTraits(void) { - trfrCRWTraits c; c.stepLength = c.rho = 0.0; - if (crw != 0) { - c.stepLength = crw->stepL; - c.rho = crw->rho; +trfrCRWTraits Individual::getIndCRWTraits(void) { + + trfrCRWTraits c; + c.stepLength = c.rho = 0.0; + if (pTrfrData != 0) { + auto& pCRW = dynamic_cast(*pTrfrData); + c.stepLength = pCRW.stepLength; + c.rho = pCRW.rho; } return c; -} -// Set phenotypic settlement traits -void Individual::setSettTraits(Species* pSpecies, short settgenelocn, short nsetttraits, - bool sexdep) { - settleTraits s; s.s0 = s.alpha = s.beta = 0.0; - if (pGenome != 0) { - if (pSpecies->has1ChromPerTrait()) { - if (sexdep) { - s.s0 = (float)pGenome->express(settgenelocn + 3 * sex, 0, 0); - s.alpha = (float)pGenome->express(settgenelocn + 3 * sex + 1, 0, 0); - s.beta = (float)pGenome->express(settgenelocn + 3 * sex + 2, 0, 0); } - else { - s.s0 = (float)pGenome->express(settgenelocn, 0, 0); - s.alpha = (float)pGenome->express(settgenelocn + 1, 0, 0); - s.beta = (float)pGenome->express(settgenelocn + 2, 0, 0); - } - } - else { - if (sexdep) { - s.s0 = (float)pGenome->express(pSpecies, settgenelocn + 3 * sex); - s.alpha = (float)pGenome->express(pSpecies, settgenelocn + 3 * sex + 1); - s.beta = (float)pGenome->express(pSpecies, settgenelocn + 3 * sex + 2); - } - else { - s.s0 = (float)pGenome->express(pSpecies, settgenelocn); - s.alpha = (float)pGenome->express(pSpecies, settgenelocn + 1); - s.beta = (float)pGenome->express(pSpecies, settgenelocn + 2); - } - - } - } - - settParams sparams; - if (sexdep) { - sparams = pSpecies->getSettParams(0, sex); - } - else { - sparams = pSpecies->getSettParams(0, 0); - } - setttraits = new settleTraits; - setttraits->s0 = (float)(s.s0 * sparams.s0Scale + sparams.s0Mean); - setttraits->alpha = (float)(s.alpha * sparams.alphaSScale + sparams.alphaSMean); - setttraits->beta = (float)(s.beta * sparams.betaSScale + sparams.betaSMean); - if (setttraits->s0 < 0.0) setttraits->s0 = 0.0; - if (setttraits->s0 > 1.0) setttraits->s0 = 1.0; - return; -} // Get phenotypic settlement traits -settleTraits Individual::getSettTraits(void) { +settleTraits Individual::getIndSettTraits(void) { settleTraits s; s.s0 = s.alpha = s.beta = 0.0; - if (setttraits != 0) { - s.s0 = setttraits->s0; - s.alpha = setttraits->alpha; - s.beta = setttraits->beta; + if (pSettleTraits != 0) { + s.s0 = pSettleTraits->s0; + s.alpha = pSettleTraits->alpha; + s.beta = pSettleTraits->beta; } return s; @@ -818,11 +682,11 @@ settleTraits Individual::getSettTraits(void) { void Individual::setStatus(short s) { - if (s >= 0 && s <= 9) status = s; + if (s >= 0 && s <= 10) status = s; status = s; } -void Individual::developing(void) { +void Individual::setToDevelop(void) { isDeveloping = true; } @@ -831,7 +695,7 @@ void Individual::develop(void) { } void Individual::ageIncrement(short maxage) { - if (status < 6) { // alive + if (status < 6 || status == 10) { // alive age++; if (age > maxage) status = 9; // exceeds max. age - dies else { @@ -855,8 +719,7 @@ void Individual::moveto(Cell* newCell) { double d = sqrt(((double)currloc.x - (double)newloc.x) * ((double)currloc.x - (double)newloc.x) + ((double)currloc.y - (double)newloc.y) * ((double)currloc.y - (double)newloc.y)); if (d >= 1.0 && d < 1.5) { // ok - pCurrCell = newCell; - status = 5; + pCurrCell = newCell; status = 5; } } @@ -864,17 +727,14 @@ void Individual::moveto(Cell* newCell) { // Move to a new cell by sampling a dispersal distance from a single or double // negative exponential kernel // Returns 1 if still dispersing (including having found a potential patch), otherwise 0 -int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, - const short repType, const bool absorbing) +int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, const bool absorbing) { - - intptr patch; int patchNum = 0; int newX = 0, newY = 0; int dispersing = 1; double xrand, yrand, meandist, dist, r1, rndangle, nx, ny; float localK; - trfrKernTraits kern; + trfrKernelParams kern; Cell* pCell; Patch* pPatch; locn loc = pCurrCell->getLocn(); @@ -882,7 +742,7 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, landData land = pLandscape->getLandData(); bool usefullkernel = pSpecies->useFullKernel(); - trfrRules trfr = pSpecies->getTrfr(); + transferRules trfr = pSpecies->getTransferRules(); settleRules sett = pSpecies->getSettRules(stage, sex); pCell = NULL; @@ -890,30 +750,31 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, if (trfr.indVar) { // get individual's kernel parameters kern.meanDist1 = kern.meanDist2 = kern.probKern1 = 0.0; - if (pGenome != 0) { - kern.meanDist1 = kerntraits->meanDist1; + + auto& pKernel = dynamic_cast(*pTrfrData); + + kern.meanDist1 = pKernel.meanDist1; if (trfr.twinKern) { - kern.meanDist2 = kerntraits->meanDist2; - kern.probKern1 = kerntraits->probKern1; + kern.meanDist2 = pKernel.meanDist2; + kern.probKern1 = pKernel.probKern1; } } - } else { // get kernel parameters for the species if (trfr.sexDep) { if (trfr.stgDep) { - kern = pSpecies->getKernTraits(stage, sex); + kern = pSpecies->getSpKernTraits(stage, sex); } else { - kern = pSpecies->getKernTraits(0, sex); + kern = pSpecies->getSpKernTraits(0, sex); } } else { if (trfr.stgDep) { - kern = pSpecies->getKernTraits(stage, 0); + kern = pSpecies->getSpKernTraits(stage, 0); } else { - kern = pSpecies->getKernTraits(0, 0); + kern = pSpecies->getSpKernTraits(0, 0); } } } @@ -928,10 +789,12 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, } else meandist = kern.meanDist1 / (float)land.resol; - + // scaled mean may not be less than 1 unless emigration derives from the kernel // (i.e. the 'use full kernel' option is applied) +# ifdef NDEBUG // bypass this requirement for tests if (!usefullkernel && meandist < 1.0) meandist = 1.0; +# endif int loopsteps = 0; // new counter to prevent infinite loop added 14/8/15 do { @@ -950,55 +813,57 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, } } // randomise the position of the individual inside the cell + // so x and y are a corner of the cell? xrand = (double)loc.x + pRandom->Random() * 0.999; yrand = (double)loc.y + pRandom->Random() * 0.999; + // draw factor r1 0 < r1 <= 1 r1 = 0.0000001 + pRandom->Random() * (1.0 - 0.0000001); - // dist = (-1.0*meandist)*std::log(r1); - dist = (-1.0 * meandist) * log(r1); // for LINUX_CLUSTER + dist = (-1.0 * meandist) * log(r1); rndangle = pRandom->Random() * 2.0 * PI; nx = xrand + dist * sin(rndangle); ny = yrand + dist * cos(rndangle); if (nx < 0.0) newX = -1; else newX = (int)nx; if (ny < 0.0) newY = -1; else newY = (int)ny; -#if RSDEBUG +#ifndef NDEBUG if (path != 0) (path->year)++; #endif loopsteps++; } while (loopsteps < 1000 && - ((!absorbing && (newX < land.minX || newX > land.maxX - || newY < land.minY || newY > land.maxY)) + // keep drawing if out of bounds of landscape or same cell + ((!absorbing + && (newX < land.minX || newX > land.maxX || newY < land.minY || newY > land.maxY)) || (!usefullkernel && newX == loc.x && newY == loc.y)) ); + if (loopsteps < 1000) { if (newX < land.minX || newX > land.maxX || newY < land.minY || newY > land.maxY) { // beyond absorbing boundary + // this cannot be reached if not absorbing? pCell = 0; - patch = 0; + pPatch = nullptr; patchNum = -1; } else { pCell = pLandscape->findCell(newX, newY); if (pCell == 0) { // no-data cell - patch = 0; + pPatch = nullptr; patchNum = -1; } else { - patch = pCell->getPatch(); - if (patch == 0) { // matrix - pPatch = 0; + pPatch = pCell->getPatch(); + if (pPatch == nullptr) { // matrix patchNum = 0; } else { - pPatch = (Patch*)patch; patchNum = pPatch->getPatchNum(); } } } } - else { - patch = 0; + else { // exceeded 1000 attempts + pPatch = nullptr; patchNum = -1; } } while (!absorbing && patchNum < 0 && loopsteps < 1000); // in a no-data region @@ -1006,6 +871,7 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, if (loopsteps < 1000) { if (pCell == 0) { // beyond absorbing boundary or in no-data cell + // only if absorbing=true and out of bounddaries pCurrCell = 0; status = 6; dispersing = 0; @@ -1018,6 +884,7 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, status = 2; // record as potential settler } else { + // unsuitable patch dispersing = 0; // can wait in matrix if population is stage structured ... if (pSpecies->stageStructured()) { @@ -1028,19 +895,18 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, else // ... it is not status = 6; // dies (unless there is a suitable neighbouring cell) } - else - status = 6; // dies (unless there is a suitable neighbouring cell) + else status = 6; // dies (unless there is a suitable neighbouring cell) } } } - else { + else { // exceeded 1000 attempts status = 6; dispersing = 0; } // apply dispersal-related mortality, which may be distance-dependent dist *= (float)land.resol; // re-scale distance moved to landscape scale - if (status < 7) { + if (status < 7 || status == 10) { double dispmort; trfrMortParams mort = pSpecies->getMortParams(); if (trfr.distMort) { @@ -1064,10 +930,8 @@ int Individual::moveKernel(Landscape* pLandscape, Species* pSpecies, int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, const short landIx, const bool absorbing) { - if (status != 1) return 0; // not currently dispersing - intptr patch; int patchNum; int newX, newY; locn loc; @@ -1076,24 +940,23 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, double angle; double mortprob, rho, steplen; movedata move; - Patch* pPatch = 0; + Patch* pPatch = nullptr; bool absorbed = false; + //int popsize; landData land = pLandscape->getLandData(); simParams sim = paramsSim->getSim(); - trfrRules trfr = pSpecies->getTrfr(); - trfrCRWTraits movt = pSpecies->getCRWTraits(); + transferRules trfr = pSpecies->getTransferRules(); + trfrCRWTraits movt = pSpecies->getSpCRWTraits(); settleSteps settsteps = pSpecies->getSteps(stage, sex); - patch = pCurrCell->getPatch(); + pPatch = pCurrCell->getPatch(); - if (patch == 0) { // matrix - pPatch = 0; + if (pPatch == nullptr) { // matrix patchNum = 0; } else { - pPatch = (Patch*)patch; patchNum = pPatch->getPatchNum(); } // apply step-dependent mortality risk ... @@ -1116,15 +979,14 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, } else { // take a step (path->year)++; - (path->total)++; - if (patch == 0 || pPatch == 0 || patchNum == 0) { // not in a patch + (path->total)++; + if (pPatch == nullptr || patchNum == 0) { // not in a patch if (path != 0) path->settleStatus = 0; // reset path settlement status (path->out)++; } loc = pCurrCell->getLocn(); newX = loc.x; newY = loc.y; - switch (trfr.moveType) { case 1: // SMS @@ -1137,16 +999,8 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, dispersing = 0; } else { - // WOULD IT BE MORE EFFICIENT FOR smsMove TO RETURN A POINTER TO THE NEW CELL? ... - - patch = pCurrCell->getPatch(); - if (patch == 0) { - pPatch = 0; - } - else { - pPatch = (Patch*)patch; - } + pPatch = pCurrCell->getPatch(); if (sim.saveVisits && pPatch != pNatalPatch) { pCurrCell->incrVisits(); } @@ -1154,20 +1008,21 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, break; case 2: // CRW + + auto & pCRW = dynamic_cast(*pTrfrData); + if (trfr.indVar) { - if (crw != 0) { - movt.stepLength = crw->stepL; - movt.rho = crw->rho; + movt.stepLength = pCRW.stepLength; + movt.rho = pCRW.rho; } - } - steplen = movt.stepLength; if (steplen < 0.2 * land.resol) steplen = 0.2 * land.resol; - rho = movt.rho; if (rho > 0.99) rho = 0.99; + steplen = movt.stepLength; + rho = movt.rho; if (pPatch == pNatalPatch) { rho = 0.99; // to promote leaving natal patch path->out = 0; } - if (movt.straigtenPath && path->settleStatus > 0) { + if (movt.straightenPath && path->settleStatus > 0) { // individual is in a patch and has already determined whether to settle rho = 0.99; // to promote leaving the patch path->out = 0; @@ -1180,13 +1035,13 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, || pCurrCell == 0) { // individual has tried to go out-of-bounds or into no-data area // allow random move to prevent repeated similar move - angle = wrpcauchy(crw->prevdrn, 0.0); + angle = wrpcauchy(pCRW.prevdrn, 0.0); } else - angle = wrpcauchy(crw->prevdrn, rho); + angle = wrpcauchy(pCRW.prevdrn, rho); // new continuous cell coordinates - xcnew = crw->xc + sin(angle) * steplen / (float)land.resol; - ycnew = crw->yc + cos(angle) * steplen / (float)land.resol; + xcnew = pCRW.xc + sin(angle) * steplen / (float)land.resol; + ycnew = pCRW.yc + cos(angle) * steplen / (float)land.resol; if (xcnew < 0.0) newX = -1; else newX = (int)xcnew; if (ycnew < 0.0) newY = -1; else newY = (int)ycnew; loopsteps++; @@ -1197,14 +1052,14 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, else pCurrCell = pLandscape->findCell(newX, newY); if (pCurrCell == 0) { // no-data cell or beyond absorbing boundary - patch = 0; + pPatch = nullptr; if (absorbing) absorbed = true; } else - patch = pCurrCell->getPatch(); + pPatch = pCurrCell->getPatch(); } while (!absorbing && pCurrCell == 0 && loopsteps < 1000); - crw->prevdrn = (float)angle; - crw->xc = (float)xcnew; crw->yc = (float)ycnew; + pCRW.prevdrn = (float)angle; + pCRW.xc = (float)xcnew; pCRW.yc = (float)ycnew; if (absorbed) { // beyond absorbing boundary or in no-data square status = 6; dispersing = 0; @@ -1224,11 +1079,9 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, break; } // end of switch (trfr.moveType) - if (dispersing == 1 && - patch > 0 // not no-data area or matrix + pPatch != nullptr // not no-data area or matrix && path->total >= settsteps.minSteps) { - pPatch = (Patch*)patch; if (pPatch != pNatalPatch) { // determine whether the new patch is potentially suitable @@ -1250,7 +1103,6 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, } // end of single movement step return dispersing; - } //--------------------------------------------------------------------------- @@ -1261,12 +1113,10 @@ int Individual::moveStep(Landscape* pLandscape, Species* pSpecies, movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, const short landIx, const bool natalPatch, const bool indvar, const bool absorbing) { - array3x3d nbr; // to hold weights/costs/probs of moving to neighbouring cells array3x3d goal; // to hold weights for moving towards a goal location array3x3f hab; // to hold weights for habitat (includes percep range) - int x2, y2; // x index from 0=W to 2=E, y index from 0=N to 2=S - int newX = -9, newY = -9; + int newX = -9, newY = -9; // BUGFIX: must not be 0 because 0,0 is a valid landscape cell Cell* pCell; Cell* pNewCell = NULL; double sum_nbrs = 0.0; @@ -1274,6 +1124,7 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, int cellcost, newcellcost; locn current; + auto& pSMS = dynamic_cast(*pTrfrData); if (pCurrCell == 0) { // x,y is a NODATA square - this should not occur here @@ -1283,19 +1134,19 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, } landData land = pLand->getLandData(); - trfrSMSTraits movt = pSpecies->getSMSTraits(); + trfrSMSTraits movt = pSpecies->getSpSMSTraits(); current = pCurrCell->getLocn(); //get weights for directional persistence.... if ((path->out > 0 && path->out <= (movt.pr + 1)) || natalPatch - || (movt.straigtenPath && path->settleStatus > 0)) { + || (movt.straightenPath && path->settleStatus > 0)) { // inflate directional persistence to promote leaving the patch - if (indvar) nbr = getSimDir(current.x, current.y, 10.0f * smsData->dp); + if (indvar) nbr = getSimDir(current.x, current.y, 10.0f * pSMS.dp); else nbr = getSimDir(current.x, current.y, 10.0f * movt.dp); } else { - if (indvar) nbr = getSimDir(current.x, current.y, smsData->dp); + if (indvar) nbr = getSimDir(current.x, current.y, pSMS.dp); else nbr = getSimDir(current.x, current.y, movt.dp); } if (natalPatch || path->settleStatus > 0) path->out = 0; @@ -1311,12 +1162,13 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, nsteps = path->total; } if (indvar) { - double exp_arg = -((double)nsteps - (double)smsData->betaDB) * (-smsData->alphaDB); + double exp_arg = -((double)nsteps - (double)pSMS.betaDB) * (-pSMS.alphaDB); if (exp_arg > 100.0) exp_arg = 100.0; // to prevent exp() overflow error - gb = 1.0 + (smsData->gb - 1.0) / (1.0 + exp(exp_arg)); + gb = 1.0 + (pSMS.gb - 1.0) / (1.0 + exp(exp_arg)); } else { double exp_arg = -((double)nsteps - (double)movt.betaDB) * (-movt.alphaDB); + if (exp_arg > 100.0) exp_arg = 100.0; // to prevent exp() overflow error gb = 1.0 + (movt.gb - 1.0) / (1.0 + exp(exp_arg)); } @@ -1326,22 +1178,25 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, // get habitat-dependent weights (mean effective costs, given perceptual range) // first check if costs have already been calculated + { +#ifdef _OPENMP + const std::unique_lock lock = pCurrCell->lockCost(); +#endif + hab = pCurrCell->getEffCosts(); + if (hab.cell[0][0] < 0.0) { // costs have not already been calculated + hab = getHabMatrix(pLand, pSpecies, current.x, current.y, movt.pr, movt.prMethod, + landIx, absorbing); + pCurrCell->setEffCosts(hab); + } + else { // they have already been calculated - no action required - hab = pCurrCell->getEffCosts(); - - if (hab.cell[0][0] < 0.0) { // costs have not already been calculated - hab = getHabMatrix(pLand, pSpecies, current.x, current.y, movt.pr, movt.prMethod, - landIx, absorbing); - pCurrCell->setEffCosts(hab); - } - else { - // they have already been calculated - no action required + } } // determine weighted effective cost for the 8 neighbours // multiply directional persistence, goal bias and habitat habitat-dependent weights - for (y2 = 2; y2 > -1; y2--) { - for (x2 = 0; x2 < 3; x2++) { + for (int y2 = 2; y2 > -1; y2--) { + for (int x2 = 0; x2 < 3; x2++) { if (x2 == 1 && y2 == 1) nbr.cell[x2][y2] = 0.0; else { if (x2 == 1 || y2 == 1) //not diagonal @@ -1353,8 +1208,8 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, } // determine reciprocal of effective cost for the 8 neighbours - for (y2 = 2; y2 > -1; y2--) { - for (x2 = 0; x2 < 3; x2++) { + for (int y2 = 2; y2 > -1; y2--) { + for (int x2 = 0; x2 < 3; x2++) { if (nbr.cell[x2][y2] > 0.0) nbr.cell[x2][y2] = 1.0f / nbr.cell[x2][y2]; } } @@ -1363,8 +1218,8 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, // to have zero probability // increment total for re-scaling to sum to unity - for (y2 = 2; y2 > -1; y2--) { - for (x2 = 0; x2 < 3; x2++) { + for (int y2 = 2; y2 > -1; y2--) { + for (int x2 = 0; x2 < 3; x2++) { if (!absorbing) { if ((current.y + y2 - 1) < land.minY || (current.y + y2 - 1) > land.maxY || (current.x + x2 - 1) < land.minX || (current.x + x2 - 1) > land.maxX) @@ -1375,15 +1230,14 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, if (pCell == 0) nbr.cell[x2][y2] = 0.0; // no-data cell } } - sum_nbrs += nbr.cell[x2][y2]; } } // scale effective costs as probabilities summing to 1 if (sum_nbrs > 0.0) { // should always be the case, but safest to check... - for (y2 = 2; y2 > -1; y2--) { - for (x2 = 0; x2 < 3; x2++) { + for (int y2 = 2; y2 > -1; y2--) { + for (int x2 = 0; x2 < 3; x2++) { nbr.cell[x2][y2] = nbr.cell[x2][y2] / (float)sum_nbrs; } } @@ -1393,13 +1247,15 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, double cumulative[9]; int j = 0; cumulative[0] = nbr.cell[0][0]; - for (y2 = 0; y2 < 3; y2++) { - for (x2 = 0; x2 < 3; x2++) { + for (int y2 = 0; y2 < 3; y2++) { + for (int x2 = 0; x2 < 3; x2++) { if (j != 0) cumulative[j] = cumulative[j - 1] + nbr.cell[x2][y2]; j++; } } + //to prevent very rare bug that random draw is greater than 0.999999999 + if (cumulative[8] != 1) cumulative[8] = 1; // select direction at random based on cell selection probabilities // landscape boundaries and no-data cells may be reflective or absorbing cellcost = pCurrCell->getCost(); @@ -1408,8 +1264,8 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, do { double rnd = pRandom->Random(); j = 0; - for (y2 = 0; y2 < 3; y2++) { - for (x2 = 0; x2 < 3; x2++) { + for (int y2 = 0; y2 < 3; y2++) { + for (int x2 = 0; x2 < 3; x2++) { if (rnd < cumulative[j]) { newX = current.x + x2 - 1; newY = current.y + y2 - 1; @@ -1444,10 +1300,11 @@ movedata Individual::smsMove(Landscape* pLand, Species* pSpecies, newcellcost = pNewCell->getCost(); move.cost = move.dist * 0.5f * ((float)cellcost + (float)newcellcost); // make the selected move - if ((short)memory.size() == movt.memSize) { + if (memory.full()) { memory.pop(); // remove oldest memory element } memory.push(current); // record previous location in memory + //if (write_out) out << "queue length is " << memory.size() << endl; pCurrCell = pNewCell; } return move; @@ -1462,6 +1319,7 @@ array3x3d Individual::getSimDir(const int x, const int y, const float dp) double theta; int xx, yy; + //if (write_out) out<<"step 0"<(*pTrfrData); if (goaltype == 0) { // no goal set for (xx = 0; xx < 3; xx++) { @@ -1512,7 +1378,7 @@ array3x3d Individual::getGoalBias(const int x, const int y, } else { d.cell[1][1] = 0; - if ((x - smsData->goal.x) == 0 && (y - smsData->goal.y) == 0) { + if ((x - pSMS.goal.x) == 0 && (y - pSMS.goal.y) == 0) { // at goal, set matrix to unity for (xx = 0; xx < 3; xx++) { for (yy = 0; yy < 3; yy++) { @@ -1532,7 +1398,8 @@ array3x3d Individual::getGoalBias(const int x, const int y, return d; } else // goaltype == 2 - theta = atan2(((double)x - (double)smsData->goal.x), ((double)y - (double)smsData->goal.y)); + theta = atan2(((double)x - (double)pSMS.goal.x), ((double)y - (double)pSMS.goal.y)); + // if (write_out) out<<"goalx,goaly: "<getLandData(); - if (absorbing) nodatacost = ABSNODATACOST; - else nodatacost = NODATACOST; + if (absorbing) nodatacost = gAbsorbingNoDataCost; + else nodatacost = gNoDataCost; for (int x2 = -1; x2 < 2; x2++) { // index of relative move in x direction for (int y2 = -1; y2 < 2; y2++) { // index of relative move in x direction @@ -1635,6 +1502,7 @@ array3x3f Individual::getHabMatrix(Landscape* pLand, Species* pSpecies, // calculate effective mean cost of cells in perceptual range ncells = 0; weight = 0.0; sumweights = 0.0; + // targetseen = 0; if (x2 != 0 || y2 != 0) { // not central cell (i.e. current cell) for (int x3 = xmin; x3 <= xmax; x3++) { for (int y3 = ymin; y3 <= ymax; y3++) { @@ -1644,6 +1512,10 @@ array3x3f Individual::getHabMatrix(Landscape* pLand, Species* pSpecies, else { if ((x + x3) > land.maxX) x4 = x + x3 - land.maxX - 1; else x4 = x + x3; } if ((y + y3) < 0) y4 = y + y3 + land.maxY + 1; else { if ((y + y3) > land.maxY) y4 = y + y3 - land.maxY - 1; else y4 = y + y3; } + // if (write_out && (x4 < 0 || y4 < 0)) { + // out<<"ERROR: x "< land.maxX || y4 < 0 || y4 > land.maxY) { // unexpected problem - e.g. due to ridiculously large PR // treat as a no-data cell @@ -1665,7 +1537,7 @@ array3x3f Individual::getHabMatrix(Landscape* pLand, Species* pSpecies, pCell->setCost(cost); } else { - + // nothing? } } } @@ -1711,6 +1583,8 @@ array3x3f Individual::getHabMatrix(Landscape* pLand, Species* pSpecies, } } } + // if (write_out2) out2<<"effective mean cost "<outGenetics(rep, year, spnum, indId, xtab); - } - } - else { // open/close file - pGenome->outGenHeaders(rep, landNr, xtab); - } - -} - #if RS_RCPP +#ifdef _OPENMP +std::mutex outMovePaths_mutex; +#endif + //--------------------------------------------------------------------------- // Write records to movement paths file void Individual::outMovePath(const int year) @@ -1743,6 +1605,9 @@ void Individual::outMovePath(const int year) //if (pPatch != pNatalPatch) { loc = pCurrCell->getLocn(); +#ifdef _OPENMP + const std::lock_guard lock(outMovePaths_mutex); +#endif // if still dispersing... if (status == 1) { // at first step, record start cell first @@ -1760,7 +1625,7 @@ void Individual::outMovePath(const int year) << endl; } // if not anymore dispersing... - if (status > 1 && status < 10) { + if (status > 1 && status <= 10) { prev_loc = pPrevCell->getLocn(); // record only if this is the first step as non-disperser if (path->pathoutput) { @@ -1812,51 +1677,72 @@ double cauchy(double location, double scale) { //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- +#ifdef UNIT_TESTS -#if RSDEBUG - - -void testIndividual() { - - Patch* pPatch = new Patch(0, 0); - int cell_x = 2; - int cell_y = 5; - int cell_hab = 2; - Cell* pCell = new Cell(cell_x, cell_y, (intptr)pPatch, cell_hab); - - // Create an individual - short stg = 0; - short age = 0; - short repInt = 0; - float probmale = 0; - bool uses_movt_process = true; - short moveType = 1; - Individual ind(pCell, pPatch, stg, age, repInt, probmale, uses_movt_process, moveType); - - // An individual can move to a neighbouring cell - //ind.moveto(); - - // Gets its sex drawn from pmale - - // Can age or develop - - // - - // Reproduces - // depending on whether it is sexual or not - // depending on the stage - // depending on the trait inheritance +Cell* Individual::getCurrCell() const { + return pCurrCell; +} +void Individual::setInitAngle(const float angle) { + auto pCRW = dynamic_cast(pTrfrData.get()); + pCRW->prevdrn = angle; +} - // Disperses - // Emigrates - // Transfers - // Settles +// Force mutations to trigger for all traits +void Individual::triggerMutations(Species* pSp) { + for (auto const& [trType, indTrait] : spTraitTable) { + indTrait->mutate(); + if (trType == GENETIC_LOAD1 + || trType == GENETIC_LOAD2 + || trType == GENETIC_LOAD3 + || trType == GENETIC_LOAD4 + || trType == GENETIC_LOAD5) + geneticFitness *= indTrait->express(); + } + this->expressDispersalPhenotypes(pSp, 1.0); +} - // Survives +// Shorthand function to edit a genotype with custom values +void Individual::overrideGenotype(TraitType whichTrait, const map>>& newGenotype) { - // Develops + GeneticFitnessTrait* pGenFitTrait; + DispersalTrait* pDispTrait; -} -#endif // RSDEBUG + switch (whichTrait) + { + case GENETIC_LOAD1: case GENETIC_LOAD2: case GENETIC_LOAD3: case GENETIC_LOAD4: case GENETIC_LOAD5: + pGenFitTrait = dynamic_cast(this->getTrait(whichTrait)); + pGenFitTrait->getGenes() = newGenotype; + break; + case E_D0: case E_ALPHA: case E_BETA: + case S_S0: case S_ALPHA: case S_BETA: + case E_D0_F: case E_ALPHA_F: case E_BETA_F: + case S_S0_F: case S_ALPHA_F: case S_BETA_F: + case E_D0_M: case E_ALPHA_M: case E_BETA_M: + case S_S0_M: case S_ALPHA_M: case S_BETA_M: + case CRW_STEPLENGTH: case CRW_STEPCORRELATION: + case KERNEL_MEANDIST_1: case KERNEL_MEANDIST_2: case KERNEL_PROBABILITY: + case KERNEL_MEANDIST_1_F: case KERNEL_MEANDIST_2_F: case KERNEL_PROBABILITY_F: + case KERNEL_MEANDIST_1_M: case KERNEL_MEANDIST_2_M: case KERNEL_PROBABILITY_M: + case SMS_DP: case SMS_GB: case SMS_ALPHADB: case SMS_BETADB: + pDispTrait = dynamic_cast(this->getTrait(whichTrait)); + pDispTrait->getGenes() = newGenotype; + break; + default: + throw logic_error("Wrong trait type: please choose a valid dispersal or genetic fitness trait."); + break; + } +}; + +void Individual::overrideGenotype(TraitType whichTrait, const map>& newGenotype) { + + if (!whichTrait == NEUTRAL) { + throw logic_error("Attempt to override non-neutral trait with neutral trait genotype.\n"); + } + NeutralTrait* pNeutralTrait; + pNeutralTrait = dynamic_cast(this->getTrait(NEUTRAL)); + pNeutralTrait->getGenes() = newGenotype; +}; + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/Individual.h b/RangeShiftR/src/RScore/Individual.h new file mode 100644 index 0000000..7ec8e50 --- /dev/null +++ b/RangeShiftR/src/RScore/Individual.h @@ -0,0 +1,436 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Tho Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + --------------------------------------------------------------------------*/ + + + + /*------------------------------------------------------------------------------ + + RangeShifter v2.0 Individual + + Implements the Individual class + + Various optional attributes (genes for traits, movement parameters, etc.) are + allocated dynamically and accessed by pointers if required. + + For full details of RangeShifter, please see: + Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial + eco-evolutionary dynamics and species responses to environmental changes. + Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + + Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + + Last updated: 28 July 2021 by Greta Bocedi + + ------------------------------------------------------------------------------*/ + +#ifndef IndividualH +#define IndividualH + + +#include +#include +#include +#include +using namespace std; + +#include "Parameters.h" +#include "Species.h" +#include "Landscape.h" +#include "Patch.h" +#include "Cell.h" +#include "TraitFactory.h" + +#ifdef _OPENMP +#include +#endif // _OPENMP + +//--------------------------------------------------------------------------- + +struct indStats { + short stage; sex_t sex; short age; short status; short fallow; + bool isDeveloping; +}; +struct pathData { // to hold path data common to SMS and CRW models + int year, total, out; // nos. of steps + Patch* pSettPatch; // pointer to most recent patch tested for settlement + short settleStatus; // whether ind may settle in current patch + // 0 = not set, + // 1 = debarred through density dependence rule + // 2 = OK to settle subject to finding a mate + +#if RS_RCPP + short pathoutput; +#endif +}; +struct pathSteps { // nos. of steps for movement model + int year, total, out; +}; +struct settlePatch { + Patch* pSettPatch; short settleStatus; +}; + +struct trfrData { + virtual void addMyself(trfrData& toAdd) = 0; + virtual void clone(const trfrData& copyFrom) = 0; + virtual void divideTraitsBy(int) = 0; + virtual movement_t getType() = 0; + virtual ~trfrData() {} +}; + +struct crwData : trfrData { // to hold data for CRW movement model + + float prevdrn; // direction of previous step (UNITS) + float xc, yc; // continuous cell co-ordinates + float rho; // phenotypic step correlation coefficient + float stepLength; // phenotypic step length (m) + + crwData(float prevdrnA, float xcA, float ycA) : prevdrn(prevdrnA), xc(xcA), yc(ycA), rho(0.0), stepLength(0.0) {} + ~crwData() {} + + void addMyself(trfrData& toAdd) { + auto& CRW = dynamic_cast(toAdd); + CRW.stepLength += stepLength; + CRW.rho += rho; + } + + movement_t getType() { return CRW; } + + void clone(const trfrData& copyFrom) { + const crwData& pCopy = dynamic_cast(copyFrom); + stepLength = pCopy.stepLength; + rho = pCopy.rho; + } + + void divideTraitsBy(int i) { + stepLength /= i; + rho /= i; + } + +}; +struct array3x3d { double cell[3][3]; }; +struct movedata { float dist; float cost; }; +struct smsData : trfrData { + locn prev; // location of previous cell + locn goal; // location of goal + float dp; // directional persistence + float gb; // goal bias + float alphaDB; // dispersal bias decay rate + int betaDB; // dispersal bias decay inflection point (no. of steps) + + smsData(locn prevA, locn goalA) : prev(prevA), goal(goalA), dp(0.0), gb(0.0), alphaDB(0.0), betaDB(0) {} + ~smsData() {} + + void addMyself(trfrData& toAdd) { + auto& SMS = dynamic_cast(toAdd); + SMS.dp += dp; + SMS.gb += gb; + SMS.alphaDB += alphaDB; + SMS.betaDB += betaDB; + } + + movement_t getType() { return SMS; } + + void clone(const trfrData& copyFrom) { + auto& pCopy = dynamic_cast(copyFrom); + dp = pCopy.dp; + gb = pCopy.gb; + alphaDB = pCopy.alphaDB; + betaDB = pCopy.betaDB; + } + + void divideTraitsBy(int i) { + dp /= i; + gb /= i; + alphaDB /= i; + betaDB /= i; + } + +}; + +// A class that mimicks std::queue with a fixed-size circular buffer. +template +class MemoryQueue { + std::unique_ptr data; + const std::size_t space; + std::size_t begin_idx; + std::size_t nb_elts; + +public: + MemoryQueue(std::size_t size); + T& front(); + T const& front() const; + T& back(); + T const& back() const; + void push(const T& value); + void push(T&& value); + void pop(); + std::size_t size() const; + bool empty() const; + bool full() const; +}; + +struct kernelData : trfrData { + float meanDist1; + float meanDist2; + float probKern1; + + kernelData(float meanDist1A, float meanDist2A, float probKern1A) : meanDist1(meanDist1A), meanDist2(meanDist2A), probKern1(probKern1A) {} + ~kernelData() {} + + void addMyself(trfrData& toAdd) { + + auto& Kernel = dynamic_cast(toAdd); + + Kernel.meanDist1 += meanDist1; + Kernel.meanDist2 += meanDist2; + Kernel.probKern1 += probKern1; + } + + movement_t getType() { return KERNEL; } + + void clone(const trfrData& copyFrom) { + const kernelData& pCopy = dynamic_cast(copyFrom); + meanDist1 = pCopy.meanDist1; + meanDist2 = pCopy.meanDist2; + probKern1 = pCopy.probKern1; + } + + void divideTraitsBy(int i) { + meanDist1 /= i; + meanDist2 /= i; + probKern1 /= i; + } +}; + + +class Individual { + +public: +#ifdef _OPENMP + static std::atomic indCounter; // used to create ID, held by class, not members of class +#else + static int indCounter; // used to create ID, held by class, not members of class +#endif + static TraitFactory traitFactory; + Individual( // Individual constructor + Species*, // pointer to species + Cell*, // pointer to Cell + Patch*, // pointer to patch + short, // stage + short, // age + short, // reproduction interval (no. of years/seasons between breeding attempts) + float, // probability that sex is male + bool, // TRUE for a movement model, FALSE for kernel-based transfer + short // movement type: 1 = SMS, 2 = CRW + ); + ~Individual(void); + void setUpGenes( // Set genes for individual variation from species initialisation parameters + Species*, // pointer to Species + int // Landscape resolution + ); + void inheritTraits( // Inherit genome from parents + Species*, // pointer to Species + Individual*, // pointer to mother + Individual*, // pointer to father (must be 0 for an asexual Species) + int // Landscape resolution + ); + + void inheritTraits(Species* pSpecies, Individual* mother, int resol); //haploid + + void expressDispersalPhenotypes(Species* pSpecies, int resol); + + void expressGeneticLoad(Species* pSpecies); + + QuantitativeTrait* getTrait(TraitType trait) const; + + set getTraitTypes(); + + void inherit(Species* pSpecies, const Individual* mother, const Individual* father); + + void inherit(Species* pSpecies, const Individual* mother); // haploid + + void setEmigTraits(Species* pSpecies, bool sexDep, bool densityDep); + void setTransferTraits(Species* pSpecies, transferRules trfr, int resol); + + emigTraits getIndEmigTraits(void); // Get phenotypic emigration traits + + void setIndKernelTraits(Species* pSpecies, bool sexDep, bool twinKernel, int resol); + + trfrKernelParams getIndKernTraits(void); // Get phenotypic transfer by kernel traits + + void setIndSMSTraits(Species* pSpecies); + + trfrSMSTraits getIndSMSTraits(void); // Get phenotypic transfer by SMS traits + + void setIndCRWTraits(Species* pSpecies); + + trfrCRWTraits getIndCRWTraits(void); // Get phenotypic transfer by CRW traits + + void setSettlementTraits(Species* pSpecies, bool sexDep, bool densDep); + + settleTraits getIndSettTraits(void); // Get phenotypic settlement traits + + trfrData* getTrfrData(void); + void setEmigTraits(const emigTraits& emig); + void setSettleTraits(const settleTraits& settle); + + + // Identify whether an individual is a potentially breeding female - + // if so, return her stage, otherwise return 0 + int breedingFem(void); + int getId(void); + sex_t getSex(void); + int getStatus(void); + float getGeneticFitness(void); + bool isViable() const; + indStats getStats(void); + Cell* getPrevCell(); // Return previous location (as pointer to Cell) + Cell* getCurrCell(); // Return current location (as pointer to Cell) + Patch* getNatalPatch(void); + void setYearSteps(int); + pathSteps getSteps(void); + settlePatch getSettPatch(void); + void setSettPatch(const settlePatch); + void setStatus(short); + void setToDevelop(void); + void develop(void); + void ageIncrement( // Age by one year + short // maximum age - if exceeded, the Individual dies + ); + void incFallow(void); // Inrement no. of reproductive seasons since last reproduction + void resetFallow(void); + void moveto( // Move to a specified neighbouring cell + Cell* // pointer to the new cell + ); + // Move to a new cell by sampling a dispersal distance from a single or double + // negative exponential kernel + // Returns 1 if still dispersing (including having found a potential patch), otherwise 0 + int moveKernel( + Landscape*, // pointer to Landscape + Species*, // pointer to Species + const bool // absorbing boundaries? + ); + // Make a single movement step according to a mechanistic movement model + // Returns 1 if still dispersing (including having found a potential patch), otherwise 0 + int moveStep( + Landscape*, // pointer to Landscape + Species*, // pointer to Species + const short, // landscape change index + const bool // absorbing boundaries? + ); + movedata smsMove( // Move to a neighbouring cell according to the SMS algorithm + Landscape*, // pointer to Landscape + Species*, // pointer to Species + const short, // landscape change index + const bool, // TRUE if still in (or returned to) natal patch + const bool, // individual variability? + const bool // absorbing boundaries? + ); + array3x3d getSimDir( // Weight neighbouring cells on basis of current movement direction + const int, // current x co-ordinate + const int, // current y co-ordinate + const float // directional persistence value + ); + array3x3d getGoalBias( // Weight neighbouring cells on basis of goal bias + const int, // current x co-ordinate + const int, // current y co-ordinate + const int, // goal type: 0 = none, 1 = towards goal (NOT IMPLEMENTED), 2 = dispersal bias + const float // GOAL BIAS VALUE + ); + array3x3d calcWeightings( // Calculate weightings for neighbouring cells + const double, // base for power-law (directional persistence or goal bias value) + const double // direction in which lowest (unit) weighting is to be applied + ); + array3x3f getHabMatrix( // Weight neighbouring cells on basis of (habitat) costs + Landscape*, // pointer to Landscape + Species*, // pointer to Species + const int, // current x co-ordinate + const int, // current y co-ordinate + const short, // perceptual range (cells) + const short, // perceptual range evaluation method (see Species) + const short, // landscape change index + const bool // absorbing boundaries? + ); +#if RS_RCPP + void outMovePath( // Write records to movement paths file + const int // year + ); +#endif +#ifdef UNIT_TESTS + // Testing utilities + Cell* getCurrCell() const; + void setInitAngle(const float angle); + void insertIndDispTrait(TraitType trType, DispersalTrait tr) { + spTraitTable.insert(make_pair(trType, make_unique(tr))); + }; + void triggerMutations(Species* pSp); + // Shorthand function to edit a genotype with custom values + void overrideGenotype(TraitType whichTrait, const map>>& newGenotype); // dispersal + gen. fitness + void overrideGenotype(TraitType whichTrait, const map>& newGenotype); // neutral +#endif + +private: + int indId; + float geneticFitness; + short stage; + sex_t sex; + short age; + short status; + // 0 = initial status in natal patch / philopatric recruit + // 1 = disperser + // 2 = disperser awaiting settlement in possible suitable patch + // 3 = waiting between dispersal events + // 4 = completed settlement + // 5 = completed settlement in a suitable neighbouring cell + // 6 = died during transfer by failing to find a suitable patch + // (includes exceeding maximum number of steps or crossing + // absorbing boundary) + // 7 = died during transfer by constant, step-dependent, + // habitat-dependent or distance-dependent mortality + // 8 = failed to survive annual (demographic) mortality + // 9 = exceeded maximum age + short fallow; // reproductive seasons since last reproduction + bool isDeveloping; + Cell* pPrevCell; // pointer to previous Cell + Cell* pCurrCell; // pointer to current Cell + Patch* pNatalPatch; // pointer to natal Patch + pathData* path; // pointer to path data for movement model + std::unique_ptr pEmigTraits; // pointer to emigration traits + std::unique_ptr pSettleTraits; // pointer to settlement traits + std::unique_ptr pTrfrData; //can be sms, kernel, crw + MemoryQueue memory; // memory of last N squares visited for SMS + map> spTraitTable; +}; + + +//--------------------------------------------------------------------------- + +double cauchy(double location, double scale); +double wrpcauchy(double location, double rho = exp(double(-1))); + +extern RSrandom* pRandom; + +#if RS_RCPP +extern ofstream outMovePaths; +#endif + +//--------------------------------------------------------------------------- +#endif // IndividualH diff --git a/RangeShiftR/src/RScore/LICENSE b/RangeShiftR/src/RScore/LICENSE new file mode 100644 index 0000000..94a9ed0 --- /dev/null +++ b/RangeShiftR/src/RScore/LICENSE @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/Landscape.cpp b/RangeShiftR/src/RScore/Landscape.cpp similarity index 60% rename from Landscape.cpp rename to RangeShiftR/src/RScore/Landscape.cpp index f1c810a..9dfa04b 100644 --- a/Landscape.cpp +++ b/RangeShiftR/src/RScore/Landscape.cpp @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -40,7 +40,7 @@ ofstream outMovePaths; InitDist::InitDist(Species* pSp) { pSpecies = pSp; - resol = 0; + resol = 1; maxX = 0; maxY = 0; minEast = 0.0; @@ -171,15 +171,7 @@ int InitDist::readDistribution(string distfile) { #endif // open distribution file -#if !RS_RCPP || RSWIN64 dfile.open(distfile.c_str()); -#else - dfile.open(distfile, std::ios::binary); - if (spdistraster.utf) { - // apply BOM-sensitive UTF-16 facet - dfile.imbue(std::locale(dfile.getloc(), new std::codecvt_utf16)); - } -#endif if (!dfile.is_open()) return 21; // read landscape data from header records of distribution file @@ -244,7 +236,48 @@ if (!dfile.eof()) EOFerrorR(distfile); return 0; } +// Read species initial distribution file for threadsafe option +#if RS_RCPP +int InitDist::readDistribution(Rcpp::NumericMatrix distfile, landOrigin habfile_origin, int spResol) { + + int d=0; + double dfloat=0; + int ncols,nrows; + + ncols = distfile.ncol(); + nrows = distfile.nrow(); + + minEast = habfile_origin.minEast; + minNorth = habfile_origin.minNorth; + resol = spResol; + maxX = ncols-1; + maxY = nrows-1; + + for (int y = nrows-1; y >= 0; y--) { + for (int x = 0; x < ncols; x++) { + + dfloat = distfile(nrows-1-y,x); + + if ( !R_IsNA(dfloat) ){ // check for NA + d = (int)dfloat; + if ( d == 0 || d == 1) { // only valid values + if (d == 1) { // species present + cells.push_back(new DistCell(x,y)); + } + } + else { // error in file +#if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found invalid value in species distribution raster." << std::endl; +#endif + return 22; + } + } + } + } + return 0; +} +#endif //--------------------------------------------------------------------------- // Landscape functions @@ -252,7 +285,8 @@ if (!dfile.eof()) EOFerrorR(distfile); Landscape::Landscape(void) { patchModel = false; spDist = false; generated = false; fractal = false; continuous = false; dynamic = false; habIndexed = false; - resol = spResol = landNum = 0; + spatialdemog = false; + resol = spResol = 1; landNum = 0; rasterType = 0; nHab = nHabMax = 0; dimX = dimY = 100; @@ -274,9 +308,7 @@ Landscape::~Landscape() { if (cells != 0) { for (int y = dimY - 1; y >= 0; y--) { - for (int x = 0; x < dimX; x++) { - if (cells[y][x] != 0) delete cells[y][x]; } if (cells[y] != 0) { @@ -286,6 +318,7 @@ Landscape::~Landscape() { delete[] cells; cells = 0; } + int npatches = (int)patches.size(); for (int i = 0; i < npatches; i++) if (patches[i] != NULL) delete patches[i]; @@ -301,27 +334,22 @@ Landscape::~Landscape() { if (initcells[i] != NULL) delete initcells[i]; initcells.clear(); - patchnums.clear(); habCodes.clear(); - colours.clear(); landchanges.clear(); patchchanges.clear(); deleteConnectMatrix(); deletePatchChgMatrix(); if (epsGlobal != 0) delete[] epsGlobal; - } // Remove all patches and cells // Used for replicating artificial landscape without deleting the landscape itself void Landscape::resetLand(void) { - resetLandLimits(); int npatches = (int)patches.size(); for (int i = 0; i < npatches; i++) if (patches[i] != NULL) delete patches[i]; patches.clear(); - if (cells != 0) { for (int y = dimY - 1; y >= 0; y--) { for (int x = 0; x < dimX; x++) { @@ -338,9 +366,12 @@ void Landscape::resetLand(void) { void Landscape::setLandParams(landParams ppp, bool batchMode) { - generated = ppp.generated; patchModel = ppp.patchModel; spDist = ppp.spDist; + generated = ppp.generated; + patchModel = ppp.patchModel; + spDist = ppp.spDist; dynamic = ppp.dynamic; landNum = ppp.landNum; + spatialdemog = ppp.spatialdemog; if (ppp.resol > 0) resol = ppp.resol; if (ppp.spResol > 0 && ppp.spResol % ppp.resol == 0) spResol = ppp.spResol; if ((ppp.rasterType >= 0 && ppp.rasterType <= 2) || ppp.rasterType == 9) @@ -376,6 +407,7 @@ landParams Landscape::getLandParams(void) landParams ppp; ppp.generated = generated; ppp.patchModel = patchModel; ppp.spDist = spDist; ppp.dynamic = dynamic; + ppp.spatialdemog = spatialdemog; ppp.landNum = landNum; ppp.resol = resol; ppp.spResol = spResol; ppp.rasterType = rasterType; @@ -500,32 +532,12 @@ int Landscape::getHabCode(int ixhab) { void Landscape::clearHabitats(void) { habCodes.clear(); - colours.clear(); -} - -void Landscape::addColour(rgb c) { - colours.push_back(c); -} - -void Landscape::changeColour(int i, rgb col) { - int ncolours = (int)colours.size(); - if (i >= 0 && i < ncolours) { - if (col.r >= 0 && col.r <= 255 && col.g >= 0 && col.g <= 255 && col.b >= 0 && col.b <= 255) - colours[i] = col; - } -} - -rgb Landscape::getColour(int ix) { - return colours[ix]; -} - -int Landscape::colourCount(void) { - return (int)colours.size(); } //--------------------------------------------------------------------------- void Landscape::setCellArray(void) { if (cells != 0) resetLand(); + //cells = new Cell **[maxY+1]; cells = new Cell * *[dimY]; for (int y = dimY - 1; y >= 0; y--) { cells[y] = new Cell * [dimX]; @@ -535,23 +547,11 @@ void Landscape::setCellArray(void) { } } -void Landscape::addPatchNum(int p) { - int npatches = (int)patchnums.size(); - bool addpatch = true; - for (int i = 0; i < npatches; i++) { - if (p == patchnums[i]) { - addpatch = false; i = npatches + 1; - } - } - if (addpatch) patchnums.push_back(p); -} - - //--------------------------------------------------------------------------- /* Create an artificial landscape (random or fractal), which can be either binary (habitat index 0 is the matrix, 1 is suitable habitat) or continuous (0 is the matrix, >0 is suitable habitat) */ -void Landscape::generatePatches(void) +void Landscape::generatePatches() { int x, y, ncells; double p; @@ -559,7 +559,6 @@ void Landscape::generatePatches(void) Cell* pCell; vector ArtLandscape; - setCellArray(); int patchnum = 0; // initial patch number for cell-based landscape @@ -727,12 +726,10 @@ void Landscape::allocatePatches(Species* pSpecies) case 2: // habitat quality for (int y = dimY - 1; y >= 0; y--) { for (int x = 0; x < dimX; x++) { - if (cells[y][x] != 0) { // not no-data cell pCell = cells[y][x]; habK = 0.0; int nhab = pCell->nHabitats(); - // for (int i = 0; i < nHab; i++) for (int i = 0; i < nhab; i++) { habK += pSpecies->getHabK(0) * pCell->getHabitat(i) / 100.0f; @@ -788,12 +785,20 @@ void Landscape::addNewCellToLand(int x, int y, int hab) { cells[y][x] = new Cell(x, y, 0, hab); } +void Landscape::addCellToLand(Cell* c) { + if (cells == 0) throw runtime_error("Landscape cells member is uninitialised."); + if (c->getHabIndex(0) < 0.0) + throw logic_error("Can't add no-data cell to landscape."); + locn l = c->getLocn(); + cells[l.y][l.x] = c; +} + void Landscape::addNewCellToPatch(Patch* pPatch, int x, int y, float q) { if (q < 0.0) { // no-data cell - no Cell created cells[y][x] = 0; } else { // create the new cell - cells[y][x] = new Cell(x, y, (intptr)pPatch, q); + cells[y][x] = new Cell(x, y, pPatch, q); if (pPatch != 0) { // not the matrix patch // add the cell to the patch pPatch->addCell(cells[y][x], x, y); @@ -805,7 +810,7 @@ void Landscape::addNewCellToPatch(Patch* pPatch, int x, int y, int hab) { if (hab < 0) // no-data cell - no Cell created cells[y][x] = 0; else { // create the new cell - cells[y][x] = new Cell(x, y, (intptr)pPatch, hab); + cells[y][x] = new Cell(x, y, pPatch, hab); if (pPatch != 0) { // not the matrix patch // add the cell to the patch pPatch->addCell(cells[y][x], x, y); @@ -814,14 +819,14 @@ void Landscape::addNewCellToPatch(Patch* pPatch, int x, int y, int hab) { } void Landscape::addCellToPatch(Cell* pCell, Patch* pPatch) { - pCell->setPatch((intptr)pPatch); + pCell->setPatch(pPatch); locn loc = pCell->getLocn(); // add the cell to the patch pPatch->addCell(pCell, loc.x, loc.y); } void Landscape::addCellToPatch(Cell* pCell, Patch* pPatch, float q) { - pCell->setPatch((intptr)pPatch); + pCell->setPatch(pPatch); // update the habitat type of the cell pCell->setHabitat(q); locn loc = pCell->getLocn(); @@ -830,7 +835,7 @@ void Landscape::addCellToPatch(Cell* pCell, Patch* pPatch, float q) { } void Landscape::addCellToPatch(Cell* pCell, Patch* pPatch, int hab) { - pCell->setPatch((intptr)pPatch); + pCell->setPatch(pPatch); // update the habitat type of the cell pCell->setHabIndex(hab); locn loc = pCell->getLocn(); @@ -867,6 +872,46 @@ Patch* Landscape::findPatch(int num) { return 0; } + +set Landscape::getPatchNbs() const { + set patchNbs; + for (auto& p : patches) + patchNbs.emplace(p->getPatchNum()); + return patchNbs; +} + +set Landscape::samplePatches(const string& samplingOption, int nbToSample, Species* pSpecies) { + + vector sampledPatches; + vector eligiblePatches; + + // Get list of viable patches where the species is present + for (auto p : patches) { + if (p->getPatchNum() == 0) continue; // skip patch 0, the matrix + if (samplingOption == "random" // then all patches are eligible + || p->speciesIsPresent(pSpecies)) // otherwise only patches with at least 1 ind + eligiblePatches.push_back(p->getPatchNum()); + } + + if (samplingOption == "all") { + sampledPatches = eligiblePatches; + } + else if (samplingOption == "random_occupied" || samplingOption == "random") { + if (nbToSample > eligiblePatches.size()) + nbToSample = eligiblePatches.size(); + auto rng = pRandom->getRNG(); + sample(eligiblePatches.begin(), eligiblePatches.end(), std::back_inserter(sampledPatches), + nbToSample, rng); + } + else { + throw logic_error("Sampling option should be random, random_occupied or all when sampling patches."); + } + + set patchIds; + copy(sampledPatches.begin(), sampledPatches.end(), inserter(patchIds, patchIds.end())); + return patchIds; +} + void Landscape::resetPatchPopns(void) { int npatches = (int)patches.size(); for (int i = 0; i < npatches; i++) { @@ -891,11 +936,35 @@ void Landscape::updateCarryingCapacity(Species* pSpecies, int yr, short landIx) } +void Landscape::updateDemoScalings(short landIx) { + + patchLimits landlimits; + landlimits.xMin = minX; landlimits.xMax = maxX; + landlimits.yMin = minY; landlimits.yMax = maxY; + + if(spatialdemog && rasterType == 2) {// demographic scaling only implemented for habitat quality maps + int npatches = (int)patches.size(); // new: for (auto& p : patches) + for (int i = 0; i < npatches; i++) { + if (patches[i]->getPatchNum() != 0) { // not matrix patch + // calculate local scaling for each patch from its constituent cells + patches[i]->setPatchDemoScaling(landIx, landlimits); + } + } + } +} + Cell* Landscape::findCell(int x, int y) { if (x >= 0 && x < dimX && y >= 0 && y < dimY) return cells[y][x]; else return 0; } +bool Landscape::checkDataCell(int x, int y) { + Cell* pCell; + pCell = findCell(x, y); + return true; +} + + int Landscape::patchCount(void) { return (int)patches.size(); } @@ -964,10 +1033,8 @@ void Landscape::updateHabitatIndices(void) { if (cells[y][x] != 0) { // not a no-data cell for (int c = 0; c <= changes; c++) { h = cells[y][x]->getHabIndex(c); - if (h >= 0) { h = findHabCode(h); - cells[y][x]->changeHabIndex(c, h); } } @@ -981,6 +1048,7 @@ void Landscape::setEnvGradient(Species* pSpecies, bool initial) { float dist_from_opt, dev; float habK; + //int hab; double envval; // gradient parameters envGradParams grad = paramsGrad->getGradient(); @@ -1004,7 +1072,6 @@ void Landscape::setEnvGradient(Species* pSpecies, bool initial) break; } } - if (habK > 0.0) { // suitable cell if (initial) { // set local environmental deviation cells[y][x]->setEnvDev((float)pRandom->Random() * (2.0f) - 1.0f); @@ -1087,8 +1154,8 @@ void Landscape::addLandChange(landChange c) { int Landscape::numLandChanges(void) { return (int)landchanges.size(); } landChange Landscape::getLandChange(short ix) { - landChange c; c.chgnum = c.chgyear = 0; - c.habfile = c.pchfile = c.costfile = "none"; + landChange c; c.chgNb = c.chgYear = 0; + c.pathHabFile = c.pathPatchFile = c.pathCostFile = "none"; int nchanges = (int)landchanges.size(); if (ix < nchanges) c = landchanges[ix]; return c; @@ -1098,18 +1165,198 @@ void Landscape::deleteLandChanges(void) { while (landchanges.size() > 0) landchanges.pop_back(); landchanges.clear(); } +#if RS_RCPP +int Landscape::readLandChange(int filenum, Rcpp::NumericMatrix habfile, Rcpp::NumericMatrix pchfile, Rcpp::NumericMatrix costfile, Rcpp::NumericVector scalinglayers){ -#if RS_RCPP && !R_CMD -int Landscape::readLandChange(int filenum, bool costs, wifstream& hfile, wifstream& pfile, wifstream& cfile, int habnodata, int pchnodata, int costnodata) -#else -int Landscape::readLandChange(int filenum, bool costs) + if (filenum < 0) return 19; + + int h = 0, p = 0, c = 0, pchseq = 0; + double hfloat = 0,pfloat = 0,cfloat = 0; + bool costs = false; + if(costfile.nrow()>0 && costfile.ncol()>0) costs = true; + + arma::vec cellDemoScalings; // vector to store local demog scalings + Rcpp::IntegerVector DSdim; + int nrDemogScaleLayers = 0; + if(scalinglayers.attr("dim")==R_NilValue) DSdim = Rcpp::IntegerVector::create(1,1,1); + else{ + DSdim = scalinglayers.attr("dim"); + if(DSdim.size()>2) nrDemogScaleLayers = DSdim[2]; //nr of slices on cube + else nrDemogScaleLayers = 1; + } + arma::cube scalingCube(scalinglayers.begin(),DSdim[0],DSdim[1],nrDemogScaleLayers,false); // turn scaling layers into a cube + + simParams sim = paramsSim->getSim(); + + if (patchModel) pchseq = patchCount(); + + switch (rasterType) { + + case 0: // raster with habitat codes - 100% habitat each cell + + for (int y = dimY-1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + + // get numerics from each raster for this cell + hfloat = habfile(dimY-1-y,x); + if (patchModel) pfloat = pchfile(dimY-1-y,x); + if (costs) cfloat = costfile(dimY-1-y,x); + + if (cells[y][x] != 0) { // not a no data cell (in initial landscape) + if ( R_IsNA(hfloat) ){ // invalid no data cell in change map + return 36; + } + else { + h = (int)hfloat; + if (h < 0 || (sim.batchMode && (h < 1 || h > nHabMax))) { // invalid habitat code + return 33; + } + else { + addHabCode(h); + cells[y][x]->setHabIndex(h); + } + } + if (patchModel) { + if ( R_IsNA(pfloat) ){ + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + #endif + return 34; + } + else { + p = (int)pfloat; + if (p < 0 ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; + #endif + return 34; + } + else { + patchChgMatrix[y][x][2] = p; + if (p > 0 && !existsPatch(p)) { + // addPatchNum(p); // was removed - why? + newPatch(pchseq++,p); + } + } + } + } + if (costs) { + if ( R_IsNA(cfloat) ){ // invalid cost + return 38; + } + else{ + c = (int)cfloat; + if (c < 1) { // invalid cost + return 38; + } + else { + costsChgMatrix[y][x][2] = c; + } + } + } + } + } + } + break; + + case 2: // habitat quality + + for (int y = dimY-1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + + // get numerics from each raster for this cell + hfloat = habfile(dimY-1-y,x); + if (patchModel) pfloat = pchfile(dimY-1-y,x); + if (costs) cfloat = costfile(dimY-1-y,x); + + if (cells[y][x] != 0) { // not a no data cell (in initial landscape) + if ( R_IsNA(hfloat) ){ // invalid no data cell in change map + Rcpp::Rcout << "Found NA in valid habitat cell. For landscape nb "<< filenum + 2 << std::endl; + return 36; + } + else { + if (hfloat < 0.0 || hfloat > 100.0) { // invalid quality score + Rcpp::Rcout << "Found invalid habitat quality value " << hfloat << " in valid habitat cell." << std::endl; + return 37; + } + else { + cells[y][x]->setHabitat((float)hfloat); + } + } + if (patchModel) { + if ( R_IsNA(pfloat) ){ + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + #endif + return 34; + } + else { + p = (int)pfloat; + if (p < 0 ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; + #endif + return 34; + } + else { + patchChgMatrix[y][x][2] = p; + if (p > 0 && !existsPatch(p)) { + //addPatchNum(p); // was removed - why? + newPatch(pchseq++,p); + } + } + } + } + if (costs) { + if ( R_IsNA(cfloat) ){ // invalid cost + return 38; + } + else{ + c = (int)cfloat; + if (c < 1) { // invalid cost + return 38; + } + else { + costsChgMatrix[y][x][2] = c; + } + } + } + //SPATIALDEMOG + // read demographic scalings + if(nrDemogScaleLayers>0){ + // get tube at (y/x) + cellDemoScalings = scalingCube(arma::span(dimY-1-y), arma::span(x), arma::span::all); + if(cellDemoScalings.n_elem==(unsigned)nDSlayer){ + // set vector percentage values in cell + cells[y][x]->addchgDemoScaling(arma::conv_to< std::vector >::from(cellDemoScalings)); + } + else{// invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Wrong number of demographic scaling layers in cell " << x << " ," << y << " at dyn land change nr " << filenum << std::endl; + #endif + return 39; + } + }// SPATIALDEMOG End + + } + } + } + break; + + default: + break; + } + + return 0; +} #endif -{ -#if RSDEBUG - DEBUGLOG << "Landscape::readLandChange(): filenum=" << filenum << " costs=" << int(costs) - << endl; +#if RS_RCPP && !R_CMD // normal file input +int Landscape::readLandChange(int filenum, bool costs, wifstream& hfile, wifstream& pfile, wifstream& cfile, int habnodata, int pchnodata, int costnodata, vector scalinglayers) +#else +int Landscape::readLandChange(int filenum, bool costs, vector scalinglayers) #endif +{ #if RS_RCPP wstring header; @@ -1134,17 +1381,17 @@ int Landscape::readLandChange(int filenum, bool costs) #if !RS_RCPP || R_CMD // open habitat file and optionally also patch and costs files - hfile.open(landchanges[filenum].habfile.c_str()); + hfile.open(landchanges[filenum].pathHabFile.c_str()); if (!hfile.is_open()) return 30; if (patchModel) { - pfile.open(landchanges[filenum].pchfile.c_str()); + pfile.open(landchanges[filenum].pathPatchFile.c_str()); if (!pfile.is_open()) { hfile.close(); hfile.clear(); return 31; } } if (costs) { - cfile.open(landchanges[filenum].costfile.c_str()); + cfile.open(landchanges[filenum].pathCostFile.c_str()); if (!cfile.is_open()) { hfile.close(); hfile.clear(); if (pfile.is_open()) { @@ -1278,7 +1525,7 @@ int Landscape::readLandChange(int filenum, bool costs) else { patchChgMatrix[y][x][2] = p; if (p > 0 && !existsPatch(p)) { - addPatchNum(p); + // addPatchNum(p); why is it removed? newPatch(pchseq++, p); } } @@ -1419,7 +1666,7 @@ int Landscape::readLandChange(int filenum, bool costs) else { patchChgMatrix[y][x][2] = p; if (p > 0 && !existsPatch(p)) { - addPatchNum(p); + // addPatchNum(p); // was removed - why? newPatch(pchseq++, p); } } @@ -1465,6 +1712,13 @@ int Landscape::readLandChange(int filenum, bool costs) if (hfile.is_open()) { hfile.close(); hfile.clear(); } if (pfile.is_open()) { pfile.close(); pfile.clear(); } if (cfile.is_open()) { cfile.close(); cfile.clear(); } + + // add here the reading of demographic scaling layers + if(scalinglayers.size()>0){ + int retcode = readDemographicScaling(scalinglayers); + if (retcode < 0) return 54; //change number + } + return 0; } @@ -1472,7 +1726,6 @@ int Landscape::readLandChange(int filenum, bool costs) // Create & initialise patch change matrix void Landscape::createPatchChgMatrix(void) { - intptr patch; Patch* pPatch; Cell* pCell; if (patchChgMatrix != 0) deletePatchChgMatrix(); @@ -1487,12 +1740,11 @@ void Landscape::createPatchChgMatrix(void) } else { // record initial patch number - patch = pCell->getPatch(); - if (patch == 0) { // matrix cell + pPatch = pCell->getPatch(); + if (pPatch == nullptr) { // matrix cell patchChgMatrix[y][x][0] = patchChgMatrix[y][x][1] = 0; } else { - pPatch = (Patch*)patch; patchChgMatrix[y][x][0] = patchChgMatrix[y][x][1] = pPatch->getPatchNum(); } } @@ -1535,8 +1787,11 @@ void Landscape::recordPatchChanges(int landIx) { int Landscape::numPatchChanges(void) { return (int)patchchanges.size(); } patchChange Landscape::getPatchChange(int i) { - patchChange c; c.chgnum = 99999999; c.x = c.y = c.oldpatch = c.newpatch = -1; - if (i >= 0 && i < (int)patchchanges.size()) c = patchchanges[i]; + patchChange c; + c.chgnum = 99999999; + c.x = c.y = c.oldpatch = c.newpatch = -1; + if (i >= 0 && i < (int)patchchanges.size()) + c = patchchanges[i]; return c; } @@ -1555,6 +1810,8 @@ void Landscape::deletePatchChgMatrix(void) { // Create & initialise costs change matrix void Landscape::createCostsChgMatrix(void) { + //intptr patch; + //Patch *pPatch; Cell* pCell; if (costsChgMatrix != 0) deleteCostsChgMatrix(); costsChgMatrix = new int** [dimY]; @@ -1576,9 +1833,7 @@ void Landscape::createCostsChgMatrix(void) } void Landscape::recordCostChanges(int landIx) { -#if RSDEBUG - DEBUGLOG << "Landscape::recordCostChanges(): landIx=" << landIx << endl; -#endif + if (costsChgMatrix == 0) return; // should not occur costChange chg; @@ -1633,7 +1888,24 @@ void Landscape::deleteCostsChgMatrix(void) { // Species distribution functions -int Landscape::newDistribution(Species* pSpecies, string distname) { +//If file input as R objects only for #RS_RCPP +#if RS_RCPP +int Landscape::newDistribution(Species *pSpecies, Rcpp::NumericMatrix distname, int spResol) { + int readcode; + int ndistns = (int)distns.size(); + distns.push_back(new InitDist(pSpecies)); + landOrigin habfile_origin = this->getOrigin(); + readcode = distns[ndistns]->readDistribution(distname,habfile_origin,spResol); + if (readcode != 0) { // error encountered + // delete the distribution created above + delete distns[ndistns]; + distns.pop_back(); + } + return readcode; +} +#endif +// Standard file input +int Landscape::newDistribution(Species *pSpecies, string distname) { int readcode; int ndistns = (int)distns.size(); distns.push_back(new InitDist(pSpecies)); @@ -1646,6 +1918,7 @@ int Landscape::newDistribution(Species* pSpecies, string distname) { return readcode; } + void Landscape::setDistribution(Species* pSpecies, int nInit) { // WILL NEED TO SELECT DISTRIBUTION FOR CORRECT SPECIES ... // ... CURRENTLY IT IS THE ONLY ONE @@ -1664,10 +1937,6 @@ bool Landscape::inInitialDist(Species* pSpecies, locn loc) { } void Landscape::deleteDistribution(Species* pSpecies) { - // WILL NEED TO SELECT DISTRIBUTION FOR CORRECT SPECIES ... - // ... CURRENTLY IT IS THE ONLY ONE ... - // ... FOR MULTIPLE SPECIES IT MAY BE BETTER TO USE A DYNAMIC ARRAY FOR - // SPECIES DISTRIBUTIONS INDEXED BY SPECIES NUMBER, RATHER THAN A VECTOR if (distns[0] != 0) delete distns[0]; distns.clear(); } @@ -1741,367 +2010,663 @@ void Landscape::clearInitCells(void) { // Read landscape file(s) // Returns error code or zero if read correctly -int Landscape::readLandscape(int fileNum, string habfile, string pchfile, string costfile) -{ - // fileNum == 0 for (first) habitat file and optional patch file - // fileNum > 0 for subsequent habitat files under the %cover option - +// for new landscape input using R objects AND spatial demography: only for RS_RCPP +// RS_THREADSAFE and SPATIALDEMOG #if RS_RCPP - wstring header; -#else - string header; -#endif - int h, seq, p, habnodata; - int pchnodata = 0; - int ncols, nrows; - float hfloat, pfloat; - Patch* pPatch; - simParams sim = paramsSim->getSim(); - +int Landscape::readLandscape(int fileNum, Rcpp::NumericMatrix habfile, Rcpp::NumericMatrix pchfile, Rcpp::NumericMatrix costfile, Rcpp::NumericVector scalinglayers) { if (fileNum < 0) return 19; -#if RS_RCPP - wifstream hfile; // habitat file input stream - wifstream pfile; // patch file input stream -#else - ifstream hfile; // habitat file input stream - ifstream pfile; // patch file input stream -#endif + int habCode,seq,patchCode,ncols,nrows,hc,maxcost = 0; + double habFloat,patchFloat,costFloat; + Patch *pPatch; + Cell *pCell; + simParams sim = paramsSim->getSim(); initParams init = paramsInit->getInit(); - // open habitat file and optionally also patch file -#if !RS_RCPP || RSWIN64 - hfile.open(habfile.c_str()); -#else - hfile.open(habfile, std::ios::binary); - if (landraster.utf) { - // apply BOM-sensitive UTF-16 facet - hfile.imbue(std::locale(hfile.getloc(), new std::codecvt_utf16)); - } -#endif - if (!hfile.is_open()) return 11; - if (fileNum == 0) { - if (patchModel) { -#if !RS_RCPP || RSWIN64 - pfile.open(pchfile.c_str()); -#else - pfile.open(pchfile, std::ios::binary); - if (patchraster.utf) { - // apply BOM-sensitive UTF-16 facet - pfile.imbue(std::locale(pfile.getloc(), new std::codecvt_utf16)); - } -#endif - if (!pfile.is_open()) { - hfile.close(); hfile.clear(); - return 12; - } - } - } - -// read landscape data from header records of habitat file -// NB headers of all files have already been compared -double tmpresol; -hfile >> header >> ncols >> header >> nrows >> header >> minEast >> header >> minNorth - >> header >> tmpresol >> header >> habnodata; -resol = (int) tmpresol; - -#if RS_RCPP - if (!hfile.good()) { - // corrupt file stream - StreamErrorR(habfile); - hfile.close(); - hfile.clear(); - if (patchModel) { - pfile.close(); - pfile.clear(); - } - return 131; - } -#endif - - dimX = ncols; dimY = nrows; minX = maxY = 0; maxX = dimX - 1; maxY = dimY - 1; + // initialise landscape size + ncols = habfile.ncol(); + nrows = habfile.nrow(); + dimX = ncols; dimY = nrows; + minX = maxY = 0; + maxX = dimX-1; maxY = dimY-1; if (fileNum == 0) { // set initialisation limits to landscape limits init.minSeedX = init.minSeedY = 0; init.maxSeedX = maxX; init.maxSeedY = maxY; paramsInit->setInit(init); - } - - if (fileNum == 0) { - if (patchModel) { - for (int i = 0; i < 5; i++) pfile >> header >> pfloat; - pfile >> header >> pchnodata; - } -#if RS_RCPP - if (!pfile.good()) { - // corrupt file stream - StreamErrorR(pchfile); - hfile.close(); - hfile.clear(); - pfile.close(); - pfile.clear(); - return 135; - } -#endif setCellArray(); } - - // set up bad float values to ensure that valid values are read - float badhfloat = -9.0; if (habnodata == -9) badhfloat = -99.0; - float badpfloat = -9.0; if (pchnodata == -9) badpfloat = -99.0; - seq = 0; // initial sequential patch landscape - p = 0; // initial patch number for cell-based landscape + patchCode= 0; // initial patch number for cell-based landscape // create patch 0 - the matrix patch (even if there is no matrix) - if (fileNum == 0) newPatch(seq++, p++); + if (fileNum == 0) { + newPatch(seq,patchCode); + seq++; + patchCode++; + } switch (rasterType) { case 0: // raster with habitat codes - 100% habitat each cell if (fileNum > 0) return 19; // error condition - should not occur - for (int y = dimY - 1; y >= 0; y--) { + + for (int y = dimY-1; y >= 0; y--) { for (int x = 0; x < dimX; x++) { - hfloat = badhfloat; -#if RS_RCPP - if (hfile >> hfloat) { -#else - hfile >> hfloat; -#endif - h = (int)hfloat; - if (patchModel) { - pfloat = badpfloat; -#if RS_RCPP - if (pfile >> pfloat) { -#else - pfile >> pfloat; -#endif - p = (int)pfloat; -#if RS_RCPP - } + + // read value from raster cell + habFloat = habfile(dimY-1-y,x); + // check for NA + if ( R_IsNA(habFloat) ) + addNewCellToLand(x,y,-1); // add cell only to landscape else { - // corrupt file stream -#if RS_RCPP && !R_CMD - Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; -#endif - StreamErrorR(pchfile); - hfile.close(); - hfile.clear(); - pfile.close(); - pfile.clear(); - return 132; + habCode= static_cast(habFloat); + if (habCode< 0 || (sim.batchMode && (habCode< 1 || habCode> nHabMax))) { + // invalid habitat code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found invalid habitat code." << std::endl; + #endif + return 13; + } + else { // valid habitat code + addHabCode(habCode); + if (patchModel) { + patchFloat = pchfile(dimY-1-y,x); + if ( R_IsNA(patchFloat) ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + #endif + return 14; + } + patchCode= static_cast(patchFloat); + if (patchCode< 0 ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; + #endif + return 14; + } + + // Does the patch already exists? + pPatch = patchCode == 0 ? nullptr : ( // matrix cell + existsPatch(patchCode) ? + findPatch(patchCode) : + newPatch(seq++, patchCode) + ); + addNewCellToPatch(pPatch, x, y, habCode); + } + else { // cell-based model + // add cell to landscape (patches created later) + addNewCellToLand(x,y,habCode); + } + } + } // end of habFloat is NA + } // end x + } // end y + break; + + case 1: // multiple % cover + + for (int y = dimY-1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + + habFloat = habfile(dimY-1-y,x); + if (fileNum == 0) { // first habitat cover layer + if ( R_IsNA(habFloat) ) { // check for NA + addNewCellToLand(x,y,-1); // add cell only to landscape + } + else { + if (habFloat < 0.0 || habFloat > 100.0) { // invalid cover score + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found invalid habitat cover score." << std::endl; + #endif + return 17; + } + else { + if (patchModel) { + patchFloat = pchfile(dimY-1-y,x); + if ( R_IsNA(patchFloat) ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + #endif + return 14; + } + + patchCode= static_cast(patchFloat); + + if (patchCode< 0 ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; + #endif + return 14; + } + + pPatch = patchCode == 0 ? nullptr : ( // matrix cell + existsPatch(patchCode) ? + findPatch(patchCode) : + newPatch(seq++, patchCode) + ); + addNewCellToPatch(pPatch, x, y, (float)habFloat); + } + else { // cell-based model + // add cell to landscape (patches created later) + addNewCellToLand(x,y,(float)habFloat); + } + } + } } -#endif + else { // additional habitat cover layers + if ( !R_IsNA(habFloat) ) { + if (habFloat < 0.0 || habFloat > 100.0) { // invalid cover score + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found invalid habitat cover score." << std::endl; + #endif + return 17; + } + else { + cells[dimY-1-y][x]->setHabitat((float)habFloat); + } + } // end of habFloat is not NA + } // end additional habitat cover layers + } // end x + } // end y + habIndexed = true; // habitats are already numbered 1...n in correct order + + break; + + case 2: // habitat quality + if (fileNum > 0) return 19; // error condition - should not occur + + for (int y = dimY-1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + habFloat = habfile(dimY-1-y,x); + if ( R_IsNA(habFloat) ) { // check for NA + addNewCellToLand(x,y,-1); // add cell only to landscape } -#if RS_RCPP + else { + if (habFloat < 0.0 || habFloat > 100.0) { // invalid quality score + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found invalid habitat quality score." << std::endl; + #endif + return 17; + } + else { // valid quality score + if (patchModel) { + patchFloat = pchfile(dimY-1-y,x); + if ( R_IsNA(patchFloat) ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + #endif + return 14; + } + patchCode= static_cast(patchFloat); + if (patchCode< 0 ) { // invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; + #endif + return 14; + } + + pPatch = patchCode == 0 ? nullptr : ( // matrix cell + existsPatch(patchCode) ? + findPatch(patchCode) : + newPatch(seq++, patchCode) + ); + addNewCellToPatch(pPatch, x, y, (float)habFloat); + } + else { // cell-based model + // add cell to landscape (patches created later) + addNewCellToLand(x,y,(float)habFloat); + } + } // end of valid quality score + } // end of habFloat is not NA + } // end x + } // end y + break; + + default: + break; + } // end switch(rasterType) + +//#if SPATIALDEMOG + int SMScosts = costfile.nrow()*costfile.ncol(); + + arma::vec cellDemoScalings; // vector to store local demog scalings + Rcpp::IntegerVector DSdim; + int nrDemogScaleLayers = 0; + if(scalinglayers.attr("dim")==R_NilValue) DSdim = Rcpp::IntegerVector::create(1,1,1); + else{ + DSdim = scalinglayers.attr("dim"); + if(DSdim.size()>2) nrDemogScaleLayers = DSdim[2]; //nr of slices on cube + else nrDemogScaleLayers = 1; + } + arma::cube scalingCube(scalinglayers.begin(),DSdim[0],DSdim[1],nrDemogScaleLayers,false); // turn scaling layers into a cube, what happens if it is not a spatial demog? + + if(SMScosts || nrDemogScaleLayers){ // are there SMS costs or demographic scaling layers to read? + + for (int y = dimY-1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + + // find the cell + pCell = findCell(x,y); + if (pCell != 0) { // not no-data cell + + // read cost raster + if(SMScosts) { + costFloat = costfile(dimY-1-y,x); + if ( !R_IsNA(costFloat) ) { + hc = (int)costFloat; + if ( hc < 1 ) { + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Cost map may only contain values of 1 or higher, but found " << hc << "." << endl; + #endif + return 54; + } + // set cost value + pCell->setCost(hc); + if (hc > maxcost) maxcost = hc; + } + } + + // read demographic scalings + if(nrDemogScaleLayers){ + // get tube at (y/x) + cellDemoScalings = scalingCube(arma::span(dimY-1-y), arma::span(x), arma::span::all); + if(cellDemoScalings.n_elem==(unsigned)nDSlayer){ + // set vector percentage values in cell + pCell->addchgDemoScaling(arma::conv_to< std::vector >::from(cellDemoScalings)); + } + else{// invalid patch code + #if RS_RCPP && !R_CMD + Rcpp::Rcout << "Wrong number of demographic scaling layers in cell " << x << " ," << y << " of first layer array." << std::endl; + #endif + return 64; + } + } } - else { - // corrupt file stream -#if RS_RCPP && !R_CMD - Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; + } + } + } + return 0; +} #endif - StreamErrorR(habfile); - hfile.close(); - hfile.clear(); - if (patchModel) { - pfile.close(); - pfile.clear(); + +int Landscape::readLandscape(int fileNum, string habfile, string pchfile, string costfile, vector scalinglayers) // vector scalinglayers is the vector of filenames for spatial demography of year 1 +{ + // fileNum == 0 for (first) habitat file and optional patch file + // fileNum > 0 for subsequent habitat files under the %cover option + +#if RS_RCPP + wstring header; +#else + string header; +#endif + int habCode, seq, patchCode, noDataHabCode; + int noDataPatch = 0; + int ncols, nrows; + float habFloat, patchFloat; + Patch* pPatch; + simParams sim = paramsSim->getSim(); + + if (fileNum < 0) return 19; + +#if RS_RCPP + wifstream ifsHabMap; // habitat file input stream + wifstream ifsPatchMap; // patch file input stream +#else + ifstream ifsHabMap; // habitat file input stream + ifstream ifsPatchMap; // patch file input stream +#endif + initParams init = paramsInit->getInit(); + + // Open habitat file and optionally also patch file +// #if RS_RCPP +// hfile.open(habfile, std::ios::binary); +// if (landraster.utf) { +// // apply BOM-sensitive UTF-16 facet +// hfile.imbue(std::locale(hfile.getloc(), new std::codecvt_utf16)); +// } +// #else + ifsHabMap.open(habfile.c_str()); +// #endif +// #endif + + if (!ifsHabMap.is_open()) return 11; + + if (fileNum == 0) { + if (patchModel) { +// #if RS_RCPP +// pfile.open(pchfile, std::ios::binary); +// if (patchraster.utf) { +// // apply BOM-sensitive UTF-16 facet +// pfile.imbue(std::locale(pfile.getloc(), new std::codecvt_utf16)); +// } +// #else + ifsPatchMap.open(pchfile.c_str()); +// #endif +// #endif + if (!ifsPatchMap.is_open()) { + ifsHabMap.close(); + ifsHabMap.clear(); + return 12; } + } + } + +// read landscape data from header records of habitat file +// NB headers of all files have already been compared +// !! DO NOT REMOVE THIS WORKAROUND !! NEEDED FOR LANDSCAPES GENERATED BY TERRA (R PACKAGE) +double tmpresol; + ifsHabMap >> header >> ncols + >> header >> nrows + >> header >> minEast + >> header >> minNorth + >> header >> tmpresol + >> header >> noDataHabCode; +resol = (int) tmpresol; +#if RS_RCPP + if (!ifsHabMap.good()) { + // corrupt file stream + StreamErrorR(habfile); + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); + } + return 131; + } +#endif + + dimX = ncols; + dimY = nrows; + minX = maxY = 0; // bottom-left / south-west corner + maxX = dimX - 1; + maxY = dimY - 1; + + if (fileNum == 0) { // First map layer + + // Set initialisation limits to landscape limits + init.minSeedX = init.minSeedY = 0; + init.maxSeedX = maxX; + init.maxSeedY = maxY; + paramsInit->setInit(init); + + if (patchModel) { + for (int i = 0; i < 5; i++) + ifsPatchMap >> header >> patchFloat; + ifsPatchMap >> header >> noDataPatch; + } + +#if RS_RCPP + if (!ifsPatchMap.good()) { + // corrupt file stream + StreamErrorR(pchfile); + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); return 135; } #endif - if (h == habnodata) - addNewCellToLand(x, y, -1); // add cell only to landscape - else { + setCellArray(); + } - // THERE IS AN ANOMALY HERE - CURRENTLY HABITAT 0 IS OK FOR GUI VERSION BUT - // NOT ALLOWED FOR BATCH VERSION (HABITATS MUST BE 1...n) - // SHOULD WE MAKE THE TWO VERSIONS AGREE? ... + // set up bad float values to ensure that valid values are read + float badHabFloat = -9.0; + if (noDataHabCode == -9) badHabFloat = -99.0; + float badPatchFloat = -9.0; + if (noDataPatch == -9) badPatchFloat = -99.0; - if (h < 0 || (sim.batchMode && (h < 1 || h > nHabMax))) { - // invalid habitat code -#if RS_RCPP && !R_CMD - Rcpp::Rcout << "Found invalid habitat code." << std::endl; + seq = 0; // initial sequential patch landscape + patchCode = 0; // initial patch number for cell-based landscape + + // Create the matrix patch (even if there is no matrix) + if (fileNum == 0) { + newPatch(seq, patchCode); + seq++; + patchCode++; + } + + switch (rasterType) { + + case 0: // Raster with habitat codes - 100% habitat each cell + if (fileNum > 0) return 19; // error condition - should not occur + + for (int y = dimY - 1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + + habFloat = badHabFloat; +#if RS_RCPP + if (ifsHabMap >> habFloat) { + habCode = (int)habFloat; + if (patchModel) { + patchFloat = badPatchFloat; + if (ifsPatchMap >> patchFloat) { + patchCode = (int)patchFloat; + } + else { // corrupt file stream +#if !R_CMD + Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; +#endif + StreamErrorR(pchfile); + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); + return 132; + } + } + } + else { // corrupt file stream +#if !R_CMD + Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; #endif - hfile.close(); hfile.clear(); + StreamErrorR(habfile); + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); + } + return 135; + } +#else + // Read habitat code in this cell + ifsHabMap >> habFloat; + habCode = static_cast(habFloat); if (patchModel) { - pfile.close(); pfile.clear(); + // Read patch code in this cell + patchFloat = badPatchFloat; + ifsPatchMap >> patchFloat; + patchCode = static_cast(patchFloat); } - return 13; - } - else { - addHabCode(h); - if (patchModel) { - if (p < 0 || p == pchnodata) { // invalid patch code +#endif + if (habCode == noDataHabCode) { + // No-data cell + addNewCellToLand(x, y, -1); // x, y is a null cell + } + else if (habCode < 0 || (sim.batchMode && (habCode < 1 || habCode > nHabMax))) { + // Invalid habitat code #if RS_RCPP && !R_CMD - if (p == pchnodata) Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; - else Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; + Rcpp::Rcout << "Found invalid habitat code." << std::endl; #endif - hfile.close(); hfile.clear(); - pfile.close(); pfile.clear(); - return 14; - } - if (p == 0) { // cell is in the matrix - addNewCellToPatch(0, x, y, h); + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); } - else { - if (existsPatch(p)) { - pPatch = findPatch(p); - addNewCellToPatch(pPatch, x, y, h); - // addNewCellToPatch(findPatch(p),x,y,h); - } - else { - pPatch = newPatch(seq++, p); - addNewCellToPatch(pPatch, x, y, h); + return 13; + } + else { // Valid habitat code + addHabCode(habCode); + if (patchModel) { + if (patchCode < 0 || patchCode == noDataPatch) { // invalid patch code +#if RS_RCPP && !R_CMD + if (patchCode == noDataPatch) Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + else Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; +#endif + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); + return 14; } + // Does the patch already exists? + pPatch = patchCode == 0 ? nullptr : ( // matrix cell + existsPatch(patchCode) ? + findPatch(patchCode) : + newPatch(seq++, patchCode) + ); + addNewCellToPatch(pPatch, x, y, habCode); + } + else { // cell-based model + // add cell to landscape (patches created later) + addNewCellToLand(x, y, habCode); } } - else { // cell-based model - // add cell to landscape (patches created later) - addNewCellToLand(x, y, h); - } - } - } - } - } + + } // for x + } // for y + #if RS_RCPP -hfile >> hfloat; -if (!hfile.eof()) EOFerrorR(habfile); -if (patchModel) -{ - pfile >> pfloat; - if (!pfile.eof()) EOFerrorR(pchfile); -} + ifsHabMap >> habFloat; + if (!ifsHabMap.eof()) EOFerrorR(habfile); + if (patchModel) { + ifsPatchMap >> patchFloat; + if (!ifsPatchMap.eof()) EOFerrorR(pchfile); + } #endif break; case 1: // multiple % cover for (int y = dimY - 1; y >= 0; y--) { for (int x = 0; x < dimX; x++) { - hfloat = badhfloat; -#if RS_RCPP - if (hfile >> hfloat) { -#else - hfile >> hfloat; -#endif - h = (int)hfloat; - if (fileNum == 0) { // first habitat cover layer - if (patchModel) { - pfloat = badpfloat; -#if RS_RCPP - if (pfile >> pfloat) { -#else - pfile >> pfloat; -#endif - p = (int)pfloat; + + habFloat = badHabFloat; #if RS_RCPP + if (ifsHabMap >> habFloat) { + habCode = static_cast(habFloat); + if (fileNum == 0) { // first habitat cover layer + if (patchModel) { + patchFloat = badPatchFloat; + if (ifsPatchMap >> patchFloat) { + patchCode = static_cast(patchFloat); } else { // corrupt file stream -#if RS_RCPP && !R_CMD +#if !R_CMD Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; #endif - StreamErrorR(pchfile); - hfile.close(); - hfile.clear(); - pfile.close(); - pfile.clear(); + StreamErrorR(pchfile); + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); return 135; } + } // end if patchModel +#else + ifsHabMap >> habFloat; + habCode = static_cast(habFloat); + + if (fileNum == 0) { // first habitat cover layer + if (patchModel) { + patchFloat = badPatchFloat; + ifsPatchMap >> patchFloat; + patchCode = static_cast(patchFloat); + } // end if patchModel #endif - } //end if patchmodel - if (h == habnodata) { + if (habCode == noDataHabCode) { addNewCellToLand(x, y, -1); // add cell only to landscape } - else { - if (hfloat < 0.0 || hfloat > 100.0) { // invalid cover score + else if (habFloat < 0.0 || habFloat > 100.0) { // invalid cover score #if RS_RCPP && !R_CMD Rcpp::Rcout << "Found invalid habitat cover score." << std::endl; #endif - hfile.close(); hfile.clear(); - if (patchModel) { - pfile.close(); pfile.clear(); + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); + } + return 17; } - return 17; - } - else { - if (patchModel) { - if (p < 0 || p == pchnodata) { // invalid patch code + else { + if (patchModel) { + if (patchCode < 0 || patchCode == noDataPatch) { // invalid patch code #if RS_RCPP && !R_CMD - if (p == pchnodata) Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + if (patchCode == noDataPatch) Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; else Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; #endif - hfile.close(); hfile.clear(); - pfile.close(); pfile.clear(); - return 14; - } - if (p == 0) { // cell is in the matrix - addNewCellToPatch(0, x, y, hfloat); - } - else { - if (existsPatch(p)) { - pPatch = findPatch(p); - addNewCellToPatch(pPatch, x, y, hfloat); - // addNewCellToPatch(findPatch(p),x,y,hfloat); - } - else { - pPatch = newPatch(seq++, p); - addNewCellToPatch(pPatch, x, y, hfloat); + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); + return 14; } + + pPatch = patchCode == 0 ? nullptr : ( // matrix cell + existsPatch(patchCode) ? + findPatch(patchCode) : + newPatch(seq++, patchCode) + ); + addNewCellToPatch(pPatch, x, y, habFloat); + } // end patchModel + else { // cell-based model + // add cell to landscape (patches created later) + addNewCellToLand(x, y, habFloat); } - } - else { // cell-based model - // add cell to landscape (patches created later) - addNewCellToLand(x, y, hfloat); - } + } // if valid habFloat } - } - } else { // additional habitat cover layers - if (h != habnodata) { - if (hfloat < 0.0 || hfloat > 100.0) { // invalid cover score + if (habCode != noDataHabCode) { + if (habFloat < 0.0 || habFloat > 100.0) { // invalid cover score #if RS_RCPP && !R_CMD Rcpp::Rcout << "Found invalid habitat cover score." << std::endl; #endif - hfile.close(); hfile.clear(); + ifsHabMap.close(); + ifsHabMap.clear(); if (patchModel) { - pfile.close(); pfile.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); } return 17; } else { - cells[y][x]->setHabitat(hfloat); - } - } // end of h != habnodata -} + cells[y][x]->setHabitat(habFloat); + } + } + } #if RS_RCPP - } -else { // couldn't read from hfile + } + else { // not ifsHabMap >> habFloat // corrupt file stream #if RS_RCPP && !R_CMD Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; #endif - StreamErrorR(habfile); - hfile.close(); - hfile.clear(); - if (patchModel) { - pfile.close(); - pfile.clear(); + StreamErrorR(habfile); + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); } return 133; -} + }// end not ifsHabMap >> habFloat #endif - } - } + } // for x + } // for y + habIndexed = true; // habitats are already numbered 1...n in correct order + #if RS_RCPP - hfile >> hfloat; - if (!hfile.eof()) EOFerrorR(habfile); - if (patchModel) - { - pfile >> pfloat; - if (!pfile.eof()) EOFerrorR(pchfile); + ifsHabMap >> habFloat; + if (!ifsHabMap.eof()) EOFerrorR(habfile); + if (patchModel) { + ifsPatchMap >> patchFloat; + if (!ifsPatchMap.eof()) EOFerrorR(pchfile); } #endif break; @@ -2110,110 +2675,111 @@ case 2: // habitat quality if (fileNum > 0) return 19; // error condition - should not occur for (int y = dimY - 1; y >= 0; y--) { for (int x = 0; x < dimX; x++) { - hfloat = badhfloat; -#if RS_RCPP - if (hfile >> hfloat) { -#else - hfile >> hfloat; -#endif - h = (int)hfloat; + + habFloat = badHabFloat; #if RS_RCPP + if (ifsHabMap >> habFloat) { + habCode = static_cast(habFloat); + } else { // corrupt file stream -#if RS_RCPP && !R_CMD +#if !R_CMD Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; #endif - StreamErrorR(habfile); - hfile.close(); - hfile.clear(); - if (patchModel) { - pfile.close(); - pfile.clear(); + StreamErrorR(habfile); + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); } return 134; } -#endif if (patchModel) { - pfloat = badpfloat; -#if RS_RCPP - if (pfile >> pfloat) { -#else - pfile >> pfloat; -#endif - p = (int)pfloat; -#if RS_RCPP + patchFloat = badPatchFloat; + if (ifsPatchMap >> patchFloat) { + patchCode = static_cast(patchFloat); } else { // corrupt file stream #if RS_RCPP && !R_CMD Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; #endif - StreamErrorR(pchfile); - hfile.close(); - hfile.clear(); - pfile.close(); - pfile.clear(); + StreamErrorR(pchfile); + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); return 135; } + } +#else + ifsHabMap >> habFloat; + habCode = static_cast(habFloat); + if (patchModel) { + patchFloat = badPatchFloat; + ifsPatchMap >> patchFloat; + patchCode = static_cast(patchFloat); + } #endif - } - if (h == habnodata) { + if (habCode == noDataHabCode) { addNewCellToLand(x, y, -1); // add cell only to landscape } - else { - if (hfloat < 0.0 || hfloat > 100.0) { // invalid quality score + else if (habFloat < 0.0 || habFloat > 100.0) { // invalid quality score #if RS_RCPP && !R_CMD Rcpp::Rcout << "Found invalid habitat quality score." << std::endl; #endif - hfile.close(); hfile.clear(); - if (patchModel) { - pfile.close(); pfile.clear(); - } - return 17; - } - else { - if (patchModel) { - if (p < 0 || p == pchnodata) { // invalid patch code + ifsHabMap.close(); + ifsHabMap.clear(); + if (patchModel) { + ifsPatchMap.close(); + ifsPatchMap.clear(); + } + return 17; + } + else { + if (patchModel) { + if (patchCode < 0 || patchCode == noDataPatch) { // invalid patch code #if RS_RCPP && !R_CMD - if (p == pchnodata) Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; + if (patchCode == noDataPatch) Rcpp::Rcout << "Found patch NA in valid habitat cell." << std::endl; else Rcpp::Rcout << "Found negative patch ID in valid habitat cell." << std::endl; #endif - hfile.close(); hfile.clear(); - pfile.close(); pfile.clear(); - return 14; - } - if (p == 0) { // cell is in the matrix - addNewCellToPatch(0, x, y, hfloat); + ifsHabMap.close(); + ifsHabMap.clear(); + ifsPatchMap.close(); + ifsPatchMap.clear(); + return 14; + } + if (patchCode == 0) { // cell is in the matrix + addNewCellToPatch(0, x, y, habFloat); } else { - if (existsPatch(p)) { - pPatch = findPatch(p); - addNewCellToPatch(pPatch, x, y, hfloat); - // addNewCellToPatch(findPatch(p),x,y,hfloat); + if (existsPatch(patchCode)) { + pPatch = findPatch(patchCode); } else { - addPatchNum(p); - pPatch = newPatch(seq++, p); - addNewCellToPatch(pPatch, x, y, hfloat); + pPatch = newPatch(seq++, patchCode); } + addNewCellToPatch(pPatch, x, y, habFloat); } - } - else { // cell-based model - // add cell to landscape (patches created later) - addNewCellToLand(x, y, hfloat); - } - } - } - } - } + } + else { // cell-based model + // add cell to landscape (patches created later) + addNewCellToLand(x, y, habFloat); + } + } + + } // for x + } // for y + #if RS_RCPP - hfile >> hfloat; - if (!hfile.eof()) EOFerrorR(habfile); - if (patchModel) - { - pfile >> pfloat; - if (!pfile.eof()) EOFerrorR(pchfile); + ifsHabMap >> habFloat; + if (!ifsHabMap.eof()) EOFerrorR(habfile); + if (patchModel) + { + ifsPatchMap >> patchFloat; + if (!ifsPatchMap.eof()) EOFerrorR(pchfile); } #endif break; @@ -2222,18 +2788,29 @@ case 2: // habitat quality break; } // end switch(rasterType) - if (hfile.is_open()) { hfile.close(); hfile.clear(); } - if (pfile.is_open()) { pfile.close(); pfile.clear(); } + if (ifsHabMap.is_open()) { + ifsHabMap.close(); + ifsHabMap.clear(); + } + if (ifsPatchMap.is_open()) { + ifsPatchMap.close(); + ifsPatchMap.clear(); + } if (sim.batchMode) { if (costfile != "NULL") { int retcode = readCosts(costfile); if (retcode < 0) return 54; + } + if (scalinglayers.size() > 0) { + if (scalinglayers.size() == nDSlayer) { + int retcode = readDemographicScaling(scalinglayers); + if (retcode < 0) return 54; //change number + } } } return 0; - } //--------------------------------------------------------------------------- @@ -2261,22 +2838,19 @@ int Landscape::readCosts(string fname) string header; #endif Cell* pCell; -#if !RS_RCPP - simView v = paramsSim->getViews(); -#endif int maxcost = 0; // open cost file -#if !RS_RCPP || RSWIN64 +// #if RS_RCPP +// costs.open(fname, std::ios::binary); +// if (costsraster.utf) { +// // apply BOM-sensitive UTF-16 facet +// costs.imbue(std::locale(costs.getloc(), new std::codecvt_utf16)); +// } +// #else costs.open(fname.c_str()); -#else - costs.open(fname, std::ios::binary); - if (costsraster.utf) { - // apply BOM-sensitive UTF-16 facet - costs.imbue(std::locale(costs.getloc(), new std::codecvt_utf16)); - } -#endif +// #endif // read headers and check that they correspond to the landscape ones costs >> header; #if RS_RCPP @@ -2291,10 +2865,6 @@ int Landscape::readCosts(string fname) #else if (header != "ncols" && header != "NCOLS") { #endif - -// MessageDlg("The selected file is not a raster.", -// MessageDlg("Header problem in import_CostsLand()", -// mtError, TMsgDlgButtons() << mbRetry,0); costs.close(); costs.clear(); return -1; } @@ -2303,10 +2873,6 @@ costs >> maxXcost >> header >> maxYcost >> header >> minLongCost; costs >> header >> minLatCost >> header >> tmpresolCost >> header >> NODATACost; resolCost = (int) tmpresolCost; -#if !RS_RCPP - MemoLine("Loading costs map. Please wait..."); -#endif - for (int y = maxYcost - 1; y > -1; y--) { for (int x = 0; x < maxXcost; x++) { #if RS_RCPP @@ -2343,13 +2909,12 @@ resolCost = (int) tmpresolCost; if (hc > maxcost) maxcost = hc; } else { // if cost value is below 0 #if RS_RCPP && !R_CMD - Rcpp::Rcout << "Cost map may only contain values of 1 or higher in habiat cells, but found " << hc << " in cell x: " << x << " y: " << y << "." << endl; + Rcpp::Rcout << "Cost map may only contain values of 1 or higher in habitat cells, but found " << hc << " in cell x: " << x << " y: " << y << "." << endl; #endif - // costs.close(); costs.clear(); // not sure if it should stop at this point - // return -999; + throw runtime_error("Found negative- or zero-cost habitat cell."); } - } // end not no data vell + } // end not no data cell } } #if RS_RCPP @@ -2360,8 +2925,6 @@ if (costs.eof()) { #endif } else EOFerrorR(fname); -#else -MemoLine("Costs map loaded."); #endif costs.close(); costs.clear(); @@ -2370,6 +2933,134 @@ return maxcost; } + //--------------------------------------------------------------------------- + int Landscape::readDemographicScaling(vector scalinglayers){ + // Create a temporary landscape to store the vectors for each cell + // I bet there is a better way to implement it, but I couldn't think of it for now + // each cell will contain a vector of three floats + std::vector>> landscape(dimY, + std::vector>(dimX, + std::vector(scalinglayers.size(), 0.0f))); //length of string is determined by DSlayer + +#if RS_RCPP + wstring header; +#else + string header; +#endif + + int DSnb = 0; // first position is 0 + int DS; + int DSnodata; + float DSfloat; // float for reading in data from file + +#if RS_RCPP + wifstream DSfile; // DS file input stream +#else + ifstream DSfile; // DS file input stream +#endif + + + + // for each element of scalinglayers + for (const auto& DSlayer : scalinglayers) { //DSlayer is a reference to file string + // open file + DSfile.open(DSlayer.c_str()); + // if file couldn't be opened, return a failure message (and the readLandscape function: close all file connections and exit) + if (!DSfile.is_open()) return -11; // might need to change the code number + + // if it opened + // skip header, but store no data value + for (int i = 0; i < 5; i++) + DSfile >> header >> DSfloat; + DSfile >> header >> DSnodata; // 6th line + +#if RS_RCPP + if (!DSfile.good()) { + // corrupt file stream + StreamErrorR(DSlayer); + DSfile.close(); + DSfile.clear(); + //do I also need to close the habitat, and potentially patchfile? or is this taken care of? + return -181; // need to change the code + } +#endif + + // set badfloat + float badDSfloat = -9.0; if (DSnodata == -9) DSfloat = -99.0; + + // loop over landscape x+y + for (int y = dimY - 1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + // read in cell value + DSfloat = badDSfloat; // set to bad float value + // do I need to check this value for any inconsistencies? -> better safe than sorry +#if RS_RCPP + if (DSfile >> DSfloat) { +#else + DSfile >> DSfloat; +#endif + // DS = (int)DSfloat; I guess non integer values are totally fine? +#if RS_RCPP + } + else { + // corrupt file stream +#if RS_RCPP && !R_CMD + Rcpp::Rcout << "At (x,y) = " << x << "," << y << " :" << std::endl; +#endif + StreamErrorR(DSlayer); + DSfile.close(); + DSfile.clear(); + return -134; // need to change number code + } +#endif + // check if the value is a no data value + if (DSfloat == DSnodata) { + // if it is, do I need to do anything? + } + else { + if (DSfloat < 0.0 || DSfloat > 100.0) { // check for negative values or values above 100 +#if RS_RCPP && !R_CMD + Rcpp::Rcout << "Found invalid demographic scaling score." << std::endl; +#endif + DSfile.close(); DSfile.clear(); + return -17; // need to change code + } + else { + // if the value is ok, + // set the vector value of this cell at this location to the float value read in: + landscape[y][x][DSnb] = DSfloat; // Assignment to specific cell's vector + } + } + } // end x loop + } // end y loop + + // use Rcpp::Rcout to print the landscape at DSnb=0: + // close file connection +#if RS_RCPP + DSfile >> DSfloat; + if (!DSfile.eof()) EOFerrorR(DSlayer); + else { +#if RS_RCPP && !R_CMD + Rcpp::Rcout << "Demographic scaling layer " << DSnb + 1 << " loaded." << endl; +#endif + } +#endif + if (DSfile.is_open()) { DSfile.close(); DSfile.clear(); } + DSnb ++; // increase the reference number and read in next file + }; // end loop over scalinglayers + + // add the cells' vector of DSfloats to the actual landscape using the function addchgDemoScaling + // loop over all cells + for (int y = dimY - 1; y >= 0; y--) { + for (int x = 0; x < dimX; x++) { + // extract the vector in landscape at x, y + std::vector localDS = landscape[y][x]; + cells[y][x]->addchgDemoScaling(localDS); // add the vector to the cell + } + } + return 0; // return success code + }; + //--------------------------------------------------------------------------- rasterdata CheckRasterFile(string fname) @@ -2386,42 +3077,18 @@ rasterdata CheckRasterFile(string fname) infile.open(fname.c_str()); if (infile.is_open()) { infile >> header >> r.ncols; -#if RSDEBUG - DebugGUI(("CheckRasterFile(): header=" + header + " r.ncols=" + Int2Str(r.ncols) - ).c_str()); -#endif if (header != "ncols" && header != "NCOLS") r.errors++; infile >> header >> r.nrows; -#if RSDEBUG - DebugGUI(("CheckRasterFile(): header=" + header + " r.nrows=" + Int2Str(r.nrows) - ).c_str()); -#endif if (header != "nrows" && header != "NROWS") r.errors++; infile >> header >> r.xllcorner; -#if RSDEBUG - DebugGUI(("CheckRasterFile(): header=" + header + " r.xllcorner=" + Float2Str(r.xllcorner) - ).c_str()); -#endif if (header != "xllcorner" && header != "XLLCORNER") r.errors++; infile >> header >> r.yllcorner; -#if RSDEBUG - DebugGUI(("CheckRasterFile(): header=" + header + " r.yllcorner=" + Float2Str(r.yllcorner) - ).c_str()); -#endif if (header != "yllcorner" && header != "YLLCORNER") r.errors++; double tmpcellsize; infile >> header >> tmpcellsize; r.cellsize = (int) tmpcellsize; -#if RSDEBUG - DebugGUI(("CheckRasterFile(): header=" + header + " r.cellsize=" + Int2Str(r.cellsize) - ).c_str()); -#endif if (header != "cellsize" && header != "CELLSIZE") r.errors++; infile >> header >> inint; -#if RSDEBUG - DebugGUI(("CheckRasterFile(): header=" + header + " inint=" + Int2Str(inint) - ).c_str()); -#endif if (header != "NODATA_value" && header != "NODATA_VALUE") r.errors++; infile.close(); infile.clear(); @@ -2444,9 +3111,6 @@ void Landscape::createConnectMatrix(void) { if (connectMatrix != 0) deleteConnectMatrix(); int npatches = (int)patches.size(); -#if RSDEBUG - //DEBUGLOG << "Landscape::createConnectMatrix(): npatches=" << npatches << endl; -#endif connectMatrix = new int* [npatches]; for (int i = 0; i < npatches; i++) { connectMatrix[i] = new int[npatches]; @@ -2486,24 +3150,26 @@ void Landscape::deleteConnectMatrix(void) } } -// Write connectivity file headers -bool Landscape::outConnectHeaders(int option) +// Close connectivity file +bool Landscape::outConnectFinishLandscape() { - if (option == -999) { // close the file if (outConnMat.is_open()) outConnMat.close(); outConnMat.clear(); return true; } +// Open connectivity file and write header record +bool Landscape::outConnectStartLandscape() +{ simParams sim = paramsSim->getSim(); string name = paramsSim->getDir(2); if (sim.batchMode) { - name += "Batch" + Int2Str(sim.batchNum) + "_"; - name += "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(landNum); + name += "Batch" + to_string(sim.batchNum) + "_"; + name += "Sim" + to_string(sim.simulation) + "_Land" + to_string(landNum); } else - name += "Sim" + Int2Str(sim.simulation); + name += "Sim" + to_string(sim.simulation); name += "_Connect.txt"; outConnMat.open(name.c_str()); @@ -2513,26 +3179,27 @@ bool Landscape::outConnectHeaders(int option) } #if RS_RCPP -// Write movement paths file headers -void Landscape::outPathsHeaders(int rep, int option) +// Close movement paths file +void Landscape::outPathsFinishReplicate() { - if (option == -999) { // close the file if (outMovePaths.is_open()) outMovePaths.close(); outMovePaths.clear(); } - if (option == 0) { // open the file and write header +// Open movement paths file and write header record +void Landscape::outPathsStartReplicate(int rep) +{ simParams sim = paramsSim->getSim(); string name = paramsSim->getDir(2); if (sim.batchMode) { - name += "Batch" + Int2Str(sim.batchNum) - + "_Sim" + Int2Str(sim.simulation) - + "_Land" + Int2Str(landNum) - + "_Rep" + Int2Str(rep); + name += "Batch" + to_string(sim.batchNum) + + "_Sim" + to_string(sim.simulation) + + "_Land" + to_string(landNum) + + "_Rep" + to_string(rep); } else { - name += "Sim" + Int2Str(sim.simulation) - + "_Rep" + Int2Str(rep); + name += "Sim" + to_string(sim.simulation) + + "_Rep" + to_string(rep); } name += "_MovePaths.txt"; @@ -2541,11 +3208,7 @@ void Landscape::outPathsHeaders(int rep, int option) outMovePaths << "Year\tIndID\tStep\tx\ty\tStatus" << endl; } else { -#if RSDEBUG - DEBUGLOG << "RunModel(): UNABLE TO OPEN MOVEMENT PATHS FILE" << endl; -#endif outMovePaths.clear(); - } } } #endif @@ -2618,20 +3281,20 @@ void Landscape::outVisits(int rep, int landNr) { if (sim.batchMode) { name = paramsSim->getDir(3) #if RS_RCPP - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) - + "_Land" + Int2Str(landNr) + "_Rep" + Int2Str(rep) + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + + "_Land" + to_string(landNr) + "_Rep" + to_string(rep) #else - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) - + "_land" + Int2Str(landNr) + "_rep" + Int2Str(rep) + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + + "_land" + to_string(landNr) + "_rep" + to_string(rep) #endif + "_Visits.txt"; } else { name = paramsSim->getDir(3) - + "Sim" + Int2Str(sim.simulation) - + "_land" + Int2Str(landNr) + "_rep" + Int2Str(rep) + + "Sim" + to_string(sim.simulation) + + "_land" + to_string(landNr) + "_rep" + to_string(rep) + "_Visits.txt"; } outvisits.open(name.c_str()); @@ -2655,11 +3318,51 @@ void Landscape::outVisits(int rep, int landNr) { outvisits << endl; } - outvisits.close(); outvisits.clear(); + outvisits.close(); + outvisits.clear(); } //--------------------------------------------------------------------------- +#ifdef UNIT_TESTS +// Tests only: shortcut setup utilities + +Landscape createLandscapeFromCells(vector cells, const landParams& lp, Species sp) { + // Set up landscape + Landscape ls; + ls.setLandParams(lp, true); + // Add cells + ls.setCellArray(); + for (auto c : cells) { + ls.addCellToLand(c); + } + ls.allocatePatches(&sp); + return ls; +} + +landParams createDefaultLandParams(const int& dim) { + + landParams ls_params; + ls_params.dimX = ls_params.dimY = dim; + ls_params.minX = ls_params.minY = 0; + ls_params.maxX = ls_params.maxY = ls_params.dimX - 1; + ls_params.resol = ls_params.spResol = 1; + ls_params.rasterType = 0; // habitat types + + ls_params.patchModel = false; + ls_params.spDist = false; + ls_params.generated = false; + ls_params.dynamic = false; + ls_params.landNum = 0; + ls_params.nHab = ls_params.nHabMax = 0; // irrelevant for habitat codes + return ls_params; +} + +void testLandscape() { + // test coordinate system... +} +#endif // UNIT_TESTS + //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- diff --git a/Landscape.h b/RangeShiftR/src/RScore/Landscape.h similarity index 83% rename from Landscape.h rename to RangeShiftR/src/RScore/Landscape.h index 2a414cc..0c025ca 100644 --- a/Landscape.h +++ b/RangeShiftR/src/RScore/Landscape.h @@ -1,25 +1,25 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * --------------------------------------------------------------------------*/ - - + + + /*------------------------------------------------------------------------------ RangeShifter v2.0 Landscape @@ -58,14 +58,14 @@ to be intialised, which are specified by the user in FormSeeding. This option is available in the GUI version only. For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. + eco-evolutionary dynamics and species’ responses to environmental changes. Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 Authors: Greta Bocedi & Steve Palmer, University of Aberdeen -Last updated: 2 December 2021 by Steve Palmer + Last updated: 28 July 2021 by Greta Bocedi ------------------------------------------------------------------------------*/ #ifndef LandscapeH @@ -88,9 +88,17 @@ using namespace std; #include #endif #include +#include #endif + //--------------------------------------------------------------------------- +// not sure whether it needs to be added here for the readDistribution() function to work + +struct landOrigin { + double minEast; double minNorth; +}; + // Initial species distribution @@ -98,9 +106,17 @@ class InitDist{ public: InitDist(Species*); ~InitDist(); +#if RS_RCPP int readDistribution( + Rcpp::NumericMatrix, + landOrigin, + int string // name of species distribution file ); +#endif + int readDistribution( + string // name of species distribution file + ); void setDistribution( int // no. of distribution cells to be initialised (0 for all cells) ); @@ -142,9 +158,10 @@ class InitDist{ //--------------------------------------------------------------------------- -struct landParams { +struct landParams { bool patchModel; bool spDist; bool generated; bool dynamic; + bool spatialdemog; int landNum; int resol; int spResol; int nHab; int nHabMax; int dimX,dimY,minX,minY,maxX,maxY; short rasterType; @@ -159,9 +176,11 @@ struct genLandParams { struct landPix { int pix; float gpix; }; +/* struct landOrigin { double minEast; double minNorth; }; + */ struct rasterHdr { bool ok; int errors,ncols,nrows,cellsize; @@ -179,7 +198,8 @@ struct patchData { Patch *pPatch; int patchNum,nCells; int x,y; }; struct landChange { - int chgnum,chgyear; string habfile,pchfile,costfile; + int chgNb, chgYear; + string pathHabFile, pathPatchFile, pathCostFile, pathSpatDemogFile; }; struct patchChange { int chgnum, x, y, oldpatch, newpatch; @@ -225,16 +245,11 @@ class Landscape{ int findHabCode(int); int getHabCode(int); void clearHabitats(void); - void addColour(rgb); - void changeColour(int,rgb); - rgb getColour(int); - int colourCount(void); // functions to handle patches and cells void setCellArray(void); - void addPatchNum(int); - void generatePatches(void); // create an artificial landscape + void generatePatches(); // create an artificial landscape void allocatePatches(Species*); // create patches for a cell-based landscape Patch* newPatch( int // patch sequential no. (id no. is set to equal sequential no.) @@ -254,6 +269,9 @@ class Landscape{ int, // y co-ordinate int // habitat class no. ); + void addCellToLand( + Cell* // cell to add to landscape + ); void addCellToPatch( Cell*, // pointer to Cell Patch* // pointer to Patch @@ -289,6 +307,8 @@ class Landscape{ Patch* findPatch( int // Patch id no. ); + set getPatchNbs() const; + set samplePatches(const string& samplingOption, int nbToSample, Species* pSpecies); int checkTotalCover(void); void resetPatchPopns(void); void updateCarryingCapacity( @@ -300,6 +320,10 @@ class Landscape{ int, // x co-ordinate int // y co-ordinate ); + bool checkDataCell( + int, // x co-ordinate + int // y co-ordinate + ); int patchCount(void); void updateHabitatIndices(void); void setEnvGradient( @@ -327,7 +351,19 @@ class Landscape{ short // change number ); void deleteLandChanges(void); +//#if RS_THREADSAFE #if RS_RCPP && !R_CMD + int readLandChange( + int, // change number + Rcpp::NumericMatrix,// habitat raster + Rcpp::NumericMatrix,// patch raster + Rcpp::NumericMatrix // cost raster +//#if SPATIALDEMOG + ,Rcpp::NumericVector// array of demographic scaling layers +//#endif + ); +//#else +// #if RS_RCPP && !R_CMD int readLandChange( int, // change file number bool, // change SMS costs? @@ -336,12 +372,16 @@ class Landscape{ wifstream&, // cost file stream int, // habnodata int, // pchnodata - int // costnodata + int, // costnodata + vector // vector of demographic scaling layers +// TODO: add spatial demography with normal file input ); #else + // TODO: add spatial demography for batch version int readLandChange( - int, // change file number - bool // change SMS costs? + int, // change file numbers + bool, // change SMS costs? + vector // vector of demographic scaling layers ); #endif void createPatchChgMatrix(void); @@ -358,6 +398,9 @@ class Landscape{ costChange getCostChange( int // cost change number ); +//#if SPATIALDEMOG + void updateDemoScalings(short); +//#endif // SPATIALDEMOG // functions to handle species distributions @@ -365,6 +408,19 @@ class Landscape{ Species*, // pointer to Species string // name of initial distribution file ); + + // function for new file input +#if RS_RCPP + int newDistribution( + Species*, // pointer to Species + //#if RS_THREADSAFE + Rcpp::NumericMatrix, + int + //#else + string // name of initial distribution file + ); +#endif + void setDistribution( Species*, // pointer to Species int // no. of distribution squares to initialise @@ -427,11 +483,11 @@ class Landscape{ int // sequential no. of settlement Patch ); void deleteConnectMatrix(void); - bool outConnectHeaders( // Write connectivity file headers - int // option - set to -999 to close the connectivity file - ); + bool outConnectFinishLandscape(); // Close connectivity file + bool outConnectStartLandscape(); // Open connectivity file and write header record #if RS_RCPP - void outPathsHeaders(int, int); + void outPathsFinishReplicate(); + void outPathsStartReplicate(int); #endif void outConnect( int, // replicate no. @@ -440,30 +496,28 @@ class Landscape{ // functions to handle input and output +#if RS_RCPP + int readLandscape( + int, // no. of seasonss + Rcpp::NumericMatrix,// habitat raster + Rcpp::NumericMatrix,// patch raster + Rcpp::NumericMatrix // cost raster + ,Rcpp::NumericVector // array of demographic scaling layers + ); +#endif int readLandscape( int, // fileNum == 0 for (first) habitat file and optional patch file // fileNum > 0 for subsequent habitat files under the %cover option string, // habitat file name string, // patch file name - string // cost file name (may be NULL) + string, // cost file name (may be NULL) + vector // demographic scaling layers (may be empty) ); void listPatches(void); int readCosts( string // costs file name ); - // the following four functions are implemented for the GUI version only - // in the batch version, they are defined, but empty - void setLandMap(void); - void drawLandscape( - int, // replicate no. - int, // landscape index number (always 0 if landscape is not dynamic) - int // landscape no. - ); - void drawGradient(void); // Draw environmental gradient map - void drawGlobalStoch( // Draw environmental stochasticity time-series - int // no. of years - ); - + int readDemographicScaling(vector ); void resetVisits(void); void outVisits(int,int); // save SMS path visits map to raster text file @@ -475,6 +529,9 @@ class Landscape{ bool continuous; // bool dynamic; // landscape changes during simulation bool habIndexed; // habitat codes have been converted to index numbers +//#if SPATIALDEMOG + bool spatialdemog; // are there spatially varying demographic rates? +//#endif // SPATIALDEMOG short rasterType; // 0 = habitat codes 1 = % cover 2 = quality 9 = artificial landscape int landNum; // landscape number int resol; // cell size (m) @@ -482,7 +539,7 @@ class Landscape{ int nHab; // no. of habitats int nHabMax; // max. no. of habitats (used for batch input only) int dimX,dimY; // dimensions - int minX,minY; // minimum available X and Y co-ordinates + int minX, minY; // minimum available X and Y co-ordinates, i.e. coordinates of the bottom-right corner int maxX,maxY; // maximum available X and Y co-ordinates float minPct,maxPct; // min and max percentage of habitat in a cell float propSuit; // proportion of suitable cells @@ -500,15 +557,9 @@ class Landscape{ // list of patches in the landscape - can be in any sequence std::vector patches; - // list of patch numbers in the landscape - std::vector patchnums; - // list of habitat codes std::vector habCodes; - // list of colours for habitat codes - std::vector colours; - // list of dynamic landscape changes std::vector landchanges; std::vector patchchanges; @@ -525,7 +576,7 @@ class Landscape{ int **connectMatrix; // global environmental stochasticity (epsilon) - float *epsGlobal; // pointer to time-series + float* epsGlobal; // pointer to time-series // patch and costs change matrices (temporary - used when reading dynamic landscape) // indexed by [descending y][x][period] @@ -545,13 +596,11 @@ extern paramInit *paramsInit; extern paramSim *paramsSim; extern RSrandom *pRandom; -#if RSDEBUG -extern ofstream DEBUGLOG; -extern void DebugGUI(string); +#ifdef UNIT_TESTS +landParams createDefaultLandParams(const int& dim); +void testLandscape(); #endif -extern void MemoLine(string); - #if RS_RCPP extern rasterdata landraster,patchraster,spdistraster,costsraster; extern void EOFerrorR(string); diff --git a/Main.cpp b/RangeShiftR/src/RScore/Main.cpp similarity index 70% rename from Main.cpp rename to RangeShiftR/src/RScore/Main.cpp index 0d15cdb..cf631f8 100644 --- a/Main.cpp +++ b/RangeShiftR/src/RScore/Main.cpp @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -34,48 +34,41 @@ #include "RSrandom.h" #include "Utils.h" #include "Parameters.h" +#include "Population.h" #include "Landscape.h" #include "Species.h" #include "SubCommunity.h" +#include "Management.h" using namespace std; +#ifdef UNIT_TESTS +void testIndividual(); +void testNeutralStats(); +void testPopulation(); + void run_unit_tests() { cout << "******* Unit test output *******" << endl; testRSrandom(); + testLandscape(); testIndividual(); + testPopulation(); + testNeutralStats(); cout << endl << "************************" << endl; } +#endif // UNIT_TESTS // Global vars -string habmapname, patchmapname, distnmapname; -string costmapname, genfilename; string landFile; paramGrad* paramsGrad; paramStoch* paramsStoch; paramInit* paramsInit; paramSim* paramsSim; RSrandom* pRandom; -ofstream DEBUGLOG; -ofstream MUTNLOG; -vector hfnames; +Management* pManagement; // pointer to management routines Species* pSpecies; Community* pComm; -void DebugGUI(string msg) { - // nothing -} -void MemoLine(string msg) { - /// nothing -} -traitCanvas SetupTraitCanvas(void) { - traitCanvas tcanv; - for (int i = 0; i < NTRAITS; i++) { tcanv.pcanvas[i] = 0; } - return tcanv; -} -void Landscape::setLandMap(void) { } -void Landscape::drawLandscape(int rep, int yr, int landnum) { } -void Community::viewOccSuit(int year, double mn, double se) { } -void Community::draw(int rep, int yr, int gen, int landNum) { } +short nDSlayer=gMaxNbLayers; #if LINUX_CLUSTER || RS_RCPP int main(int argc, char* argv[]) @@ -83,10 +76,18 @@ int main(int argc, char* argv[]) int _tmain(int argc, _TCHAR* argv[]) #endif { -#ifdef NDEBUG - cout << "This code is only for running tests and not meant to run in release." << endl; +#ifndef UNIT_TESTS + cout << "This version is only for running unit tests." << endl; return 1; -# else +#else + + // Initialise globals + paramsGrad = new paramGrad; + paramsStoch = new paramStoch; + paramsInit = new paramInit; + paramsSim = new paramSim; + pRandom = new RSrandom; + assert(0.1 > 0.0); // assert does run correctly try { @@ -97,6 +98,7 @@ int _tmain(int argc, _TCHAR* argv[]) cerr << endl << "Error: " << e.what() << endl; } cout << "All tests have completed." << endl; + return 0; // if tests succeed, we are happy # endif // NDEBUG } diff --git a/RangeShiftR/src/RScore/Management.cpp b/RangeShiftR/src/RScore/Management.cpp new file mode 100644 index 0000000..9dd0504 --- /dev/null +++ b/RangeShiftR/src/RScore/Management.cpp @@ -0,0 +1,327 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Jette Wolff + --------------------------------------------------------------------------*/ + + +//--------------------------------------------------------------------------- + +#include "Management.h" + +//--------------------------------------------------------------------------- +/* + * Initialize management class + */ + +Management::Management(void) { + translocation = false; + catching_rate = 1.0; // Catching rate + non_dispersed = false; // do not consider non-dispersed individuals + std::vector translocation_years; // Number of years of translocation + std::map< int, std::vector > source; // Source patch or cell: should be a vector of arrays + std::map< int, std::vector > target; // Target patch or cell + std::map< int, std::vector > nb; // number of ttanslocated individuals + std::map< int, std::vector > min_age; // Minimum age of translocated individuals + std::map< int, std::vector > max_age; // Maximum age of translocated individuals + std::map< int, std::vector > stage; // Stage of translocated individuals + std::map< int, std::vector > sex; // Sex of translocated individuals + +} + +Management::~Management(void) { + translocation_years.clear(); + source.clear(); + target.clear(); + nb.clear(); + min_age.clear(); + max_age.clear(); + stage.clear(); +} + +managementParams Management::getManagementParams(void) { + managementParams m; + m.translocation = translocation; + return m; +} + +void Management::setManagementParams(const managementParams m){ + translocation = m.translocation; +}; + +translocationParams Management::getTranslocationParams(void) { + translocationParams t; + t.catching_rate = catching_rate; + t.translocation_years = translocation_years; + t.source = source; + t.target = target; + t.nb = nb; + t.min_age = min_age; + t.max_age = max_age; + t.stage = stage; + t.sex = sex; + return t; +} + +// not sure if this is a good way, so won't use it for now +void Management::setTranslocationParams(const translocationParams t){ + catching_rate = t.catching_rate; + translocation_years = t.translocation_years; + source = t.source; + target = t.target; + nb = t.nb; + min_age = t.min_age; + max_age = t.max_age; + stage = t.stage; + sex = t.sex; + +}; + +void Management::translocate(int yr + , Landscape* pLandscape + , Species* pSpecies + ){ +#if RS_RCPP + Rcpp::Rcout << "Start translocation events in year " << yr << endl; +#endif +#ifndef NDEBUG + cout << "Start translocation events in year " << yr << endl; +#endif + landParams ppLand = pLandscape->getLandParams(); + auto it = nb.find(yr); // the number of translocation events is determined by the number of elements of the maps at year yr + auto nb_it = nb.find(yr); + auto source_it = source.find(yr); + auto target_it = target.find(yr); + auto min_age_it = min_age.find(yr); + auto max_age_it = max_age.find(yr); + auto stage_it = stage.find(yr); + auto sex_it = sex.find(yr); + // iterate over the number of events + for (int e = 0; e < it->second.size(); e++) { +#if RS_RCPP + Rcpp::Rcout << "Translocation event " << e << " in year " << yr << endl; +#endif +#ifndef NDEBUG + cout << "Translocation event " << e << " in year " << yr << endl; +#endif + // find the source patch + Patch* s_patch; + Population* s_pPop; + if(ppLand.patchModel){ + if(pLandscape->existsPatch(source_it->second[e].x)){ +#if RS_RCPP + Rcpp::Rcout << "Source patch exist." << endl; +#endif +#ifndef NDEBUG + cout << "Source patch exist." << endl; +#endif + + s_patch = pLandscape->findPatch(source_it->second[e].x); + if (s_patch) { // if it is not a nullpointer + // test if population in patch is not zero + s_pPop = s_patch->getPopn(pSpecies); // returns the population of the species in that cell + if (s_pPop && s_pPop->getNbInds() > 0){ + } else { +#if RS_RCPP + Rcpp::Rcout << "Population does not exist in source patch or is 0! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Population does not exist in source patch or is 0! skipping translocation event." << endl; +#endif + return; + } + } else { +#if RS_RCPP + Rcpp::Rcout << "Source patch was found but NULL! skipping translocation event." << endl; // not sure if this ever happens +#endif +#ifndef NDEBUG + cout << "Source patch was found but NULL! skipping translocation event." << endl; // not sure if this ever happens +#endif + return; + } + // + } else{ +#if RS_RCPP + Rcpp::Rcout << "Source patch was not found in landscape! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Source patch was not found in landscape! skipping translocation event." << endl; +#endif + return; + } + } else{ + Cell* pCell; + pCell = pLandscape->findCell(source_it->second[e].x, source_it->second[e].y); + if (pCell != 0) { +#if RS_RCPP + Rcpp::Rcout << "Source cell was found" << endl; +#endif +#ifndef NDEBUG + cout << "Source cell was found" << endl; +#endif + Patch *s_ppatch = pCell->getPatch(); + if (s_ppatch) { + s_patch = s_ppatch; + // test if population in patch is not zero + s_pPop = s_patch->getPopn(pSpecies); // returns the population of the species in that cell + if (s_pPop && s_pPop->getNbInds() > 0){ + } else { +#if RS_RCPP + Rcpp::Rcout << "Population does not exist in source cell or is 0! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Population does not exist in source cell or is 0! skipping translocation event." << endl; +#endif + return; + } + } else { +#if RS_RCPP + Rcpp::Rcout << "Source cell does not exist! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Source cell does not exist! skipping translocation event." << endl; +#endif + + return; + } + } else { +#if RS_RCPP + Rcpp::Rcout << "Cell does not belong to landscape! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Cell does not belong to landscape! skipping translocation event." << endl; +#endif + return; + } + } + // find the target patch and check for existence + Patch* t_patch; + Population* t_pPop; + if(ppLand.patchModel){ + if(pLandscape->existsPatch(target_it->second[e].x)){ +#if RS_RCPP + Rcpp::Rcout << "Target patch exist." << endl; +#endif +#ifndef NDEBUG + cout << "Target patch exist." << endl; +#endif + t_patch = pLandscape->findPatch(target_it->second[e].x); + } else{ +#if RS_RCPP + Rcpp::Rcout << "Target patch was not found in landscape! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Target patch was not found in landscape! skipping translocation event." << endl; +#endif + return; + } + } else{ + Cell* pCell; + pCell = pLandscape->findCell(target_it->second[e].x, target_it->second[e].y); + if (pCell != 0) { +#if RS_RCPP + Rcpp::Rcout << "Target cell was found" << endl; +#endif +#ifndef NDEBUG + cout << "Target cell was found" << endl; +#endif + Patch *t_ppatch = pCell->getPatch(); + if (t_ppatch) { + t_patch = t_ppatch; + } else { +#if RS_RCPP + Rcpp::Rcout << "Target cell does not exist! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Target cell does not exist! skipping translocation event." << endl; +#endif + return; + } + } else { +#if RS_RCPP + Rcpp::Rcout << "Target cell does not belong to landscape! skipping translocation event." << endl; +#endif +#ifndef NDEBUG + cout << "Target cell does not belong to landscape! skipping translocation event." << endl; +#endif + return; + } + } + + // only if source and target cell/patch exist, we can translocate individuals: + // get individuals with the given characteristics in that population + int min_age = min_age_it->second[e]; + int max_age = max_age_it->second[e]; + int stage = stage_it->second[e]; + int sex = sex_it->second[e]; + int nb = nb_it->second[e]; + int nbSampledInds = 0; + // We made already sure by now that in s_pPop at least some individuals exist + nbSampledInds = s_pPop->sampleIndividuals(nb, min_age, max_age, stage, sex); // checking values was done when reading in the parameters + popStats s_stats = s_pPop->getStats(s_patch->getDemoScaling()); + Individual* catched_individual; + int translocated = 0; + // loop over all indsividuals, extract sampled individuals, try to catch individual + translocate them to new patch + for (int j = 0; j < s_stats.nInds; j++) { + // if there are individuals to catch + if(s_pPop->getSizeSampledInds()){ + // if this individual is matching one of the sampled individuals + catched_individual = s_pPop->catchIndividual(catching_rate, j); // catch individual in the source patch + if (catched_individual !=NULL) { // translocated individual - has already been removed from natal population + // Check if a population of this species already exists in target patch t_patch + t_pPop = t_patch->getPopn(pSpecies); + if (!t_pPop) { // translocated individual is the first in a previously uninhabited patch +#if RS_RCPP + Rcpp::Rcout << "Population does not exist in target patch. Creating new population." << endl; +#endif +#ifndef NDEBUG + cout << "Population does not exist in target patch. Creating new population." << endl; +#endif + // create a new population in the corresponding sub-community + SubCommunity* pSubComm = (SubCommunity*)t_patch->getSubComm(); + t_pPop = pSubComm->newPopn(pLandscape, pSpecies, t_patch, 0); + } + catched_individual->setStatus(10); // make sure individual is not dispersing after the translocation + t_pPop->recruit(catched_individual); // recruit individual to target population TODO: maybe use a specified function which also updates pCurrCell + pPrevCell to a random cell in target patch? + translocated ++; + // NOTE: + // the variables pCurrCell and pPrevCell are not updated! These are important for the dispersal process! + // currently, translocated individuals are not considered as potential emigrants, thus there is no problem in changing that + // however, if we want to consider dispersal events after translocation, we need to adapt that; but that would also mean, that we might loose the information + // about the natal patch of an individual? + simParams sim = paramsSim->getSim(); + if (sim.outConnect) { // increment connectivity totals + int newpatch = t_patch->getSeqNum(); + int prevpatch = s_patch->getSeqNum(); + pLandscape->incrConnectMatrix(prevpatch, newpatch); + } + + } + } + } +#if RS_RCPP + Rcpp::Rcout << "Successfully translocated " << translocated << " out of " << nb_it->second[e] << " individuals in translocation event " << e <<"." << endl; +#endif +#ifndef NDEBUG + cout << "Successfully translocated " << translocated << " out of " << nb_it->second[e] << " individuals in translocation event " << e <<"." << endl; +#endif + // remove pointers to sampled individuals + s_pPop->clean(); + } +}; diff --git a/RangeShiftR/src/RScore/Management.h b/RangeShiftR/src/RScore/Management.h new file mode 100644 index 0000000..6ef0f3c --- /dev/null +++ b/RangeShiftR/src/RScore/Management.h @@ -0,0 +1,136 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Jette Wolff + --------------------------------------------------------------------------*/ + + +/*------------------------------------------------------------------------------ + + RangeShifter v2.0 Parameters + + Implements the following classes: + + paramManagement - Management parameters + paramTranslocation - Translocation parameters + + + Last updated: 12 March 2024 by Jette Reeg + + ------------------------------------------------------------------------------*/ + + +#ifndef ManagementH +#define ManagementH + +#include +#include +#include +#include +#include +#include +#include +using namespace std; +#if RS_RCPP +#include // for Rcpp::Rcout +#endif +#include "Parameters.h" +#include "Species.h" +#include "Cell.h" +#include "Landscape.h" + +#include "SubCommunity.h" +#include "Population.h" + + +#if RS_RCPP +typedef intptr_t intptr; +#else +typedef unsigned long long intptr; +#endif // RS_RCPP + + + +//--------------------------------------------------------------------------- + +/* + * Management settings + */ + +// Structure for management parameters +struct managementParams { + bool translocation; // Translocation +}; + +// Structure for translocation parameters +struct translocationParams { + double catching_rate; // Catching rate + std::vector translocation_years; // Number of years of translocation -> will be increased at the beginning of a simulation + std::map< int, std::vector > source; // Source patch or cell: should be a vector of arrays + std::map< int, std::vector > target; // Target patch or cell + std::map< int, std::vector > nb; // number of ttanslocated individuals + std::map< int, std::vector > min_age; // Minimum age of translocated individuals + std::map< int, std::vector > max_age; // Maximum age of translocated individuals + std::map< int, std::vector > stage; // Stage of translocated individuals + std::map< int, std::vector > sex; // Sex of translocated individuals +}; + + +//--------------------------------------------------------------------------- + +class Management{ +public: + Management(void); + ~Management(void); + void setManagementParams( // function to set management parameters + const managementParams // structure holding general management parameters + ); + managementParams getManagementParams(void); // get management parameters + void setTranslocationParams( // function to set translocation parameters + const translocationParams // structure holding translocation parameters + ); + translocationParams getTranslocationParams(void); + void translocate( // Translocation + int , // year of translocation + Landscape* , // pointer to the landscape + // Community*, // pointer to the community + Species* // pointer to the species + ); + + // + bool translocation; // Translocation + double catching_rate; // Catching rate + bool non_dispersed; // whether non-dispersed individuals should be translocated + std::vector translocation_years; // Number of years of translocation -> should be a dynamic vector + std::map< int, std::vector > source; // Source patch or cell: should be a vector of arrays + std::map< int, std::vector > target; // Target patch or cell + std::map< int, std::vector > nb; // number of ttanslocated individuals + std::map< int, std::vector > min_age; // Minimum age of translocated individuals + std::map< int, std::vector > max_age; // Maximum age of translocated individuals + std::map< int, std::vector > stage; // Stage of translocated individuals + std::map< int, std::vector > sex; // Sex of translocated individuals + +}; + +//--------------------------------------------------------------------------- + +extern paramSim *paramsSim; + +//--------------------------------------------------------------------------- +#endif diff --git a/Model.cpp b/RangeShiftR/src/RScore/Model.cpp similarity index 65% rename from Model.cpp rename to RangeShiftR/src/RScore/Model.cpp index 3134f8d..0cb436b 100644 --- a/Model.cpp +++ b/RangeShiftR/src/RScore/Model.cpp @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -25,11 +25,11 @@ #include "Model.h" ofstream outPar; - +using namespace std::chrono; //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- #if RS_RCPP && !R_CMD -Rcpp::List RunModel(Landscape* pLandscape, int seqsim) +Rcpp::List RunModel(Landscape* pLandscape, int seqsim, Rcpp::S4 ParMaster) //Rcpp::S4 ParMaster new for all variants #else int RunModel(Landscape* pLandscape, int seqsim) #endif @@ -40,21 +40,13 @@ int RunModel(Landscape* pLandscape, int seqsim) landParams ppLand = pLandscape->getLandParams(); envGradParams grad = paramsGrad->getGradient(); envStochParams env = paramsStoch->getStoch(); - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + transferRules trfr = pSpecies->getTransferRules(); + managementParams manage = pManagement->getManagementParams(); + translocationParams transloc = pManagement->getTranslocationParams(); initParams init = paramsInit->getInit(); simParams sim = paramsSim->getSim(); - simView v = paramsSim->getViews(); - -#if RSDEBUG - landPix p = pLandscape->getLandPix(); - DEBUGLOG << "RunModel(): reps=" << sim.reps - << " ppLand.nHab=" << ppLand.nHab - << " p.pix=" << p.pix - << endl; - DEBUGLOG << endl; -#endif if (!ppLand.generated) { if (!ppLand.patchModel) { // cell-based landscape @@ -62,11 +54,18 @@ int RunModel(Landscape* pLandscape, int seqsim) // NB this is an overhead here, but is necessary in case the identity of // suitable habitats has been changed from one simulation to another (GUI or batch) // substantial time savings may result during simulation in certain landscapes + // if using neutral markers, set up patches to sample from pLandscape->allocatePatches(pSpecies); } pComm = new Community(pLandscape); // set up community // set up a sub-community associated with each patch (incl. the matrix) pLandscape->updateCarryingCapacity(pSpecies, 0, 0); + + //if SPATIALDEMOG + if (ppLand.rasterType == 2 && ppLand.spatialdemog) + pLandscape->updateDemoScalings(0); // TODO -> is this needed independent of whether it is on or off? + // endif SPATIALDEMOG + patchData ppp; int npatches = pLandscape->patchCount(); for (int i = 0; i < npatches; i++) { @@ -81,6 +80,13 @@ int RunModel(Landscape* pLandscape, int seqsim) else { pLandscape->resetLandLimits(); } + + // Random patches are sampled once per landscape + if (sim.patchSamplingOption == "random") { + int nbToSample = pSpecies->getNbPatchesToSample(); + auto patchesToSample = pLandscape->samplePatches(sim.patchSamplingOption, nbToSample, pSpecies); + pSpecies->setSamplePatchList(patchesToSample); + } } #if RS_RCPP && !R_CMD @@ -89,79 +95,46 @@ int RunModel(Landscape* pLandscape, int seqsim) // Loop through replicates for (int rep = 0; rep < sim.reps; rep++) { -#if RSDEBUG - DEBUGLOG << endl << "RunModel(): starting simulation=" << sim.simulation << " rep=" << rep << endl; -#endif -#if RS_RCPP && !R_CMD - Rcpp::Rcout << endl << "starting replicate " << rep << endl; -#else -#if BATCH - cout << endl << "starting replicate " << rep << endl; -#endif -#endif - MemoLine(("Running replicate " + Int2Str(rep) + "...").c_str()); + cout << "Running replicate " << rep + 1 << " / " << sim.reps << endl; if (sim.saveVisits && !ppLand.generated) { pLandscape->resetVisits(); } + if (sim.fixReplicateSeed) { + pRandom->fixNewSeed(rep); + } patchChange patchchange; costChange costchange; int npatchchanges = pLandscape->numPatchChanges(); int ncostchanges = pLandscape->numCostChanges(); int ixpchchg = 0; int ixcostchg = 0; -#if RSDEBUG - DEBUGLOG << "RunModel(): npatchchanges=" << npatchchanges << " ncostchanges=" << ncostchanges << endl; -#endif if (ppLand.generated) { -#if RSDEBUG - DEBUGLOG << endl << "RunModel(): generating new landscape ..." << endl; -#endif // delete previous community (if any) // Note: this must be BEFORE the landscape is reset (as a sub-community accesses // its corresponding patch upon deletion) if (pComm != 0) delete pComm; // generate new cell-based landscape - MemoLine("...generating new landscape..."); pLandscape->resetLand(); -#if RSDEBUG - DEBUGLOG << "RunModel(): finished resetting landscape" << endl << endl; -#endif pLandscape->generatePatches(); - if (v.viewLand || sim.saveMaps) { - pLandscape->setLandMap(); - pLandscape->drawLandscape(rep, 0, ppLand.landNum); - } -#if RSDEBUG - DEBUGLOG << endl << "RunModel(): finished generating patches" << endl; -#endif pComm = new Community(pLandscape); // set up community // set up a sub-community associated with each patch (incl. the matrix) pLandscape->updateCarryingCapacity(pSpecies, 0, 0); patchData ppp; int npatches = pLandscape->patchCount(); -#if RSDEBUG - DEBUGLOG << "RunModel(): patch count is " << npatches << endl; -#endif for (int i = 0; i < npatches; i++) { ppp = pLandscape->getPatchData(i); -#if RSWIN64 -#if LINUX_CLUSTER - pComm->addSubComm(ppp.pPatch, ppp.patchNum); // SET UP ALL SUB-COMMUNITIES -#else - SubCommunity* pSubComm = pComm->addSubComm(ppp.pPatch, ppp.patchNum); // SET UP ALL SUB-COMMUNITIES -#endif -#else pComm->addSubComm(ppp.pPatch, ppp.patchNum); // SET UP ALL SUB-COMMUNITIES -#endif } - MemoLine("...completed..."); -#if RSDEBUG - DEBUGLOG << endl << "RunModel(): finished generating populations" << endl; -#endif + if (sim.patchSamplingOption == "random") { + // Then patches must be resampled for new landscape + int nbToSample = pSpecies->getNbPatchesToSample(); + auto patchesToSample = pLandscape->samplePatches(sim.patchSamplingOption, nbToSample, pSpecies); + pSpecies->setSamplePatchList(patchesToSample); + } } if (init.seedType == 0 && init.freeType < 2 && init.initFrzYr > 0) { // restrict available landscape to initialised region @@ -173,64 +146,78 @@ int RunModel(Landscape* pLandscape, int seqsim) } filesOK = true; +#if RS_RCPP + if(init.seedType==2 && init.indsFile=="NULL"){ // initialisation from InitInds list of dataframes + if(rep > 0){ + int error_init = 0; + Rcpp::S4 InitParamsR("InitialisationParams"); + InitParamsR = Rcpp::as(ParMaster.slot("init")); + Rcpp::List InitIndsList = Rcpp::as(InitParamsR.slot("InitIndsList")); + error_init = ReadInitIndsFileR(0, pLandscape, Rcpp::as(InitIndsList[rep])); + if(error_init>0) { + filesOK = false; + } + } + } +#endif if (rep == 0) { // open output files if (sim.outRange) { // open Range file - if (!pComm->outRangeHeaders(pSpecies, ppLand.landNum)) { - MemoLine("UNABLE TO OPEN RANGE FILE"); + if (!pComm->outRangeStartLandscape(pSpecies, ppLand.landNum)) { filesOK = false; } } if (sim.outOccup && sim.reps > 1) - if (!pComm->outOccupancyHeaders(0)) { - MemoLine("UNABLE TO OPEN OCCUPANCY FILE(S)"); + if (!pComm->outOccupancyStartLandscape()) { filesOK = false; } +#if RS_RCPP + if (sim.outPop && sim.CreatePopFile) { +#else if (sim.outPop) { +#endif // open Population file - if (!pComm->outPopHeaders(pSpecies, ppLand.landNum)) { - MemoLine("UNABLE TO OPEN POPULATION FILE"); + if (!pComm->outPopStartLandscape(pSpecies)) { filesOK = false; } } if (sim.outTraitsCells) - if (!pComm->outTraitsHeaders(pSpecies, ppLand.landNum)) { - MemoLine("UNABLE TO OPEN TRAITS FILE"); + if (!pComm->outTraitsStartLandscape(pSpecies, ppLand.landNum)) { filesOK = false; } if (sim.outTraitsRows) - if (!pComm->outTraitsRowsHeaders(pSpecies, ppLand.landNum)) { - MemoLine("UNABLE TO OPEN TRAITS ROWS FILE"); + if (!pComm->outTraitsRowsStartLandscape(pSpecies, ppLand.landNum)) { filesOK = false; } if (sim.outConnect && ppLand.patchModel) // open Connectivity file - if (!pLandscape->outConnectHeaders(0)) { - MemoLine("UNABLE TO OPEN CONNECTIVITY FILE"); + if (!pLandscape->outConnectStartLandscape()) { filesOK = false; } + if (sim.outputGlobalFst) { // open neutral genetics file + if (!pComm->openNeutralOutputFile(pSpecies, ppLand.landNum)) { + filesOK = false; + } + } } -#if RSDEBUG - DEBUGLOG << "RunModel(): completed opening output files" << endl; -#endif if (!filesOK) { -#if RSDEBUG - DEBUGLOG << "RunModel(): PROBLEM - closing output files" << endl; -#endif // close any files which may be open if (sim.outRange) { - pComm->outRangeHeaders(pSpecies, -999); + pComm->outRangeFinishLandscape(); } if (sim.outOccup && sim.reps > 1) - pComm->outOccupancyHeaders(-999); + pComm->outOccupancyFinishLandscape(); if (sim.outPop) { - pComm->outPopHeaders(pSpecies, -999); + pComm->outPopFinishLandscape(); } if (sim.outTraitsCells) - pComm->outTraitsHeaders(pSpecies, -999); + pComm->outTraitsFinishLandscape(); if (sim.outTraitsRows) - pComm->outTraitsRowsHeaders(pSpecies, -999); + pComm->outTraitsRowsFinishLandscape(); if (sim.outConnect && ppLand.patchModel) - pLandscape->outConnectHeaders(-999); + pLandscape->outConnectFinishLandscape(); + if (sim.outputGlobalFst) { + pComm->openNeutralOutputFile(pSpecies, -999); + } #if RS_RCPP && !R_CMD return Rcpp::List::create(Rcpp::Named("Errors") = 666); #else @@ -251,59 +238,50 @@ int RunModel(Landscape* pLandscape, int seqsim) pLandscape->createConnectMatrix(); // variables to control dynamic landscape - landChange landChg; landChg.chgnum = 0; landChg.chgyear = 999999; + landChange landChg; landChg.chgNb = 0; landChg.chgYear = 999999; if (!ppLand.generated && ppLand.dynamic) { landChg = pLandscape->getLandChange(0); // get first change year } // set up populations in the community pLandscape->updateCarryingCapacity(pSpecies, 0, 0); -#if RSDEBUG - DEBUGLOG << "RunModel(): completed updating carrying capacity" << endl; -#endif - // if (init.seedType != 2) { + + if (ppLand.rasterType == 2 && ppLand.spatialdemog) + pLandscape->updateDemoScalings(0); + +// if (init.seedType != 2) { pComm->initialise(pSpecies, -1); - // } bool updateland = false; int landIx = 0; // landscape change index -#if RSDEBUG - DEBUGLOG << "RunModel(): completed initialisation, rep=" << rep - << " pSpecies=" << pSpecies << endl; -#endif #if BATCH && RS_RCPP && !R_CMD Rcpp::Rcout << "RunModel(): completed initialisation " << endl; #endif // open a new individuals file for each replicate if (sim.outInds) - pComm->outInds(rep, 0, 0, ppLand.landNum); + pComm->outIndsStartReplicate(rep, ppLand.landNum); // open a new genetics file for each replicate - if (sim.outGenetics) { - pComm->outGenetics(rep, 0, 0, ppLand.landNum); - if (!dem.stageStruct && sim.outStartGenetic == 0) { - // write genetic data for initialised individuals of non-strucutred population - pComm->outGenetics(rep, 0, 0, -1); + if (sim.outputGenes) { + bool geneOutFileHasOpened = pComm->openOutGenesFile(pSpecies->isDiploid(), ppLand.landNum, rep); + if (!geneOutFileHasOpened) throw logic_error("Output gene value file could not be initialised."); } + + // open a new genetics file for each replicate for per locus and pairwise stats + if (sim.outputPerLocusFst) { + pComm->openPerLocusFstFile(pSpecies, pLandscape, ppLand.landNum, rep); + } + if (sim.outPairwiseFst) { + pComm->openPairwiseFstFile(pSpecies, pLandscape, ppLand.landNum, rep); } -#if RSDEBUG - // output initialised Individuals - if (sim.outInds) - pComm->outInds(rep, -1, -1, -1); -#endif #if RS_RCPP // open a new movement paths file for each replicate if (sim.outPaths) - pLandscape->outPathsHeaders(rep, 0); + pLandscape->outPathsStartReplicate(rep); #endif // years loop - MemoLine("...running..."); for (yr = 0; yr < sim.years; yr++) { -#if RSDEBUG - DEBUGLOG << endl << "RunModel(): starting simulation=" << sim.simulation - << " rep=" << rep << " yr=" << yr << endl; -#endif #if RS_RCPP && !R_CMD Rcpp::checkUserInterrupt(); #endif @@ -317,9 +295,9 @@ int RunModel(Landscape* pLandscape, int seqsim) || (yr < 3000001 && yr % 1000000 == 0) ) { #if RS_RCPP && !R_CMD - Rcpp::Rcout << "starting year " << yr << "..." << endl; + Rcpp::Rcout << "Starting year " << yr << "..." << endl; #else - cout << "starting year " << yr << endl; + cout << "Starting year " << yr << endl; #endif } if (init.seedType == 0 && init.freeType < 2) { @@ -336,13 +314,6 @@ int RunModel(Landscape* pLandscape, int seqsim) commStats s = pComm->getStats(); int minY = s.maxY - init.restrictRows; if (minY < 0) minY = 0; -#if RSDEBUG - DEBUGLOG << "RunModel(): restriction yr=" << yr - << " s.minY=" << s.minY << " s.maxY=" << s.maxY - << " init.restrictRows=" << init.restrictRows - << " minY=" << minY - << endl; -#endif pLandscape->setLandLimits(ppLand.minX, minY, ppLand.maxX, ppLand.maxY); updateCC = true; } @@ -350,11 +321,6 @@ int RunModel(Landscape* pLandscape, int seqsim) if (yr == init.finalFrzYr) { // apply final range restriction commStats s = pComm->getStats(); -#if RSDEBUG - DEBUGLOG << "RunModel(): final restriction yr=" << yr - << " s.minY=" << s.minY << " s.maxY=" << s.maxY - << endl; -#endif pLandscape->setLandLimits(ppLand.minX, s.minY, ppLand.maxX, s.maxY); updateCC = true; } @@ -374,22 +340,14 @@ int RunModel(Landscape* pLandscape, int seqsim) updateCC = true; } if (ppLand.dynamic) { -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " landChg.chgnum=" << landChg.chgnum - << " landChg.chgyear=" << landChg.chgyear - << " npatchchanges=" << npatchchanges << " ncostchanges=" << ncostchanges - << " ixpchchg=" << ixpchchg << " ixcostchg=" << ixcostchg - << endl; -#endif - if (yr == landChg.chgyear) { // apply landscape change - landIx = landChg.chgnum; + if (yr == landChg.chgYear) { // apply landscape change + landIx = landChg.chgNb; updateland = updateCC = true; if (ppLand.patchModel) { // apply any patch changes Patch* pPatch; Cell* pCell; patchchange = pLandscape->getPatchChange(ixpchchg++); while (patchchange.chgnum <= landIx && ixpchchg <= npatchchanges) { - // move cell from original patch to new patch pCell = pLandscape->findCell(patchchange.x, patchchange.y); if (patchchange.oldpatch != 0) { // not matrix @@ -403,17 +361,14 @@ int RunModel(Landscape* pLandscape, int seqsim) pPatch = pLandscape->findPatch(patchchange.newpatch); pPatch->addCell(pCell, patchchange.x, patchchange.y); } - pCell->setPatch((intptr)pPatch); + pCell->setPatch(pPatch); // get next patch change patchchange = pLandscape->getPatchChange(ixpchchg++); } ixpchchg--; pLandscape->resetPatches(); // reset patch limits } - if (landChg.costfile != "NULL") { // apply any SMS cost changes -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " landChg.costfile=" << landChg.costfile << endl; -#endif + if (landChg.pathCostFile != "NULL") { // apply any SMS cost changes Cell* pCell; costchange = pLandscape->getCostChange(ixcostchg++); while (costchange.chgnum <= landIx && ixcostchg <= ncostchanges) { @@ -430,7 +385,7 @@ int RunModel(Landscape* pLandscape, int seqsim) landChg = pLandscape->getLandChange(landIx); } else { - landChg.chgyear = 9999999; + landChg.chgYear = 9999999; } } } @@ -438,14 +393,17 @@ int RunModel(Landscape* pLandscape, int seqsim) if (updateCC) { pLandscape->updateCarryingCapacity(pSpecies, yr, landIx); - } + if (ppLand.rasterType == 2 && ppLand.spatialdemog) //ppLand.spatialdemog false by default + pLandscape->updateDemoScalings((short)landIx); + + } if (sim.outConnect && ppLand.patchModel) pLandscape->resetConnectMatrix(); if (ppLand.dynamic && updateland) { - if (trfr.moveModel && trfr.moveType == 1) { // SMS + if (trfr.usesMovtProc && trfr.moveType == 1) { // SMS if (!trfr.costMap) pLandscape->resetCosts(); // in case habitats have changed } // apply effects of landscape change to species present in changed patches @@ -472,36 +430,68 @@ int RunModel(Landscape* pLandscape, int seqsim) for (int gen = 0; gen < dem.repSeasons; gen++) // generation loop { -#if RSDEBUG - // TEMPORARY RANDOM STREAM CHECK - if (yr % 1 == 0) - { - DEBUGLOG << endl << "RunModel(): start of gen " << gen << " in year " << yr - << " for rep " << rep << " ("; - for (int i = 0; i < 5; i++) { - int rrrr = pRandom->IRandom(1000, 2000); - DEBUGLOG << " " << rrrr; - } - DEBUGLOG << " )" << endl; + // TODO move translocation before dispersal? + if (manage.translocation && std::find(transloc.translocation_years.begin(), transloc.translocation_years.end(), yr) != transloc.translocation_years.end()) { + pManagement->translocate(yr + , pLandscape + , pSpecies + ); } -#endif - if (v.viewPop || (sim.saveMaps && yr % sim.mapInt == 0)) { - if (updateland && gen == 0) { - pLandscape->drawLandscape(rep, landIx, ppLand.landNum); - } - pComm->draw(rep, yr, gen, ppLand.landNum); - } // Output and pop. visualisation before reproduction - if (v.viewPop || v.viewTraits || sim.outOccup - || sim.outTraitsCells || sim.outTraitsRows || sim.saveMaps) + if (sim.outOccup || sim.outTraitsCells || sim.outTraitsRows) PreReproductionOutput(pLandscape, pComm, rep, yr, gen); // for non-structured population, also produce range and population output now if (!dem.stageStruct && (sim.outRange || sim.outPop)) RangePopOutput(pComm, rep, yr, gen); #if RS_RCPP && !R_CMD - if (sim.ReturnPopRaster && sim.outPop && yr >= sim.outStartPop && yr % sim.outIntPop == 0) { - list_outPop.push_back(pComm->addYearToPopList(rep, yr), "rep" + std::to_string(rep) + "_year" + std::to_string(yr)); + if ((sim.ReturnPopMatrix || sim.ReturnPopDataFrame) && sim.outPop && yr >= sim.outStartPop && yr % sim.outIntPop == 0) { + + // if ReturnPopMatrix + if(sim.ReturnPopMatrix) { + // total abundance + list_outPop.push_back( + pComm->addYearToPopList(rep, yr, PopOutType::NInd, -1), + "rep" + std::to_string(rep) + "_year" + std::to_string(yr) + "_NInd" + ); + + // also output single stages + if(sim.ReturnStages.length() > 1){ + bool ReturnStage; + for(int i = 1; i < sim.ReturnStages.length(); i++) { + ReturnStage = sim.ReturnStages[i] == 1; + if(ReturnStage) { + list_outPop.push_back( + pComm->addYearToPopList(rep, yr, PopOutType::Stage, i), + "rep" + std::to_string(rep) + + "_year" + std::to_string(yr) + + "_NInd_stage" + std::to_string(i) + ); + } + } + // + // + ReturnStage = sim.ReturnStages[0] == 1; + if (ReturnStage) { + //Rcpp::Rcout << "Return Juveniles" << endl; + list_outPop.push_back( + pComm->addYearToPopList(rep, yr, PopOutType::Juvs, -1), + "rep" + std::to_string(rep) + "_year" + std::to_string(yr) + "_NJuv" + ); + } + } + } + + if(sim.ReturnPopDataFrame){ + // in contrast to ReturnMatrix, this function produces a list of data frames, one per rep and year, holding all (stage-specific) abundances for all patches, + // instead of a single matrix for each population size metric (total abundance, stage-specific abundance, juvenile abundance) and each year and replicate + list_outPop.push_back( + pComm->addYearToPopListPatchBased(rep, yr, sim.ReturnStages), + "rep" + std::to_string(rep) + "_year" + std::to_string(yr) + ); + } + + // list_outPop.push_back(pComm->addYearToPopList(rep, yr), "rep" + std::to_string(rep) + "_year" + std::to_string(yr)); } #endif // apply local extinction for generation 0 only @@ -517,7 +507,7 @@ int RunModel(Landscape* pLandscape, int seqsim) if (dem.stageStruct) { if (sstruct.survival == 0) { // at reproduction - pComm->survival(0, 2, 1); // survival of all non-juvenile stages + pComm->survival0(2, 1); // survival of all non-juvenile stages } } @@ -525,70 +515,93 @@ int RunModel(Landscape* pLandscape, int seqsim) if (dem.stageStruct && (sim.outRange || sim.outPop)) RangePopOutput(pComm, rep, yr, gen); -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " gen=" << gen << " completed reproduction" << endl; -#endif - // Dispersal - pComm->emigration(); -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " gen=" << gen << " completed emigration" << endl; -#endif #if RS_RCPP pComm->dispersal(landIx, yr); #else pComm->dispersal(landIx); #endif // RS_RCPP -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " gen=" << gen << " completed dispersal" << endl; -#endif // survival part 0 if (dem.stageStruct) { if (sstruct.survival == 0) { // at reproduction - pComm->survival(0, 0, 1); // survival of juveniles only + pComm->survival0(0, 1); // survival of juveniles only } if (sstruct.survival == 1) { // between reproduction events - pComm->survival(0, 1, 1); // survival of all stages + pComm->survival0(1, 1); // survival of all stages } if (sstruct.survival == 2) { // annually - pComm->survival(0, 1, 0); // development only of all stages + pComm->survival0(1, 0); // development only of all stages } } else { // non-structured population - pComm->survival(0, 1, 1); + pComm->survival0(1, 1); } -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " gen=" << gen << " completed survival part 0" << endl; -#endif - // output Individuals if (sim.outInds && yr >= sim.outStartInd && yr % sim.outIntInd == 0) - pComm->outInds(rep, yr, gen, -1); - // output Genetics - if (sim.outGenetics && yr >= sim.outStartGenetic && yr % sim.outIntGenetic == 0) - pComm->outGenetics(rep, yr, gen, -1); + pComm->outIndividuals(rep, yr, gen); + + bool doGenes = + sim.outputGenes && + yr >= sim.outputGenesStart && + sim.outputGenesInterval > 0 && + yr % sim.outputGenesInterval == 0; + + bool doGlobalFst = + sim.outputGlobalFst && + yr >= sim.outputGlobalFstStart && + sim.outputGlobalFstInterval > 0 && + yr % sim.outputGlobalFstInterval == 0; + + bool doPairwiseFst = + sim.outPairwiseFst && + yr >= sim.outputPairwiseFstStart && + sim.outputPairwiseFstInterval > 0 && + yr % sim.outputPairwiseFstInterval == 0; + + if (doGenes || doGlobalFst || doPairwiseFst) { + + if (sim.patchSamplingOption != "list" && + sim.patchSamplingOption != "random") { + + int nbToSample = pSpecies->getNbPatchesToSample(); + auto patchesToSample = + pLandscape->samplePatches(sim.patchSamplingOption, nbToSample, pSpecies); + pSpecies->setSamplePatchList(patchesToSample); + } - // survival part 1 - if (dem.stageStruct) { - pComm->survival(1, 0, 1); - } - else { // non-structured population - pComm->survival(1, 0, 1); + pComm->sampleIndividuals(pSpecies); + + if (doGenes) { + pComm->outputGeneValues(yr, gen, pSpecies); + } + + if (doGlobalFst || doPairwiseFst) { + pComm->calculateNeutralGenetics( + pSpecies, rep, yr, gen, + doPairwiseFst, sim.outputPairwiseFstStart, sim.outputPairwiseFstInterval, + doGlobalFst, sim.outputGlobalFstStart, sim.outputGlobalFstInterval, + sim.outputPerLocusFst); + } } -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " gen=" << gen << " completed survival part 1" << endl; -#endif + + + + + + // Resolve survival and devlpt + pComm->survival1(); } // end of the generation loop -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " completed generation loop" << endl; -#endif totalInds = pComm->totalInds(); - if (totalInds <= 0) { yr++; break; } + if (totalInds <= 0) { + cout << "All populations went extinct." << endl; + yr++; + break; + } // Connectivity Matrix if (sim.outConnect && ppLand.patchModel @@ -596,45 +609,31 @@ int RunModel(Landscape* pLandscape, int seqsim) pLandscape->outConnect(rep, yr); if (dem.stageStruct && sstruct.survival == 2) { // annual survival - all stages - pComm->survival(0, 1, 2); - pComm->survival(1, 0, 1); -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " completed annual survival" << endl; -#endif + pComm->survival0(1, 2); + pComm->survival1(); } if (dem.stageStruct) { pComm->ageIncrement(); // increment age of all individuals if (sim.outInds && yr >= sim.outStartInd && yr % sim.outIntInd == 0) - pComm->outInds(rep, yr, -1, -1); // list any individuals dying having reached maximum age - pComm->survival(1, 0, 1); // delete any such individuals -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " completed Age_increment and final survival" << endl; -#endif + pComm->outIndividuals(rep, yr, -1); // list any individuals dying having reached maximum age + pComm->survival1(); // delete any such individuals totalInds = pComm->totalInds(); - if (totalInds <= 0) { yr++; break; } + if (totalInds <= 0) { + cout << "All populations went extinct." << endl; + yr++; + break; + } } } // end of the years loop - // Final output and popn. visualisation -#if BATCH - if (sim.saveMaps && yr % sim.mapInt == 0) { - if (updateland) { - pLandscape->drawLandscape(rep, landIx, ppLand.landNum); - } - pComm->draw(rep, yr, 0, ppLand.landNum); - } -#endif + // Final output // produce final summary output - if (v.viewPop || v.viewTraits || sim.outOccup - || sim.outTraitsCells || sim.outTraitsRows || sim.saveMaps) + if (sim.outOccup || sim.outTraitsCells || sim.outTraitsRows) PreReproductionOutput(pLandscape, pComm, rep, yr, 0); if (sim.outRange || sim.outPop) RangePopOutput(pComm, rep, yr, 0); -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " completed final summary output" << endl; -#endif pComm->resetPopns(); @@ -642,12 +641,6 @@ int RunModel(Landscape* pLandscape, int seqsim) if (grad.gradient) paramsGrad->resetOptY(); pLandscape->resetLandLimits(); -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " landIx=" << "reset" - << " npatchchanges=" << npatchchanges << " ncostchanges=" << ncostchanges - << " ixpchchg=" << ixpchchg << " ixcostchg=" << ixcostchg - << endl; -#endif if (ppLand.patchModel && ppLand.dynamic && ixpchchg > 0) { // apply any patch changes to reset landscape to original configuration // (provided that at least one has already occurred) @@ -656,7 +649,6 @@ int RunModel(Landscape* pLandscape, int seqsim) Cell* pCell; patchchange = pLandscape->getPatchChange(ixpchchg++); while (patchchange.chgnum <= 666666 && ixpchchg <= npatchchanges) { - // move cell from original patch to new patch pCell = pLandscape->findCell(patchchange.x, patchchange.y); if (patchchange.oldpatch != 0) { // not matrix @@ -670,7 +662,7 @@ int RunModel(Landscape* pLandscape, int seqsim) pPatch = pLandscape->findPatch(patchchange.newpatch); pPatch->addCell(pCell, patchchange.x, patchchange.y); } - pCell->setPatch((intptr)pPatch); + pCell->setPatch(pPatch); // get next patch change patchchange = pLandscape->getPatchChange(ixpchchg++); } @@ -678,15 +670,14 @@ int RunModel(Landscape* pLandscape, int seqsim) pLandscape->resetPatches(); } if (ppLand.dynamic) { - trfrRules trfr = pSpecies->getTrfr(); - if (trfr.moveModel && trfr.moveType == 1) { // SMS + transferRules trfr = pSpecies->getTransferRules(); + if (trfr.usesMovtProc && trfr.moveType == 1) { // SMS if (ixcostchg > 0) { // apply any cost changes to reset landscape to original configuration // (provided that at least one has already occurred) Cell* pCell; costchange = pLandscape->getCostChange(ixcostchg++); while (costchange.chgnum <= 666666 && ixcostchg <= ncostchanges) { - pCell = pLandscape->findCell(costchange.x, costchange.y); if (pCell != 0) { pCell->setCost(costchange.newcost); @@ -699,18 +690,23 @@ int RunModel(Landscape* pLandscape, int seqsim) if (!trfr.costMap) pLandscape->resetCosts(); // in case habitats have changed } } -#if RSDEBUG - DEBUGLOG << "RunModel(): yr=" << yr << " completed reset" - << endl; -#endif if (sim.outConnect && ppLand.patchModel) pLandscape->resetConnectMatrix(); // set connectivity matrix to zeroes if (sim.outInds) // close Individuals output file - pComm->outInds(rep, 0, 0, -999); - if (sim.outGenetics) // close Genetics output file - pComm->outGenetics(rep, 0, 0, -999); + pComm->outIndsFinishReplicate(); + + if (sim.outputGenes) { // close genetic values output file + pComm->openOutGenesFile(false, -999, rep); + } + + //if (sim.outputGlobalFst) //close per locus file + // pComm->openNeutralOutputFile(pSpecies, -999); + if (sim.outputPerLocusFst) //close per locus file + pComm->openPerLocusFstFile(pSpecies, pLandscape, -999, rep); + if (sim.outPairwiseFst) //close per locus file + pComm->openPairwiseFstFile(pSpecies, pLandscape, -999, rep); if (sim.saveVisits) { pLandscape->outVisits(rep, ppLand.landNum); @@ -719,47 +715,52 @@ int RunModel(Landscape* pLandscape, int seqsim) #if RS_RCPP if (sim.outPaths) - pLandscape->outPathsHeaders(rep, -999); -#endif -#if RSDEBUG - DEBUGLOG << endl << "RunModel(): finished rep=" << rep << endl; + pLandscape->outPathsFinishReplicate(); #endif } // end of the replicates loop if (sim.outConnect && ppLand.patchModel) { pLandscape->deleteConnectMatrix(); - pLandscape->outConnectHeaders(-999); // close Connectivity Matrix file + pLandscape->outConnectFinishLandscape(); // close Connectivity Matrix file } // Occupancy outputs if (sim.outOccup && sim.reps > 1) { - MemoLine("Writing final occupancy output..."); pComm->outOccupancy(); - pComm->outOccSuit(v.viewGraph); + pComm->outOccSuit(); pComm->deleteOccupancy((sim.years / sim.outIntOcc) + 1); - pComm->outOccupancyHeaders(-999); - MemoLine("...finished"); + pComm->outOccupancyFinishLandscape(); } if (sim.outRange) { - pComm->outRangeHeaders(pSpecies, -999); // close Range file + pComm->outRangeFinishLandscape(); // close Range file } +#if RS_RCPP + if (sim.outPop && sim.CreatePopFile) { +#else if (sim.outPop) { - pComm->outPopHeaders(pSpecies, -999); // close Population file +#endif + pComm->outPopFinishLandscape(); // close Population file } if (sim.outTraitsCells) - pComm->outTraitsHeaders(pSpecies, -999); // close Traits file + pComm->outTraitsFinishLandscape(); // close Traits file if (sim.outTraitsRows) - pComm->outTraitsRowsHeaders(pSpecies, -999); // close Traits rows file + pComm->outTraitsRowsFinishLandscape(); // close Traits rows file // close Individuals & Genetics output files if open // they can still be open if the simulation was stopped by the user - if (sim.outInds) pComm->outInds(0, 0, 0, -999); - if (sim.outGenetics) pComm->outGenetics(0, 0, 0, -999); + if (sim.outInds) pComm->outIndsFinishReplicate(); + if (sim.outputGenes) pComm->openOutGenesFile(0, -999, 0); + if (sim.outputGlobalFst) { + pComm->openNeutralOutputFile(pSpecies, -999); + } + if (sim.outputPerLocusFst) { + pComm->openPerLocusFstFile(pSpecies, pLandscape, -999, 0); + } + if (sim.outPairwiseFst) pComm->openPairwiseFstFile(pSpecies, pLandscape, -999, 0); - MemoLine("Deleting community..."); - delete pComm; pComm = 0; - MemoLine("...finished"); + delete pComm; + pComm = 0; #if RS_RCPP && !R_CMD return list_outPop; @@ -780,61 +781,46 @@ bool is_directory(const char* pathname) { #endif //--------------------------------------------------------------------------- -bool CheckDirectory(void) +bool CheckDirectory(const string& pathToProjDir) { bool errorfolder = false; string subfolder; - subfolder = paramsSim->getDir(0) + "Inputs"; + subfolder = pathToProjDir + "Inputs"; const char* inputs = subfolder.c_str(); if (!is_directory(inputs)) errorfolder = true; - subfolder = paramsSim->getDir(0) + "Outputs"; + subfolder = pathToProjDir + "Outputs"; const char* outputs = subfolder.c_str(); if (!is_directory(outputs)) errorfolder = true; - subfolder = paramsSim->getDir(0) + "Output_Maps"; + subfolder = pathToProjDir + "Output_Maps"; const char* outputmaps = subfolder.c_str(); if (!is_directory(outputmaps)) errorfolder = true; - return errorfolder; + if (errorfolder) { + cout << endl << "***** Invalid working directory: " << pathToProjDir + << endl << endl; + cout << "***** Working directory must contain Inputs, Outputs and Output_Maps folders" + << endl << endl; + cout << "*****" << endl; + cout << "***** Simulation ABORTED" << endl; + cout << "*****" << endl; + return false; +} + else return true; } //--------------------------------------------------------------------------- //For outputs and population visualisations pre-reproduction void PreReproductionOutput(Landscape* pLand, Community* pComm, int rep, int yr, int gen) { -#if RSDEBUG - landParams ppLand = pLand->getLandParams(); -#endif simParams sim = paramsSim->getSim(); - simView v = paramsSim->getViews(); - -#if RSDEBUG - DEBUGLOG << "PreReproductionOutput(): 11111 rep=" << rep << " yr=" << yr << " gen=" << gen - << " landNum=" << ppLand.landNum << " maxX=" << ppLand.maxX << " maxY=" << ppLand.maxY - << endl; - DEBUGLOG << "PreReproductionOutput(): 11112 outRange=" << sim.outRange - << " outIntRange=" << sim.outIntRange - << " outPop=" << sim.outPop << " outIntPop=" << sim.outIntPop - << endl; -#endif - - traitCanvas tcanv; - for (int i = 0; i < NTRAITS; i++) { - tcanv.pcanvas[i] = 0; - } // trait outputs and visualisation - - if (v.viewTraits) { - tcanv = SetupTraitCanvas(); - } - - if (v.viewTraits - || ((sim.outTraitsCells && yr >= sim.outStartTraitCell && yr % sim.outIntTraitCell == 0) || - (sim.outTraitsRows && yr >= sim.outStartTraitRow && yr % sim.outIntTraitRow == 0))) + if ((sim.outTraitsCells && yr >= sim.outStartTraitCell && yr % sim.outIntTraitCell == 0) + || (sim.outTraitsRows && yr >= sim.outStartTraitRow && yr % sim.outIntTraitRow == 0)) { - pComm->outTraits(tcanv, pSpecies, rep, yr, gen); + pComm->outTraits(pSpecies, rep, yr, gen); } if (sim.outOccup && yr % sim.outIntOcc == 0 && gen == 0) pComm->updateOccupancy(yr / sim.outIntOcc, rep); @@ -848,7 +834,11 @@ void RangePopOutput(Community* pComm, int rep, int yr, int gen) if (sim.outRange && (yr % sim.outIntRange == 0 || pComm->totalInds() <= 0)) pComm->outRange(pSpecies, rep, yr, gen); +#if RS_RCPP +if (sim.outPop && sim.CreatePopFile && yr >= sim.outStartPop && yr%sim.outIntPop == 0) +#else if (sim.outPop && yr >= sim.outStartPop && yr % sim.outIntPop == 0) +#endif pComm->outPop(rep, yr, gen); } @@ -864,10 +854,10 @@ void OutParameters(Landscape* pLandscape) genLandParams ppGenLand = pLandscape->getGenLandParams(); envGradParams grad = paramsGrad->getGradient(); envStochParams env = paramsStoch->getStoch(); - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); settleRules srules; settleSteps ssteps; @@ -877,22 +867,15 @@ void OutParameters(Landscape* pLandscape) string name; if (sim.batchMode) name = paramsSim->getDir(2) - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) - + "_Land" + Int2Str(ppLand.landNum) + "_Parameters.txt"; + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + + "_Land" + to_string(ppLand.landNum) + "_Parameters.txt"; else - name = paramsSim->getDir(2) + "Sim" + Int2Str(sim.simulation) + "_Parameters.txt"; + name = paramsSim->getDir(2) + "Sim" + to_string(sim.simulation) + "_Parameters.txt"; outPar.open(name.c_str()); - outPar << "RangeShifter 2.0 "; + outPar << "RangeShifter 3.0 "; -#if !RS_RCPP -#if RSWIN64 - outPar << " - 64 bit implementation"; -#else - outPar << " - 32 bit implementation"; -#endif -#endif outPar << endl; outPar << "================ "; @@ -901,10 +884,9 @@ void OutParameters(Landscape* pLandscape) outPar << endl << endl; outPar << "BATCH MODE \t"; - if (sim.batchMode) outPar << "yes" << endl; else outPar << "no" << endl; -#if RS_RCPP - outPar << "SEED \t" << RS_random_seed << endl; -#endif + if (sim.batchMode) outPar << "yes" << endl; + else outPar << "no" << endl; + outPar << "SEED \t" << pRandom->getSeed() << endl; outPar << "REPLICATES \t" << sim.reps << endl; outPar << "YEARS \t" << sim.years << endl; outPar << "REPRODUCTIVE SEASONS / YEAR\t" << dem.repSeasons << endl; @@ -960,17 +942,6 @@ void OutParameters(Landscape* pLandscape) } #else if (sim.batchMode) outPar << " (see batch file) " << landFile << endl; - else { - outPar << habmapname << endl; - if (ppLand.rasterType == 1) { // habitat % cover - list additional layers - for (int i = 0; i < ppLand.nHab - 1; i++) { - outPar << " " << hfnames[i] << endl; - } - } - if (ppLand.patchModel) { - outPar << "PATCH FILE: " << patchmapname << endl; - } - } #endif outPar << "No. HABITATS:\t" << ppLand.nHab << endl; } @@ -984,17 +955,17 @@ void OutParameters(Landscape* pLandscape) int nchanges = pLandscape->numLandChanges(); for (int i = 0; i < nchanges; i++) { chg = pLandscape->getLandChange(i); - outPar << "Change no. " << chg.chgnum << " in year " << chg.chgyear << endl; - outPar << "Landscape: " << chg.habfile << endl; + outPar << "Change no. " << chg.chgNb << " in year " << chg.chgYear << endl; + outPar << "Landscape: " << chg.pathHabFile << endl; if (ppLand.patchModel) { - outPar << "Patches : " << chg.pchfile << endl; + outPar << "Patches : " << chg.pathPatchFile << endl; } - if (chg.costfile != "none" && chg.costfile != "NULL") { - outPar << "Costs : " << chg.costfile << endl; + if (chg.pathCostFile != "none" && chg.pathCostFile != "NULL") { + outPar << "Costs : " << chg.pathCostFile << endl; } + } } - outPar << endl << "SPECIES DISTRIBUTION LOADED: \t"; if (ppLand.spDist) { @@ -1003,9 +974,6 @@ void OutParameters(Landscape* pLandscape) outPar << "FILE NAME: "; #if !RS_RCPP if (sim.batchMode) outPar << " (see batch file) " << landFile << endl; - else { - outPar << distnmapname << endl; - } #else outPar << name_sp_dist << endl; #endif @@ -1182,7 +1150,7 @@ void OutParameters(Landscape* pLandscape) } int mSize; // index for weights matrices - if (dem.repType == 2) mSize = sstruct.nStages * NSEXES; + if (dem.repType == 2) mSize = sstruct.nStages * gMaxNbSexes; else mSize = sstruct.nStages; outPar << "DENSITY-DEPENDENCE IN FECUNDITY:\t"; @@ -1192,8 +1160,8 @@ void OutParameters(Landscape* pLandscape) outPar << "STAGE'S WEIGHTS:" << endl; for (int i = 0; i < mSize; i++) { if (dem.repType == 2) { - outPar << "stage " << i / NSEXES << " "; - if (i % NSEXES == 0) outPar << "males : \t"; + outPar << "stage " << i / gMaxNbSexes << " "; + if (i % gMaxNbSexes == 0) outPar << "males : \t"; else outPar << "females: \t"; } else outPar << "stage " << i << ": \t"; @@ -1214,8 +1182,8 @@ void OutParameters(Landscape* pLandscape) outPar << "STAGE'S WEIGHTS:" << endl; for (int i = 0; i < mSize; i++) { if (dem.repType == 2) { - outPar << "stage " << i / NSEXES << " "; - if (i % NSEXES == 0) outPar << "males : \t"; + outPar << "stage " << i / gMaxNbSexes << " "; + if (i % gMaxNbSexes == 0) outPar << "males : \t"; else outPar << "females: \t"; } else outPar << "stage " << i << ": \t"; @@ -1234,8 +1202,8 @@ void OutParameters(Landscape* pLandscape) outPar << "STAGE'S WEIGHTS:" << endl; for (int i = 0; i < mSize; i++) { if (dem.repType == 2) { - outPar << "stage " << i / NSEXES << " "; - if (i % NSEXES == 0) outPar << "males : \t"; + outPar << "stage " << i / gMaxNbSexes << " "; + if (i % gMaxNbSexes == 0) outPar << "males : \t"; else outPar << "females: \t"; } else outPar << "stage " << i << ": \t"; @@ -1246,6 +1214,49 @@ void OutParameters(Landscape* pLandscape) else outPar << "not stage-dependent" << endl; } else outPar << "no" << endl; + + if (ppLand.spatialdemog){ + outPar << "SPATIALLY VARYING DEMOGRAPHY:\t in" << endl; + // file names for the spatial layers + + if(pSpecies->getFecSpatial()){ + outPar << "FECUNDITY" << endl; + outPar << "LAYERS:" << endl; + for (int i = 0; i < sstruct.nStages; i++) { + if (dem.repType == 2){ + outPar << "stage: " << i << "females: \t" << pSpecies->getFecLayer(i,0) << "\tmales: \t" << pSpecies->getFecLayer(i,1) << endl; + } else{ + outPar << "stage: " << i << pSpecies->getFecLayer(i,0) << endl; + } + } + } + + if(pSpecies->getDevSpatial()){ + outPar << "DEVELOPMENT" << endl; + outPar << "LAYERS:" << endl; + for (int i = 0; i < sstruct.nStages; i++) { + if (dem.repType == 2){ + outPar << "stage: " << i << "females: \t" << pSpecies->getDevLayer(i,0) << "\tmales: \t" << pSpecies->getDevLayer(i,1) << endl; + } else{ + outPar << "stage: " << i << pSpecies->getDevLayer(i,0) << endl; + } + } + } + if(pSpecies->getSurvSpatial()){ + outPar << "SURVIVAL" << endl; + outPar << "LAYERS:" << endl; + for (int i = 0; i < sstruct.nStages; i++) { + if (dem.repType == 2){ + outPar << "stage: " << i << "females: \t" << pSpecies->getSurvLayer(i,0) << "\tmales: \t" << pSpecies->getSurvLayer(i,1) << endl; + } else{ + outPar << "stage: " << i << pSpecies->getSurvLayer(i,0) << endl; + } + } + } + } + else { + outPar << "SPATIALLY VARYING DEMOGRAPHY:\t no" << endl; + } } // end of if (dem.stageStruct) else { // not stage-strutured outPar << "no" << endl; @@ -1275,9 +1286,7 @@ void OutParameters(Landscape* pLandscape) else outPar << "K "; outPar << k << endl; } - emigTraits ep0, ep1; - emigParams eparams0, eparams1; string sexdept = "SEX-DEPENDENT: "; string stgdept = "STAGE-DEPENDENT: "; string indvar = "INDIVIDUAL VARIABILITY: "; @@ -1286,7 +1295,6 @@ void OutParameters(Landscape* pLandscape) outPar << endl << "DISPERSAL - EMIGRATION:\t"; if (emig.densDep) { outPar << "density-dependent" << endl; - if (emig.sexDep) { outPar << sexdept << "yes" << endl; if (emig.stgDep) { @@ -1294,8 +1302,8 @@ void OutParameters(Landscape* pLandscape) outPar << indvar << "no" << endl; for (int i = 0; i < sstruct.nStages; i++) { outPar << "stage " << i << ":" << endl; - ep0 = pSpecies->getEmigTraits(i, 0); - ep1 = pSpecies->getEmigTraits(i, 1); + ep0 = pSpecies->getSpEmigTraits(i, 0); + ep1 = pSpecies->getSpEmigTraits(i, 1); outPar << "D0: females " << ep0.d0 << " males " << ep1.d0 << endl; outPar << "alpha: females " << ep0.alpha << " males " << ep1.alpha << endl; outPar << "beta: females " << ep0.beta << " males " << ep1.beta << endl; @@ -1303,79 +1311,37 @@ void OutParameters(Landscape* pLandscape) } else { // !emig.stgDep outPar << stgdept << "no" << endl; - outPar << indvar; - if (emig.indVar) { - eparams0 = pSpecies->getEmigParams(0, 0); - eparams1 = pSpecies->getEmigParams(0, 1); - outPar << "yes" << endl; - if (dem.stageStruct) { - outPar << emigstage << emig.emigStage << endl; - } - outPar << "D0 females: mean " << eparams0.d0Mean << " s.d. " << eparams0.d0SD - << " scaling factor " << eparams0.d0Scale << endl; - outPar << "D0 males: mean " << eparams1.d0Mean << " s.d. " << eparams1.d0SD - << " scaling factor " << eparams1.d0Scale << endl; - outPar << "Alpha females: mean " << eparams0.alphaMean << " s.d. " << eparams0.alphaSD - << " scaling factor " << eparams0.alphaScale << endl; - outPar << "Alpha males: mean " << eparams1.alphaMean << " s.d. " << eparams1.alphaSD - << " scaling factor " << eparams1.alphaScale << endl; - outPar << "Beta females: mean " << eparams0.betaMean << " s.d. " << eparams0.betaSD - << " scaling factor " << eparams0.betaScale << endl; - outPar << "Beta males: mean " << eparams1.betaMean << " s.d. " << eparams1.betaSD - << " scaling factor " << eparams1.betaScale << endl; - } - else { - outPar << "no" << endl; - ep0 = pSpecies->getEmigTraits(0, 0); - ep1 = pSpecies->getEmigTraits(0, 1); + ep0 = pSpecies->getSpEmigTraits(0, 0); + ep1 = pSpecies->getSpEmigTraits(0, 1); outPar << "D0: females " << ep0.d0 << " males " << ep1.d0 << endl; outPar << "alpha: females " << ep0.alpha << " males " << ep1.alpha << endl; outPar << "beta: females " << ep0.beta << " males " << ep1.beta << endl; } } - } else { // !emig.sexDep outPar << sexdept << "no" << endl; if (emig.stgDep) { outPar << stgdept << "yes" << endl; outPar << indvar << "no" << endl; for (int i = 0; i < sstruct.nStages; i++) { - ep0 = pSpecies->getEmigTraits(i, 0); + ep0 = pSpecies->getSpEmigTraits(i, 0); outPar << "stage " << i << ": \t" << "D0: " << ep0.d0; outPar << " \talpha: " << ep0.alpha << " \tbeta: " << ep0.beta << endl; } } else { // !emig.stgDep outPar << stgdept << "no" << endl; - outPar << indvar; - if (emig.indVar) { - eparams0 = pSpecies->getEmigParams(0, 0); - emigScales scale = pSpecies->getEmigScales(); - outPar << "yes" << endl; - if (dem.stageStruct) { - outPar << emigstage << emig.emigStage << endl; - } - outPar << "D0 mean: " << eparams0.d0Mean << " s.d.: " << eparams0.d0SD - << " scaling factor: " << scale.d0Scale << endl; - outPar << "Alpha mean: " << eparams0.alphaMean << " s.d.: " << eparams0.alphaSD - << " scaling factor: " << scale.alphaScale << endl; - outPar << "Beta mean: " << eparams0.betaMean << " s.d.: " << eparams0.betaSD - << " scaling factor: " << scale.betaScale << endl; - } - else { - outPar << "no" << endl; - ep0 = pSpecies->getEmigTraits(0, 0); + ep0 = pSpecies->getSpEmigTraits(0, 0); outPar << "D0: " << ep0.d0 << endl; outPar << "alpha: " << ep0.alpha << endl; outPar << "beta: " << ep0.beta << endl; } } } - } else { // not density-dependent string initprob = "INITIAL EMIGRATION PROB. "; outPar << "density-independent" << endl; - if (!trfr.moveModel) { // transfer by kernel + if (!trfr.usesMovtProc) { // transfer by kernel outPar << "USE FULL KERNEL TO DETERMINE EMIGRATION: "; if (pSpecies->useFullKernel()) outPar << "yes"; else outPar << "no"; @@ -1389,34 +1355,15 @@ void OutParameters(Landscape* pLandscape) outPar << indvar << "no" << endl; for (int i = 0; i < sstruct.nStages; i++) { outPar << "stage " << i << ": \t" << "EMIGRATION PROB.: \tfemales " - << pSpecies->getEmigD0(i, 0) << " \tmales " << pSpecies->getEmigD0(i, 1) << endl; + << pSpecies->getSpEmigD0(i, 0) << " \tmales " << pSpecies->getSpEmigD0(i, 1) << endl; } } else { // !emig.stgDep outPar << stgdept << "no" << endl; - outPar << indvar; - if (emig.indVar) { - eparams0 = pSpecies->getEmigParams(0, 0); - eparams1 = pSpecies->getEmigParams(0, 1); - emigScales scale = pSpecies->getEmigScales(); - outPar << "yes" << endl; - if (dem.stageStruct) { - outPar << emigstage << emig.emigStage << endl; + outPar << "EMIGRATION PROB.: \tfemales " << pSpecies->getSpEmigD0(0, 0) + << "\t males " << pSpecies->getSpEmigD0(0, 1) << endl; } - outPar << initprob << "mean: " << "females " << eparams0.d0Mean - << " males " << eparams1.d0Mean << endl; - outPar << initprob << "s.d.: " << "females " << eparams0.d0SD - << " males " << eparams1.d0SD << endl; - outPar << initprob << "scaling factor: " << scale.d0Scale - << endl; } - else { - outPar << "no" << endl; - outPar << "EMIGRATION PROB.: \tfemales " << pSpecies->getEmigD0(0, 0) - << "\t males " << pSpecies->getEmigD0(0, 1) << endl; - } - } - } else { // !emig.sexDep outPar << sexdept << "no" << endl; if (emig.stgDep) { @@ -1424,45 +1371,27 @@ void OutParameters(Landscape* pLandscape) outPar << indvar << "no" << endl; for (int i = 0; i < sstruct.nStages; i++) { outPar << "stage " << i << ": \t" << "EMIGRATION PROB.: " - << pSpecies->getEmigD0(i, 0) << endl; + << pSpecies->getSpEmigD0(i, 0) << endl; } } else { // !emig.stgDep outPar << stgdept << "no" << endl; - outPar << indvar; - if (emig.indVar) { - eparams0 = pSpecies->getEmigParams(0, 0); - emigScales scale = pSpecies->getEmigScales(); - outPar << "yes" << endl; - if (dem.stageStruct) { - outPar << emigstage << emig.emigStage << endl; + outPar << "EMIGRATION PROB.:\t" << pSpecies->getSpEmigD0(0, 0) << endl; } - outPar << initprob << "mean: " << eparams0.d0Mean << endl; - outPar << initprob << "s.d.: " << eparams0.d0SD << endl; - outPar << initprob << "scaling factor: " << scale.d0Scale << endl; } - else { - outPar << "no" << endl; - outPar << "EMIGRATION PROB.:\t" << pSpecies->getEmigD0(0, 0) << endl; } - } - } - } // Transfer outPar << endl << "DISPERSAL - TRANSFER: \t"; - if (trfr.moveModel) { - bool straigtenPath; + if (trfr.usesMovtProc) { + bool straightenPath; if (trfr.moveType == 1) { // SMS - trfrSMSTraits move = pSpecies->getSMSTraits(); - straigtenPath = move.straigtenPath; + trfrSMSTraits move = pSpecies->getSpSMSTraits(); + straightenPath = move.straightenPath; if (trfr.costMap) { outPar << "SMS\tcosts from imported cost map" << endl; -#if !RS_RCPP - outPar << "FILE NAME: " << costmapname << endl; -#endif } else { outPar << "SMS\tcosts:" << endl; @@ -1490,48 +1419,19 @@ void OutParameters(Landscape* pLandscape) outPar << "BETA DB: " << move.betaDB << endl; } } - if (trfr.indVar) { - trfrSMSParams s = pSpecies->getSMSParams(0, 0); - outPar << indvar << "yes " << endl; - outPar << "DP mean: " << s.dpMean << " s.d.: " << s.dpSD - << " scaling factor: " << s.dpScale << endl; - outPar << "GB mean: " << s.gbMean << " s.d.: " << s.gbSD - << " scaling factor: " << s.gbScale << endl; - if (move.goalType == 2) { // dispersal bias - outPar << "Alpha DB mean: " << s.alphaDBMean << " s.d.: " << s.alphaDBSD - << " scaling factor: " << s.alphaDBScale << endl; - outPar << "Beta DB mean: " << s.betaDBMean << " s.d.: " << s.betaDBSD - << " scaling factor: " << s.betaDBScale << endl; - } - } - else { outPar << indvar << "no " << endl; } - } else { // CRW - trfrCRWTraits move = pSpecies->getCRWTraits(); - straigtenPath = move.straigtenPath; + trfrCRWTraits move = pSpecies->getSpCRWTraits(); + straightenPath = move.straightenPath; outPar << "CRW" << endl; string lgth = "STEP LENGTH (m) "; string corr = "STEP CORRELATION"; - if (trfr.indVar) { - trfrCRWParams m = pSpecies->getCRWParams(0, 0); - outPar << indvar << "yes" << endl; - outPar << lgth << " mean: " << m.stepLgthMean; - outPar << " s.d.: " << m.stepLgthSD; - outPar << " scaling factor: " << m.stepLScale << endl; - outPar << corr << " mean: " << m.rhoMean; - outPar << " s.d.: " << m.rhoSD; - outPar << " scaling factor: " << m.rhoScale << endl; - } - else { - outPar << indvar << "no" << endl; outPar << lgth << ": " << move.stepLength << endl; outPar << corr << ": " << move.rho << endl; } - } outPar << "STRAIGHTEN PATH AFTER DECISION NOT TO SETTLE: "; - if (straigtenPath) outPar << "yes" << endl; + if (straightenPath) outPar << "yes" << endl; else outPar << "no" << endl; outPar << "STEP MORTALITY:\t" << endl; if (trfr.habMort) @@ -1550,15 +1450,14 @@ void OutParameters(Landscape* pLandscape) } else { - trfrCRWTraits move = pSpecies->getCRWTraits(); + trfrCRWTraits move = pSpecies->getSpCRWTraits(); outPar << "constant " << move.stepMort << endl; } } // end of movement process else { // kernel string meandist = "MEAN DISTANCE"; string probkern = "PROB. KERNEL I"; - trfrKernTraits kern0, kern1; - trfrKernParams k0, k1; + trfrKernelParams kern0, kern1; outPar << "dispersal kernel" << endl << "TYPE: \t"; if (trfr.twinKern) outPar << "double "; outPar << "negative exponential" << endl; @@ -1570,8 +1469,8 @@ void OutParameters(Landscape* pLandscape) outPar << indvar << "no" << endl; for (int i = 0; i < sstruct.nStages; i++) { outPar << "stage " << i << ":" << endl; - kern0 = pSpecies->getKernTraits(i, 0); - kern1 = pSpecies->getKernTraits(i, 1); + kern0 = pSpecies->getSpKernTraits(i, 0); + kern1 = pSpecies->getSpKernTraits(i, 1); outPar << meandist << " I: \tfemales " << kern0.meanDist1 << " \tmales " << kern1.meanDist1 << endl; if (trfr.twinKern) { @@ -1582,37 +1481,8 @@ void OutParameters(Landscape* pLandscape) } else { // !trfr.stgDep outPar << stgdept << "no" << endl; - outPar << indvar; - if (trfr.indVar) { - k0 = pSpecies->getKernParams(0, 0); - k1 = pSpecies->getKernParams(0, 1); - outPar << "yes" << endl; - outPar << meandist << " I (mean): \tfemales " << k0.dist1Mean - << " \tmales " << k1.dist1Mean << endl; - outPar << meandist << " I (s.d.): \tfemales " << k0.dist1SD - << " \tmales " << k1.dist1SD << endl; - outPar << meandist << " I (scaling factor): \tfemales " << k0.dist1Scale - << " \tmales " << k1.dist1Scale << endl; - if (trfr.twinKern) - { - outPar << meandist << " II (mean): \tfemales " << k0.dist2Mean - << " \tmales " << k1.dist2Mean << endl; - outPar << meandist << " II (s.d.): \tfemales " << k0.dist2SD - << " \tmales " << k1.dist2SD << endl; - outPar << meandist << " II (scaling factor): \tfemales " << k0.dist2Scale - << " \tmales " << k1.dist2Scale << endl; - outPar << probkern << " (mean): \tfemales " << k0.PKern1Mean - << " \tmales " << k1.PKern1Mean << endl; - outPar << probkern << " (s.d.): \tfemales " << k0.PKern1SD - << " \tmales " << k1.PKern1SD << endl; - outPar << probkern << " (scaling factor): \tfemales " << k0.PKern1Scale - << " \tmales " << k1.PKern1Scale << endl; - } - } - else { - outPar << "no" << endl; - kern0 = pSpecies->getKernTraits(0, 0); - kern1 = pSpecies->getKernTraits(0, 1); + kern0 = pSpecies->getSpKernTraits(0, 0); + kern1 = pSpecies->getSpKernTraits(0, 1); outPar << meandist << " I: \tfemales " << kern0.meanDist1 << " \tmales " << kern1.meanDist1 << endl; if (trfr.twinKern) { @@ -1621,14 +1491,13 @@ void OutParameters(Landscape* pLandscape) } } } - } else { // !trfr.sexDep outPar << sexdept << "no" << endl; if (trfr.stgDep) { outPar << stgdept << "yes" << endl; outPar << indvar << "no" << endl; for (int i = 0; i < sstruct.nStages; i++) { - kern0 = pSpecies->getKernTraits(i, 0); + kern0 = pSpecies->getSpKernTraits(i, 0); outPar << "stage " << i << ": \t" << meandist << " I: " << kern0.meanDist1; if (trfr.twinKern) { @@ -1640,26 +1509,7 @@ void OutParameters(Landscape* pLandscape) } else { // !trfr.stgDep outPar << stgdept << "no" << endl; - outPar << indvar; - if (trfr.indVar) { - k0 = pSpecies->getKernParams(0, 0); - outPar << "yes" << endl; - outPar << meandist << " I (mean): " << k0.dist1Mean - << " \t(s.d.): " << k0.dist1SD - << " \t(scaling factor): " << k0.dist1Scale << endl; - if (trfr.twinKern) - { - outPar << meandist << " II (mean): " << k0.dist2Mean - << " \t(s.d.): " << k0.dist2SD - << " \t(scaling factor): " << k0.dist2Scale << endl; - outPar << probkern << " (mean): " << k0.PKern1Mean - << " \t(s.d.): " << k0.PKern1SD - << " \t(scaling factor): " << k0.PKern1Scale << endl; - } - } - else { - outPar << "no" << endl; - kern0 = pSpecies->getKernTraits(0, 0); + kern0 = pSpecies->getSpKernTraits(0, 0); outPar << meandist << " I: \t" << kern0.meanDist1 << endl; if (trfr.twinKern) { @@ -1668,7 +1518,6 @@ void OutParameters(Landscape* pLandscape) } } } - } outPar << "DISPERSAL MORTALITY: "; trfrMortParams mort = pSpecies->getMortParams(); @@ -1685,7 +1534,7 @@ void OutParameters(Landscape* pLandscape) outPar << endl << "DISPERSAL - SETTLEMENT:" << endl; - if (trfr.moveModel) { + if (trfr.usesMovtProc) { string plusmating = "+ mating requirements"; if (sett.sexDep) { @@ -1761,7 +1610,7 @@ void OutParameters(Landscape* pLandscape) outPar << "find a suitable cell/patch "; srules = pSpecies->getSettRules(i, sx); if (srules.densDep) { - settleDD = pSpecies->getSettTraits(i, sx); + settleDD = pSpecies->getSpSettTraits(i, sx); outPar << "+ density dependence "; if (srules.findMate) outPar << plusmating; outPar << endl; @@ -1782,25 +1631,7 @@ void OutParameters(Landscape* pLandscape) } } } - if (sett.indVar) { - settParams sparams0; - outPar << "DENSITY DEPENDENCE + " << indvar << "yes" << endl; - for (int sex = 0; sex < nsexes; sex++) { - if (sett.sexDep) { - if (sex == 0) outPar << "FEMALES:" << endl; - else outPar << "MALES:" << endl; } - sparams0 = pSpecies->getSettParams(0, sex); - settScales scale = pSpecies->getSettScales(); - outPar << "S0 - mean: " << sparams0.s0Mean << " s.d.: " << sparams0.s0SD - << " scaling factor: " << scale.s0Scale << endl; - outPar << "AlphaS - mean: " << sparams0.alphaSMean << " s.d.: " << sparams0.alphaSSD - << " scaling factor: " << scale.alphaSScale << endl; - outPar << "BetaS - mean: " << sparams0.betaSMean << " s.d.: " << sparams0.betaSSD - << " scaling factor: " << scale.betaSScale << endl; - } - } - } else { // kernel-based transfer string notsuit = "IF THE ARRIVAL CELL/PATCH IS UNSUITABLE: "; string rchoose = " randomly choose a suitable neighb. cell/patch or "; @@ -1860,72 +1691,65 @@ void OutParameters(Landscape* pLandscape) } // Genetics - outPar << endl << "GENETICS:" << endl; - int nspptraits = pSpecies->getNTraits(); - outPar << "No. of variable traits: " << nspptraits << endl; - genomeData d = pSpecies->getGenomeData(); - if (emig.indVar || trfr.indVar || sett.indVar || d.neutralMarkers) - { - if (d.diploid) outPar << "DIPLOID" << endl; else outPar << "HAPLOID" << endl; - int nchromosomes = pSpecies->getNChromosomes(); - outPar << "No. of chromosomes: " << nchromosomes; - if (d.trait1Chromosome) { - outPar << endl << "No. of loci/chromosome: " << d.nLoci << endl; - } - else { - outPar << " (chrom:loci)"; - for (int i = 0; i < nchromosomes; i++) { - outPar << " " << i << ":" << pSpecies->getNLoci(i); - } + // only if genetics are simulated + if(sim.outputGenes) { + set traitList = pSpecies->getTraitTypes(); + + if (pSpecies->isDiploid()) outPar << "DIPLOID" << endl; else outPar << "HAPLOID" << endl; + outPar << "Genome size: " << pSpecies->getGenomeSize() << endl; + outPar << "Chromosome breaks : "; + + for (auto end : pSpecies->getChromosomeEnds()) + outPar << end << " "; outPar << endl; - } - outPar << "Mutation probability: " << d.probMutn << endl; - outPar << "Crossover probability: " << d.probCrossover << endl; - outPar << "Initial allele s.d.: " << d.alleleSD << endl; - outPar << "Mutation s.d.: " << d.mutationSD << endl; - if (d.neutralMarkers) { - outPar << "NEUTRAL MARKERS ONLY" << endl; - } - else { - if (!d.trait1Chromosome) { - traitAllele allele; - outPar << "TRAIT MAPPING:" << endl; - outPar << "Architecture file: " << genfilename << endl; - int ntraitmaps = pSpecies->getNTraitMaps(); - outPar << "No. of traits defined: " << ntraitmaps << endl; - for (int i = 0; i < ntraitmaps; i++) { - int nalleles = pSpecies->getNTraitAlleles(i); - outPar << "Trait " << i << ": (" << pSpecies->getTraitName(i) - << ") alleles: " << nalleles << " (chrom:locus)"; - for (int j = 0; j < nalleles; j++) { - allele = pSpecies->getTraitAllele(i, j); - outPar << " " << allele.chromo << ":" << allele.locus; - } - outPar << endl; - } - if (ntraitmaps < nspptraits) { // list undefined traits - outPar << "WARNING - the following traits were not defined" - << " in the genetic architecture file:" << endl; - for (int i = ntraitmaps; i < nspptraits; i++) { - outPar << "Trait " << i << ": (" << pSpecies->getTraitName(i) - << ") all individuals have mean phenotype" << endl; - } - } - int nneutral = pSpecies->getNNeutralLoci(); - if (nneutral > 0) { - outPar << "Neutral loci: " << nneutral << " (chrom:locus)"; - for (int i = 0; i < nneutral; i++) { - allele = pSpecies->getNeutralAllele(i); - outPar << " " << allele.chromo << ":" << allele.locus; - } - outPar << endl; - } - if (d.pleiotropic) - outPar << "Genome exhibits pleiotropy" << endl; - } - } + outPar << "Recombination rate: " << pSpecies->getRecombinationRate() << endl; + outPar << "Traits modelled: " << endl; + for (auto trait : traitList) + outPar << trait << endl; + } else { + outPar << "No genetics simulated" << endl; + } + + + // Management + managementParams manage = pManagement->getManagementParams(); + translocationParams transloc = pManagement->getTranslocationParams(); + if(manage.translocation){ + outPar << endl << "MANAGEMENT - TRANSLOCATION: \t"; + // loop over translocation_years and print them + outPar << endl; + outPar << "Catching rate: " << transloc.catching_rate << endl; + for( int i = 0; i < transloc.translocation_years.size(); i++ ) { + auto yr = transloc.translocation_years[i]; + auto it = transloc.nb.find(yr); + auto nb_it = transloc.nb.find(yr); + auto source_it = transloc.source.find(yr); + auto target_it = transloc.target.find(yr); + auto min_age_it = transloc.min_age.find(yr); + auto max_age_it = transloc.max_age.find(yr); + auto stage_it = transloc.stage.find(yr); + auto sex_it = transloc.sex.find(yr); + outPar << " Translocation events in year: " << yr << endl; + for( int j = 0; j < it->second.size(); j++ ){ + outPar << " Event Nr. " << j+1 << " :" << endl; + // if it is a cell based model + if(ppLand.patchModel){ + outPar << " Source patch ID: " << source_it->second[j].x << endl; + outPar << " Target patch ID: " << target_it->second[j].x << endl; + } else{ + outPar << " Source cell: X " << source_it->second[j].x << " Y " << source_it->second[j].y << endl; + outPar << " Target cell: X " << target_it->second[j].x << " Y " << target_it->second[j].y << endl; + } + outPar << " Min age: " << min_age_it->second[j] << endl; + outPar << " Max age: " << max_age_it->second[j] << endl; + outPar << " Stage: " << stage_it->second[j] << endl; + outPar << " Sex: " << sex_it->second[j] << endl; + outPar << " Number of individuals: " << nb_it->second[j] << endl; + + } + } } // Initialisation @@ -2010,6 +1834,9 @@ void OutParameters(Landscape* pLandscape) outPar << "GEOGRAPHICAL CONSTRAINTS (cell numbers): " << endl; outPar << "min X: " << init.minSeedX << " max X: " << init.maxSeedX << endl; outPar << "min Y: " << init.minSeedY << " max Y: " << init.maxSeedY << endl; + // if (init.seedType != 1 && init.freeType < 2 && init.initFrzYr > 0) { + // outPar << "Freeze initial range until year " << init.initFrzYr << endl; + // } if (init.seedType == 0 && init.freeType < 2) { if (init.initFrzYr > 0) { outPar << "Freeze initial range until year " << init.initFrzYr << endl; @@ -2028,11 +1855,13 @@ void OutParameters(Landscape* pLandscape) if (sim.outRange) { outPar << "Range - every " << sim.outIntRange << " year"; if (sim.outIntRange > 1) outPar << "s"; + // if (sim.outStartRange > 0) outPar << " starting year " << sim.outStartRange; outPar << endl; } if (sim.outOccup) { outPar << "Occupancy - every " << sim.outIntOcc << " year"; if (sim.outIntOcc > 1) outPar << "s"; + // if (sim.outStartOcc > 0) outPar << " starting year " << sim.outStartOcc; outPar << endl; } if (sim.outPop) { @@ -2047,27 +1876,20 @@ void OutParameters(Landscape* pLandscape) if (sim.outStartInd > 0) outPar << " starting year " << sim.outStartInd; outPar << endl; } - if (sim.outGenetics) { - outPar << "Genetics - every " << sim.outIntGenetic << " year"; - if (sim.outIntGenetic > 1) outPar << "s"; - if (sim.outStartGenetic > 0) outPar << " starting year " << sim.outStartGenetic; - if (dem.stageStruct) { - switch (sim.outGenType) { - case 0: - outPar << " - juveniles only"; - break; - case 1: - outPar << " - all individuals"; - break; - case 2: - outPar << " - adults only"; - break; - } - } - if (sim.outGenXtab) outPar << " (as cross table)"; + if (sim.outputGlobalFst) { + outPar << "Global Fst and neutral genetics - every " << sim.outputGlobalFstInterval << " year"; + if (sim.outputGlobalFstInterval > 1) outPar << "s"; + if (sim.outputPerLocusFst) outPar << "outputting per locus Fst too"; + outPar << endl; + } + + if (sim.outPairwiseFst) { + outPar << "Pairwise Fst - every " << sim.outputPairwiseFstInterval << " year"; + if (sim.outputPairwiseFstInterval > 1) outPar << "s"; outPar << endl; } + if (sim.outTraitsCells) { outPar << "Traits per "; if (ppLand.patchModel) outPar << "patch"; else outPar << "cell"; @@ -2096,28 +1918,13 @@ void OutParameters(Landscape* pLandscape) outPar << endl; } #endif - outPar << "SAVE MAPS: "; - if (sim.saveMaps) { - outPar << "yes - every " << sim.mapInt << " year"; - if (sim.mapInt > 1) outPar << "s"; - outPar << endl; - } - else outPar << "no" << endl; - outPar << "SAVE TRAITS MAPS: "; - if (sim.saveTraitMaps) { - outPar << "yes - every " << sim.traitInt << " year"; - if (sim.traitInt > 1) outPar << "s"; - outPar << endl; - } - else outPar << "no" << endl; - if (trfr.moveModel && trfr.moveType == 1) { + + if (trfr.usesMovtProc && trfr.moveType == 1) { outPar << "SMS HEAT MAPS: "; if (sim.saveVisits) outPar << "yes" << endl; else outPar << "no" << endl; } - outPar.close(); outPar.clear(); - } //--------------------------------------------------------------------------- diff --git a/Model.h b/RangeShiftR/src/RScore/Model.h similarity index 67% rename from Model.h rename to RangeShiftR/src/RScore/Model.h index f48d155..61474c0 100644 --- a/Model.h +++ b/RangeShiftR/src/RScore/Model.h @@ -1,25 +1,25 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * + * --------------------------------------------------------------------------*/ - - + + /*------------------------------------------------------------------------------ RangeShifter v2.0 Model @@ -33,14 +33,14 @@ Further functions are declared here, but defined differently in main function of GUI and batch versions. For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. + eco-evolutionary dynamics and species’ responses to environmental changes. Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 Authors: Greta Bocedi & Steve Palmer, University of Aberdeen -Last updated: 26 October 2021 by Steve Palmer + Last updated: 28 July 2021 by Greta Bocedi ------------------------------------------------------------------------------*/ #ifndef ModelH @@ -48,26 +48,29 @@ Last updated: 26 October 2021 by Steve Palmer #include #include +#if RS_RCPP +#include +#include "../Rinterface.h" +#endif // RS_RCPP +#include #include "Parameters.h" #include "Landscape.h" #include "Community.h" #include "SubCommunity.h" #include "Species.h" +#include "Management.h" -#if !RS_EMBARCADERO && !LINUX_CLUSTER && !RS_RCPP +#if !LINUX_CLUSTER && !RS_RCPP #include using namespace std::filesystem; #endif -#if RSDEBUG -extern ofstream DEBUGLOG; -#endif - #if RS_RCPP && !R_CMD Rcpp::List RunModel( Landscape*, // pointer to Landscape - int // sequential simulation number + int, // sequential simulation number + Rcpp::S4 // parameter master to read initial conditions in each replicate simulation ); #else int RunModel( @@ -75,7 +78,9 @@ int RunModel( int // sequential simulation number ); #endif // RS_RCPP && !R_CMD -bool CheckDirectory(void); + +bool CheckDirectory(const string& pathToProjDir); + void PreReproductionOutput( Landscape*, // pointer to Landscape Community*, // pointer to Community @@ -89,20 +94,7 @@ void RangePopOutput( int, // year int // generation ); -void Outputs_Visuals_B( - int, // replicate - int, // year - int, // generation - int // Landscape number -); -void RefreshVisualCost(void); -traitCanvas SetupTraitCanvas(void); -void SetupVisualOutput(void); -void ResetVisualOutput(void); -void DrawPopnGraph( - Community*, // pointer to Community - int // year -); + void OutParameters( Landscape* // pointer to Landscape ); @@ -113,26 +105,11 @@ extern Species *pSpecies; extern paramSim *paramsSim; extern paramInit *paramsInit; extern Community *pComm; +extern Management *pManagement; -const bool batchMode = true; extern string landFile; -extern vector hfnames; -extern string habmapname; // see Main.cpp (batch) -extern string patchmapname; // see Main.cpp (batch) -extern string distnmapname; // see Main.cpp (batch) -extern string costmapname; // see Main.cpp (batch) -extern string genfilename; // see Main.cpp (batch) extern RSrandom *pRandom; -// these functions to have different version for GUI and batch applications ... -#if BATCH -extern void MemoLine(string); -#endif -void GUIsetLandScale( - int, // landscape image height (pixels) - int // landscape image width (pixels) -); - #if RS_RCPP extern std::uint32_t RS_random_seed; extern string name_landscape, name_patch, name_costfile, name_sp_dist; diff --git a/RangeShiftR/src/RScore/NeutralStatsManager.cpp b/RangeShiftR/src/RScore/NeutralStatsManager.cpp new file mode 100644 index 0000000..6acdc19 --- /dev/null +++ b/RangeShiftR/src/RScore/NeutralStatsManager.cpp @@ -0,0 +1,592 @@ +#include "NeutralStatsManager.h" +#include "Population.h" + +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + + // ---------------------------------------------------------------------------------------- + // Constructor + // ---------------------------------------------------------------------------------------- +NeutralStatsManager::NeutralStatsManager(const int& nbSampledPatches, const int nLoci) { + this->pairwiseFstMatrix = PatchMatrix(nbSampledPatches, nbSampledPatches); + commNeutralCountTables.reserve(nLoci); //don't have to be pointers, not shared or moved + + perLocusFst = perLocusFis = perLocusFit = vector(nLoci, 0.0); +} + +// ---------------------------------------------------------------------------------------- +// Populate population and community-level NEUTRAL count tables +// Update allele occurrence and heterozygosity counts, and allele frequencies +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::updateAllNeutralTables(Species* pSpecies, Landscape* pLandscape, set const& patchList) { + + const int nLoci = pSpecies->getNPositionsForTrait(NEUTRAL); + const int maxNbNeutralAlleles = pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); + const int ploidy = pSpecies->isDiploid() ? 2 : 1; + + // Create / Update community-level NEUTRAL counts table + if (!commNeutralCountTables.empty()) { + resetCommNeutralTables(); + } + else { // populate the tables with default values + for (int thisLocus = 0; thisLocus < nLoci; thisLocus++) { + NeutralCountsTable newNeutralTbl = NeutralCountsTable(maxNbNeutralAlleles); + commNeutralCountTables.push_back(newNeutralTbl); + } + } + + int nbSampledInds = 0; + int patchAlleleCount; + + // Update counts for each population + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + // Update this population's NEUTRAL counts tables + pPop->updatePopNeutralTables(); + nbSampledInds += pPop->sampleSize(); + } + // Add population-level counts to community-level counts + for (int thisLocus = 0; thisLocus < nLoci; thisLocus++) { + for (int allele = 0; allele < maxNbNeutralAlleles; allele++) { + + if (pPop != 0) { + patchAlleleCount = pPop->getAlleleTally(thisLocus, allele); + } + else { + patchAlleleCount = 0; + } + commNeutralCountTables[thisLocus].incrementTallyBy(patchAlleleCount, allele); + } + } + } + + // Update community-level frequencies + std::for_each(commNeutralCountTables.begin(), + commNeutralCountTables.end(), + [&](NeutralCountsTable& v) -> void { + v.setFrequencies(nbSampledInds * ploidy); + }); +} + +// ---------------------------------------------------------------------------------------- +// Reset allele tables in NeutralTable structs +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::resetCommNeutralTables() { + for (auto& entry : commNeutralCountTables) { + entry.reset(); + } +} + +// ---------------------------------------------------------------------------------------- +// Calculate allelic diversity metrics +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::calcAllelicDiversityMetrics(set const& patchList, const int nInds, Species* pSpecies, Landscape* pLandscape) +{ + int i, j; + const int nLoci = pSpecies->getNPositionsForTrait(NEUTRAL); + const int nAlleles = pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); + const int ploidy = pSpecies->isDiploid() ? 2 : 1; + unsigned int nbPops = 0; + int nbAllelesInPatch = 0; + double meanAllelicDivInPatch = 0; + bool alleleExistsInPop = 0; + + vector> alleleExistsInCommTable(nLoci); + for (i = 0; i < nLoci; ++i) { + alleleExistsInCommTable[i] = vector(nAlleles, false); + } + + // Compute mean nb alleles per locus per patch + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + if (pPop->sampleSize() > 0) { + nbPops++; + nbAllelesInPatch = 0; + for (i = 0; i < nLoci; ++i) + for (j = 0; j < nAlleles; ++j) { + alleleExistsInPop = pPop->getAlleleTally(i, j) != 0; + nbAllelesInPatch += alleleExistsInPop; + alleleExistsInCommTable[i][j] = alleleExistsInCommTable[i][j] || alleleExistsInPop; + } + // add mean nb of alleles per locus for Patch k to the pop mean + meanAllelicDivInPatch += static_cast(nbAllelesInPatch) / nLoci; + } + } + } + meanNbAllelesPerLocusPerPatch = nbPops > 0 ? meanAllelicDivInPatch / nbPops : 0; + + // Compute mean nb alleles per locus + meanNbAllelesPerLocus = 0; + for (i = 0; i < nLoci; ++i) + for (j = 0; j < nAlleles; ++j) + meanNbAllelesPerLocus += alleleExistsInCommTable[i][j]; + meanNbAllelesPerLocus /= nLoci; + + // Compute number of fixed loci per patch + // mean number of loci that are fixed at pop level per pop + meanNbFixedLociPerPatch = 0; + if (nbPops > 0) { + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + for (i = 0; i < nLoci; ++i) + for (j = 0; j < nAlleles; ++j) + meanNbFixedLociPerPatch += pPop->getAlleleFrequency(i, j) == 1; + } + } + meanNbFixedLociPerPatch /= nbPops; + } + + // Compute number of fixed loci + meanFixedLoci = 0; + for (i = 0; i < nLoci; ++i) + for (j = 0; j < nAlleles; ++j) + meanFixedLoci += commNeutralCountTables[i].getFrequency(j) == 1; +} + +// ---------------------------------------------------------------------------------------- +// Calculate Ho per Nei and Chesser +// Average (observed) heterozygosity per individual +// Sum (nb of heterozygote loci) across individuals / nb individuals / nb loci +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::calculateHo(set const& patchList, const int nbInds, const int nbrLoci, Species* pSpecies, Landscape* pLandscape) { + + int nbHetero = 0; + + if (nbInds != 0 && pSpecies->isDiploid()) { + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) nbHetero += pPop->countHeterozygoteLoci(); + } + ho = static_cast(nbHetero) / (nbInds * nbrLoci); + } + else ho = 0.0; +} + +// ---------------------------------------------------------------------------------------- +// Calculate Hs per Nei and Chesser +// Average expected population-level heterozygosity per locus per population +// currently not used but may be useful +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::calculateHs(set const& patchList, const int nbrLoci, Species* pSpecies, Landscape* pLandscape) { + + double hs = 0; + int nPatches = 0; + + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop->sampleSize() > 0) { + nPatches++; + hs += pPop->computeHs(); + } + } + hs = (nPatches != 0 ? hs / (nbrLoci * nPatches) : 0.0); +} + +// ---------------------------------------------------------------------------------------- +// Calculate Ht per Nei and Chesser +// Average expected community-level heterozygosity per locus +// Currently not used but may be useful +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::calculateHt(Species* pSpecies, Landscape* pLandscape, const int nLoci, const int nAlleles) { + + double ht = 0; + int nPatches = 0; + vectorlocihet(nLoci, 1); + double freq; + + for (int thisLocus = 0; thisLocus < nLoci; ++thisLocus) { + for (int allele = 0; allele < nAlleles; ++allele) { + freq = commNeutralCountTables[thisLocus].getFrequency(allele); + freq *= freq; //squared frequencies + locihet[thisLocus] -= freq; //1 - sum of p2 = expected heterozygosity + } + ht += locihet[thisLocus]; + } + ht = ht / nLoci; +} + +// ---------------------------------------------------------------------------------------- +// Calculate Ho per locus as per Nei and Chesser +// Observed proportion of heterozygote individuals for each locus +// Sum (nb of heterozygote individuals) / nb individuals for each locus +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::calculatePerLocusHo(set const& patchList, const int nbInds, const int nbrLoci, Species* pSpecies, Landscape* pLandscape) { + + vector nbHeterosInComm(nbrLoci, 0); + vector nbHeterosInPop(nbrLoci); + + if (pSpecies->isDiploid()) { + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + if (pPop->sampleSize() > 0) { + nbHeterosInPop = pPop->countNbHeterozygotesEachLocus(); + // Add counts to community total + transform(nbHeterosInComm.begin(), nbHeterosInComm.end(), nbHeterosInPop.begin(), + nbHeterosInComm.begin(), plus()); + } + } + } + } + + perLocusHo = vector(nbrLoci, 0); + if (nbInds != 0) { + for (int i = 0; i < nbHeterosInComm.size(); i++) { + perLocusHo[i] = static_cast(nbHeterosInComm[i]) / nbInds; + } + } +} + +// ---------------------------------------------------------------------------------------- +// Fstat Weir & Cockerham +// ---------------------------------------------------------------------------------------- +void NeutralStatsManager::calculateFstatWC(set const& patchList, const int nbSampledIndsInComm, const int nLoci, const int nAlleles, + Species* pSpecies, Landscape* pLandscape, bool isPairwise) { + + double inverseNtotal; + double sumWeights = 0; + double nBar, nC, inverseNbar; + unsigned int nbPops = 0; + const int totalSampleSize = nbSampledIndsInComm; // r * n_bar + const double ploidy = pSpecies->isDiploid() ? 2.0 : 1.0; + + + // Reset per-locus vectors between generations + perLocusFst = perLocusFis = perLocusFit = vector(nLoci, 0.0); + + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + int popSampleSize = pPop->sampleSize(); // n_i + if (popSampleSize > 0) { + nbPops++; + sumWeights += static_cast(popSampleSize * popSampleSize) / totalSampleSize; // sum(n_i^2/rn_bar) + } + } + } + + nbExtantPops = nbPops; // r + totalNbSampledInds = nbSampledIndsInComm; + + if (nbPops > 1) { + + // Calculate F stats + nBar = static_cast(totalSampleSize) / nbPops; // average sample size, cannot be less than 1 + nC = (totalSampleSize - sumWeights) / (nbPops - 1); + double nBarMinusOne = (nBar == 1.0) ? 1.0 : nBar - 1.0; // avoid / 0 if exactly 1 ind per pop + inverseNbar = 1.0 / nBarMinusOne; + inverseNtotal = 1.0 / totalSampleSize; + + double var, intermediateTerm; + double s2, pBar, hBar; + int pairwiseAlleleCount; + double s2Denom = (nbPops - 1) * nBar; + double rTerm = static_cast(nbPops - 1) / nbPops; + double hBarFactor = (2 * nBar - 1) / (4 * nBar); + + double numFst = 0.0, numFis = 0.0, numFit = 0.0; + double denomFst = 0.0, denomFis = 0.0, denomFit = 0.0; + + for (int l = 0; l < nLoci; ++l) { + + // Sums of a_u, b_u, c_u for all alleles u at locus l + double a_l = 0, b_l = 0, c_l = 0; + + for (int u = 0; u < nAlleles; ++u) { + + pBar = s2 = hBar = 0; + pairwiseAlleleCount = 0; + + //if global wc approach use this + if (!isPairwise) { + pBar = commNeutralCountTables[l].getFrequency(u); + } + //else calculate total frequencies just in pair of patches for pairwise + else { + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + double patchLocusAlleleTally = pPop->getAlleleTally(l, u); + pairwiseAlleleCount += patchLocusAlleleTally; + } + const double denomAlleleCount = totalSampleSize * ploidy; + pBar = pairwiseAlleleCount / denomAlleleCount; + + } + + for (int patchId : patchList) { + const auto patch = pLandscape->findPatch(patchId); + const auto pPop = patch->getPopn(pSpecies); + if (pPop != 0) { + var = pPop->getAlleleFrequency(l, u) - pBar; + var *= var; + s2 += var * pPop->sampleSize(); + hBar += pPop->getHeteroTally(l, u); // n_i * h_i + + } + } //end for pop + + s2 /= s2Denom; + hBar /= static_cast(totalSampleSize); // / (r * n_bar) + + intermediateTerm = pBar * (1 - pBar) - rTerm * s2; + a_l += s2 - inverseNbar * (intermediateTerm - 0.25 * hBar); + b_l += intermediateTerm - hBarFactor * hBar; + c_l += hBar; + + } // end for allele + + a_l *= nBar / nC; + b_l *= nBar / nBarMinusOne; + c_l *= 0.5; + + perLocusFst[l] = a_l / (a_l + b_l + c_l); + perLocusFis[l] = (b_l + c_l) == 0.0 ? 0.0 : b_l / (b_l + c_l); + perLocusFit[l] = a_l + b_l / (a_l + b_l + c_l); + + numFst += a_l; + numFis += b_l; + numFit += a_l + b_l; + denomFst += a_l + b_l + c_l; + denomFis += b_l + c_l; + + } // end for locus + + denomFit = denomFst; // same quantity + + fst = numFst / denomFst; // theta hat in eq. 1 in WC 1984 + fis = (denomFis == 0.0) ? 0.0 : numFis / denomFis; // f hat + fit = numFit / denomFit; // F hat + } + else { // zero or one sampled pops, cannot compute F-stats + fst = 0.0; + fis = 0.0; + fit = 0.0; + } +} + +////////New pairwise function /////////// + + +void NeutralStatsManager::calculatePairwiseFst(set const& patchList, const int nLoci, const int nAlleles, Species* pSpecies, Landscape* pLandscape) { + + // Needs to be in vector to iterate over, copy preserves order + vector patchVect; + copy(patchList.begin(), patchList.end(), std::back_inserter(patchVect)); + + const int nPatches = static_cast(patchVect.size()); + + // Initialise + pairwiseFstMatrix = PatchMatrix(nPatches, nPatches); + + // Reset table + pairwiseFstMatrix.setAll(0.0); // or nanf("NULL")? + + + for (int i = 0; i < nPatches - 1; ++i) + { + const auto patchA = pLandscape->findPatch(patchVect[i]); + const auto pPopA = patchA->getPopn(pSpecies); + + // Skip if patch A has no individuals + if (pPopA->sampleSize() == 0) + continue; + + for (int j = i + 1; j < nPatches; ++j) + { + const auto patchB = pLandscape->findPatch(patchVect[j]); + const auto pPopB = patchB->getPopn(pSpecies); + + // Skip if patch B has no individuals + if (pPopB->sampleSize() == 0) + continue; + + // Build pair-of-patches list + set pairofPatchesList; + pairofPatchesList.insert(patchVect[i]); + pairofPatchesList.insert(patchVect[j]); + + // Total individuals in the pair + int nbSampledIndsInPair = pPopA->sampleSize() + pPopB->sampleSize(); + + //NB this overwrites global fst variable so be careful!! + calculateFstatWC(pairofPatchesList, nbSampledIndsInPair, + nLoci, nAlleles,pSpecies, pLandscape, true); + + pairwiseFstMatrix.set(i, j, fst); + // else remain 0 + } + } + +} + + + +// ---------------------------------------------------------------------------------------- +// Patch pairwise Fst +// Computes the weighted within and between patch Fst's as well as the overall Fst (Theta). +// The method used here is that of Weir & Hill 2002, Ann.Rev.Genet. 36:721 - 750. +// The weighting is done for samples(patches) of unequal sizes. +// ---------------------------------------------------------------------------------------- +//void NeutralStatsManager::calcPairwiseWeightedFst(set const& patchList, const int nInds, const int nLoci, Species* pSpecies, Landscape* pLandscape) { +// +// const int nAlleles = (int)pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); +// +// // Needs to be in vector to iterate over, copy preserves order +// vector patchVect; +// copy(patchList.begin(), patchList.end(), std::back_inserter(patchVect)); +// +// int nPatches = static_cast(patchList.size()); +// int nbPops = 0; +// +// // Initialise +// pairwiseFstMatrix = PatchMatrix(nPatches, nPatches); +// +// // Reset table +// pairwiseFstMatrix.setAll(0.0); // or nanf("NULL")? +// +// //init +// vector popWeights(nPatches); +// vector popSizes(nPatches); +// vector> numeratorPairwiseFst(nPatches); +// for (int i = 0; i < nPatches; i++) numeratorPairwiseFst[i].resize(nPatches); +// double totSize; +// double numeratorWeightedFst = 0; +// double denominator = 0; +// double sumWeights = 0; +// +// totalNbSampledInds = nInds; +// totSize = nInds; +// +// // Calculate weight (n_ic) terms +// for (int i = 0; i < nPatches; ++i) { +// const auto patch = pLandscape->findPatch(patchVect[i]); +// const auto pPop = patch->getPopn(pSpecies); +// if (pPop != 0) { +// popSizes[i] = pPop->sampleSize(); +// } // else popSizes[i] remain default init value 0, safe +// popWeights[i] = popSizes[i] - (popSizes[i] * popSizes[i] / totSize); // n_ic in Weir & Hill 2002 +// sumWeights += popWeights[i]; +// if (popSizes[i] > 0) nbPops++; +// +// // Fill the pairwise Fst matrix with default value 0 +// for (int j = 0; j < nPatches; j++) +// numeratorPairwiseFst[i][j] = 0; +// } +// +// nbExtantPops = nbPops; +// +// if (nbPops > 1) { +// // Calculate Fst numerators and denominators +// double p, pq, pBar, sqDist, num; +// for (int i = 0; i < nPatches; ++i) { +// if (popSizes[i] == 0) continue; +// const auto patch = pLandscape->findPatch(patchVect[i]); +// const auto pPop = patch->getPopn(pSpecies); +// +// for (int l = 0; l < nLoci; ++l) { +// for (int u = 0; u < nAlleles; ++u) { +// p = pPop->getAlleleFrequency(l, u); //p_liu +// pq = p * (1 - p); +// pBar = commNeutralCountTables[l].getFrequency(u); +// sqDist = p - pBar; //(p_liu - pbar_u)^2 +// sqDist *= sqDist; +// +// num = pq * popSizes[i] ; // eq. 8 Weir & Hill 2002 +// num /= popSizes[i] == 1 ? 1 : popSizes[i] - 1; // avoid division by zero +// numeratorPairwiseFst[i][i] += num; +// numeratorWeightedFst += num * popSizes[i]; // see equ. 9, Weir & Hill 2002 +// denominator += popSizes[i] * sqDist + popWeights[i] * pq; //common denominator +// +// } // end for allele +// } // end for locus +// } // end for pop +// +// // Diagonals +// double pairwiseFst; +// for (int i = 0; i < nPatches; ++i) { +// if (popSizes[i] == 0) continue; +// else if (denominator != 0) +// { +// pairwiseFst = 1 - (numeratorPairwiseFst[i][i] * sumWeights / denominator); +// pairwiseFstMatrix.set(i, i, pairwiseFst); +// } +// // else remain 0 +// } +// +// // Add allele frequencies to numerators +// double pi, pj; +// for (int l = 0; l < nLoci; ++l) +// for (int u = 0; u < nAlleles; ++u) +// for (int i = 0; i < nPatches - 1; ++i) { // nPatches-1 bc bottom row not filled +// if (popSizes[i] == 0) continue; +// const auto patch = pLandscape->findPatch(patchVect[i]); +// const auto pPopI = patch->getPopn(pSpecies); +// +// for (int j = i + 1; j < nPatches; ++j) { // fill only upper half of matrix +// if (popSizes[j] == 0) continue; +// const auto patch = pLandscape->findPatch(patchVect[j]); +// const auto pPopJ = patch->getPopn(pSpecies); +// +// pi = pPopI->getAlleleFrequency(l, u); +// pj = pPopJ->getAlleleFrequency(l, u); +// numeratorPairwiseFst[i][j] += pi * (1 - pj) + pj * (1 - pi); // equ. 7 of Weir & Hill 2002 +// } +// } +// +// // Final estimates of pairwise Fst (beta_ii' in eq. 7 in WC 2002) +// for (int i = 0; i < nPatches - 1; ++i) { +// if (popSizes[i] == 0) continue; // Fst for this pair remains NULL +// for (int j = i + 1; j < nPatches; ++j) { +// if (popSizes[j] == 0) continue; +// else if (denominator != 0) { +// pairwiseFst = 1 - (numeratorPairwiseFst[i][j] * sumWeights) / (2 * denominator); +// pairwiseFstMatrix.set(i, j, pairwiseFst); +// } +// // else remain 0 +// } +// } +// +// // Estimator of global Fst weighted by sample sizes (beta_W in eq. 9 in WH 2002) +// if (denominator != 0) { +// weightedFst = 1 - (numeratorWeightedFst * sumWeights) / (denominator * totSize); // beta_w in Eq. 9 in WH 2002 +// } +// else { +// weightedFst = 0.0; +// } +// } +// else { // zero or one pop, cannot calculate Fst +// // pairwiseFstMatrix keeps default values (0) +// weightedFst = 0.0; +// } +//} + diff --git a/RangeShiftR/src/RScore/NeutralStatsManager.h b/RangeShiftR/src/RScore/NeutralStatsManager.h new file mode 100644 index 0000000..dbc24c8 --- /dev/null +++ b/RangeShiftR/src/RScore/NeutralStatsManager.h @@ -0,0 +1,195 @@ +#ifndef NEUTRALSTATSH +#define NEUTRALSTATSH + +#include "Species.h" +#include "Landscape.h" +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + + +using namespace std; + +// Patch * patch matrix to store pairwise Fst calculations +/** Creates an array of doubles of size = rows*cols, taken from NEMO **/ +struct PatchMatrix +{ +public: + PatchMatrix(unsigned int nRows = 0, unsigned int nCols = 0) : + rows{ nRows }, + cols{ nCols }, + nbCells{nCols * nRows} { + value.resize(nbCells); + }; + + // Get value at specified position + double get(unsigned int i, unsigned int j) { + if (i >= cols || j >= rows) + throw runtime_error("PatchMatrix::get() out of range!\n"); + else return value[i * cols + j]; + } + + int getNbCells() { return nbCells; }; + + /** Sets element at row i and column j to value val **/ + void set(unsigned int i, unsigned int j, double val) { + if (i >= cols || j >= rows) + throw runtime_error("PatchMatrix::set() out of range!\n"); + else value[i * cols + j] = val; + } + + /** Assigns a value to all elements of the matrix. */ + void setAll(double val) + { + for (unsigned int i = 0; i < nbCells; ++i) value[i] = val; + } + +private: + unsigned int rows, cols, nbCells; + vector value; +}; + +// Counts of NEUTRAL allele occurrences in populations +// for neutral statistics calculations +struct NeutralCountsTable { + +public: + NeutralCountsTable(int maxNbNeutralAlleles) : alleleTallies(maxNbNeutralAlleles), alleleFrequencies(maxNbNeutralAlleles), alleleHeterozygoteTallies(maxNbNeutralAlleles) {}; + + void reset() { + fill(alleleTallies.begin(), alleleTallies.end(), 0); fill(alleleFrequencies.begin(), alleleFrequencies.end(), 0); + fill(alleleHeterozygoteTallies.begin(), alleleHeterozygoteTallies.end(), 0); + } + + // Getters + int getTally(int whichAllele) { return alleleTallies[whichAllele]; }; + double getFrequency(int whichAllele) { return alleleFrequencies[whichAllele]; }; + int getHeteroTally(int whichAllele) { + return alleleHeterozygoteTallies[whichAllele]; + }; + + // Setters / increments + void incrementTally(int whichAllele) { alleleTallies[whichAllele]++; }; + void incrementTallyBy(int count, int whichAllele) { this->alleleTallies[whichAllele] += count; } + void incrementHeteroTally(int whichAllele) { this->alleleHeterozygoteTallies[whichAllele]++; } + void setFrequencies(int sampleSize) { + for (int i = 0; i < alleleFrequencies.size(); i++) { + alleleFrequencies[i] = sampleSize > 0 ? static_cast(alleleTallies[i]) / sampleSize : 0.0; + } + }; + +private: + // Tallies, one for each possible allele (so absolute max size is 255) + vector alleleTallies; // number of occurrences of each allele in pop + vector alleleFrequencies; // frequency of each allele in pop + vector alleleHeterozygoteTallies; // nb of times each allele is found in a heterozygous pair +}; + + +// Handles calculations of neutral statistics +class NeutralStatsManager { + +public: + + NeutralStatsManager(const int& nbSampledPatches, const int nLoci); + + // Count alleles and their frequencies in all pops and community + void updateAllNeutralTables(Species* pSpecies, Landscape* pLandscape, set const& patchList); + void resetCommNeutralTables(); + + void calcAllelicDiversityMetrics(set const& patchList, const int nInds, Species* pSpecies, Landscape* pLandscape); + + // Heterozygosity calculations + void calculateHo(set const& patchList, const int totalNbSampledInds, const int nbrLoci, Species* pSpecies, Landscape* pLandscape); + void calculateHs(set const& patchList, const int nbrLoci, Species* pSpecies, Landscape* pLandscape); + void calculateHt(Species* pSpecies, Landscape* pLandscape, const int nLoci, const int nAlleles); + void calculatePerLocusHo(set const& patchList, const int totalNbSampledInds, const int nbrLoci, Species* pSpecies, Landscape* pLandscape); + + + + + // F-stats calculations + void calculateFstatWC(set const& patchList, const int nbSampledIndsInComm, const int nLoci, const int nAlleles, Species* pSpecies, Landscape* pLandscape, bool isPairwise); + + void calculatePairwiseFst(set const& patchList, const int nLoci, const int nAlleles, Species* pSpecies, Landscape* pLandscape); + + //void calcPairwiseWeightedFst(set const& patchList, const int nInds, const int nLoci, Species* pSpecies, Landscape* pLandscape); + + // Getters + int getNbPopulatedSampledPatches() const { return nbExtantPops; } + int getTotalNbSampledInds() const { return totalNbSampledInds; } + + double getMeanNbAllPerLocusPerPatch() const { return meanNbAllelesPerLocusPerPatch; } + double getMeanNbAllPerLocus() const { return meanNbAllelesPerLocus; } + double getMeanFixdAllelesPerPatch() const { return meanNbFixedLociPerPatch; } + double getTotalFixdAlleles() const { return meanFixedLoci; } + + double getHo() const { return ho; } + double getHs() const { return hs; } + double getHt() const { return ht; } + + double getPerLocusHo(int i) const { return perLocusHo[i]; } + + double getFstWC() const { return fst; } + double getFisWC() const { return fis; } + double getFitWC() const { return fit; } + + //double getWeightedFst() { return weightedFst; } + + double getPerLocusFst(int i) const { return perLocusFst[i]; } + double getPerLocusFis(int i) const { return perLocusFis[i]; } + double getPerLocusFit(int i) const { return perLocusFit[i]; } + + double getPairwiseFst(int i, int j) { return pairwiseFstMatrix.get(i, j); } + +private: + + int nbExtantPops, totalNbSampledInds; + vector commNeutralCountTables; // community-level tallies of allele counts and freqs + + double meanNbAllelesPerLocusPerPatch, meanNbAllelesPerLocus; + double meanNbFixedLociPerPatch, meanFixedLoci; + + double ho; // observed heterozygosity + double hs; // expected population-level heterozygosity + double ht; // expected community-level heterozygosity + + vector perLocusHo; // Per-locus observed heterozygosity + + // F-statistics + // Weir & Cockerham (1984) F-stat estimates. + double fst, fis, fit; + + // Weir & Hill (2002) F-stat estimates + double weightedFst; + + // Per-locus F-stats (Weir & Cockerham). + vector perLocusFst, perLocusFis, perLocusFit; + + // Pairwise Fst matrix + PatchMatrix pairwiseFstMatrix; +}; + +#endif + + + + diff --git a/RangeShiftR/src/RScore/NeutralTrait.cpp b/RangeShiftR/src/RScore/NeutralTrait.cpp new file mode 100644 index 0000000..dc7742a --- /dev/null +++ b/RangeShiftR/src/RScore/NeutralTrait.cpp @@ -0,0 +1,341 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#include "NeutralTrait.h" + +// ---------------------------------------------------------------------------------------- +// Initialisation constructor +// Called when initialising community +// Sets up initial values, and immutable attributes (distributions and parameters) +// that are defined at the species-level +// ---------------------------------------------------------------------------------------- +NeutralTrait::NeutralTrait(SpeciesTrait* P) +{ + pSpeciesTrait = P; + + DistributionType mutationDistribution = pSpeciesTrait->getMutationDistribution(); + map mutationParameters = pSpeciesTrait->getMutationParameters(); + + // Set default value to user-specified max + wildType = (int)mutationParameters.find(MAX)->second; + if (wildType > NeutralValUpperBound) + throw logic_error("max number of alleles cannot exceed " + to_string(NeutralValUpperBound) + ".\n"); + + _inherit_func_ptr = (pSpeciesTrait->getPloidy() == 1) ? &NeutralTrait::inheritHaploid : &NeutralTrait::inheritDiploid; //this could be changed if we wanted some alternative form of inheritance + + if (mutationDistribution == SSM) + _mutate_func_ptr = &NeutralTrait::mutate_SSM; + + if (mutationDistribution == KAM) + _mutate_func_ptr = &NeutralTrait::mutate_KAM; + + if (mutationDistribution != SSM && mutationDistribution != KAM) + throw logic_error("wrong mutation distribution for neutral markers, must be KAM or SSM \n"); + + if (mutationParameters.count(MAX) != 1) + throw logic_error("KAM or SSM mutation distribution parameter must contain max value (e.g. max= ), max cannot exceed 256 \n"); + + DistributionType initialDistribution = pSpeciesTrait->getInitialDistribution(); + map initialParameters = pSpeciesTrait->getInitialParameters(); + + if (mutationDistribution == SSM && initialDistribution != UNIFORM) + throw logic_error("If using SSM mutation model for neutral trait, must use uniform initial distribution.\n"); + + switch (initialDistribution) { + case UNIFORM: + { + if (initialParameters.count(MAX) != 1) + throw logic_error("initial distribution parameter must contain one max value if set to UNIFORM (e.g. max= ), max cannot exceed " + to_string(NeutralValUpperBound) + "\n"); + + float maxNeutralVal = initialParameters.find(MAX)->second; + if (maxNeutralVal > NeutralValUpperBound) { + throw logic_error("initial distribution parameter max cannot exceed " + to_string(NeutralValUpperBound) + ", resetting to " + to_string(NeutralValUpperBound) + "\n"); + maxNeutralVal = NeutralValUpperBound; //reserve 255 for wildtype + } + initialiseUniform(maxNeutralVal); + break; + } + default: + { + throw logic_error("wrong parameter value for parameter \"initialisation of neutral trait\", must be left uniform \n"); + break; //should return false + } + } +} + +// ---------------------------------------------------------------------------------------- +// Inheritance constructor +// Copies immutable features from a parent trait +// Only called via clone() +// ---------------------------------------------------------------------------------------- +NeutralTrait::NeutralTrait(const NeutralTrait& T) : + pSpeciesTrait(T.pSpeciesTrait), _mutate_func_ptr(T._mutate_func_ptr), _inherit_func_ptr(T._inherit_func_ptr) { +} + +// ---------------------------------------------------------------------------------------- +// mutate options +// ---------------------------------------------------------------------------------------- + +// ---------------------------------------------------------------------------------------- +// Draw and apply mutations according to a KAM process +// +// Mutations drawn only for existing positions, +// that is no new genes are created during simulation +// KAM = randomly drawn value in 0-MAX, differs from previous value +// ---------------------------------------------------------------------------------------- +void NeutralTrait::mutate_KAM() +{ + const int positionsSize = pSpeciesTrait->getPositionsSize(); + const auto& genePositions = pSpeciesTrait->getGenePositions(); + const short ploidy = pSpeciesTrait->getPloidy(); + const float mutationRate = pSpeciesTrait->getMutationRate(); + auto rng = pRandom->getRNG(); + unsigned char mut; + + map mutationParameters = pSpeciesTrait->getMutationParameters(); + + int maxNeutralVal = (int)mutationParameters.find(MAX)->second; + if (maxNeutralVal > NeutralValUpperBound) maxNeutralVal = NeutralValUpperBound; //reserve max value for wildtype + + for (int whichChromosome = 0; whichChromosome < ploidy; whichChromosome++) { + + unsigned int NbMut = pRandom->Binomial(positionsSize, mutationRate); + if (NbMut > 0) { + vector mutationPositions; + sample(genePositions.begin(), genePositions.end(), std::back_inserter(mutationPositions), + NbMut, rng); // without replacement + + for (int m : mutationPositions) { + mut = (unsigned char)pRandom->IRandom(0, maxNeutralVal); // draw new mutation, could draw wildtype + + auto it = genes.find(m); + if (it == genes.end()) + throw runtime_error("Locus selected for mutation doesn't exist."); + auto currentChar = it->second[whichChromosome]; // current allele + if (maxNeutralVal > 0) { // dodge the infinite loop + do { + mut = (unsigned char)pRandom->IRandom(0, maxNeutralVal); + } while (mut == currentChar); // new allele value is different + } + else mut = 0; + it->second[whichChromosome] = mut; //overwrite with new value + } + } + } +} + + +// ---------------------------------------------------------------------------------------- +// Draw and apply single-step mutations (SSM) +// +// Mutations drawn only for existing positions, +// that is no new genes are created during simulation +// Increment previous value by 1 or -1, +// unless already 0 (then always +1) or MAX (then always -1) +// ---------------------------------------------------------------------------------------- +void NeutralTrait::mutate_SSM() +{ + const int positionsSize = pSpeciesTrait->getPositionsSize(); + const auto& genePositions = pSpeciesTrait->getGenePositions(); + const short ploidy = pSpeciesTrait->getPloidy(); + const float mutationRate = pSpeciesTrait->getMutationRate(); + auto rng = pRandom->getRNG(); + + map mutationParameters = pSpeciesTrait->getMutationParameters(); + + int maxNeutralVal = (int)mutationParameters.find(MAX)->second; + if (maxNeutralVal > NeutralValUpperBound) maxNeutralVal = NeutralValUpperBound; //reserved max value for wildtype + + for (int whichChromosome = 0; whichChromosome < ploidy; whichChromosome++) { + + unsigned int NbMut = pRandom->Binomial(positionsSize, mutationRate); + if (NbMut > 0) { + vector mutationPositions; + sample(genePositions.begin(), genePositions.end(), std::back_inserter(mutationPositions), + NbMut, rng); + + for (int m : mutationPositions) { + int mutateUp = pRandom->Bernoulli(0.5); + auto it = genes.find(m); + if (it == genes.end()) + throw runtime_error("Locus selected for mutation doesn't exist."); + auto currentAllele = it->second[whichChromosome]; + if (mutateUp == 1 && currentAllele < maxNeutralVal) + it->second[whichChromosome] += 1; // one step up + else if (currentAllele > 0) // step down or already max + it->second[whichChromosome] -= 1; // one step down + else // current allele is 0, step up + it->second[whichChromosome] += 1; + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// Wrapper to inheritance function +// ---------------------------------------------------------------------------------------- +void NeutralTrait::inheritGenes(const bool& fromMother, QuantitativeTrait* parent, set const& recomPositions, int startingChromosome) +{ + auto parentCast = dynamic_cast (parent); // must convert QuantitativeTrait to NeutralTrait + const auto& parent_seq = parentCast->getGenes(); + (this->*_inherit_func_ptr) (fromMother, parent_seq, recomPositions, startingChromosome); +} + +// ---------------------------------------------------------------------------------------- +// Inheritance for diploid, sexual species +// Called once for each parent. Given a list of recombinant sites, +// populates offspring genes with appropriate parent alleles +// Assumes mother genes are inherited first +// ---------------------------------------------------------------------------------------- +void NeutralTrait::inheritDiploid(const bool& fromMother, map> const& parentGenes, set const& recomPositions, int parentChromosome) { + + const int lastPosition = parentGenes.rbegin()->first; + auto recomIt = recomPositions.lower_bound(parentGenes.begin()->first); + // If no recombination sites, only breakpoint is last position + // i.e., no recombination occurs + int nextBreakpoint = recomIt == recomPositions.end() ? lastPosition : *recomIt; + + // Is the first parent gene position already recombinant? + auto distance = std::distance(recomPositions.begin(), recomIt); + if (distance % 2 != 0) + parentChromosome = 1 - parentChromosome; //switch chromosome + + for (auto const& [locus, allelePair] : parentGenes) { + + // Switch chromosome if locus is past recombination site + while (locus > nextBreakpoint) { + parentChromosome = 1 - parentChromosome; + std::advance(recomIt, 1); // go to next recombination site + nextBreakpoint = recomIt == recomPositions.end() ? lastPosition : *recomIt; + } + + if (locus <= nextBreakpoint) { + unsigned char parentAllele = allelePair[parentChromosome]; + auto it = genes.find(locus); + if (it == genes.end()) { + // locus does not exist yet, create and initialise it + if (!fromMother) throw runtime_error("Father-inherited locus does not exist."); + vector newAllelePair(2, wildType); + newAllelePair[sex_t::FEM] = parentAllele; + genes.insert(make_pair(locus, newAllelePair)); + } + else { // father, locus already exists + if (fromMother) throw runtime_error("Mother-inherited locus already exists."); + it->second[sex_t::MAL] = parentAllele; + } + } + } +} + +// ---------------------------------------------------------------------------------------- +// Inheritance for haploid, asexual species +// Simply pass down parent genes +// Arguments are still needed to match overloaded function in base class +// ---------------------------------------------------------------------------------------- +void NeutralTrait::inheritHaploid(const bool& fromMother, map> const& parentGenes, set const& recomPositions, int parentChromosome) +{ + genes = parentGenes; +} + +// ---------------------------------------------------------------------------------------- +// Initialise neutral loci +// ---------------------------------------------------------------------------------------- +void NeutralTrait::initialiseUniform(int maxAlleleVal) +{ + const auto& genePositions = pSpeciesTrait->getGenePositions(); + const auto& initPositions = pSpeciesTrait->getInitPositions(); + short ploidy = pSpeciesTrait->getPloidy(); + + for (auto position : genePositions) { + vector allelePair; + + for (int i = 0; i < ploidy; i++) { + unsigned char alleleVal = char(0); + if (initPositions.contains(position)) { + // allele values span 0 - max inclusive, max is wildtype + alleleVal = (unsigned char)pRandom->IRandom(0, maxAlleleVal); + } + allelePair.emplace_back(alleleVal); + } + genes.insert(make_pair(position, allelePair)); + } +} + + +// ---------------------------------------------------------------------------------------- +// Check if particular loci is heterozygote +// ---------------------------------------------------------------------------------------- +bool NeutralTrait::isHeterozygoteAtLocus(int locus) const { + // assumes diploidy + auto it = genes.find(locus); + if (it == genes.end()) + throw runtime_error("Neutral gene queried for heterozygosity does not exist."); + else + return(it->second[0] != it->second[1]); +} + +// ---------------------------------------------------------------------------------------- +// Count heterozygote loci in genome +// ---------------------------------------------------------------------------------------- +int NeutralTrait::countHeterozygoteLoci() const { + // assumes diploidy + int count = 0; + for (auto const& [locus, allelePair] : genes) { + count += (allelePair[0] != allelePair[1]); + } + return count; +} + +// ---------------------------------------------------------------------------------------- +// Get allele value at loci +// ---------------------------------------------------------------------------------------- +float NeutralTrait::getAlleleValueAtLocus(short whichChromosome, int position) const { + + auto it = genes.find(position); + if (it == genes.end()) //no mutations there + throw runtime_error("The neutral locus queried for its allele value does not exist."); + return it->second[whichChromosome]; +} + +#ifdef UNIT_TESTS // Testing only + +// Create a default set of neutral alleles for testing +// +// Shorthand function to manually set genotypes for neutral +// traits, instead of having to manipulate mutations. +map> createTestNeutralGenotype( + const int genomeSz, const bool isDiploid, + const unsigned char valAlleleA, + const unsigned char valAlleleB +) { + vector gene(isDiploid ? 2 : 1); + gene[0] = valAlleleA; + if (isDiploid) gene[1] = valAlleleB; + + map> genotype; + for (int i = 0; i < genomeSz; i++) { + genotype.emplace(i, gene); + } + return genotype; +} + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/NeutralTrait.h b/RangeShiftR/src/RScore/NeutralTrait.h new file mode 100644 index 0000000..aa87159 --- /dev/null +++ b/RangeShiftR/src/RScore/NeutralTrait.h @@ -0,0 +1,116 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#ifndef NeutralTRAITH +#define NeutralTRAITH + +#include +#include +#include +#include + +#include "QuantitativeTrait.h" + +using namespace std; + +// Neutral traits +// +// Not expressed and are only used to compute neutral statistics +// e.g. the Fst. +// To save on mem usage, allele values are represented by character types, +// taking a value between 0 and a user-specified max >= 255 +class NeutralTrait : public QuantitativeTrait { + +public: + + // Initialisation constructor, set initial values and immutable features + NeutralTrait(SpeciesTrait* P); + + // Inheritance constructor, copies pointers to immutable features when cloning from parent + NeutralTrait(const NeutralTrait& T); + + // Make a shallow copy to pass to offspring trait + // Return new pointer to new trait created by inheritance c'tor + // This avoids copying shared attributes: distributions and parameters + virtual unique_ptr clone() const override { return std::make_unique(*this); } + + virtual ~NeutralTrait() { } + + // Getters + virtual int getNLoci() const override { return pSpeciesTrait->getPositionsSize(); } + float getMutationRate() const override { return pSpeciesTrait->getMutationRate(); } + bool isInherited() const override { return pSpeciesTrait->isInherited(); } + map>& getGenes() { return genes; } //returning reference, reciever must be const + + virtual void mutate() override { (this->*_mutate_func_ptr) (); } + virtual void inheritGenes(const bool& fromMother, QuantitativeTrait* parent, set const& recomPositions, int startingChromosome) override; + virtual float express() { + throw runtime_error("Neutral trait shouldn't be expressed."); + return -9999; + } + + virtual float getAlleleValueAtLocus(short chromosome, int position) const override; + virtual float getDomCoefAtLocus(short chromosome, int position) const override { + return 0.0; + } + + int countHeterozygoteLoci() const; + bool isHeterozygoteAtLocus(int locus) const; + +private: + + inline static int wildType; // default allele value, value set at construction + const int NeutralValUpperBound = UCHAR_MAX; // alleles are char, can take value 0-255 + + // > + map> genes; + + // Initialisation + void initialiseUniform(int max); + + // Immutable features, set at initialisation + // and passed down to every subsequent trait copy + //// Species-level trait attributes, invariant across individuals + SpeciesTrait* pSpeciesTrait; + //// Species-level trait functions + void (NeutralTrait::* _mutate_func_ptr) (void); + void (NeutralTrait::* _inherit_func_ptr) (const bool& fromMother, map> const& parent, set const& recomPositions, int parentChromosome); + + // Possible values for immutable functions + //// Inheritance + void inheritDiploid(const bool& fromMother, map> const&, set const& recomPositions, int parentChromosome); + void inheritHaploid(const bool& fromMother, map> const& parentMutations, set const& recomPositions, int parentChromosome); + //// Mutation + void mutate_KAM(); + void mutate_SSM(); // single-step mutations + +}; + +#ifdef UNIT_TESTS // for testing purposes only +map> createTestNeutralGenotype( + const int genomeSz, const bool isDiploid, + const unsigned char valAlleleA, + const unsigned char valAlleleB = char(0) // if haploid +); +#endif + +#endif // NeutralTraitH diff --git a/Parameters.cpp b/RangeShiftR/src/RScore/Parameters.cpp similarity index 64% rename from Parameters.cpp rename to RangeShiftR/src/RScore/Parameters.cpp index 5cfb3d7..ff36d9d 100644 --- a/Parameters.cpp +++ b/RangeShiftR/src/RScore/Parameters.cpp @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -128,7 +128,7 @@ paramInit::paramInit(void) { minSeedX = 0; maxSeedX = 99999999; minSeedY = 0; maxSeedY = 99999999; nSeedPatches = 1; nSpDistPatches = 1; indsFile = "NULL"; - for (int i = 0; i < NSTAGES; i++) { + for (int i = 0; i < gMaxNbStages; i++) { initProp[i] = 0.0; } } @@ -176,12 +176,12 @@ initParams paramInit::getInit(void) { } void paramInit::setProp(short stg, float p) { - if (stg >= 0 && stg < NSTAGES && p >= 0.0 && p <= 1.0) initProp[stg] = p; + if (stg >= 0 && stg < gMaxNbStages && p >= 0.0 && p <= 1.0) initProp[stg] = p; } float paramInit::getProp(short stg) { float p = 0.0; - if (stg >= 0 && stg < NSTAGES) p = initProp[stg]; + if (stg >= 0 && stg < gMaxNbStages) p = initProp[stg]; return p; } @@ -210,30 +210,27 @@ int paramInit::numInitInds(void) { return (int)initinds.size(); } // Simulation parameters -paramSim::paramSim(void) { +paramSim::paramSim(const string& pathToProjDir) : + dir{pathToProjDir} +{ simulation = 0; reps = years = 1; outIntRange = 1; - outStartPop = outStartInd = outStartGenetic = 0; + outStartPop = outStartInd = 0; outStartTraitCell = outStartTraitRow = outStartConn = 0; - outIntOcc = outIntPop = outIntInd = outIntGenetic = 10; + outputGlobalFstStart = outputPairwiseFstStart = 0; + outIntOcc = outIntPop = outIntInd = outputGlobalFstInterval = outputPairwiseFstInterval= 10; outIntTraitCell = outIntTraitRow = outIntConn = 10; - mapInt = traitInt = 10; - slowFactor = 1; + traitInt = 10; batchMode = absorbing = false; outRange = outOccup = outPop = outInds = false; - outGenetics = outGenXtab = false; outGenType = 0; outTraitsCells = outTraitsRows = outConnect = false; - saveMaps = false; saveTraitMaps = false; + outputGenes = outputGlobalFst = outPairwiseFst = false; saveVisits = false; #if RS_RCPP outStartPaths = 0; outIntPaths = 0; - outPaths = false; ReturnPopRaster = false; CreatePopFile = true; + outPaths = false; ReturnPopMatrix = false; ReturnPopDataFrame = false; CreatePopFile = true; #endif - drawLoaded = false; - viewLand = false; viewPatch = false; viewGrad = false; viewCosts = false; - viewPop = false; viewTraits = false; viewPaths = false; viewGraph = false; - dir = ' '; } paramSim::~paramSim(void) { } @@ -243,21 +240,14 @@ void paramSim::setSim(simParams s) { if (s.simulation >= 0) simulation = s.simulation; if (s.reps >= 1) reps = s.reps; if (s.years >= 1) years = s.years; - if (s.mapInt >= 1) mapInt = s.mapInt; if (s.traitInt >= 1) traitInt = s.traitInt; batchMode = s.batchMode; absorbing = s.absorbing; outRange = s.outRange; outOccup = s.outOccup; outPop = s.outPop; outInds = s.outInds; - outGenetics = s.outGenetics; - if (s.outGenType >= 0 && s.outGenType <= 2) { - outGenType = s.outGenType; - } - outGenXtab = s.outGenXtab; outTraitsCells = s.outTraitsCells; outTraitsRows = s.outTraitsRows; outConnect = s.outConnect; if (s.outStartPop >= 0) outStartPop = s.outStartPop; if (s.outStartInd >= 0) outStartInd = s.outStartInd; - if (s.outStartGenetic >= 0) outStartGenetic = s.outStartGenetic; if (s.outStartTraitCell >= 0) outStartTraitCell = s.outStartTraitCell; if (s.outStartTraitRow >= 0) outStartTraitRow = s.outStartTraitRow; if (s.outStartConn >= 0) outStartConn = s.outStartConn; @@ -265,78 +255,86 @@ void paramSim::setSim(simParams s) { if (s.outIntOcc >= 1) outIntOcc = s.outIntOcc; if (s.outIntPop >= 1) outIntPop = s.outIntPop; if (s.outIntInd >= 1) outIntInd = s.outIntInd; - if (s.outIntGenetic >= 1) outIntGenetic = s.outIntGenetic; if (s.outIntTraitCell >= 1) outIntTraitCell = s.outIntTraitCell; if (s.outIntTraitRow >= 1) outIntTraitRow = s.outIntTraitRow; if (s.outIntConn >= 1) outIntConn = s.outIntConn; - saveMaps = s.saveMaps; saveTraitMaps = s.saveTraitMaps; saveVisits = s.saveVisits; #if RS_RCPP outStartPaths = s.outStartPaths; outIntPaths = s.outIntPaths; outPaths = s.outPaths; - ReturnPopRaster = s.ReturnPopRaster; + ReturnPopMatrix = s.ReturnPopMatrix; + ReturnPopDataFrame = s.ReturnPopDataFrame; + ReturnStages = s.ReturnStages; CreatePopFile = s.CreatePopFile; #endif - drawLoaded = s.drawLoaded; + fixReplicateSeed = s.fixReplicateSeed; +} + +void paramSim::setGeneticSim(string patchSamplingOption, bool outputGenes, int outputGenesStart, int outputGenesInterval, bool outPairwiseFst, + int outputGlobalFst, int outputStartGlobalFst, int outputGlobalFstInterval, int outputStartPairwiseFst, int outputPairwiseFstIntervals, bool outputPerLocusFst) { + this->patchSamplingOption = patchSamplingOption; + this->outputGenes = outputGenes; + this->outputGenesStart = outputGenesStart; + this->outputGenesInterval = outputGenesInterval; + this->outputGlobalFst = outputGlobalFst; + this->outputGlobalFstStart = outputStartGlobalFst; + this->outputGlobalFstInterval = outputGlobalFstInterval; + this->outPairwiseFst = outPairwiseFst; + this->outputPairwiseFstStart = outputStartPairwiseFst; + this->outputPairwiseFstInterval = outputPairwiseFstIntervals; + this->outputPerLocusFst = outputPerLocusFst; } -simParams paramSim::getSim(void) { +simParams paramSim::getSim() { simParams s; s.batchNum = batchNum; s.simulation = simulation; s.reps = reps; s.years = years; s.outRange = outRange; s.outOccup = outOccup; s.outPop = outPop; s.outInds = outInds; - s.outGenetics = outGenetics; s.outGenType = outGenType; s.outGenXtab = outGenXtab; s.outTraitsCells = outTraitsCells; s.outTraitsRows = outTraitsRows; s.outConnect = outConnect; - s.outStartPop = outStartPop; s.outStartInd = outStartInd; s.outStartGenetic = outStartGenetic; + s.outStartPop = outStartPop; s.outStartInd = outStartInd; s.outStartTraitCell = outStartTraitCell; s.outStartTraitRow = outStartTraitRow; s.outStartConn = outStartConn; s.outIntRange = outIntRange; s.outIntOcc = outIntOcc; s.outIntPop = outIntPop; - s.outIntInd = outIntInd; s.outIntGenetic = outIntGenetic; + s.outIntInd = outIntInd; s.outIntTraitCell = outIntTraitCell; s.outIntTraitRow = outIntTraitRow; s.outIntConn = outIntConn; s.batchMode = batchMode; s.absorbing = absorbing; - s.saveMaps = saveMaps; s.saveTraitMaps = saveTraitMaps; - s.saveVisits = saveVisits; - s.mapInt = mapInt; s.traitInt = traitInt; + s.traitInt = traitInt; #if RS_RCPP + s.saveVisits = saveVisits; s.outStartPaths = outStartPaths; s.outIntPaths = outIntPaths; s.outPaths = outPaths; - s.ReturnPopRaster = ReturnPopRaster; + s.ReturnPopMatrix = ReturnPopMatrix; + s.ReturnPopDataFrame = ReturnPopDataFrame; + s.ReturnStages = ReturnStages; s.CreatePopFile = CreatePopFile; #endif - s.drawLoaded = drawLoaded; + s.patchSamplingOption = patchSamplingOption; + + s.outputGenes = outputGenes; + s.outputGenesStart = outputGenesStart; + s.outputGenesInterval = outputGenesInterval; + + s.outputGlobalFst = outputGlobalFst; + s.outputGlobalFstStart = outputGlobalFstStart; + s.outputGlobalFstInterval = outputGlobalFstInterval; + + s.outPairwiseFst = outPairwiseFst; + s.outputPairwiseFstStart = outputPairwiseFstStart; + s.outputPairwiseFstInterval = outputPairwiseFstInterval; + + s.outputPerLocusFst = outputPerLocusFst; + return s; } int paramSim::getSimNum(void) { return simulation; } -void paramSim::setViews(simView v) { - viewLand = v.viewLand; viewPatch = v.viewPatch; - viewGrad = v.viewGrad; viewCosts = v.viewCosts; - viewPop = v.viewPop; viewTraits = v.viewTraits; - viewPaths = v.viewPaths; viewGraph = v.viewGraph; - if (v.slowFactor > 0) slowFactor = v.slowFactor; -} - -simView paramSim::getViews(void) { - simView v; - v.viewLand = viewLand; v.viewPatch = viewPatch; - v.viewGrad = viewGrad; v.viewCosts = viewCosts; - v.viewPop = viewPop; v.viewTraits = viewTraits; - v.viewPaths = viewPaths; v.viewGraph = viewGraph; - v.slowFactor = slowFactor; - return v; -} - -void paramSim::setDir(string s) { - dir = s; -} - // return directory name depending on option specified string paramSim::getDir(int option) { string s; @@ -371,12 +369,103 @@ string paramSim::getDir(int option) { return s; } +string to_string(const TraitType& tr) { + switch (tr) + { + case NEUTRAL: return "NEUTRAL"; + case GENETIC_LOAD: return "GENETIC_LOAD"; + case GENETIC_LOAD1: return "GENETIC_LOAD1"; + case GENETIC_LOAD2: return "GENETIC_LOAD2"; + case GENETIC_LOAD3: return "GENETIC_LOAD3"; + case GENETIC_LOAD4: return "GENETIC_LOAD4"; + case GENETIC_LOAD5: return "GENETIC_LOAD5"; + + case E_D0: return "E_D0"; + case E_D0_M: return "E_D0_M"; + case E_D0_F: return "E_D0_F"; + case E_ALPHA: return "E_ALPHA"; + case E_ALPHA_M: return "E_ALPHA_M"; + case E_ALPHA_F: return "E_ALPHA_F"; + case E_BETA: return "E_BETA"; + case E_BETA_M: return "E_BETA_M"; + case E_BETA_F: return "E_BETA_F"; + + case S_S0: return "S_S0"; + case S_S0_M: return "S_S0_M"; + case S_S0_F: return "S_S0_F"; + case S_ALPHA: return "S_ALPHA"; + case S_ALPHA_M: return "S_ALPHA_M"; + case S_ALPHA_F: return "S_ALPHA_F"; + case S_BETA: return "S_BETA"; + case S_BETA_M: return "S_BETA_M"; + case S_BETA_F: return "S_BETA_F"; + + case CRW_STEPLENGTH: return "CRW_STEPLENGTH"; + case CRW_STEPCORRELATION: return "CRW_STEPCORRELATION"; + case KERNEL_MEANDIST_1: return "KERNEL_MEANDIST_1"; + case KERNEL_MEANDIST_2: return "KERNEL_MEANDIST_2"; + case KERNEL_MEANDIST_1_F: return "KERNEL_MEANDIST_1_F"; + case KERNEL_MEANDIST_2_F: return "KERNEL_MEANDIST_2_F"; + case KERNEL_MEANDIST_1_M: return "KERNEL_MEANDIST_1_M"; + case KERNEL_MEANDIST_2_M: return "KERNEL_MEANDIST_2_M"; + case KERNEL_PROBABILITY: return "KERNEL_PROBABILITY"; + case KERNEL_PROBABILITY_F: return "KERNEL_PROBABILITY_F"; + case KERNEL_PROBABILITY_M: return "KERNEL_PROBABILITY_M"; + + case SMS_DP: return "SMS_DP"; + case SMS_GB: return "SMS_GB"; + case SMS_ALPHADB: return "SMS_ALPHADB"; + case SMS_BETADB: return "SMS_BETADB"; + case INVALID_TRAIT: return "INVALID_TRAIT"; + default: return ""; + } +} + +string to_string(const GenParamType& param) { + switch (param) + { + case MEAN: return "MEAN"; + case SD: return "SD"; + case MIN: return "MIN"; + case MAX: return "MAX"; + case SHAPE: return "SHAPE"; + case SCALE: return "SCALE"; + case INVALID: return "INVALID"; + default: return ""; + } +} + +string to_string(const DistributionType& dist) { + switch (dist) + { + case UNIFORM: return "UNIFORM"; + case NORMAL: return "NORMAL"; + case GAMMA: return "GAMMA"; + case NEGEXP: return "NEGEXP"; + case SCALED: return "SCALED"; + case KAM: return "KAM"; + case SSM: return "SSM"; + case NONE: return "NONE"; + default: return ""; + } +} + +string to_string(const ExpressionType& expr) { + switch (expr) + { + case AVERAGE: return "AVERAGE"; + case ADDITIVE: return "ADDITIVE"; + case NOTEXPR: return "NOTEXPR"; + case MULTIPLICATIVE: return "MULTIPLICATIVE"; + default: return ""; + } +} + #if RS_RCPP -bool paramSim::getReturnPopRaster(void) { return ReturnPopRaster; } +bool paramSim::getReturnPopMatrix(void) { return ReturnPopMatrix; } +bool paramSim::getReturnPopDataFrame(void) { return ReturnPopDataFrame; } bool paramSim::getCreatePopFile(void) { return CreatePopFile; } #endif //--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- diff --git a/Parameters.h b/RangeShiftR/src/RScore/Parameters.h similarity index 61% rename from Parameters.h rename to RangeShiftR/src/RScore/Parameters.h index 9cc51d2..f44929e 100644 --- a/Parameters.h +++ b/RangeShiftR/src/RScore/Parameters.h @@ -1,25 +1,25 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * + * --------------------------------------------------------------------------*/ - - + + /*------------------------------------------------------------------------------ RangeShifter v2.0 Parameters @@ -34,9 +34,9 @@ paramStoch - Environmental stochasticity parameters Also declares some structures and functions used throughout the program. For full details of RangeShifter, please see: -Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial -eco-evolutionary dynamics and species responses to environmental changes. + eco-evolutionary dynamics and species’ responses to environmental changes. Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 Authors: Greta Bocedi & Steve Palmer, University of Aberdeen @@ -48,43 +48,37 @@ Last updated: 25 June 2021 by Steve Palmer #ifndef ParametersH #define ParametersH -//#if LINUX_CLUSTER -//#include -//#else #include -//#endif #include #include -//#include #include #include #include +#include +#include using namespace std; #include "RSrandom.h" -#define NSTAGES 10 // maximum number of stages permitted -#define NSEXES 2 // maximum number of sexes permitted -#define PARAMDEBUG 0 -#define NTRAITS 18 // maximum number of variable traits which can be displayed - // in GUI (VCL version) -#define NSD 3.0 // no. of s.d. to use to control range for displaying traits +constexpr int gNoDataCost = 100000; // cost to use in place of nodata value for SMS; +constexpr int gAbsorbingNoDataCost = 100; // cost to use in place of nodata value for SMS; +// when boundaries are absorbing +constexpr int gMaxNbStages = 10; // maximum number of stages permitted +constexpr int gMaxNbSexes = 2; // maximum number of sexes permitted +constexpr int gMaxNbLayers = 3*gMaxNbSexes*gMaxNbStages; // maximum number of demographic scaling layers permitted #if RS_RCPP typedef intptr_t intptr; #else -#if RSWIN64 typedef unsigned long long intptr; -#else -typedef unsigned int intptr; -#endif -#endif +#endif // RS_RCPP #if RS_RCPP #ifndef R_EXT_CONSTANTS_H_ // the R headers define PI as a macro, so that the 'else' line results in an error #define M_2PI 6.283185307179586 const double PI = 3.141592653589793238462643383279502884197169399375; #endif +#include #else #define M_2PI 6.283185307179586 const double PI = 3.141592654; @@ -95,26 +89,62 @@ const double SQRT2 = std::sqrt(double(2.0)); // more efficient than calculating //--------------------------------------------------------------------------- // Common declarations - struct locn { int x; int y; }; -struct rgb { // colour scheme for drawing maps - int r,g,b; + +//-------------------------------------------------------------------------- + +/** Trait types **/ + +enum TraitType { + NEUTRAL, + GENETIC_LOAD, GENETIC_LOAD1, GENETIC_LOAD2, GENETIC_LOAD3, GENETIC_LOAD4, GENETIC_LOAD5, + + E_D0, E_ALPHA, E_BETA, + S_S0, S_ALPHA, S_BETA, + + E_D0_F, E_ALPHA_F, E_BETA_F, + S_S0_F, S_ALPHA_F, S_BETA_F, + + E_D0_M, E_ALPHA_M, E_BETA_M, + S_S0_M, S_ALPHA_M, S_BETA_M, + + CRW_STEPLENGTH, CRW_STEPCORRELATION, + + KERNEL_MEANDIST_1, KERNEL_MEANDIST_2, KERNEL_PROBABILITY, + KERNEL_MEANDIST_1_F, KERNEL_MEANDIST_2_F, KERNEL_PROBABILITY_F, + KERNEL_MEANDIST_1_M, KERNEL_MEANDIST_2_M, KERNEL_PROBABILITY_M, + + SMS_DP, SMS_GB, SMS_ALPHADB, SMS_BETADB, + + INVALID_TRAIT // error }; -const string Int2Str(const int); -#if RS_RCPP -const string Int2Str(const int, unsigned int); -#endif -const string Float2Str(const float); -const string Double2Str(const double); -const rgb draw_wheel(int); +enum GenParamType { MEAN, SD, MIN, MAX, SHAPE, SCALE, INVALID }; +enum DistributionType { UNIFORM, NORMAL, GAMMA, NEGEXP, SCALED, KAM, SSM, NONE }; +enum ExpressionType { AVERAGE, ADDITIVE, NOTEXPR, MULTIPLICATIVE }; + +string to_string(const TraitType& tr); + +string to_string(const GenParamType& param); + +string to_string(const DistributionType& dist); + +string to_string(const ExpressionType& expr); + +/** Param's types **/ +typedef enum { KERNEL, SMS, CRW} movement_t; + +//sex types +typedef enum { + FEM = 0, MAL = 1, + NA, // not applicable. e.g. for NEUTRAL or genetic load trait + INVALID_SEX // error +} sex_t; //--------------------------------------------------------------------------- // Environmental gradient parameters -// SHOULD THIS BE PART OF LANDSCAPE OBJECT OR A SEPARATE OBJECT????????????? - struct envGradParams { bool gradient; bool shifting; int gradType; float grad_inc; float opt_y; float factor; float extProbOpt; @@ -167,7 +197,7 @@ class paramGrad { struct envStochParams { bool stoch; bool local; bool inK; bool localExt; - float ac; float std; + float ac; float std; float locExtProb; }; @@ -185,7 +215,7 @@ class paramStoch { bool local; // applied locally (if not, application is global) bool inK; // in carrying capacity (if not, in growth rate) bool localExt; // local extinction applied - float ac; // temporal autocorrelation coefficient + float ac; // temporal autocorrelation coefficient float std; // amplitude of fluctuations: sampled from N(0,std) float locExtProb; // local extinction probability }; @@ -205,7 +235,8 @@ struct initParams { }; struct initInd { - int year,patchID,x,y; short species,sex,age,stage; + int year, patchID, x, y; + short species, sex, age, stage; }; class paramInit { @@ -260,7 +291,7 @@ class paramInit { int nSeedPatches; // no. of cells/patches to initialise int nSpDistPatches; // no. of species distribution cells to initialise string indsFile; // no. of species distribution cells to initialise - float initProp[NSTAGES]; // initial stage proportions (structured population only) + float initProp[gMaxNbStages]; // initial stage proportions (structured population only) vector initinds; // individuals to be initialised @@ -272,25 +303,45 @@ class paramInit { struct simParams { int batchNum; - int simulation; int reps; int years; -// int outStartRange; -// int outStartOcc; - int outStartPop; int outStartInd; int outStartGenetic; - int outStartTraitCell; int outStartTraitRow; int outStartConn; - int outIntRange; int outIntOcc; int outIntPop; int outIntInd; int outIntGenetic; - int outIntTraitCell; int outIntTraitRow; int outIntConn; - int mapInt; int traitInt; - bool batchMode; bool absorbing; - bool outRange; bool outOccup; bool outPop; bool outInds; - bool outGenetics; short outGenType; bool outGenXtab; - bool outTraitsCells; bool outTraitsRows; bool outConnect; - bool saveMaps; - bool drawLoaded; bool saveTraitMaps; + int simulation; + int reps; + int years; + int outStartPop; + int outStartInd; + int outIntInd; + int outStartTraitCell; + int outStartTraitRow; + int outStartConn; + int outIntRange; + int outIntOcc; + int outIntPop; bool saveVisits; + int outIntTraitCell; + int outIntTraitRow; + int outIntConn; + int traitInt; + bool batchMode; + bool absorbing; + bool outRange; + bool outOccup; + bool outPop; + bool outInds; + bool outTraitsCells; + bool outTraitsRows; + bool outConnect; #if RS_RCPP int outStartPaths; int outIntPaths; - bool outPaths; bool ReturnPopRaster; bool CreatePopFile; + bool outPaths; bool ReturnPopMatrix; bool ReturnPopDataFrame; bool CreatePopFile; + Rcpp::LogicalVector ReturnStages; #endif + bool fixReplicateSeed; + string patchSamplingOption; + bool outputGenes; + bool outputGlobalFst, outPairwiseFst; + bool outputPerLocusFst; + int outputGenesStart, outputGenesInterval; + int outputGlobalFstStart, outputGlobalFstInterval; + int outputPairwiseFstStart, outputPairwiseFstInterval; }; struct simView { @@ -302,85 +353,77 @@ struct simView { class paramSim { public: - paramSim(void); + paramSim(const string& pathToProjDir = ""); ~paramSim(void); void setSim(simParams); + void setGeneticSim(string patchSamplingOption, bool outputGenes, int outputGenesStart, int outputGenesInterval, bool outPairwiseFst, + int outputGlobalFst, int outputStartGlobalFst, int outputGlobalFstInterval, int outputStartPairwiseFst, int outputPairwiseFstIntervals, bool outputPerLocusFst); simParams getSim(void); int getSimNum(void); - void setViews(simView); - simView getViews(void); - void setDir(string); string getDir(int); + void setBatchNum(const int& batchNb) { + batchNum = batchNb; + batchMode = true; + } #if RS_RCPP - bool getReturnPopRaster(void); + bool getReturnPopDataFrame(void); + bool getReturnPopMatrix(void); bool getCreatePopFile(void); #endif private: - int batchNum; // batch number - int simulation; // simulation no. - int reps; // no. of replicates - int years; // no. of years -// int outStartRange; // output start year for range file -// int outStartOcc; // output start year for occupancy file - int outStartPop; // output start year for population file - int outStartInd; // output start year for individuals file - int outStartGenetic; // output start year for genetics file - int outStartTraitCell; // output start year for traits by cell file + int batchNum; // batch number + int simulation; // simulation no. + int reps; // no. of replicates + int years; // no. of years + int outStartPop; // output start year for population file + int outStartInd; // output start year for individuals file + int outStartTraitCell; // output start year for traits by cell file int outStartTraitRow; // output start year for traits by row file - int outStartConn; // output start year for connectivity matrix - int outIntRange; // output interval for range file - int outIntOcc; // output interval for occupancy file - int outIntPop; // output interval for population file - int outIntInd; // output interval for individuals file - int outIntGenetic; // output interval for genetics file + int outStartConn; // output start year for connectivity matrix + int outIntRange; // output interval for range file + int outIntOcc; // output interval for occupancy file + int outIntPop; // output interval for population file + int outIntInd; // output interval for individuals file int outIntTraitCell; // output interval for traits by cell file int outIntTraitRow; // output interval for traits by row file - int outIntConn; // output interval for connectivity matrix - int mapInt; // output interval for maps - int traitInt; // output interval for evolving traits maps - int slowFactor; // to reduce speed of movement paths on screen - bool batchMode; // - bool absorbing; // landscape boundary and no-data regions are - // absorbing boundaries - bool outRange; // produce output range file? - bool outOccup; // produce output occupancy file? - bool outPop; // produce output population file? - bool outInds; // produce output individuals file? - bool outGenetics; // produce output genetics file? - short outGenType; // produce output genetics for: 0 = juveniles only - // 1 = all individuals, 2 = adults (i.e. final stage) only - bool outGenXtab; // produce output genetics as a cross table? + int outIntConn; // output interval for connectivity matrix + int traitInt; // output interval for evolving traits maps + bool batchMode; + bool absorbing; // landscape boundary and no-data regions are absorbing boundaries + bool outRange; // produce output range file? + bool outOccup; // produce output occupancy file? + bool outPop; // produce output population file? + bool outInds; // produce output individuals file? bool outTraitsCells; // produce output summary traits by cell file? bool outTraitsRows; // produce output summary traits by row (y) file? - bool outConnect; // produce output connectivity file? - bool saveMaps; // save landscape/population maps? + bool outConnect; // produce output connectivity file? bool saveVisits; // save dispersal visits heat maps? #if RS_RCPP int outStartPaths; int outIntPaths; bool outPaths; - bool ReturnPopRaster; + bool ReturnPopMatrix; + bool ReturnPopDataFrame; bool CreatePopFile; + Rcpp::LogicalVector ReturnStages; #endif - bool drawLoaded; // draw initial distribution on landscape/population maps? - bool saveTraitMaps; // save summary traits maps? - bool viewLand; // view landscape map on screen? - bool viewPatch; // view map of landscape patches on screen? - bool viewGrad; // view gradient map on screen? - bool viewCosts; // view costs map on screen? - bool viewPop; // view population density on landscape map on screen? - bool viewTraits; // view summary traits map(s) on screen? - bool viewPaths; // view individual movement paths on screen? - bool viewGraph; // view population/occupancy graph on screen? - string dir; // full name of working directory - + string dir; // full name of working directory + bool fixReplicateSeed; + string patchSamplingOption; + bool outputGenes; + int outputGenesStart; + int outputGenesInterval; + bool outputGlobalFst; + bool outPairwiseFst; + bool outputPerLocusFst; + int outputPairwiseFstStart; + int outputGlobalFstStart; + int outputPairwiseFstInterval; + int outputGlobalFstInterval; }; -#if RSDEBUG -extern ofstream DEBUGLOG; -void DebugGUI(string); -#endif +extern RSrandom* pRandom; //--------------------------------------------------------------------------- #endif diff --git a/RangeShiftR/src/RScore/Patch.cpp b/RangeShiftR/src/RScore/Patch.cpp new file mode 100644 index 0000000..f67d5ec --- /dev/null +++ b/RangeShiftR/src/RScore/Patch.cpp @@ -0,0 +1,373 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + + //--------------------------------------------------------------------------- + +#include "Patch.h" +//--------------------------------------------------------------------------- + +//--------------------------------------------------------------------------- + +Patch::Patch(int seqnum, int num) +{ + patchSeqNum = seqnum; patchNum = num; nCells = 0; + xMin = yMin = 999999999; xMax = yMax = 0; x = y = 0; +subCommPtr = nullptr; + localK = 0.0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + nTemp[sex] = 0; + } + localDemoScaling.assign(nDSlayer,1.0); + changed = false; +} + +Patch::~Patch() { + cells.clear(); + popns.clear(); + localDemoScaling.clear(); +} + +int Patch::getSeqNum(void) { return patchSeqNum; } + +int Patch::getPatchNum(void) { return patchNum; } + +int Patch::getNCells(void) { return nCells; } + +patchLimits Patch::getLimits(void) { + patchLimits p; + p.xMin = xMin; p.xMax = xMax; p.yMin = yMin; p.yMax = yMax; + return p; +} + +// Does the patch fall (partially) within a specified rectangle? +bool Patch::withinLimits(patchLimits rect) { + locn loc; + if (xMin <= rect.xMax && xMax >= rect.xMin && yMin <= rect.yMax && yMax >= rect.yMin) { + // patch is within the rectangle UNLESS it is irregular in shape and lies at a corner + // of the rectangle + if ((xMin >= rect.xMin && xMax <= rect.xMax) + || (yMin >= rect.yMin && yMax <= rect.yMax)) { + // patch lies within or along an edge of the initialistaion rectangle + return true; + } + else { + // check for any cell of the patch lying within the rectangle + int ncells = (int)cells.size(); + for (int i = 0; i < ncells; i++) { + loc = getCellLocn(i); + if (loc.x >= rect.xMin && loc.x <= rect.xMax + && loc.y >= rect.yMin && loc.y <= rect.yMax) { + // cell lies within the rectangle + return true; + } + } + } + } + return false; +} + +// Reset minimum and maximum co-ordinates of the patch if it has been changed +void Patch::resetLimits(void) { + if (changed) { + // remove any deleted cells + std::vector newcells; // for all retained and added cells + int ncells = (int)cells.size(); + for (int i = 0; i < ncells; i++) { + if (cells[i] != NULL) { + newcells.push_back(cells[i]); + } + } + cells.clear(); + cells = newcells; + // reset patch limits + locn loc; + xMin = yMin = 999999999; xMax = yMax = 0; + ncells = (int)cells.size(); + for (int i = 0; i < ncells; i++) { + loc = getCellLocn(i); + if (loc.x < xMin) xMin = loc.x; + if (loc.x > xMax) xMax = loc.x; + if (loc.y < yMin) yMin = loc.y; + if (loc.y > yMax) yMax = loc.y; + } + changed = false; + } +} + +// Add a cell to the patch +void Patch::addCell(Cell* pCell, int x, int y) { + cells.push_back(pCell); + nCells++; + if (x < xMin) xMin = x; + if (x > xMax) xMax = x; + if (y < yMin) yMin = y; + if (y > yMax) yMax = y; +} + +// Calculate the total carrying capacity (no. of individuals) and +// centroid co-ordinates of the patch +void Patch::setCarryingCapacity(Species* pSpecies, patchLimits landlimits, + float epsGlobal, short nHab, short rasterType, short landIx, bool gradK) { + envStochParams env = paramsStoch->getStoch(); + locn loc; + int xsum, ysum; + short hx; + float k, q, envval; + + localK = 0.0; // no. of suitable cells (unadjusted K > 0) in the patch + int nsuitable = 0; + double mean; + + if (xMin > landlimits.xMax || xMax < landlimits.xMin + || yMin > landlimits.yMax || yMax < landlimits.yMin) { + // patch lies wholely outwith current landscape limits + // NB the next statement is unnecessary, as localK has been set to zero above + // retained only for consistency in standard variant + localK = 0.0; + return; + } + + int ncells = (int)cells.size(); + xsum = ysum = 0; + for (int i = 0; i < ncells; i++) { + if (gradK) // gradient in carrying capacity + envval = cells[i]->getEnvVal(); // environmental gradient value + else envval = 1.0; // no gradient effect + if (env.stoch && env.inK) { // environmental stochasticity in K + if (env.local) { + envval += cells[i]->getEps(); + } + else { // global stochasticity + envval += epsGlobal; + } + } + switch (rasterType) { + case 0: // habitat codes + hx = cells[i]->getHabIndex(landIx); + k = pSpecies->getHabK(hx); + if (k > 0.0) { + nsuitable++; + localK += envval * k; + } + break; + case 1: // cover % + k = 0.0; + for (int j = 0; j < nHab; j++) { // loop through cover layers + q = cells[i]->getHabitat(j); + k += q * pSpecies->getHabK(j) / 100.0f; + } + if (k > 0.0) { + nsuitable++; + localK += envval * k; + } + break; + case 2: // habitat quality + q = cells[i]->getHabitat(landIx); + if (q > 0.0) { + nsuitable++; + localK += envval * pSpecies->getHabK(0) * q / 100.0f; + } + break; + } + loc = cells[i]->getLocn(); + xsum += loc.x; ysum += loc.y; + } +// calculate centroid co-ordinates + if (ncells > 0) { + mean = (double)xsum / (double)ncells; + x = (int)(mean + 0.5); + mean = (double)ysum / (double)ncells; + y = (int)(mean + 0.5); + } + if (env.stoch && env.inK) { // environmental stochasticity in K + // apply min and max limits to K over the whole patch + // NB limits have been stored as N/cell rather than N/ha + float limit; + limit = pSpecies->getMinMax(0) * (float)nsuitable; + if (localK < limit) localK = limit; + limit = pSpecies->getMinMax(1) * (float)nsuitable; + if (localK > limit) localK = limit; + } +} + + +float Patch::getK(void) { return localK; } + +// SPATIALDEMOG +void Patch::setDemoScaling(std::vector ds) { + + std::for_each(ds.begin(), ds.end(), [](float& perc){ if(perc < 0.0 || perc > 1.0) perc=1; }); + + localDemoScaling.assign(ds.begin(), ds.end()); + + return; +} + +std::vector Patch::getDemoScaling(void) { return localDemoScaling; } + +void Patch::setPatchDemoScaling(short landIx, patchLimits landlimits) { + + // if patch wholly outside current landscape boundaries + if (xMin > landlimits.xMax || xMax < landlimits.xMin + || yMin > landlimits.yMax || yMax < landlimits.yMin) { + localDemoScaling.assign(nDSlayer,0.0); // set all local scales to zero + return; + } + + // loop through constituent cells of the patch + int ncells = (int)cells.size(); + std::vector patchDS(nDSlayer, 0.0); + std::vector cellDS(nDSlayer, 0.0); + + for (int i = 0; i < ncells; i++) { + cellDS = cells[i]->getDemoScaling(landIx); // is that ok? + + //add cell value to patch value + for (int ly = 0; ly < nDSlayer; ly++) { + patchDS[ly] += cellDS[ly]; + } + } + + // take mean over cells and divide by 100 to scale to range [0,1] + for (int ly = 0; ly < nDSlayer; ly++) { + patchDS[ly] = patchDS[ly] / ncells / 100.0f; + } + + // set values + setDemoScaling(patchDS); + + return; +} +//SPATIALDEMOG + +// Return co-ordinates of a specified cell +locn Patch::getCellLocn(int ix) { + locn loc; loc.x = -666; loc.y = -666; + int ncells = (int)cells.size(); + if (ix >= 0 && ix < ncells) { + loc = cells[ix]->getLocn(); + } + return loc; +} +// Return pointer to a specified cell +Cell* Patch::getCell(int ix) { + int ncells = (int)cells.size(); + if (ix >= 0 && ix < ncells) return cells[ix]; + else return 0; +} +// Return co-ordinates of patch centroid +locn Patch::getCentroid(void) { + locn loc; loc.x = x; loc.y = y; + return loc; +} + +// Select a Cell within the Patch at random, and return pointer to it +// For a cell-based model, this will be the only Cell +Cell* Patch::getRandomCell(void) { + Cell* pCell = 0; + int ix; + int ncells = (int)cells.size(); + if (ncells > 0) { + if (ncells == 1) ix = 0; + else ix = pRandom->IRandom(0, ncells - 1); + pCell = cells[ix]; + } + return pCell; +} + +// Remove a cell from the patch +void Patch::removeCell(Cell* pCell) { + int ncells = (int)cells.size(); + for (int i = 0; i < ncells; i++) { + if (pCell == cells[i]) { + cells[i] = NULL; i = ncells; + nCells--; + changed = true; + } + } +} + +void Patch::setSubComm(SubCommunity* sc) +{ + subCommPtr = sc; +} + +// Get pointer to corresponding Sub-community +SubCommunity* Patch::getSubComm(void) +{ return subCommPtr; } + +#ifdef _OPENMP +std::unique_lock Patch::lockPopns() { + return std::unique_lock(popns_mutex); +} +#endif + +void Patch::addPopn(patchPopn pop) { + popns.push_back(pop); +} + +// Return pointer to the Population of the specified Species +Population* Patch::getPopn(Species *sp) +{ + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { + if (popns[i].pSp == sp) return popns[i].pPop; + } + return 0; +} + +void Patch::resetPopn(void) { + popns.clear(); +} + +void Patch::resetPossSettlers(void) { + for (int sex = 0; sex < gMaxNbSexes; sex++) { + nTemp[sex] = 0; + } +} + +// Record the presence of a potential settler within the Patch +void Patch::incrPossSettler(Species* pSpecies, int sex) { +// NOTE: THE FOLLOWING OPERATION WILL NEED TO BE MADE SPECIES-SPECIFIC... + if (sex >= 0 && sex < gMaxNbSexes) { + nTemp[sex]++; + } +} + +// Get number of a potential settlers within the Patch +int Patch::getPossSettlers(Species* pSpecies, int sex) { +// NOTE: THE FOLLOWING OPERATION WILL NEED TO BE MADE SPECIES-SPECIFIC... + if (sex >= 0 && sex < gMaxNbSexes) return nTemp[sex]; + else return 0; +} + +bool Patch::speciesIsPresent(Species* pSpecies) { + const auto pPop = this->getPopn(pSpecies); + return pPop != 0; +} + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + + + diff --git a/RangeShiftR/src/RScore/Patch.h b/RangeShiftR/src/RScore/Patch.h new file mode 100644 index 0000000..a26dd28 --- /dev/null +++ b/RangeShiftR/src/RScore/Patch.h @@ -0,0 +1,194 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Tho Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + + /*------------------------------------------------------------------------------ + + RangeShifter v2.0 Patch + + Implements the class: Patch + + A patch is a collection of one or more Cells in the the gridded Landscape, + which together provide the area in which a single demographic unit of a Species, + i.e. a Population, can reproduce. One or more Populations (of different Species) + form a Sub-community associated with the Patch. + + There is no requirement that all the Cells be adjacent, although in practice + that would usually be the case. + + Each Patch must have a unique positive integer id number supplied by the user, + and the matrix, i.e. any part of the landscape which is not a breeding patch, + is represented by Patch 0. However, as patch numbers need not be sequential, + an internal sequential number is also applied. + + For a 'cell-based model', the user supplies no patch numbers, and a separate + Patch is generated internally for each Cell, i.e. the 'cell-based model' is a + special case of the 'patch-based model' in which each Patch has a single Cell. + Moreover, there is also the 'matrix' Patch 0, which has no cells, but which + holds the disperser population whilst its Individuals are in transit. + + In a true patch-based model, each Patch hold a list of its constituent Cells, + EXCEPT for the matrix Patch 0. This is because that list would be extremely + long for a very large landscape in which suitable patches are small and/or rare, + and removing Cells from it if the landscape is dynamic would be inefficient. + + For full details of RangeShifter, please see: + Bocedi G., Palmer S.C.F., Peer G., Heikkinen R.K., Matsinos Y.G., Watts K. + and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial + eco-evolutionary dynamics and species responses to environmental changes. + Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + + Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + + Last updated: 25 June 2021 by Steve Palmer + + ------------------------------------------------------------------------------*/ + +#ifndef PatchH +#define PatchH + +#include +using namespace std; + +#include "Parameters.h" +#include "Cell.h" +#include "Species.h" + +#ifdef _OPENMP +#include +#include +#endif + + //--------------------------------------------------------------------------- + +class Population; +class SubCommunity; + +struct patchLimits { + int xMin, xMax, yMin, yMax; +}; +struct patchPopn { + Species *pSp; // pointers to Species + Population *pPop; // pointers to Population +}; + +class Patch { +public: + Patch( + int, // internal sequential number + int // patch id number + ); + ~Patch(); + int getSeqNum(void); + int getPatchNum(void); + int getNCells(void); + patchLimits getLimits(void); // Returns the minimum and maximum co-ordinates of the patch + bool withinLimits( // Does the patch fall (partially) within a specified rectangle? + patchLimits // structure holding the SW and NE co-ordinates of the rectangle + ); + void resetLimits(void); // Reset minimum and maximum co-ordinates of the patch + void addCell( + Cell*, // pointer to the Cell to be added to the Patch + int, int // x (column) and y (row) co-ordinates of the Cell + ); + locn getCellLocn( // Return co-ordinates of a specified cell + int // index no. of the Cell within the vector cells + ); + Cell* getCell( // Return pointer to a specified cell + int // index no. of the Cell within the vector cells + ); + locn getCentroid(void); // Return co-ordinates of patch centroid + void removeCell( + Cell* // pointer to the Cell to be removed from the Patch + ); + Cell* getRandomCell(void); + void setSubComm( + SubCommunity * // pointer to the Sub-community + ); + SubCommunity *getSubComm(void); +#ifdef _OPENMP + std::unique_lock lockPopns(); +#endif + void addPopn( + patchPopn // structure holding pointers to Species and Population + ); + Population *getPopn( // return pointer to the Population of the Species + Species * // pointer to Species + ); + void resetPopn(void); + void resetPossSettlers(void); + void incrPossSettler( // Record the presence of a potential settler within the Patch + Species*, // pointer to the Species + int // sex of the settler + ); + int getPossSettlers( // Get number of a potential settlers within the Patch + Species*, // pointer to the Species + int // sex of the settlers + ); + void setCarryingCapacity( // Calculate total Patch carrying capacity (no. of inds) + Species*, // pointer to the Species + patchLimits, // current min and max limits of landscape + float, // global stochasticity value (epsilon) for the current year + short, // no. of habitat classes in the Landscape + short, // rasterType (see Landscape) + short, // landscape change index (always zero if not dynamic) + bool // TRUE if there is a gradient in carrying capacity across the Landscape + ); + float getK(void); + bool speciesIsPresent(Species* pSpecies); + void setDemoScaling(std::vector ); + std::vector getDemoScaling(void); + void setPatchDemoScaling(short, patchLimits); // calculate demog. scalings of patch from its cells //TODO arguments + +private: + int patchSeqNum;// sequential patch number - patch 0 is reserved for the inter-patch matrix + int patchNum; // patch number as supplied by the user (not forced to be sequential) + int nCells; // no. of cells in the patch + int xMin, xMax, yMin, yMax; // min and max cell co-ordinates + int x, y; // centroid co-ordinates (approx.) + SubCommunity *subCommPtr; // pointer to sub-community associated with the patch + // NOTE: FOR MULTI-SPECIES MODEL, PATCH WILL NEED TO STORE K FOR EACH SPECIES + float localK; // patch carrying capacity (individuals) + std::vector localDemoScaling; + bool changed; + // NOTE: THE FOLLOWING ARRAY WILL NEED TO BE MADE SPECIES-SPECIFIC... +#ifdef _OPENMP + std::atomic nTemp[gMaxNbSexes]; // no. of potential settlers in each sex +#else + short nTemp[gMaxNbSexes]; // no. of potential settlers in each sex +#endif + + std::vector cells; + std::vector popns; + +#ifdef _OPENMP + std::mutex popns_mutex; +#endif +}; + +//--------------------------------------------------------------------------- + +extern paramStoch* paramsStoch; +extern RSrandom* pRandom; + +extern short nDSlayer; + +#endif diff --git a/Population.cpp b/RangeShiftR/src/RScore/Population.cpp similarity index 52% rename from Population.cpp rename to RangeShiftR/src/RScore/Population.cpp index 3dbb6a2..0b42b6e 100644 --- a/Population.cpp +++ b/RangeShiftR/src/RScore/Population.cpp @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -23,6 +23,8 @@ //--------------------------------------------------------------------------- #include "Population.h" + +#include //--------------------------------------------------------------------------- ofstream outPop; @@ -57,15 +59,14 @@ Population::Population(Species* pSp, Patch* pPch, int ninds, int resol) pPatch = pPch; // record the new population in the patch patchPopn pp; - pp.pSp = (intptr)pSpecies; pp.pPop = (intptr)this; + pp.pSp = pSpecies; pp.pPop = this; pPatch->addPopn(pp); - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); - genomeData gen = pSpecies->getGenomeData(); initParams init = paramsInit->getInit(); // determine no. of stages and sexes of species to initialise @@ -78,14 +79,14 @@ Population::Population(Species* pSp, Patch* pPch, int ninds, int resol) else { nSexes = 2; probmale = dem.propMales; } // set up population sub-totals - for (int stg = 0; stg < NSTAGES; stg++) { - for (int sex = 0; sex < NSEXES; sex++) { + for (int stg = 0; stg < gMaxNbStages; stg++) { + for (int sex = 0; sex < gMaxNbSexes; sex++) { nInds[stg][sex] = 0; } } // set up local copy of minimum age table - short minAge[NSTAGES][NSEXES]; + short minAge[gMaxNbStages][gMaxNbSexes]; for (int stg = 0; stg < nStages; stg++) { for (int sex = 0; sex < nSexes; sex++) { if (dem.stageStruct) { @@ -174,21 +175,15 @@ Population::Population(Species* pSp, Patch* pPch, int ninds, int resol) } } else age = stg; -#if RSDEBUG - // NOTE: CURRENTLY SETTING ALL INDIVIDUALS TO RECORD NO. OF STEPS ... - inds.push_back(new Individual(pCell, pPatch, stg, age, sstruct.repInterval, - probmale, true, trfr.moveType)); -#else - inds.push_back(new Individual(pCell, pPatch, stg, age, sstruct.repInterval, - probmale, trfr.moveModel, trfr.moveType)); -#endif - sex = inds[nindivs + i]->getSex(); - if (emig.indVar || trfr.indVar || sett.indVar || gen.neutralMarkers) - { - // individual variation - set up genetics - inds[nindivs + i]->setGenes(pSpecies, resol); + + Individual* newInd = new Individual(pSpecies, pCell, pPatch, stg, age, sstruct.repInterval, + probmale, trfr.usesMovtProc, trfr.moveType); + + if (pSpecies->getNTraits() > 0) { + newInd->setUpGenes(pSpecies, resol); } - nInds[stg][sex]++; + inds.push_back(newInd); + nInds[stg][newInd->getSex()]++; } } } @@ -204,78 +199,252 @@ Population::~Population(void) { if (juvs[i] != NULL) delete juvs[i]; } juvs.clear(); + int nsampledInds = (int)sampledInds.size(); + for (int i = 0; i < nsampledInds; i++) { + if (sampledInds[i] != NULL) sampledInds[i]=NULL; } + sampledInds.clear(); +} + +traitsums Population::getIndTraitsSums(Species* pSpecies) { + + traitsums ts = traitsums(); + for (int sex = 0; sex < gMaxNbSexes; sex++) { + ts.ninds[sex] = 0; + ts.sumD0[sex] = ts.ssqD0[sex] = 0.0; + ts.sumAlpha[sex] = ts.ssqAlpha[sex] = 0.0; + ts.sumBeta[sex] = ts.ssqBeta[sex] = 0.0; + ts.sumDist1[sex] = ts.ssqDist1[sex] = 0.0; + ts.sumDist2[sex] = ts.ssqDist2[sex] = 0.0; + ts.sumProp1[sex] = ts.ssqProp1[sex] = 0.0; + ts.sumDP[sex] = ts.ssqDP[sex] = 0.0; + ts.sumGB[sex] = ts.ssqGB[sex] = 0.0; + ts.sumAlphaDB[sex] = ts.ssqAlphaDB[sex] = 0.0; + ts.sumBetaDB[sex] = ts.ssqBetaDB[sex] = 0.0; + ts.sumStepL[sex] = ts.ssqStepL[sex] = 0.0; + ts.sumRho[sex] = ts.ssqRho[sex] = 0.0; + ts.sumS0[sex] = ts.ssqS0[sex] = 0.0; + ts.sumAlphaS[sex] = ts.ssqAlphaS[sex] = 0.0; + ts.sumBetaS[sex] = ts.ssqBetaS[sex] = 0.0; + ts.sumGeneticFitness[sex] = ts.ssqGeneticFitness[sex] = 0.0; + } -traitsums Population::getTraits(Species* pSpecies) { - int g; - traitsums ts; - for (int i = 0; i < NSEXES; i++) { - ts.ninds[i] = 0; - ts.sumD0[i] = ts.ssqD0[i] = 0.0; - ts.sumAlpha[i] = ts.ssqAlpha[i] = 0.0; ts.sumBeta[i] = ts.ssqBeta[i] = 0.0; - ts.sumDist1[i] = ts.ssqDist1[i] = 0.0; ts.sumDist2[i] = ts.ssqDist2[i] = 0.0; - ts.sumProp1[i] = ts.ssqProp1[i] = 0.0; - ts.sumDP[i] = ts.ssqDP[i] = 0.0; - ts.sumGB[i] = ts.ssqGB[i] = 0.0; - ts.sumAlphaDB[i] = ts.ssqAlphaDB[i] = 0.0; - ts.sumBetaDB[i] = ts.ssqBetaDB[i] = 0.0; - ts.sumStepL[i] = ts.ssqStepL[i] = 0.0; ts.sumRho[i] = ts.ssqRho[i] = 0.0; - ts.sumS0[i] = ts.ssqS0[i] = 0.0; - ts.sumAlphaS[i] = ts.ssqAlphaS[i] = 0.0; ts.sumBetaS[i] = ts.ssqBetaS[i] = 0.0; - } - - demogrParams dem = pSpecies->getDemogr(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); - int ninds = (int)inds.size(); - for (int i = 0; i < ninds; i++) { - int sex = inds[i]->getSex(); - if (emig.sexDep || trfr.sexDep || sett.sexDep) g = sex; else g = 0; - ts.ninds[g] += 1; + for (auto& ind : inds) { + + int sex = ind->getSex(); + ts.ninds[sex] += 1; + // emigration traits - emigTraits e = inds[i]->getEmigTraits(); - if (emig.sexDep) g = sex; else g = 0; - ts.sumD0[g] += e.d0; ts.ssqD0[g] += e.d0 * e.d0; - ts.sumAlpha[g] += e.alpha; ts.ssqAlpha[g] += e.alpha * e.alpha; - ts.sumBeta[g] += e.beta; ts.ssqBeta[g] += e.beta * e.beta; + emigTraits e = ind->getIndEmigTraits(); + ts.sumD0[sex] += e.d0; + ts.ssqD0[sex] += e.d0 * e.d0; + ts.sumAlpha[sex] += e.alpha; + ts.ssqAlpha[sex] += e.alpha * e.alpha; + ts.sumBeta[sex] += e.beta; + ts.ssqBeta[sex] += e.beta * e.beta; + // transfer traits - trfrKernTraits k = inds[i]->getKernTraits(); - if (trfr.sexDep) g = sex; else g = 0; - ts.sumDist1[g] += k.meanDist1; ts.ssqDist1[g] += k.meanDist1 * k.meanDist1; - ts.sumDist2[g] += k.meanDist2; ts.ssqDist2[g] += k.meanDist2 * k.meanDist2; - ts.sumProp1[g] += k.probKern1; ts.ssqProp1[g] += k.probKern1 * k.probKern1; - trfrSMSTraits sms = inds[i]->getSMSTraits(); - g = 0; // CURRENTLY INDIVIDUAL VARIATION CANNOT BE SEX-DEPENDENT - ts.sumDP[g] += sms.dp; ts.ssqDP[g] += sms.dp * sms.dp; - ts.sumGB[g] += sms.gb; ts.ssqGB[g] += sms.gb * sms.gb; - ts.sumAlphaDB[g] += sms.alphaDB; ts.ssqAlphaDB[g] += sms.alphaDB * sms.alphaDB; - ts.sumBetaDB[g] += sms.betaDB; ts.ssqBetaDB[g] += sms.betaDB * sms.betaDB; - trfrCRWTraits c = inds[i]->getCRWTraits(); - g = 0; // CURRENTLY INDIVIDUAL VARIATION CANNOT BE SEX-DEPENDENT - ts.sumStepL[g] += c.stepLength; ts.ssqStepL[g] += c.stepLength * c.stepLength; - ts.sumRho[g] += c.rho; ts.ssqRho[g] += c.rho * c.rho; + if (trfr.usesMovtProc) { + + switch (trfr.moveType) { + + case 1: { // SMS + trfrSMSTraits sms = ind->getIndSMSTraits(); + ts.sumDP[sex] += sms.dp; + ts.ssqDP[sex] += sms.dp * sms.dp; + ts.sumGB[sex] += sms.gb; + ts.ssqGB[sex] += sms.gb * sms.gb; + ts.sumAlphaDB[sex] += sms.alphaDB; + ts.ssqAlphaDB[sex] += sms.alphaDB * sms.alphaDB; + ts.sumBetaDB[sex] += sms.betaDB; + ts.ssqBetaDB[sex] += sms.betaDB * sms.betaDB; + break; + } + case 2: { + trfrCRWTraits c = ind->getIndCRWTraits(); + ts.sumStepL[sex] += c.stepLength; + ts.ssqStepL[sex] += c.stepLength * c.stepLength; + ts.sumRho[sex] += c.rho; + ts.ssqRho[sex] += c.rho * c.rho; + break; + } + default: + throw runtime_error("usesMoveProcess is ON but moveType is neither 1 (SMS) or 2 (CRW)."); + break; + } + } + else { + trfrKernelParams k = ind->getIndKernTraits(); + ts.sumDist1[sex] += k.meanDist1; + ts.ssqDist1[sex] += k.meanDist1 * k.meanDist1; + ts.sumDist2[sex] += k.meanDist2; + ts.ssqDist2[sex] += k.meanDist2 * k.meanDist2; + ts.sumProp1[sex] += k.probKern1; + ts.ssqProp1[sex] += k.probKern1 * k.probKern1; + } // settlement traits - settleTraits s = inds[i]->getSettTraits(); - if (sett.sexDep) g = sex; else g = 0; - ts.sumS0[g] += s.s0; ts.ssqS0[g] += s.s0 * s.s0; - ts.sumAlphaS[g] += s.alpha; ts.ssqAlphaS[g] += s.alpha * s.alpha; - ts.sumBetaS[g] += s.beta; ts.ssqBetaS[g] += s.beta * s.beta; + settleTraits s = ind->getIndSettTraits(); + ts.sumS0[sex] += s.s0; + ts.ssqS0[sex] += s.s0 * s.s0; + ts.sumAlphaS[sex] += s.alpha; + ts.ssqAlphaS[sex] += s.alpha * s.alpha; + ts.sumBetaS[sex] += s.beta; + ts.ssqBetaS[sex] += s.beta * s.beta; + + double fitness = ind->getGeneticFitness(); + ts.sumGeneticFitness[sex] += fitness; + ts.ssqGeneticFitness[sex] += fitness * fitness; } - return ts; } +//int Population::getNInds() { return static_cast(inds.size()); } + +// ---------------------------------------------------------------------------------------- +// reset allele table +// ---------------------------------------------------------------------------------------- +void Population::resetPopNeutralTables() { + for (auto& entry : popNeutralCountTables) { + entry.reset(); + } +} + +// ---------------------------------------------------------------------------------------- +// Populate population-level NEUTRAL count tables +// Update allele occurrence and heterozygosity counts, and allele frequencies +// ---------------------------------------------------------------------------------------- +void Population::updatePopNeutralTables() { + + const int nLoci = pSpecies->getNPositionsForTrait(NEUTRAL); + const int nAlleles = pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); + const auto& positions = pSpecies->getSpTrait(NEUTRAL)->getGenePositions(); + const int ploidy = pSpecies->isDiploid() ? 2 : 1; + + // Create /reset empty tables + if (popNeutralCountTables.size() != 0) + resetPopNeutralTables(); + else { + popNeutralCountTables.reserve(nLoci); + + for (int l = 0; l < nLoci; l++) { + popNeutralCountTables.push_back(NeutralCountsTable(nAlleles)); + } + } -int Population::getNInds(void) { return (int)inds.size(); } + // Fill tallies for each locus + for (Individual* individual : sampledInds) { -popStats Population::getStats(void) + const auto trait = individual->getTrait(NEUTRAL); + int whichLocus = 0; + for (auto position : positions) { + + int alleleOnChromA = (int)trait->getAlleleValueAtLocus(0, position); + popNeutralCountTables[whichLocus].incrementTally(alleleOnChromA); + + if (ploidy == 2) { // second allele and heterozygosity + int alleleOnChromB = (int)trait->getAlleleValueAtLocus(1, position); + popNeutralCountTables[whichLocus].incrementTally(alleleOnChromB); + + bool isHetero = alleleOnChromA != alleleOnChromB; + if (isHetero) { + popNeutralCountTables[whichLocus].incrementHeteroTally(alleleOnChromA); + popNeutralCountTables[whichLocus].incrementHeteroTally(alleleOnChromB); + } + } + whichLocus++; + } + } + + // Fill frequencies + if (sampledInds.size() > 0) { + std::for_each( + popNeutralCountTables.begin(), + popNeutralCountTables.end(), + [&](NeutralCountsTable& thisLocus) -> void { + thisLocus.setFrequencies(static_cast(sampledInds.size()) * ploidy); + }); + } +} + +double Population::getAlleleFrequency(int thisLocus, int whichAllele) { + return popNeutralCountTables[thisLocus].getFrequency(whichAllele); +} + +int Population::getAlleleTally(int thisLocus, int whichAllele) { + return popNeutralCountTables[thisLocus].getTally(whichAllele); +} + +int Population::getHeteroTally(int thisLocus, int whichAllele) { + return popNeutralCountTables[thisLocus].getHeteroTally(whichAllele); +} + +// ---------------------------------------------------------------------------------------- +// Count number of heterozygotes loci in sampled individuals +// ---------------------------------------------------------------------------------------- +int Population::countHeterozygoteLoci() { + int nbHetero = 0; + if (pSpecies->isDiploid()) { + for (Individual* ind : sampledInds) { + const NeutralTrait* trait = (NeutralTrait*)(ind->getTrait(NEUTRAL)); + nbHetero += trait->countHeterozygoteLoci(); + } + } + return nbHetero; +} + +// ---------------------------------------------------------------------------------------- +// Count number of heterozygotes among sampled individuals for each locus +// ---------------------------------------------------------------------------------------- +vector Population::countNbHeterozygotesEachLocus() { + const auto& positions = pSpecies->getSpTrait(NEUTRAL)->getGenePositions(); + vector hetero(positions.size(), 0); + + if (pSpecies->isDiploid()) { + for (Individual* ind : sampledInds) { + const NeutralTrait* trait = (NeutralTrait*)ind->getTrait(NEUTRAL); + int counter = 0; + for (auto position : positions) { + hetero[counter] += trait->isHeterozygoteAtLocus(position); + counter++; + } + } + } + return hetero; +} + +// ---------------------------------------------------------------------------------------- +// Compute the expected heterozygosity for population +// ---------------------------------------------------------------------------------------- +double Population::computeHs() { + int nLoci = pSpecies->getNPositionsForTrait(NEUTRAL); + int nAlleles = pSpecies->getSpTrait(NEUTRAL)->getNbNeutralAlleles(); + double hs = 0; + double freq; + vector locihet(nLoci, 1); + + if (sampledInds.size() > 0) { + for (int thisLocus = 0; thisLocus < nLoci; ++thisLocus) { + for (int allele = 0; allele < nAlleles; ++allele) { + freq = getAlleleFrequency(thisLocus, allele); + freq *= freq; //squared frequencies (expected _homozygosity) + locihet[thisLocus] -= freq; // 1 - sum of p2 = expected heterozygosity + } + hs += locihet[thisLocus]; + } + } + return hs; +} + +popStats Population::getStats(std::vector localDemoScaling) { - popStats p; + popStats p = popStats(); int ninds; float fec; - bool breeders[2]; breeders[0] = breeders[1] = false; - demogrParams dem = pSpecies->getDemogr(); + bool breeders[2] = { false, false }; + demogrParams dem = pSpecies->getDemogrParams(); p.pSpecies = pSpecies; p.pPatch = pPatch; p.spNum = pSpecies->getSpNum(); @@ -286,11 +455,20 @@ popStats Population::getStats(void) for (int sex = 0; sex < nSexes; sex++) { ninds = nInds[stg][sex]; p.nNonJuvs += ninds; - if (ninds > 0) { if (pSpecies->stageStructured()) { - if (dem.repType == 2) fec = pSpecies->getFec(stg, sex); + if (dem.repType == 2) { + if (pSpecies->getFecSpatial() && pSpecies->getFecLayer(stg,sex)>=0){ + fec = pSpecies->getFec(stg,sex)*localDemoScaling[pSpecies->getFecLayer(stg,sex)]; + } + else fec = pSpecies->getFec(stg,sex); + } + else { + if (pSpecies->getFecSpatial() && pSpecies->getFecLayer(stg,0)>=0){ + fec = pSpecies->getFec(stg,0)*localDemoScaling[pSpecies->getFecLayer(stg,0)]; + } else fec = pSpecies->getFec(stg, 0); + } if (fec > 0.0) { breeders[sex] = true; p.nAdults += ninds; } } else breeders[sex] = true; @@ -309,25 +487,24 @@ popStats Population::getStats(void) Species* Population::getSpecies(void) { return pSpecies; } -int Population::totalPop(void) { - int t = 0; - for (int stg = 0; stg < nStages; stg++) { - for (int sex = 0; sex < nSexes; sex++) { - t += nInds[stg][sex]; - } - } - return t; +int Population::getNbInds() const { + return inds.size(); } -int Population::stagePop(int stg) { +int Population::getNbInds(int stg) const { int t = 0; - if (stg < 0 || stg >= nStages) return t; + if (stg < 0 || stg >= nStages) throw runtime_error("Attempt to get nb individuals for stage " + to_string(stg) + ", no such stage."); for (int sex = 0; sex < nSexes; sex++) { t += nInds[stg][sex]; } return t; } +int Population::getNbInds(int stg, int sex) const { + if (stg < 0 || stg >= nStages) throw runtime_error("Attempt to get nb individuals for stage " + to_string(stg) + ", no such stage."); + return nInds[stg][sex]; +} + //--------------------------------------------------------------------------- // Remove all Individuals void Population::extirpate(void) { @@ -350,7 +527,7 @@ void Population::extirpate(void) { //--------------------------------------------------------------------------- // Produce juveniles and hold them in the juvs vector -void Population::reproduction(const float localK, const float envval, const int resol) +void Population::reproduction(const float localK, const float envval, const int resol, std::vector localDemoScaling) { // get population size at start of reproduction @@ -364,27 +541,36 @@ void Population::reproduction(const float localK, const float envval, const int bool skipbreeding; envStochParams env = paramsStoch->getStoch(); - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); - genomeData gen = pSpecies->getGenomeData(); - simView v = paramsSim->getViews(); - if (dem.repType == 0) nsexes = 1; else nsexes = 2; + if (dem.repType == 0) + nsexes = 1; + else nsexes = 2; + // set up local copy of species fecundity table - float fec[NSTAGES][NSEXES]; + float fec[gMaxNbStages][gMaxNbSexes]; for (int stg = 0; stg < sstruct.nStages; stg++) { for (int sex = 0; sex < nsexes; sex++) { if (dem.stageStruct) { if (dem.repType == 1) { // simple sexual model // both sexes use fecundity recorded for females - fec[stg][sex] = pSpecies->getFec(stg, 0); + if (pSpecies->getFecSpatial() && pSpecies->getFecLayer(stg,0)>=0){ + fec[stg][sex] = pSpecies->getFec(stg,0)*localDemoScaling[pSpecies->getFecLayer(stg,0)]; + } + else fec[stg][sex] = pSpecies->getFec(stg,0); } + else { + if (pSpecies->getFecSpatial() && pSpecies->getFecLayer(stg,sex)>=0){ + fec[stg][sex] = pSpecies->getFec(stg,sex)*localDemoScaling[pSpecies->getFecLayer(stg,sex)]; + } else fec[stg][sex] = pSpecies->getFec(stg, sex); } + } else { // non-structured population if (stg == 1) fec[stg][sex] = dem.lambda; // adults else fec[stg][sex] = 0.0; // juveniles @@ -428,7 +614,7 @@ void Population::reproduction(const float localK, const float envval, const int } } else // not stage-specific - effect = (float)totalPop(); + effect = (float)getNbInds(); if (localK > 0.0) fec[stg][0] *= exp(-effect / localK); } } @@ -457,7 +643,7 @@ void Population::reproduction(const float localK, const float envval, const int } double propBreed; - Individual* father; + Individual* father = nullptr; std::vector fathers; switch (dem.repType) { @@ -487,17 +673,20 @@ void Population::reproduction(const float localK, const float envval, const int nj = (int)juvs.size(); pCell = pPatch->getRandomCell(); for (int j = 0; j < njuvs; j++) { -#if RSDEBUG - // NOTE: CURRENTLY SETTING ALL INDIVIDUALS TO RECORD NO. OF STEPS ... - juvs.push_back(new Individual(pCell, pPatch, 0, 0, 0, 0.0, true, trfr.moveType)); -#else - juvs.push_back(new Individual(pCell, pPatch, 0, 0, 0, 0.0, trfr.moveModel, trfr.moveType)); -#endif + + Individual* newJuv; + newJuv = new Individual(pSpecies, pCell, pPatch, 0, 0, 0, dem.propMales, trfr.usesMovtProc, trfr.moveType); + + if (pSpecies->getNTraits() > 0) { + newJuv->inheritTraits(pSpecies, inds[i], resol); + } + + if (!newJuv->isViable()) { + delete newJuv; + } + else { + juvs.push_back(newJuv); nInds[0][0]++; - if (emig.indVar || trfr.indVar || sett.indVar || gen.neutralMarkers) - { - // juv inherits genome from parent (mother) - juvs[nj + j]->setGenes(pSpecies, inds[i], 0, resol); } } } @@ -509,7 +698,6 @@ void Population::reproduction(const float localK, const float envval, const int case 2: // complex sexual model // count breeding females and males // add breeding males to list of potential fathers - nfemales = nmales = 0; for (int i = 0; i < ninds; i++) { ind = inds[i]->getStats(); @@ -553,6 +741,7 @@ void Population::reproduction(const float localK, const float envval, const int else expected = 0.0; // fails to breed if (expected <= 0.0) njuvs = 0; else njuvs = pRandom->Poisson(expected); + if (njuvs > 0) { nj = (int)juvs.size(); @@ -562,18 +751,21 @@ void Population::reproduction(const float localK, const float envval, const int father = fathers[rrr]; pCell = pPatch->getRandomCell(); for (int j = 0; j < njuvs; j++) { -#if RSDEBUG - // NOTE: CURRENTLY SETTING ALL INDIVIDUALS TO RECORD NO. OF STEPS ... - juvs.push_back(new Individual(pCell, pPatch, 0, 0, 0, dem.propMales, true, trfr.moveType)); -#else - juvs.push_back(new Individual(pCell, pPatch, 0, 0, 0, dem.propMales, trfr.moveModel, trfr.moveType)); -#endif - sex = juvs[nj + j]->getSex(); + Individual* newJuv; + + newJuv = new Individual(pSpecies, pCell, pPatch, 0, 0, 0, dem.propMales, trfr.usesMovtProc, trfr.moveType); + + if (pSpecies->getNTraits() > 0) { + newJuv->inheritTraits(pSpecies, inds[i], father, resol); + } + + if (!newJuv->isViable()) { + delete newJuv; + } + else { + juvs.push_back(newJuv); + sex = newJuv->getSex(); nInds[0][sex]++; - if (emig.indVar || trfr.indVar || sett.indVar || gen.neutralMarkers) - { - // juv inherits genome from parents - juvs[nj + j]->setGenes(pSpecies, inds[i], father, resol); } } } @@ -593,7 +785,7 @@ void Population::reproduction(const float localK, const float envval, const int // Following reproduction of ALL species, add juveniles to the population prior to dispersal void Population::fledge(void) { - demogrParams dem = pSpecies->getDemogr(); + demogrParams dem = pSpecies->getDemogrParams(); if (dem.stageStruct) { // juveniles are added to the individuals vector inds.insert(inds.end(), juvs.begin(), juvs.end()); @@ -607,75 +799,124 @@ void Population::fledge(void) for (int sex = 0; sex < nSexes; sex++) { nInds[1][sex] = 0; // set count of adults to zero } - inds = juvs; + inds = std::move(juvs); } juvs.clear(); +} +Individual* Population::sampleInd() const { + int index = pRandom->IRandom(0, static_cast(inds.size() - 1)); + return inds[index]; +} + +void Population::sampleIndsWithoutReplacement(string strNbToSample, const set& sampleStages) { + + if (sampledInds.size() > 0) { + sampledInds.clear(); + } + auto rng = pRandom->getRNG(); + vector stagedInds; + + // Stage individuals in eligible stages + for (int stage : sampleStages) { + vector toAdd = getIndividualsInStage(stage); + stagedInds.insert(stagedInds.begin(), toAdd.begin(), toAdd.end()); + } + + if (strNbToSample == "all") { + // Sample all individuals in selected stages + sampledInds = stagedInds; + } + else { // random + int nbToSample = stoi(strNbToSample); + if (stagedInds.size() <= nbToSample) { + // Sample all individuals in selected stages + sampledInds = stagedInds; + } + else { + // Sample n individuals across selected stages + sample(stagedInds.begin(), stagedInds.end(), std::back_inserter(sampledInds), nbToSample, rng); + } + } +} + +int Population::sampleSize() const { + return static_cast(sampledInds.size()); +} + +vector Population::getIndividualsInStage(int stage) { + vector indsInStage; + for (auto ind : inds) { + if (ind->getStats().stage == stage) + indsInStage.push_back(ind); + } + return indsInStage; } // Determine which individuals will disperse void Population::emigration(float localK) { int nsexes; - double disp, Pdisp, NK; - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); + double disp, pbDisp, NK; + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); emigTraits eparams; - trfrRules trfr = pSpecies->getTrfr(); + transferRules trfr = pSpecies->getTransferRules(); indStats ind; // to avoid division by zero, assume carrying capacity is at least one individual // localK can be zero if there is a moving gradient or stochasticity in K if (localK < 1.0) localK = 1.0; - NK = (float)totalPop() / localK; + NK = static_cast(getNbInds()) / localK; - int ninds = (int)inds.size(); + int ninds = static_cast(inds.size()); // set up local copy of emigration probability table // used when there is no individual variability // NB - IT IS DOUBTFUL THIS CONTRIBUTES ANY SUBSTANTIAL TIME SAVING - if (dem.repType == 0) nsexes = 1; else nsexes = 2; - double Pemig[NSTAGES][NSEXES]; + if (dem.repType == 0) nsexes = 1; + else nsexes = 2; + double pbEmig[gMaxNbStages][gMaxNbSexes]; for (int stg = 0; stg < sstruct.nStages; stg++) { for (int sex = 0; sex < nsexes; sex++) { - if (emig.indVar) Pemig[stg][sex] = 0.0; + if (emig.indVar) pbEmig[stg][sex] = 0.0; else { if (emig.densDep) { if (emig.sexDep) { if (emig.stgDep) { - eparams = pSpecies->getEmigTraits(stg, sex); + eparams = pSpecies->getSpEmigTraits(stg, sex); } else { - eparams = pSpecies->getEmigTraits(0, sex); + eparams = pSpecies->getSpEmigTraits(0, sex); } } else { // !emig.sexDep if (emig.stgDep) { - eparams = pSpecies->getEmigTraits(stg, 0); + eparams = pSpecies->getSpEmigTraits(stg, 0); } else { - eparams = pSpecies->getEmigTraits(0, 0); + eparams = pSpecies->getSpEmigTraits(0, 0); } } - Pemig[stg][sex] = eparams.d0 / (1.0 + exp(-(NK - eparams.beta) * eparams.alpha)); + pbEmig[stg][sex] = eparams.d0 / (1.0 + exp(-(NK - eparams.beta) * eparams.alpha)); } else { // density-independent if (emig.sexDep) { if (emig.stgDep) { - Pemig[stg][sex] = pSpecies->getEmigD0(stg, sex); + pbEmig[stg][sex] = pSpecies->getSpEmigD0(stg, sex); } else { // !emig.stgDep - Pemig[stg][sex] = pSpecies->getEmigD0(0, sex); + pbEmig[stg][sex] = pSpecies->getSpEmigD0(0, sex); } } else { // !emig.sexDep if (emig.stgDep) { - Pemig[stg][sex] = pSpecies->getEmigD0(stg, 0); + pbEmig[stg][sex] = pSpecies->getSpEmigD0(stg, 0); } else { // !emig.stgDep - Pemig[stg][sex] = pSpecies->getEmigD0(0, 0); + pbEmig[stg][sex] = pSpecies->getSpEmigD0(0, 0); } } } @@ -685,25 +926,25 @@ void Population::emigration(float localK) for (int i = 0; i < ninds; i++) { ind = inds[i]->getStats(); - if (ind.status < 1) + if (ind.status < 1) // ToDo: Maybe allow dispersal after translocation? If so, we need to update the pPrevCell and pCurrCell variables of the translocated individuals! { if (emig.indVar) { // individual variability in emigration if (dem.stageStruct && ind.stage != emig.emigStage) { // emigration may not occur - Pdisp = 0.0; + pbDisp = 0.0; } else { // non-structured or individual is in emigration stage - eparams = inds[i]->getEmigTraits(); + eparams = inds[i]->getIndEmigTraits(); if (emig.densDep) { // density-dependent - NK = (float)totalPop() / localK; - Pdisp = eparams.d0 / (1.0 + exp(-(NK - eparams.beta) * eparams.alpha)); + NK = (float)getNbInds() / localK; + pbDisp = eparams.d0 / (1.0 + exp(-(NK - eparams.beta) * eparams.alpha)); } else { // density-independent if (emig.sexDep) { - Pdisp = Pemig[0][ind.sex] + eparams.d0; + pbDisp = pbEmig[0][ind.sex] + eparams.d0; } else { - Pdisp = Pemig[0][0] + eparams.d0; + pbDisp = pbEmig[0][0] + eparams.d0; } } } @@ -713,44 +954,41 @@ void Population::emigration(float localK) if (emig.densDep) { if (emig.sexDep) { if (emig.stgDep) { - Pdisp = Pemig[ind.stage][ind.sex]; + pbDisp = pbEmig[ind.stage][ind.sex]; } else { - Pdisp = Pemig[0][ind.sex]; + pbDisp = pbEmig[0][ind.sex]; } } else { // !emig.sexDep if (emig.stgDep) { - Pdisp = Pemig[ind.stage][0]; + pbDisp = pbEmig[ind.stage][0]; } else { - Pdisp = Pemig[0][0]; + pbDisp = pbEmig[0][0]; } } } else { // density-independent if (emig.sexDep) { if (emig.stgDep) { - Pdisp = Pemig[ind.stage][ind.sex]; + pbDisp = pbEmig[ind.stage][ind.sex]; } else { // !emig.stgDep - Pdisp = Pemig[0][ind.sex]; + pbDisp = pbEmig[0][ind.sex]; } } else { // !emig.sexDep if (emig.stgDep) { - Pdisp = Pemig[ind.stage][0]; + pbDisp = pbEmig[ind.stage][0]; } else { // !emig.stgDep - Pdisp = Pemig[0][0]; + pbDisp = pbEmig[0][0]; } } } - - } // end of no individual variability - - disp = pRandom->Bernoulli(Pdisp); + disp = pRandom->Bernoulli(pbDisp); if (disp == 1) { // emigrant inds[i]->setStatus(1); @@ -767,13 +1005,23 @@ void Population::allEmigrate(void) { } } +// Remove an Individual from the Population +Individual* Population::extractIndividual(int ix) { + Individual* pInd = inds[ix]; + indStats ind = pInd->getStats(); + inds[ix] = nullptr; + nInds[ind.stage][ind.sex]--; + return pInd; +} + // If an Individual has been identified as an emigrant, remove it from the Population disperser Population::extractDisperser(int ix) { - disperser d; + disperser d = disperser(); indStats ind = inds[ix]->getStats(); if (ind.status == 1) { // emigrant - d.pInd = inds[ix]; d.yes = true; - inds[ix] = 0; + d.pInd = inds[ix]; + d.yes = true; + inds[ix] = nullptr; nInds[ind.stage][ind.sex]--; } else { @@ -782,16 +1030,17 @@ disperser Population::extractDisperser(int ix) { return d; } + // For an individual identified as being in the matrix population: // if it is a settler, return its new location and remove it from the current population // otherwise, leave it in the matrix population for possible reporting before deletion disperser Population::extractSettler(int ix) { - disperser d; + disperser d = disperser(); Cell* pCell; indStats ind = inds[ix]->getStats(); - pCell = inds[ix]->getLocn(1); + pCell = inds[ix]->getCurrCell(); d.pInd = inds[ix]; d.pCell = pCell; d.yes = false; if (ind.status == 4 || ind.status == 5) { // settled d.yes = true; @@ -804,300 +1053,25 @@ disperser Population::extractSettler(int ix) { // Add a specified individual to the new/current dispersal group // Add a specified individual to the population void Population::recruit(Individual* pInd) { - inds.push_back(pInd); - indStats ind = pInd->getStats(); + indStats ind = pInd->getStats(); // potentially I need to add localscalings or so? nInds[ind.stage][ind.sex]++; +#ifdef _OPENMP + const std::lock_guard lock(inds_mutex); +#endif // _OPENMP + inds.push_back(pInd); } -//--------------------------------------------------------------------------- - -// Transfer is run for populations in the matrix only -#if RS_RCPP // included also SEASONAL -int Population::transfer(Landscape* pLandscape, short landIx, short nextseason) -#else -int Population::transfer(Landscape* pLandscape, short landIx) -#endif -{ - int ndispersers = 0; - int disperser; - short othersex; - bool mateOK, densdepOK; - intptr patch, popn; - int patchnum; - double localK, popsize, settprob; - Patch* pPatch = 0; - Cell* pCell = 0; - indStats ind; - Population* pNewPopn = 0; - locn newloc, nbrloc; - - landData ppLand = pLandscape->getLandData(); - short reptype = pSpecies->getRepType(); - trfrRules trfr = pSpecies->getTrfr(); - settleType settletype = pSpecies->getSettle(); - settleRules sett; - settleTraits settDD; - settlePatch settle; - simParams sim = paramsSim->getSim(); - - // each individual takes one step - // for dispersal by kernel, this should be the only step taken - int ninds = (int)inds.size(); - for (int i = 0; i < ninds; i++) { - if (trfr.moveModel) { - disperser = inds[i]->moveStep(pLandscape, pSpecies, landIx, sim.absorbing); - } - else { - disperser = inds[i]->moveKernel(pLandscape, pSpecies, reptype, sim.absorbing); - } - ndispersers += disperser; - if (disperser) { - if (reptype > 0) - { // sexual species - record as potential settler in new patch - if (inds[i]->getStatus() == 2) - { // disperser has found a patch - pCell = inds[i]->getLocn(1); - patch = pCell->getPatch(); - if (patch != 0) { // not no-data area - pPatch = (Patch*)patch; - pPatch->incrPossSettler(pSpecies, inds[i]->getSex()); - } - } - } - } - } - -// each individual which has reached a potential patch decides whether to settle - for (int i = 0; i < ninds; i++) { - ind = inds[i]->getStats(); - if (ind.sex == 0) othersex = 1; else othersex = 0; - if (settletype.stgDep) { - if (settletype.sexDep) sett = pSpecies->getSettRules(ind.stage, ind.sex); - else sett = pSpecies->getSettRules(ind.stage, 0); - } - else { - if (settletype.sexDep) sett = pSpecies->getSettRules(0, ind.sex); - else sett = pSpecies->getSettRules(0, 0); - } - if (ind.status == 2) - { // awaiting settlement - pCell = inds[i]->getLocn(1); - if (pCell == 0) { - // this condition can occur in a patch-based model at the time of a dynamic landscape - // change when there is a range restriction in place, since a patch can straddle the - // range restriction and an individual forced to disperse upon patch removal could - // start its trajectory beyond the boundary of the restrictyed range - such a model is - // not good practice, but the condition must be handled by killing the individual conceerned - ind.status = 6; - } - else { - mateOK = false; - if (sett.findMate) { - // determine whether at least one individual of the opposite sex is present in the - // new population - if (matePresent(pCell, othersex)) mateOK = true; - } - else { // no requirement to find a mate - mateOK = true; - } - - densdepOK = false; - settle = inds[i]->getSettPatch(); - if (sett.densDep) - { - patch = pCell->getPatch(); - if (patch != 0) { // not no-data area - pPatch = (Patch*)patch; - if (settle.settleStatus == 0 - || settle.pSettPatch != pPatch) - // note: second condition allows for having moved from one patch to another - // adjacent one - { - // determine whether settlement occurs in the (new) patch - localK = (double)pPatch->getK(); - popn = pPatch->getPopn((intptr)pSpecies); - if (popn == 0) { // population has not been set up in the new patch - popsize = 0.0; - } - else { - pNewPopn = (Population*)popn; - popsize = (double)pNewPopn->totalPop(); - } - if (localK > 0.0) { - // make settlement decision - if (settletype.indVar) settDD = inds[i]->getSettTraits(); -#if RS_RCPP - else settDD = pSpecies->getSettTraits(ind.stage, ind.sex); -#else - else { - if (settletype.sexDep) { - if (settletype.stgDep) - settDD = pSpecies->getSettTraits(ind.stage, ind.sex); - else - settDD = pSpecies->getSettTraits(0, ind.sex); - } - else { - if (settletype.stgDep) - settDD = pSpecies->getSettTraits(ind.stage, 0); - else - settDD = pSpecies->getSettTraits(0, 0); - } - } -#endif //RS_RCPP - settprob = settDD.s0 / - (1.0 + exp(-(popsize / localK - (double)settDD.beta) * (double)settDD.alpha)); - - if (pRandom->Bernoulli(settprob)) { // settlement allowed - densdepOK = true; - settle.settleStatus = 2; - } - else { // settlement procluded - settle.settleStatus = 1; - } - settle.pSettPatch = pPatch; - } - inds[i]->setSettPatch(settle); - } - else { - if (settle.settleStatus == 2) { // previously allowed to settle - densdepOK = true; - } - } - } - } - else { // no density-dependent settlement - densdepOK = true; - settle.settleStatus = 2; - settle.pSettPatch = pPatch; - inds[i]->setSettPatch(settle); - } - - if (mateOK && densdepOK) { // can recruit to patch - ind.status = 4; - ndispersers--; - } - else { // does not recruit - if (trfr.moveModel) { - ind.status = 1; // continue dispersing, unless ... - // ... maximum steps has been exceeded - pathSteps steps = inds[i]->getSteps(); - settleSteps settsteps = pSpecies->getSteps(ind.stage, ind.sex); - if (steps.year >= settsteps.maxStepsYr) { - ind.status = 3; // waits until next year - } - if (steps.total >= settsteps.maxSteps) { - ind.status = 6; // dies - } - } - else { // dispersal kernel - if (sett.wait) { - ind.status = 3; // wait until next dispersal event - } - else { - ind.status = 6; // (dies unless a neighbouring cell is suitable) - } - ndispersers--; - } - } - } - - inds[i]->setStatus(ind.status); - } -#if RS_RCPP - // write each individuals current movement step and status to paths file - if (trfr.moveModel && sim.outPaths) { - if (nextseason >= sim.outStartPaths && nextseason % sim.outIntPaths == 0) { - inds[i]->outMovePath(nextseason); - } - } -#endif - - if (!trfr.moveModel && sett.go2nbrLocn && (ind.status == 3 || ind.status == 6)) - { - // for kernel-based transfer only ... - // determine whether recruitment to a neighbouring cell is possible - - pCell = inds[i]->getLocn(1); - newloc = pCell->getLocn(); - vector nbrlist; - for (int dx = -1; dx < 2; dx++) { - for (int dy = -1; dy < 2; dy++) { - if (dx != 0 || dy != 0) { //cell is not the current cell - nbrloc.x = newloc.x + dx; nbrloc.y = newloc.y + dy; - if (nbrloc.x >= 0 && nbrloc.x <= ppLand.maxX - && nbrloc.y >= 0 && nbrloc.y <= ppLand.maxY) { // within landscape - // add to list of potential neighbouring cells if suitable, etc. - pCell = pLandscape->findCell(nbrloc.x, nbrloc.y); - if (pCell != 0) { // not no-data area - patch = pCell->getPatch(); - if (patch != 0) { // not no-data area - pPatch = (Patch*)patch; - patchnum = pPatch->getPatchNum(); - if (patchnum > 0 && pPatch != inds[i]->getNatalPatch()) - { // not the matrix or natal patch - if (pPatch->getK() > 0.0) - { // suitable - if (sett.findMate) { - if (matePresent(pCell, othersex)) nbrlist.push_back(pCell); - } - else - nbrlist.push_back(pCell); - } - } - } - } - } - } - } - } - int listsize = (int)nbrlist.size(); - if (listsize > 0) { // there is at least one suitable neighbouring cell - if (listsize == 1) { - inds[i]->moveto(nbrlist[0]); - } - else { // select at random from the list - int rrr = pRandom->IRandom(0, listsize - 1); - inds[i]->moveto(nbrlist[rrr]); - } - } - // else list empty - do nothing - individual retains its current location and status - } - } - return ndispersers; -} - -// Determine whether there is a potential mate present in a patch which a potential -// settler has reached -bool Population::matePresent(Cell* pCell, short othersex) -{ - int patch; - Patch* pPatch; - Population* pNewPopn; - int popsize = 0; - bool matefound = false; - - patch = (int)pCell->getPatch(); - if (patch != 0) { - pPatch = (Patch*)pCell->getPatch(); - if (pPatch->getPatchNum() > 0) { // not the matrix patch - if (pPatch->getK() > 0.0) - { // suitable - pNewPopn = (Population*)pPatch->getPopn((intptr)pSpecies); - if (pNewPopn != 0) { - // count members of other sex already resident in the patch - for (int stg = 0; stg < nStages; stg++) { - popsize += pNewPopn->nInds[stg][othersex]; - } - } - if (popsize < 1) { - // add any potential settlers of the other sex - popsize += pPatch->getPossSettlers(pSpecies, othersex); - } - } - } +// Add specified individuals to the population +void Population::recruitMany(std::vector& recruits) { + if (recruits.empty()) return; + for (Individual* pInd : recruits) { + indStats ind = pInd->getStats(); + nInds[ind.stage][ind.sex]++; } - if (popsize > 0) matefound = true; - return matefound; +#ifdef _OPENMP + const std::lock_guard lock(inds_mutex); +#endif // _OPENMP + inds.insert(inds.end(), recruits.begin(), recruits.end()); } //--------------------------------------------------------------------------- @@ -1107,41 +1081,53 @@ bool Population::matePresent(Cell* pCell, short othersex) // FOR MULTIPLE SPECIES, MAY NEED TO SEPARATE OUT THIS IDENTIFICATION STAGE, // SO THAT IT CAN BE PERFORMED FOR ALL SPECIES BEFORE ANY UPDATING OF POPULATIONS -void Population::survival0(float localK, short option0, short option1) +void Population::survival0(float localK, short option0, short option1, std::vector localDemoScaling) { // option0: 0 - stage 0 (juveniles) only // 1 - all stages // 2 - stage 1 and above (all non-juveniles) + // // option1: 0 - development only (when survival is annual) // 1 - development and survival // 2 - survival only (when survival is annual) - densDepParams ddparams = pSpecies->getDensDep(); - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); - // get surrent population size - int ninds = (int)inds.size(); + // get current population size + int ninds = inds.size(); if (ninds == 0) return; // set up local copies of species development and survival tables - int nsexes; - if (dem.repType == 0) nsexes = 1; else nsexes = 2; - float dev[NSTAGES][NSEXES]; - float surv[NSTAGES][NSEXES]; - short minAge[NSTAGES][NSEXES]; + int nsexes = dem.repType == 0 ? 1 : 2; + float dev[gMaxNbStages][gMaxNbSexes]; + float surv[gMaxNbStages][gMaxNbSexes]; + short minAge[gMaxNbStages][gMaxNbSexes]; + for (int stg = 0; stg < sstruct.nStages; stg++) { for (int sex = 0; sex < nsexes; sex++) { if (dem.stageStruct) { if (dem.repType == 1) { // simple sexual model // both sexes use development and survival recorded for females - dev[stg][sex] = pSpecies->getDev(stg, 0); - surv[stg][sex] = pSpecies->getSurv(stg, 0); + if (pSpecies->getDevSpatial() && pSpecies->getDevLayer(stg,0)>=0){ + dev[stg][sex] = pSpecies->getDev(stg,0)*localDemoScaling[pSpecies->getDevLayer(stg,0)]; + } + else dev[stg][sex] = pSpecies->getDev(stg,0); + if (pSpecies->getSurvSpatial() && pSpecies->getSurvLayer(stg,0)>=0){ + surv[stg][sex] = pSpecies->getSurv(stg,0)*localDemoScaling[pSpecies->getSurvLayer(stg,0)]; + } + else surv[stg][sex] = pSpecies->getSurv(stg,0); minAge[stg][sex] = pSpecies->getMinAge(stg, 0); } else { - dev[stg][sex] = pSpecies->getDev(stg, sex); - surv[stg][sex] = pSpecies->getSurv(stg, sex); + if (pSpecies->getDevSpatial() && pSpecies->getDevLayer(stg,sex)>=0){ + dev[stg][sex] = pSpecies->getDev(stg,sex)*localDemoScaling[pSpecies->getDevLayer(stg,sex)]; + } + else dev[stg][sex] = pSpecies->getDev(stg,sex); + if (pSpecies->getSurvSpatial() && pSpecies->getSurvLayer(stg,sex)>=0){ + surv[stg][sex] = pSpecies->getSurv(stg,sex)*localDemoScaling[pSpecies->getSurvLayer(stg,sex)]; + } + else surv[stg][sex] = pSpecies->getSurv(stg,sex); minAge[stg][sex] = pSpecies->getMinAge(stg, sex); } if (option1 == 0) surv[stg][sex] = 1.0; // development only - all survive @@ -1157,14 +1143,11 @@ void Population::survival0(float localK, short option0, short option1) } } } - if (dem.stageStruct) { - // apply density dependence in development and/or survival probabilities for (int stg = 0; stg < nStages; stg++) { for (int sex = 0; sex < nsexes; sex++) { if (option1 != 2 && sstruct.devDens && stg > 0) { // NB DD in development does NOT apply to juveniles, - // which must develop to stage 1 if they survive float effect = 0.0; if (sstruct.devStageDens) { // stage-specific density dependence // NOTE: matrix entries represent effect of ROW on COLUMN @@ -1186,11 +1169,12 @@ void Population::survival0(float localK, short option0, short option1) } } else // not stage-specific - effect = (float)totalPop(); + effect = (float)getNbInds(); if (localK > 0.0) dev[stg][sex] *= exp(-(ddparams.devCoeff * effect) / localK); } // end of if (sstruct.devDens && stg > 0) if (option1 != 0 && sstruct.survDens) { + float effect = 0.0; if (sstruct.survStageDens) { // stage-specific density dependence // NOTE: matrix entries represent effect of ROW on COLUMN @@ -1212,20 +1196,20 @@ void Population::survival0(float localK, short option0, short option1) } } else // not stage-specific - effect = (float)totalPop(); + effect = (float)getNbInds(); if (localK > 0.0) surv[stg][sex] *= exp(-(ddparams.survCoeff * effect) / localK); } // end of if (sstruct.survDens) } } } - // identify which individuals die or develop for (int i = 0; i < ninds; i++) { indStats ind = inds[i]->getStats(); + if ((ind.stage == 0 && option0 < 2) || (ind.stage > 0 && option0 > 0)) { // condition for processing the stage is met... - if (ind.status < 6) { // not already doomed + if (ind.status < 6 || ind.status == 10) { // not already doomed double probsurv = surv[ind.stage][ind.sex]; // does the individual survive? if (pRandom->Bernoulli(probsurv)) { // survives @@ -1234,7 +1218,7 @@ void Population::survival0(float localK, short option0, short option1) if (ind.stage < nStages - 1) { // not final stage if (ind.age >= minAge[ind.stage + 1][ind.sex]) { // old enough to enter next stage if (pRandom->Bernoulli(probdev)) { - inds[i]->developing(); + inds[i]->setToDevelop(); } } } @@ -1250,13 +1234,15 @@ void Population::survival0(float localK, short option0, short option1) // Apply survival changes to the population void Population::survival1(void) { - int ninds = (int)inds.size(); + for (int i = 0; i < ninds; i++) { indStats ind = inds[i]->getStats(); - if (ind.status > 5) { // doomed to die + + if (ind.status > 5 && ind.status != 10) { // doomed to die; status 10 is translocated? + if (ind.status != 10) //not going into cold storage -> is there a new status 10 in this new_genetics version?? delete inds[i]; - inds[i] = NULL; + inds[i] = nullptr; nInds[ind.stage][ind.sex]--; } else { @@ -1267,14 +1253,12 @@ void Population::survival1(void) } } } - -// remove pointers to dead individuals clean(); } void Population::ageIncrement(void) { int ninds = (int)inds.size(); - stageParams sstruct = pSpecies->getStage(); + stageParams sstruct = pSpecies->getStageParams(); for (int i = 0; i < ninds; i++) { inds[i]->ageIncrement(sstruct.maxAge); } @@ -1286,38 +1270,32 @@ void Population::clean(void) { int ninds = (int)inds.size(); if (ninds > 0) { - // ALTERNATIVE METHOD: AVOIDS SLOW SORTING OF POPULATION - std::vector survivors; // all surviving individuals - for (int i = 0; i < ninds; i++) { - if (inds[i] != NULL) { - survivors.push_back(inds[i]); - } - } - inds.clear(); - inds = survivors; + inds.erase(std::remove(inds.begin(), inds.end(), (Individual *)NULL), inds.end()); #if RS_RCPP shuffle(inds.begin(), inds.end(), pRandom->getRNG()); #else -#if !RSDEBUG - // do not randomise individuals in RSDEBUG mode, as the function uses rand() +#ifdef NDEBUG + // do not randomise individuals in DEBUG mode, as the function uses rand() // and therefore the randomisation will differ between identical runs of RS shuffle(inds.begin(), inds.end(), pRandom->getRNG()); -#endif // !RSDEBUG +#endif // NDEBUG #endif // RS_RCPP } } //--------------------------------------------------------------------------- -// Open population file and write header record -bool Population::outPopHeaders(int landNr, bool patchModel) { +// Close population file +bool Population::outPopFinishLandscape() { + if (outPop.is_open()) outPop.close(); + outPop.clear(); + return true; +} - if (landNr == -999) { // close file - if (outPop.is_open()) outPop.close(); - outPop.clear(); - return true; - } +//--------------------------------------------------------------------------- +// Open population file and write header record +bool Population::outPopStartLandscape(int landNr, bool patchModel) { string name; simParams sim = paramsSim->getSim(); @@ -1325,16 +1303,19 @@ bool Population::outPopHeaders(int landNr, bool patchModel) { // NEED TO REPLACE CONDITIONAL COLUMNS BASED ON ATTRIBUTES OF ONE SPECIES TO COVER // ATTRIBUTES OF *ALL* SPECIES AS DETECTED AT MODEL LEVEL - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + name = paramsSim->getDir(2) + + (sim.batchMode ? "Batch" + to_string(sim.batchNum) + "_" : "") + + "Sim" + to_string(sim.simulation) + "_Land" + to_string(landNr) + "_Pop.txt"; if (sim.batchMode) { name = paramsSim->getDir(2) - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(landNr) + "_Pop.txt"; + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + to_string(landNr) + "_Pop.txt"; } else { - name = paramsSim->getDir(2) + "Sim" + Int2Str(sim.simulation) + "_Pop.txt"; + name = paramsSim->getDir(2) + "Sim" + to_string(sim.simulation) + "_Pop.txt"; } outPop.open(name.c_str()); outPop << "Rep\tYear\tRepSeason"; @@ -1362,7 +1343,6 @@ bool Population::outPopHeaders(int landNr, bool patchModel) { if (dem.repType != 0) outPop << "\tNfemales\tNmales"; } outPop << endl; - return outPop.is_open(); } @@ -1372,12 +1352,11 @@ void Population::outPopulation(int rep, int yr, int gen, float eps, bool patchModel, bool writeEnv, bool gradK) { Cell* pCell; + // NEED TO REPLACE CONDITIONAL COLUMNS BASED ON ATTRIBUTES OF ONE SPECIES TO COVER -// ATTRIBUTES OF *ALL* SPECIES AS DETECTED AT MODEL LEVEL - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - popStats p; + demogrParams dem = pSpecies->getDemogrParams(); + popStats p; outPop << rep << "\t" << yr << "\t" << gen; if (patchModel) { outPop << "\t" << pPatch->getPatchNum(); @@ -1401,7 +1380,7 @@ void Population::outPopulation(int rep, int yr, int gen, float eps, } outPop << "\t" << pSpecies->getSpNum(); if (dem.stageStruct) { - p = getStats(); + p = getStats(pPatch->getDemoScaling()); outPop << "\t" << p.nNonJuvs; // non-juvenile stage totals from permanent array for (int stg = 1; stg < nStages; stg++) { @@ -1415,7 +1394,7 @@ void Population::outPopulation(int rep, int yr, int gen, float eps, } } else { // non-structured population - outPop << "\t" << totalPop(); + outPop << "\t" << getNbInds(); if (dem.repType != 0) { // sexual model outPop << "\t" << nInds[1][0] << "\t" << nInds[1][1]; @@ -1427,47 +1406,44 @@ void Population::outPopulation(int rep, int yr, int gen, float eps, //--------------------------------------------------------------------------- //--------------------------------------------------------------------------- -// Open individuals file and write header record -void Population::outIndsHeaders(int rep, int landNr, bool patchModel) +// Close individuals file +void Population::outIndsFinishReplicate() { - - if (landNr == -999) { // close file - if (outInds.is_open()) { - outInds.close(); outInds.clear(); - } - return; + if (outInds.is_open()) { + outInds.close(); outInds.clear(); } + return; +} +//--------------------------------------------------------------------------- +// Open individuals file and write header record +void Population::outIndsStartReplicate(int rep, int landNr, bool patchModel) +{ string name; - demogrParams dem = pSpecies->getDemogr(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); simParams sim = paramsSim->getSim(); - if (sim.batchMode) { name = paramsSim->getDir(2) - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) - + "_Land" + Int2Str(landNr) + "_Rep" + Int2Str(rep) + "_Inds.txt"; - } - else { - name = paramsSim->getDir(2) + "Sim" + Int2Str(sim.simulation) - + "_Rep" + Int2Str(rep) + "_Inds.txt"; - } - outInds.open(name.c_str()); + + (sim.batchMode ? "Batch" + to_string(sim.batchNum) + "_" : "") + + "Sim" + to_string(sim.simulation) + + "_Land" + to_string(landNr) + "_Rep" + to_string(rep) + "_Inds.txt"; + outInds.open(name.c_str()); outInds << "Rep\tYear\tRepSeason\tSpecies\tIndID\tStatus"; if (patchModel) outInds << "\tNatal_patch\tPatchID"; else outInds << "\tNatal_X\tNatal_Y\tX\tY"; if (dem.repType != 0) outInds << "\tSex"; if (dem.stageStruct) outInds << "\tAge\tStage"; + if (pSpecies->getNbGenLoadTraits() > 0) outInds << "\tProbViable"; if (emig.indVar) { if (emig.densDep) outInds << "\tD0\tAlpha\tBeta"; else outInds << "\tEP"; } if (trfr.indVar) { - if (trfr.moveModel) { + if (trfr.usesMovtProc) { if (trfr.moveType == 1) { // SMS outInds << "\tDP\tGB\tAlphaDB\tBetaDB"; } @@ -1484,11 +1460,10 @@ void Population::outIndsHeaders(int rep, int landNr, bool patchModel) outInds << "\tS0\tAlphaS\tBetaS"; } outInds << "\tDistMoved"; -#if RSDEBUG - // ALWAYS WRITE NO. OF STEPS +#ifndef NDEBUG outInds << "\tNsteps"; #else - if (trfr.moveModel) outInds << "\tNsteps"; + if (trfr.usesMovtProc) outInds << "\tNsteps"; #endif outInds << endl; } @@ -1498,20 +1473,17 @@ void Population::outIndsHeaders(int rep, int landNr, bool patchModel) void Population::outIndividual(Landscape* pLandscape, int rep, int yr, int gen, int patchNum) { - //int x, y, p_id; bool writeInd; pathSteps steps; Cell* pCell; - landParams ppLand = pLandscape->getLandParams(); - demogrParams dem = pSpecies->getDemogr(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); + demogrParams dem = pSpecies->getDemogrParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); settleType sett = pSpecies->getSettle(); short spNum = pSpecies->getSpNum(); int ninds = (int)inds.size(); - for (int i = 0; i < ninds; i++) { indStats ind = inds[i]->getStats(); if (yr == -1) { // write all initialised individuals @@ -1537,11 +1509,11 @@ void Population::outIndividual(Landscape* pLandscape, int rep, int yr, int gen, else { // non-structured population outInds << "\t" << ind.status; } - pCell = inds[i]->getLocn(1); + pCell = inds[i]->getCurrCell(); locn loc; if (pCell == 0) loc.x = loc.y = -1; // beyond boundary or in no-data cell else loc = pCell->getLocn(); - pCell = inds[i]->getLocn(0); + pCell = inds[i]->getPrevCell(); locn natalloc = pCell->getLocn(); if (ppLand.patchModel) { outInds << "\t" << inds[i]->getNatalPatch()->getPatchNum(); @@ -1555,8 +1527,10 @@ void Population::outIndividual(Landscape* pLandscape, int rep, int yr, int gen, if (dem.repType != 0) outInds << "\t" << ind.sex; if (dem.stageStruct) outInds << "\t" << ind.age << "\t" << ind.stage; + if (pSpecies->getNbGenLoadTraits() > 0) outInds << "\t" << inds[i]->getGeneticFitness(); + if (emig.indVar) { - emigTraits e = inds[i]->getEmigTraits(); + emigTraits e = inds[i]->getIndEmigTraits(); if (emig.densDep) { outInds << "\t" << e.d0 << "\t" << e.alpha << "\t" << e.beta; } @@ -1564,21 +1538,20 @@ void Population::outIndividual(Landscape* pLandscape, int rep, int yr, int gen, outInds << "\t" << e.d0; } } // end of if (emig.indVar) - if (trfr.indVar) { - if (trfr.moveModel) { + if (trfr.usesMovtProc) { if (trfr.moveType == 1) { // SMS - trfrSMSTraits s = inds[i]->getSMSTraits(); + trfrSMSTraits s = inds[i]->getIndSMSTraits(); outInds << "\t" << s.dp << "\t" << s.gb; outInds << "\t" << s.alphaDB << "\t" << s.betaDB; } // end of SMS if (trfr.moveType == 2) { // CRW - trfrCRWTraits c = inds[i]->getCRWTraits(); + trfrCRWTraits c = inds[i]->getIndCRWTraits(); outInds << "\t" << c.stepLength << "\t" << c.rho; } // end of CRW } else { // kernel - trfrKernTraits k = inds[i]->getKernTraits(); + trfrKernelParams k = inds[i]->getIndKernTraits(); if (trfr.twinKern) { outInds << "\t" << k.meanDist1 << "\t" << k.meanDist2 << "\t" << k.probKern1; @@ -1590,7 +1563,7 @@ void Population::outIndividual(Landscape* pLandscape, int rep, int yr, int gen, } if (sett.indVar) { - settleTraits s = inds[i]->getSettTraits(); + settleTraits s = inds[i]->getIndSettTraits(); outInds << "\t" << s.s0 << "\t" << s.alpha << "\t" << s.beta; } @@ -1601,73 +1574,244 @@ void Population::outIndividual(Landscape* pLandscape, int rep, int yr, int gen, + (natalloc.y - loc.y) * (natalloc.y - loc.y))); outInds << "\t" << d; } -#if RSDEBUG +#ifndef NDEBUG // ALWAYS WRITE NO. OF STEPS steps = inds[i]->getSteps(); outInds << "\t" << steps.year; #else - if (trfr.moveModel) { + if (trfr.usesMovtProc) { steps = inds[i]->getSteps(); outInds << "\t" << steps.year; } #endif outInds << endl; } // end of writeInd condition + } } -//--------------------------------------------------------------------------- +void Population::outputGeneValues(ofstream& ofsGenes, const int& yr, const int& gen) const { -//--------------------------------------------------------------------------- -// Write records to genetics file -void Population::outGenetics(const int rep, const int year, const int landNr) -{ + const bool isDiploid = pSpecies->isDiploid(); + int indID; + float alleleOnChromA, alleleOnChromB; + float domCoefA, domCoefB; - simParams sim = paramsSim->getSim(); + // Subset traits that are selected to be output + set traitTypes = pSpecies->getTraitTypes(); + set outputTraitTypes; + for (auto trType : traitTypes) { + if (pSpecies->getSpTrait(trType)->isOutput()) + outputTraitTypes.insert(trType); +} - if (landNr >= 0) { // open file - Genome* pGenome; - genomeData gen = pSpecies->getGenomeData(); - if (gen.trait1Chromosome) { - pGenome = new Genome(pSpecies->getNChromosomes(), pSpecies->getNLoci(0), - pSpecies->isDiploid()); - } - else { - pGenome = new Genome(pSpecies); + // Fetch map to positions for each trait + // Presumably faster than fetching for every individual + map> allGenePositions; + for (auto trType : outputTraitTypes) { + set traitPositions = pSpecies->getSpTrait(trType)->getGenePositions(); + allGenePositions.insert(make_pair(trType, traitPositions)); } - pGenome->outGenHeaders(rep, landNr, sim.outGenXtab); - delete pGenome; - return; - } - if (landNr == -999) { // close file - Genome* pGenome = new Genome(); - pGenome->outGenHeaders(rep, landNr, sim.outGenXtab); - delete pGenome; - return; + set positions; + for (Individual* ind : sampledInds) { + indID = ind->getId(); + for (auto trType : outputTraitTypes) { + positions = allGenePositions[trType]; + auto indTrait = ind->getTrait(trType); + for (auto pos : positions) { + alleleOnChromA = indTrait->getAlleleValueAtLocus(0, pos); + if (trType == GENETIC_LOAD1 || trType == GENETIC_LOAD2 || trType == GENETIC_LOAD3 || trType == GENETIC_LOAD4 || trType == GENETIC_LOAD5) { + domCoefA = indTrait->getDomCoefAtLocus(0, pos); } - - short spNum = pSpecies->getSpNum(); - short nstages = 1; - if (pSpecies->stageStructured()) { - stageParams sstruct = pSpecies->getStage(); - nstages = sstruct.nStages; + else { + domCoefA = 0.0; + } + ofsGenes << yr << '\t' << gen << '\t' << indID << '\t' << to_string(trType) << '\t' << pos << '\t' << alleleOnChromA << '\t' << domCoefA; + if (isDiploid) { + alleleOnChromB = indTrait->getAlleleValueAtLocus(1, pos); + if (trType == GENETIC_LOAD1 || trType == GENETIC_LOAD2 || trType == GENETIC_LOAD3 || trType == GENETIC_LOAD4 || trType == GENETIC_LOAD5) { + domCoefB = indTrait->getDomCoefAtLocus(1, pos); +} + else { + domCoefB = 0.0; + } + ofsGenes << '\t' << alleleOnChromB << '\t' << domCoefB; + } + ofsGenes << endl; + } + } } +} +// --------------------------------------------------------------------------- +// Extract all individuals of a population with certain characteristics based on age, stage and sex +// returns a set of pointers to the individuals +// --------------------------------------------------------------------------- +std::vector Population::getIndsWithCharacteristics( // Select a set of individuals with specified characteristics + int min_age, // min age (0 if not set) + int max_age, // max age (max age if not set) + int stage, // stage + int sex //sex +){ + // get all suitable individuals based on settings + std::vector filteredInds; int ninds = (int)inds.size(); +#if RS_RCPP + Rcpp::Rcout << "Number individuals in cell: " << ninds << endl; +#endif + if (ninds > 0) { + // copy ALL individuals to filteredInds for (int i = 0; i < ninds; i++) { - indStats ind = inds[i]->getStats(); - if (year == 0 || sim.outGenType == 1 - || (sim.outGenType == 0 && ind.stage == 0) - || (sim.outGenType == 2 && ind.stage == nstages - 1)) { - inds[i]->outGenetics(rep, year, spNum, landNr, sim.outGenXtab); + filteredInds.push_back(inds[i]); } - } + // check status of inividuals + for (int i = 0; i < ninds; i++) { + if (inds[i] != NULL && inds[i]->getStats().status != 0 && inds[i]->getStats().status != 4 && inds[i]->getStats().status != 5){ // only accept individuals with status 0, 4 or 5 (not in transfer phase + not dead + not already translocated) + // Rcpp::Rcout << "Status: " << inds[i]->getStats().status << endl; + filteredInds[i] = NULL; // set it to NULL + } + } + + // Check minimal age + if (min_age!=-9){ + // loop over all number of individuals in cell + for (int i = 0; i < ninds; i++) { + if (filteredInds[i] != NULL && inds[i]->getStats().age < min_age){ // if not already NULL + age too young + filteredInds[i] = NULL; // set it to NULL } - + } + } + // check max age + if (max_age!=-9){ + // loop over all number of individuals in cell + for (int i = 0; i < ninds; i++) { + if (filteredInds[i] != NULL && inds[i]->getStats().age < max_age){// if not already NULL + age too old + if (filteredInds[i] != NULL) filteredInds[i] = NULL; // set it to NULL if not already NULL + } + } + } + // check stage + if (stage!=-9){ + // loop over all number of individuals in cell + for (int i = 0; i < ninds; i++) { + if (filteredInds[i] != NULL && inds[i]->getStats().stage != stage){// if not already NULL + stage not correct + if (filteredInds[i] != NULL) filteredInds[i] = NULL; // set it to NULL if not already NULL + } + } + } + // check sex + if (sex!=-9){ + // loop over all number of individuals in cell + for (int i = 0; i < ninds; i++) { + if (filteredInds[i] != NULL && inds[i]->getStats().sex != sex){// if not already NULL + sex not correct + if (filteredInds[i] != NULL) filteredInds[i] = NULL; // set it to NULL if not already NULL + } + } + } + } else { +#if RS_RCPP + Rcpp::Rcout << "No individuals in source patch" << endl; +#endif + return filteredInds; + } + int nfiltered = 0; + for ( auto filtered : filteredInds){ + if (filtered != NULL) nfiltered++; + } + + // loop over iterator of filteredInds and remove NULL values + filteredInds.erase(std::remove(filteredInds.begin(), filteredInds.end(), nullptr), filteredInds.end()); + + return filteredInds; +}; //--------------------------------------------------------------------------- +// Clean the sampled individuals //--------------------------------------------------------------------------- +void Population::cleanSampledInds(Individual* pInd // Return a set of individuals with specified characteristics +){ + // find inds[j] and remove it from sampledInds + sampledInds.erase(std::remove(sampledInds.begin(), sampledInds.end(), pInd), sampledInds.end()); +}; +//--------------------------------------------------------------------------- +// Sample N individuals from the population with a given set of characteristics +// --------------------------------------------------------------------------- +int Population::sampleIndividuals( // Select a set of individuals with specified characteristics +// void Population::sampleIndividuals( // Select a set of individuals with specified characteristics + int nb, // number of individuals to sample + int min_age, // min age (0 if not set) + int max_age, // max age (max age if not set) + int stage, // stage + int sex //sex + ){ + if(sampledInds.size() > 0) sampledInds.clear(); // clear old vector + auto rng = pRandom->getRNG(); // random number for sampling from suitable individuals + + // get individuals with the characteristics + std::vector filtered; + filtered = getIndsWithCharacteristics(min_age, max_age, stage, sex); +#if RS_RCPP + Rcpp::Rcout << "Number of individuals with fitting characteristics: " << filtered.size() << endl; +#endif + if (filtered.size() <= nb) + // Sample all individuals in selected stages + sampledInds = filtered; + else { + vector out; + // Sample n individuals across filtered individuals + std::sample(filtered.begin(), filtered.end(), std::back_inserter(out), nb, rng); + std::copy(out.begin(), out.end(), std::inserter(sampledInds, sampledInds.end())); + } + + int nb_sampled = 0; + if (sampledInds.size() > 0) { + for (int i = 0; i < (int)sampledInds.size(); i++) { + if (sampledInds[i] != NULL) nb_sampled++; + } + } + return nb_sampled; +} +// --------------------------------------------------------------------------- +// catch individuals according to catching rate +// --------------------------------------------------------------------------- +Individual* Population::catchIndividual( // Translocate a set of individuals with specified characteristics + double catching_rate, + int j +){ + Individual* catched; + int id = inds[j]->getId(); + // If individual is part of the sampledInds vector: + if (std::find(sampledInds.begin(), sampledInds.end(), inds[j]) != std::end(sampledInds)){ + // try to catch individual +#if RS_RCPP + if(catching_rate > 1) Rcpp::Rcout << "Catching rate: " << catching_rate << std::endl; +#endif + if (pRandom->Bernoulli(catching_rate)){ + indStats indstat = inds[j]->getStats(); + catched = inds[j]; + // remove individual from source patch + inds[j] = 0; + nInds[indstat.stage][indstat.sex]--; + cleanSampledInds(catched); // clean vector of sampled individuals after the event + return catched; + }else { + cleanSampledInds(inds[j]); // clean vector of sampled individuals after the event + return NULL; + } + } else { + return NULL; + } +} + +// --------------------------------------------------------------------------- +bool Population::getSizeSampledInds( +){ + bool size = false; + if (sampledInds.size() > 0) size = true; + return size; +}; + //--------------------------------------------------------------------------- diff --git a/RangeShiftR/src/RScore/Population.h b/RangeShiftR/src/RScore/Population.h new file mode 100644 index 0000000..df1db74 --- /dev/null +++ b/RangeShiftR/src/RScore/Population.h @@ -0,0 +1,299 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + +/*------------------------------------------------------------------------------ + +RangeShifter v2.0 Population + +Implements the Population class + +There is ONE instance of a Population for each Species within each SubCommunity +(including the matrix). The Population holds a list of all the Individuals in +the Population. + +The matrix Population(s) hold(s) Individuals which are currently in the process +of transfer through the matrix. + +For full details of RangeShifter, please see: +Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. +and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial +eco-evolutionary dynamics and species’ responses to environmental changes. +Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + +Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + + Last updated: 25 June 2021 by Steve Palmer + +------------------------------------------------------------------------------*/ + +#ifndef PopulationH +#define PopulationH + +#include +#include +using namespace std; + +#include "Parameters.h" +#include "Individual.h" +#include "Species.h" +#include "Landscape.h" +#include "Patch.h" +#include "Cell.h" +#include "NeutralStatsManager.h" + +#ifdef _OPENMP +#include +#include +#endif + +//--------------------------------------------------------------------------- + +struct popStats { + Species *pSpecies; Patch *pPatch; int spNum,nInds,nNonJuvs,nAdults; bool breeding; +}; +struct disperser { + Individual *pInd; Cell *pCell; bool yes; +}; +struct zombie { + Individual* pInd; +}; +struct traitsums { // sums of trait genes for dispersal + int ninds[gMaxNbSexes]; // no. of individuals + double sumD0[gMaxNbSexes]; // sum of maximum emigration probability + double ssqD0[gMaxNbSexes]; // sum of squares of maximum emigration probability + double sumAlpha[gMaxNbSexes]; // sum of slope of emigration dens-dep reaction norm + double ssqAlpha[gMaxNbSexes]; // sum of squares of slope of emigration den-dep reaction norm + double sumBeta[gMaxNbSexes]; // sum of inflection point of emigration reaction norm + double ssqBeta[gMaxNbSexes]; // sum of squares of inflection point of emigration reaction norm + double sumDist1[gMaxNbSexes]; // sum of kernel I mean + double ssqDist1[gMaxNbSexes]; // sum of squares of kernel I mean + double sumDist2[gMaxNbSexes]; // sum of kernel II mean + double ssqDist2[gMaxNbSexes]; // sum of squares of kernel II mean + double sumProp1[gMaxNbSexes]; // sum of propn using kernel I + double ssqProp1[gMaxNbSexes]; // sum of squares of propn using kernel I + double sumDP[gMaxNbSexes]; // sum of SMS directional persistence + double ssqDP[gMaxNbSexes]; // sum of squares of SMS directional persistence + double sumGB[gMaxNbSexes]; // sum of SMS goal bias + double ssqGB[gMaxNbSexes]; // sum of squares of SMS goal bias + double sumAlphaDB[gMaxNbSexes]; // sum of SMS dispersal bias decay rate + double ssqAlphaDB[gMaxNbSexes]; // sum of squares of SMS dispersal bias decay rate + double sumBetaDB[gMaxNbSexes]; // sum of SMS dispersal bias decay infl. pt. + double ssqBetaDB[gMaxNbSexes]; // sum of squares of SMS dispersal bias decay infl. pt. + double sumStepL[gMaxNbSexes]; // sum of CRW step length + double ssqStepL[gMaxNbSexes]; // sum of squares of CRW step length + double sumRho[gMaxNbSexes]; // sum of CRW correlation coefficient + double ssqRho[gMaxNbSexes]; // sum of squares of CRW correlation coefficient + double sumS0[gMaxNbSexes]; // sum of maximum settlement probability + double ssqS0[gMaxNbSexes]; // sum of squares of maximum settlement probability + double sumAlphaS[gMaxNbSexes]; // sum of slope of settlement den-dep reaction norm + double ssqAlphaS[gMaxNbSexes]; // sum of squares of slope of settlement den-dep reaction norm + double sumBetaS[gMaxNbSexes]; // sum of inflection point of settlement reaction norm + double ssqBetaS[gMaxNbSexes]; // sum of squares of inflection point of settlement reaction norm + double sumGeneticFitness[gMaxNbSexes]; + double ssqGeneticFitness[gMaxNbSexes]; +}; + +class Population { + +public: + Population(void); // default constructor + Population( // constructor for a Population of a specified size + Species*, // pointer to Species + Patch*, // pointer to Patch + int, // no. of Individuals + int // Landscape resolution + ); + ~Population(void); + traitsums getIndTraitsSums(Species*); + popStats getStats( + std::vector + ); + Species* getSpecies(void); + int getNbInds() const; + int getNbInds(int stg) const ; + int getNbInds(int stg, int sex) const; + void extirpate(void); // Remove all individuals + void reproduction( + const float, // local carrying capacity + const float, // effect of environmental gradient and/or stochasticty + const int, // Landscape resolution + std::vector // local demographic scaling + ); + // Following reproduction of ALL species, add juveniles to the population + void fledge(void); + void emigration( // Determine which individuals will disperse + float // local carrying capacity + ); + void allEmigrate(void); // All individuals emigrate after patch destruction + // Remove an individual from the Population + Individual* extractIndividual( + int // index no. to the Individual in the inds vector + ); + // If an individual has been identified as an emigrant, remove it from the Population + disperser extractDisperser( + int // index no. to the Individual in the inds vector + ); + // For an individual identified as being in the matrix population: + // if it is a settler, return its new location and remove it from the current population + // otherwise, leave it in the matrix population for possible reporting before deletion + disperser extractSettler( + int // index no. to the Individual in the inds vector + ); + void recruit( // Add a specified individual to the population + Individual* // pointer to Individual + ); + Individual* sampleInd() const; + void sampleIndsWithoutReplacement(string n, const set& sampleStages); + int sampleSize() const; + vector getIndividualsInStage(int stage); + void recruitMany( // Add specified individuals to the population + std::vector& // vector of pointers to Individuals + ); + + // Determine survival and development and record in individual's status code + // Changes are NOT applied to the Population at this stage + void survival0( + float, // local carrying capacity + short, // option0: 0 - stage 0 (juveniles) only + // 1 - all stages + // 2 - stage 1 and above (all non-juveniles) + short, // option1: 0 - development only (when survival is annual) + // 1 - development and survival + // 2 - survival only (when survival is annual) + std::vector // local demographic scaling + ); + void survival1(void); // Apply survival changes to the population + void ageIncrement(void); + bool outPopFinishLandscape(); // Close population file + bool outPopStartLandscape( // Open population file and write header record + int, // Landscape number + bool // TRUE for a patch-based model, FALSE for a cell-based model + ); + void outPopulation( // Write record to population file + int, // replicate + int, // year + int, // generation + float, // epsilon - global stochasticity value + bool, // TRUE for a patch-based model, FALSE for a cell-based model + bool, // TRUE to write environmental data + bool // TRUE if there is a gradient in carrying capacity + ); + + void outIndsFinishReplicate(); // Close individuals file + void outIndsStartReplicate( // Open individuals file and write header record + int, // replicate + int, // Landscape number + bool // TRUE for a patch-based model, FALSE for a cell-based model + ); + void outIndividual( // Write records to individuals file + Landscape*, // pointer to Landscape + int, // replicate + int, // year + int, // generation + int // Patch number + ); + void outputGeneValues(ofstream& ofsGenes, const int& yr, const int& gen) const; + void clean(void); // Remove zero pointers to dead or dispersed individuals + + void updatePopNeutralTables(); + double getAlleleFrequency(int locus, int allele); + int getAlleleTally(int locus, int allele); + int getHeteroTally(int locus, int allele); + int countHeterozygoteLoci(); + vector countNbHeterozygotesEachLocus(); + double computeHs(); + std::vector getIndsWithCharacteristics( // Return a set of individuals with specified characteristics + int, // min age + int, // max age + int, // stage + int //sex + ); + void cleanSampledInds( + Individual* // individual to remove from sampled individuals vector + ); // clean sampled individuals vector + + int sampleIndividuals( // Select a set of individuals with specified characteristics; return the number of individuals with those characteristics + // void sampleIndividuals( // Select a set of individuals with specified characteristics; return the number of individuals with those characteristics + int, //number of individuals to sample + int, // min age (0 if not set) + int, // max age (max age if not set) + int, // stage + int //sex + ); + + Individual* catchIndividual( + double, // catching rate + int + ); + + // void completeTranslocation( + // std::vector // catched individuals + // ); + + // void recruitTranslocated( + // Individual* + // ); + + bool getSizeSampledInds( + ); + +#ifdef UNIT_TESTS + // Testing only + void clearInds() { inds.clear(); } // empty inds vector to avoid deallocating individual is used separately in test + void shuffleInds() { shuffle(inds.begin(), inds.end(), pRandom->getRNG()); } +#endif // UNIT_TESTS + +private: + short nStages; + short nSexes; + Species *pSpecies; // pointer to the species + Patch *pPatch; // pointer to the patch +#ifdef _OPENMP + std::atomic nInds[gMaxNbStages][gMaxNbSexes]; // no. of individuals in each stage/sex +#else + int nInds[gMaxNbStages][gMaxNbSexes]; // no. of individuals in each stage/sex +#endif // _OPENMP + + vector inds; // all individuals in population except ... + vector juvs; // ... juveniles until reproduction of ALL species + // has been completed + + vector sampledInds; + //std::vector sampledInds; // individuals with specified characteristics from translocation!!! + vector popNeutralCountTables; + void resetPopNeutralTables(); +#ifdef _OPENMP + std::mutex inds_mutex; +#endif // _OPENMP +}; + +//--------------------------------------------------------------------------- + +extern paramGrad *paramsGrad; +extern paramStoch *paramsStoch; +extern paramInit *paramsInit; +extern paramSim *paramsSim; +extern RSrandom *pRandom; + +//--------------------------------------------------------------------------- +#endif + diff --git a/RangeShiftR/src/RScore/QuantitativeTrait.h b/RangeShiftR/src/RScore/QuantitativeTrait.h new file mode 100644 index 0000000..3ffe997 --- /dev/null +++ b/RangeShiftR/src/RScore/QuantitativeTrait.h @@ -0,0 +1,53 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ + +#ifndef TRAITTH +#define TRAITTH + +#include +#include +#include + +#include "Parameters.h" +#include "Allele.h" +#include "SpeciesTrait.h" + +using namespace std; + +// Base interface for all genetic traits +class QuantitativeTrait { +public: + virtual void mutate() = 0; + virtual unique_ptr clone() const = 0; //copies parameters (if not static) not gene seqeunces + virtual void inheritGenes(const bool&, QuantitativeTrait*, set const& , int ) = 0; + virtual int getNLoci() const = 0; + virtual float getMutationRate() const = 0; + virtual bool isInherited() const = 0; + virtual float getAlleleValueAtLocus(short chromosome, int i) const = 0; + virtual float getDomCoefAtLocus(short whichChromosome, int position) const = 0; + virtual float express() = 0; + virtual ~QuantitativeTrait() { } +}; + +extern RSrandom* pRandom; + +#endif diff --git a/RangeShiftR/src/RScore/README.md b/RangeShiftR/src/RScore/README.md new file mode 100644 index 0000000..bd266e6 --- /dev/null +++ b/RangeShiftR/src/RScore/README.md @@ -0,0 +1,101 @@ +# RangeShifter core code + +This repo contains the core simulation code for RangeShifter v3.0 and is not meant to be compiled or run on its own. It is used as a shared codebase for multiple interfaces. + + + +If you are only interested in using RangeShifter, you can ignore this and head to the repo of one of the interfaces: + +- [WIP] RangeShifter GUI + +- [RangeShiftR](https://github.com/RangeShifter/RangeShiftR-pkg) + +- [RangeShifter-batch](https://github.com/RangeShifter/RangeShifter_batch) + +## Usage: git subtree + +In order to ensure that the same version of RangeShifter's core code is used by all three interfaces (RangeShiftR, RangeShifter-batch and the GUI), each interface repo keeps a copy of RScore as a git subtree. + +In this section, we describe how to use the git subtrees to update the subfolder and copy this repo anew. + +⚠️Please note: + +Modifying files inside the RScore subtree directly in the interface repositories can lead to merge conflicts or broken history, if you do not strictly follow the workflow presented here. + +You must ensure that you always push changes on files located in the RScore directory to the git subtree repository RScore using `git subtree push` and must **not** push them to the RangeShiftR-pkg or RangeShifter_batch repository. + +The most robust way to avoid merge conflicts and broken history is to modify files directly inside the RScore repository and then pull the changes into the interface repositories by using `git subtree pull`. + +### Set up + +First, in a local clone of one of the interface repos, add a remote named `RScore` pointing to the RScore repo. This will be convenient as a shortcut for git subtree commands. + +```bash +git remote add RScore https://github.com/RangeShifter/RScore.git +``` + +### Pulling new changes + +To update the RScore subfolder with new changes made to the RScore repo, one can use the `git subtree pull` command: + +```bash +git subtree pull --prefix RScore +``` + +Note the path must match the location of the RScore subfolder, and the branch must match the one the subtree was originally added from (by default, this should be `main`). + +e.g. for RangeShifter-batch, use: + +```bash +git subtree pull --prefix src/RScore RScore main +``` + +while for RangeShiftR, use: + +```bash +git subtree pull --prefix RangeShiftR/src/RScore RScore main +``` + +#### Dealing with conflicts + +If conflicts occur, the RScore repository should be treated as the source of truth: + +``` +git checkout --theirs +git add +git commit +``` + +### Pushing new changes to RScore + +If changes were made inside the subtree directory (not recommended, but sometimes unavoidable), they must be pushed back to this repository **before** pushing to the interface repository: + +```bash +git subtree push --prefix RScore +``` + +e.g., from RangeShifter-batch's `main` to RScore's `main`: + +```bash +git subtree push --prefix src/RScore RScore main +``` + +Afterwards, update other interface repositories using `git subtree pull`. + +### Switching the subfolder to a new branch + +There is unfortunately to do so. To track a different branch of RScore, one must delete the RScore subfolder (via git) and import the subtree again: + +```bash +git rm src/RScore -r +git commit -m "switching subtree branch" +git subtree add --prefix src/RScore RScore +``` + +## Contributing to RangeShifter core code + +See [CONTRIBUTING](https://github.com/RangeShifter/RScore/blob/main/CONTRIBUTING.md). + +## Maintainers + +- [\@JetteReeg](https://github.com/JetteReeg) diff --git a/RangeShiftR/src/RScore/RS_repos.png b/RangeShiftR/src/RScore/RS_repos.png new file mode 100644 index 0000000..b138a01 Binary files /dev/null and b/RangeShiftR/src/RScore/RS_repos.png differ diff --git a/RScore_logo.png b/RangeShiftR/src/RScore/RScore_logo.png similarity index 100% rename from RScore_logo.png rename to RangeShiftR/src/RScore/RScore_logo.png diff --git a/RangeShiftR/src/RScore/RSrandom.cpp b/RangeShiftR/src/RScore/RSrandom.cpp new file mode 100644 index 0000000..c284400 --- /dev/null +++ b/RangeShiftR/src/RScore/RSrandom.cpp @@ -0,0 +1,258 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + +#include "RSrandom.h" +#ifdef _OPENMP +#include +#endif // _OPENMP +#ifndef NDEBUG +#include "Parameters.h" +extern paramSim* paramsSim; +#endif + +#if RS_RCPP +std::uint32_t RS_random_seed = 0; +#else +int RS_random_seed = 0; +#endif + +// C'tor +#if RS_RCPP +// if parameter seed is negative, a random seed will be generated, else it is used as seed +RSrandom::RSrandom(std::int64_t seed) +{ + // get seed + std::vector random_seed(3); + random_seed[0] = 1967593562; + random_seed[1] = 3271254416; + if (seed < 0) { + // random seed +#if RSWIN64 + random_seed[2] = std::time(NULL) + (seed * (-17)); +#else + std::random_device device; + random_seed[2] = device(); +#endif + } + else { + // fixed seed + random_seed[2] = seed; + } + + RS_random_seed = random_seed[2]; + + // set up Mersenne Twister random number generator with seed sequence + std::seed_seq seq(random_seed.begin(), random_seed.end()); + +#ifdef _OPENMP + int nb_generators = omp_get_max_threads(); + gens.reserve(nb_generators); + for (int i = 0; i < nb_generators; i++) + gens.emplace_back(seq); +#else + gens.reserve(1); + gens.emplace_back(seq); +#endif // _OPENMP + + + // Set up standard uniform distribution + pRandom01 = new uniform_real_distribution(0.0, 1.0); + // Set up standard normal distribution + pNormal = new normal_distribution(0.0, 1.0); +} +#else +RSrandom::RSrandom() { + +#ifndef NDEBUG + // fixed seed + RS_random_seed = 11011; +#else + // random seed +#if LINUX_CLUSTER + std::random_device device; + RS_random_seed = device(); // old versions of g++ on Windows return a constant value within a given Windows + // session; in this case better use time stamp +#else + RS_random_seed = std::time(NULL); +#endif +#endif // NDEBUG + + // set up Mersenne Twister RNG +#ifdef _OPENMP + int nb_generators = omp_get_max_threads(); + gens.reserve(nb_generators); + for (int i = 0; i < nb_generators; i++) + gens.emplace_back(RS_random_seed + i); +#else + gens.reserve(1); + gens.emplace_back(RS_random_seed); +#endif // _OPENMP + + // Set up standard uniform distribution + pRandom01 = new uniform_real_distribution(0.0, 1.0); + // Set up standard normal distribution + pNormal = new normal_distribution(0.0, 1.0); +} +#endif // RS_RCPP + +RSrandom::~RSrandom(void) { + gens.clear(); + if (pRandom01 != 0) + delete pRandom01; + if (pNormal != 0) + delete pNormal; +} + +mt19937 RSrandom::getRNG() { +#ifdef _OPENMP + return gens[omp_get_thread_num() % gens.size()]; +#else + return gens[0]; +#endif // _OPENMP +} + +double RSrandom::Random() { + // return random number between 0 and 1 +#ifdef _OPENMP + return pRandom01->operator()(gens[omp_get_thread_num() % gens.size()]); +#else + return pRandom01->operator()(gens[0]); +#endif // _OPENMP +} + +int RSrandom::IRandom(int min, int max) { + // return random integer in the interval min <= x <= max + if (min == max) + return min; + + uniform_int_distribution unif(min, max); +#ifdef _OPENMP + return unif(gens[omp_get_thread_num() % gens.size()]); +#else + return unif(gens[0]); +#endif // _OPENMP +} + +float RSrandom::FRandom(float min, float max) { + if (min == max) return min; + // return random double in the interval min <= x <= max + uniform_real_distribution unif(min, max); + +#ifdef _OPENMP + return unif(gens[omp_get_thread_num() % gens.size()]); +#else + return unif(gens[0]); +#endif +} + +int RSrandom::Bernoulli(double p) { + if (p < 0) { + throw runtime_error("Bernoulli's p cannot be negative.\n"); + } + if (p > 1) { + throw runtime_error("Bernoulli's p cannot be above 1.\n"); + } + return Random() < p; +} + +int RSrandom::Binomial(const int& n, const double& p) { + binomial_distribution binom(n, p); +#ifdef _OPENMP + return binom(gens[omp_get_thread_num() % gens.size()]); +#else + return binom(gens[0]); +#endif +} + +double RSrandom::Normal(double mean, double sd) { +#ifdef _OPENMP + return mean + sd * pNormal->operator()(gens[omp_get_thread_num() % gens.size()]); +#else + return mean + sd * pNormal->operator()(gens[0]); +#endif // _OPENMP +} + +int RSrandom::Poisson(double mean) { + poisson_distribution poiss(mean); +#ifdef _OPENMP + return poiss(gens[omp_get_thread_num() % gens.size()]); +#else + return poiss(gens[0]); +#endif // _OPENMP +} + +double RSrandom::Gamma(double shape, double scale) { //scale = mean/shape, shape must be positive and scale can be positive or negative + + gamma_distribution<> gamma(shape, abs(scale)); + +#ifdef _OPENMP + double x = poiss(gens[omp_get_thread_num() % gens.size()]); +#else + double x = gamma(gens[0]); +#endif // _OPENMP + if (scale < 0) x = -x; + return x; +} + +double RSrandom::NegExp(double mean) { + double r1 = 0.0000001 + this->Random() * (1.0 - 0.0000001); + double x = (-1.0 * mean) * log(r1); + return x; +} + +void RSrandom::fixNewSeed(int seed) { +#ifdef _OPENMP + for (int i = 0; i < omp_get_max_threads(); i++) + gens[i].seed(seed + i); +#else + gens[0].seed(seed); +#endif // _OPENMP +} + +//-------------------------------------------------------------------------------------------------- +//-------------------------------------------------------------------------------------------------- + +#ifdef UNIT_TESTS +#if !RS_RCPP + void testRSrandom() { + + { + // Bernoulli distribution + // Abuse cases + assert_error("Bernoulli's p cannot be negative.\n", []{ + RSrandom rsr; + rsr.Bernoulli(-0.3); + }); + assert_error("Bernoulli's p cannot be above 1.\n", [] { + RSrandom rsr; + rsr.Bernoulli(1.1); + }); + // Use cases + RSrandom rsr; + assert(rsr.Bernoulli(0) == 0); + assert(rsr.Bernoulli(1) == 1); + int bern_trial = rsr.Bernoulli(0.5); + assert(bern_trial == 0 || bern_trial == 1); + } + } +#endif +#endif // UNIT_TESTS +//--------------------------------------------------------------------------- diff --git a/RangeShiftR/src/RScore/RSrandom.h b/RangeShiftR/src/RScore/RSrandom.h new file mode 100644 index 0000000..7ed9e34 --- /dev/null +++ b/RangeShiftR/src/RScore/RSrandom.h @@ -0,0 +1,97 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + + /*------------------------------------------------------------------------------ + + RangeShifter v2.0 RSrandom + + Implements the RSrandom class + + Authors: Steve Palmer, University of Aberdeen + Anne-Kathleen Malchow, Potsdam University + + Last updated: 12 January 2021 by Steve Palmer + + ------------------------------------------------------------------------------*/ + +#ifndef RSrandomH +#define RSrandomH + +#include +#include +#include +#include +#include +#include +#include "Utils.h" +#if !LINUX_CLUSTER +#include +#endif + +using namespace std; + +#if RS_RCPP +typedef uint32_t seed_t; +#else +typedef int seed_t; +#endif + +class RSrandom +{ + +public: +#if !RS_RCPP + RSrandom(void); +#else + RSrandom(std::int64_t); // if int is negative, a random seed will be generated, else it is used as seed +#endif + ~RSrandom(void); + double Random(void); + int IRandom(int, int); + float FRandom(float, float); + int Bernoulli(double); + int Binomial(const int& n, const double& p); + double Normal(double, double); + double Gamma(double, double); + double NegExp(double); + int Poisson(double); + mt19937 getRNG(void); + void fixNewSeed(int); + seed_t getSeed() const { return RS_random_seed; }; + + private: + seed_t RS_random_seed; + std::vector gens; + std::uniform_real_distribution<>* pRandom01; + std::normal_distribution<>* pNormal; + }; + +#ifdef UNIT_TESTS + void testRSrandom(); +#endif // UNIT_TESTS + +//--------------------------------------------------------------------------- + +#endif // RSrandomH + + + diff --git a/RangeShiftR/src/RScore/Species.cpp b/RangeShiftR/src/RScore/Species.cpp new file mode 100644 index 0000000..a192df2 --- /dev/null +++ b/RangeShiftR/src/RScore/Species.cpp @@ -0,0 +1,925 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + + //--------------------------------------------------------------------------- + +#include "Species.h" +//--------------------------------------------------------------------------- + +Species::Species(const short& repro, const short& nbRepSeasons, const bool& hasStgStruct, const short& nStg, const bool& usesMovtProc, const short& movementType) : + repType{repro}, + repSeasons{nbRepSeasons}, + stageStruct{hasStgStruct}, + nStages{nStg}, + usesMovtProcess{usesMovtProc}, + moveType{movementType} +{ + // initialise demographic parameters + propMales = 0.0; + harem = 1.0; + bc = 1.0; + lambda = 1.5; + probRep = 1.0; + repInterval = 0; + maxAge = 1000; + survival = 1; + fecDens = false; + fecStageDens = false; + devDens = false; + devStageDens = false; + survDens = false; + survStageDens = false; + fecSpatial = false; + survSpatial = false; + devSpatial = false; + disperseOnLoss = false; + for (int i = 0; i < gMaxNbStages; i++) { + for (int j = 0; j < gMaxNbSexes; j++) { + fec[i][j] = 0.0; + dev[i][j] = 0.0; + surv[i][j] = 0.0; + minAge[i][j] = 0; + fecLayer[i][j] = -9; + devLayer[i][j] = -9; + survLayer[i][j] = -9; + } + } + devCoeff = survCoeff = 1.0; + ddwtFec = ddwtDev = ddwtSurv = 0; + ddwtFecDim = ddwtDevDim = ddwtSurvDim = 0; + habK = 0; + habDimK = 0; + minRK = 1.0; + maxRK = 2.0; + + // initialise emigration parameters + densDepEmig = false; + stgDepEmig = false; + sexDepEmig = false; + indVarEmig = false; + emigStage = 0; + for (int i = 0; i < gMaxNbStages; i++) { + for (int j = 0; j < gMaxNbSexes; j++) { + d0[i][j] = 0.0; + alphaEmig[i][j] = 0.0; + betaEmig[i][j] = 1.0; + } + } + // initialise transfer parameters + stgDepTrfr = false; + sexDepTrfr = false; + distMort = false; + indVarTrfr = false; + twinKern = false; + habMort = false; + costMap = false; + for (int i = 0; i < gMaxNbStages; i++) { + for (int j = 0; j < gMaxNbSexes; j++) { + meanDist1[i][j] = 100.0f; + meanDist2[i][j] = 1000.0f; + probKern1[i][j] = 0.99f; + } + } + pr = 1; + prMethod = 1; + memSize = 1; + goalType = 0; + dp = 1.0; + gb = 1.0; + alphaDB = 1.0; + betaDB = 100000; + stepMort = 0.0; + stepLength = 10.0; + rho = 0.9f; + habStepMort = 0; + habCost = 0; + fixedMort = 0.0; + mortAlpha = 0.0; + mortBeta = 1.0; + habDimTrfr = 0; + straightenPath = false; + fullKernel = false; + // initialise settlement parameters + stgDepSett = false; + sexDepSett = false; + indVarSett = false; + for (int i = 0; i < gMaxNbStages; i++) { + for (int j = 0; j < gMaxNbSexes; j++) { + densDepSett[i][j] = false; + wait[i][j] = false; + go2nbrLocn[i][j] = false; + findMate[i][j] = false; + maxStepsYr[i][j] = 99999999; + minSteps[i][j] = 0; + maxSteps[i][j] = 99999999; + s0[i][j] = 1.0; + alphaS[i][j] = 0.0; + betaS[i][j] = 1.0; + } + } + // initialise attribute defaults + spNum = 0; + resetGeneticParameters(); +} + +Species::~Species() { + // demographic parameters + if (habK != NULL) deleteHabK(); + if (ddwtFec != 0) deleteDDwtFec(); + if (ddwtDev != 0) deleteDDwtDev(); + if (ddwtSurv != 0) deleteDDwtSurv(); + // transfer parameters + if (habCost != 0 || habStepMort != 0) deleteHabCostMort(); +} + +short Species::getSpNum(void) { return spNum; } + +//--------------------------------------------------------------------------- + +// Demographic functions + +void Species::setDemogr(const demogrParams d) { + if (d.repType >= 0 && d.repType <= 2) repType = d.repType; + if (d.repType == 1 || d.repType == 2) diploid = true; + else diploid = false; + if (d.repSeasons >= 1) repSeasons = d.repSeasons; + stageStruct = d.stageStruct; + if (d.propMales > 0.0 && d.propMales < 1.0) propMales = d.propMales; + if (d.harem > 0.0) harem = d.harem; + if (d.bc > 0.0) bc = d.bc; + if (d.lambda > 0.0) lambda = d.lambda; +} + +demogrParams Species::getDemogrParams(void) { + demogrParams d; + d.repType = repType; + d.repSeasons = repSeasons; + d.stageStruct = stageStruct; + d.propMales = propMales; + d.harem = harem; + d.bc = bc; + d.lambda = lambda; + return d; +} + +short Species::getRepType(void) { return repType; } + +bool Species::stageStructured(void) { return stageStruct; } + +void Species::createHabK(short nhab) { + if (nhab >= 0) { + habDimK = nhab; + if (habK != 0) deleteHabK(); + habK = new float[nhab]; + for (int i = 0; i < nhab; i++) habK[i] = 0.0; + } +} + +void Species::setHabK(short hx, float k) { + if (hx >= 0 && hx < habDimK) { + if (k >= 0.0) habK[hx] = k; + } +} + +float Species::getHabK(short hx) { + float k = 0.0; + if (hx >= 0 && hx < habDimK) k = habK[hx]; + return k; +} + +float Species::getMaxK(void) { + float k = 0.0; + for (int i = 0; i < habDimK; i++) { + if (habK[i] > k) k = habK[i]; + } + return k; +} + +void Species::deleteHabK(void) { + if (habK != 0) { + delete[] habK; habK = 0; + } +} + +void Species::setStage(const stageParams s) { + if (s.nStages > 1) nStages = s.nStages; + if (s.repInterval >= 0) repInterval = s.repInterval; + if (s.maxAge >= 1) maxAge = s.maxAge; + if (s.survival >= 0 && s.survival <= 2) survival = s.survival; + if (s.probRep > 0.0 && s.probRep <= 1.0) probRep = s.probRep; + fecDens = s.fecDens; + fecStageDens = s.fecStageDens; + devDens = s.devDens; + devStageDens = s.devStageDens; + survDens = s.survDens; + survStageDens = s.survStageDens; + disperseOnLoss = s.disperseOnLoss; +} + +stageParams Species::getStageParams(void) { + stageParams s; + s.nStages = nStages; s.repInterval = repInterval; s.maxAge = maxAge; + s.survival = survival; s.probRep = probRep; + s.fecDens = fecDens; s.fecStageDens = fecStageDens; + s.devDens = devDens; s.devStageDens = devStageDens; + s.survDens = survDens; s.survStageDens = survStageDens; + s.disperseOnLoss = disperseOnLoss; + return s; +} + +void Species::setFec(short stg, short sex, float f) { + // NB fecundity for stage 0 must always be zero + if (stg > 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && f >= 0) + fec[stg][sex] = f; +} + +float Species::getFec(short stg, short sex) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return fec[stg][sex]; + else return 0.0; +} + +float Species::getMaxFec(void) { + float maxfec = 0.0; + if (stageStruct) { + for (int stg = 1; stg < gMaxNbStages; stg++) { + if (fec[stg][0] > maxfec) maxfec = fec[stg][0]; + } + } + else maxfec = lambda; + return maxfec; +} + +void Species::setDev(short stg, short sex, float d) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && d >= 0) + dev[stg][sex] = d; +} + +float Species::getDev(short stg, short sex) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return dev[stg][sex]; + else return 0.0; +} + +void Species::setSurv(short stg, short sex, float s) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && s >= 0) + surv[stg][sex] = s; +} + +float Species::getSurv(short stg, short sex) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return surv[stg][sex]; + else return 0.0; +} + +void Species::setFecSpatial(bool spat) { + fecSpatial = spat; +} + +void Species::setDevSpatial(bool spat) { + devSpatial = spat; +} + +void Species::setSurvSpatial(bool spat) { + survSpatial = spat; +} + +void Species::setFecLayer(short stg,short sex,short l) { +if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && l >= 0) + fecLayer[stg][sex] = l; +} + +short Species::getFecLayer(short stg,short sex) { +if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return fecLayer[stg][sex]; +else return -9; +} + +void Species::setDevLayer(short stg,short sex,short l) { +if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && l >= 0) + devLayer[stg][sex] = l; +} + +short Species::getDevLayer(short stg,short sex) { +if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return devLayer[stg][sex]; +else return -9; +} + +void Species::setSurvLayer(short stg,short sex,short l) { +if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && l >= 0) + survLayer[stg][sex] = l; +} + +short Species::getSurvLayer(short stg,short sex) { +if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return survLayer[stg][sex]; +else return -9; +} + +void Species::setMinAge(short stg, short sex, int age) { + // NB min age for stages 0 & 1 must always be zero + if (stg > 1 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes && age >= 0) + minAge[stg][sex] = age; +} + +short Species::getMinAge(short stg, short sex) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) + return minAge[stg][sex]; + else return 0; +} + +void Species::setDensDep(float d, float s) { + if (d > 0.0) devCoeff = d; + if (s > 0.0) survCoeff = s; +} + +densDepParams Species::getDensDep(void) { + densDepParams d; + d.devCoeff = devCoeff; d.survCoeff = survCoeff; + return d; +} + +void Species::createDDwtFec(short mSize) { + if (mSize >= 0 && mSize < (gMaxNbStages * gMaxNbSexes)) { + if (ddwtFec != 0) deleteDDwtFec(); + ddwtFecDim = mSize; + ddwtFec = new float* [mSize]; + for (int i = 0; i < mSize; i++) { + ddwtFec[i] = new float[mSize]; + for (int j = 0; j < mSize; j++) ddwtFec[i][j] = 1.0; + } + } +} + +void Species::setDDwtFec(short row, short col, float f) { + if (row >= 0 && row < ddwtFecDim && col >= 0 && col < ddwtFecDim) + ddwtFec[row][col] = f; +} + +float Species::getDDwtFec(short row, short col) { + if (row >= 0 && row < ddwtFecDim && col >= 0 && col < ddwtFecDim) + return ddwtFec[row][col]; + else return 0.0; +} + +void Species::deleteDDwtFec(void) { + if (ddwtFec != 0) { + for (int i = 0; i < ddwtFecDim; i++) if (ddwtFec[i] != 0) { + delete[] ddwtFec[i]; + } + delete[] ddwtFec; ddwtFec = 0; + } +} + +void Species::createDDwtDev(short mSize) { + if (mSize >= 0 && mSize < (gMaxNbStages * gMaxNbSexes)) { + if (ddwtDev != 0) deleteDDwtDev(); + ddwtDevDim = mSize; + ddwtDev = new float* [mSize]; + for (int i = 0; i < mSize; i++) { + ddwtDev[i] = new float[mSize]; + for (int j = 0; j < mSize; j++) ddwtDev[i][j] = 1.0; + } + } +} + +void Species::setDDwtDev(short row, short col, float f) { + if (row >= 0 && row < ddwtDevDim && col >= 0 && col < ddwtDevDim) + ddwtDev[row][col] = f; +} + +float Species::getDDwtDev(short row, short col) { + if (row >= 0 && row < ddwtDevDim && col >= 0 && col < ddwtDevDim) + return ddwtDev[row][col]; + else return 0.0; +} + +void Species::deleteDDwtDev(void) { + if (ddwtDev != 0) { + for (int i = 0; i < ddwtDevDim; i++) if (ddwtDev[i] != 0) { + delete[] ddwtDev[i]; + } + delete[] ddwtDev; ddwtDev = 0; + } +} + +void Species::createDDwtSurv(short mSize) { + if (mSize >= 0 && mSize < (gMaxNbStages * gMaxNbSexes)) { + if (ddwtSurv != 0) deleteDDwtSurv(); + ddwtSurvDim = mSize; + ddwtSurv = new float* [mSize]; + for (int i = 0; i < mSize; i++) { + ddwtSurv[i] = new float[mSize]; + for (int j = 0; j < mSize; j++) ddwtSurv[i][j] = 1.0; + } + } +} + +void Species::setDDwtSurv(short row, short col, float f) { + if (row >= 0 && row < ddwtSurvDim && col >= 0 && col < ddwtSurvDim) + ddwtSurv[row][col] = f; +} + +float Species::getDDwtSurv(short row, short col) { + if (row >= 0 && row < ddwtSurvDim && col >= 0 && col < ddwtSurvDim) + return ddwtSurv[row][col]; + else return 0.0; +} + +void Species::deleteDDwtSurv(void) { + if (ddwtSurv != 0) { + for (int i = 0; i < ddwtSurvDim; i++) if (ddwtSurv[i] != 0) { + delete[] ddwtSurv[i]; + } + delete[] ddwtSurv; ddwtSurv = 0; + } +} +//void Species::setMinMax(float min,float max) { +void Species::setMinMax(float min, float max) { + if (min >= 0.0 && max > min) { + minRK = min; maxRK = max; + } +} +float Species::getMinMax(short opt) { + if (opt == 0) return minRK; + else return maxRK; +} + +//--------------------------------------------------------------------------- + +bool Species::areMutationsOn(void) { + return mutationsOn; +} + +void Species::resetGeneticParameters() { + mutationsOn = true; + nbGeneticFitnessTraits = 0; + genomeSize = -9999; + recombinationRate = -9999; + nPatchesToSample = 0; + nIndsToSample = ""; + chromosomeEnds.clear(); + samplePatchList.clear(); +} + +bool Species::isDiploid() const { + return diploid; +} + +int Species::incrNbGenLoadTraits() +{ + nbGeneticFitnessTraits++; + return nbGeneticFitnessTraits; +} + +int Species::getNbGenLoadTraits() const +{ + return nbGeneticFitnessTraits; +} + +void Species::addTrait(TraitType traitType, const SpeciesTrait& trait) { + + TraitType traitT = traitType; + // hack to deal with multiple genetic load traits, could be handled better + if (traitType == GENETIC_LOAD) { + int n = incrNbGenLoadTraits(); + + switch (n) { + case 1: + { + traitT = GENETIC_LOAD1; + break; + } + case 2: + { + traitT = GENETIC_LOAD2; + break; + } + case 3: + { + traitT = GENETIC_LOAD3; + break; + } + case 4: + { + traitT = GENETIC_LOAD4; + break; + } + case 5: + { + traitT = GENETIC_LOAD5; + break; + } + default: + { + cout << endl << ("Too many genetic load traits in Traits file, max = 5 \n"); + break; + } + } + } + spTraitTable.emplace(traitT, make_unique(trait)); +} + +SpeciesTrait* Species::getSpTrait(TraitType trait) const { + return spTraitTable.find(trait)->second.get(); +} + +void Species::clearTraitTable() { + spTraitTable.clear(); +} + +set Species::getTraitTypes() { + auto kv = std::ranges::views::keys(spTraitTable); + set keys{ kv.begin(), kv.end() }; + return keys; +} + +int Species::getNTraits() const { + return static_cast(spTraitTable.size()); +} + +int Species::getNPositionsForTrait(const TraitType trait) const { + return this->getSpTrait(trait)->getPositionsSize(); +} + +int Species::getGenomeSize() const { + return genomeSize; +} + +float Species::getRecombinationRate() const { + return recombinationRate; +} + +set Species::getChromosomeEnds() const { + return chromosomeEnds; +} + +//--------------------------------------------------------------------------- + +// Emigration functions +void Species::setEmigRules(const emigRules e) { + densDepEmig = e.densDep; + stgDepEmig = e.stgDep; + sexDepEmig = e.sexDep; + indVarEmig = e.indVar; + emigStage = e.emigStage; +} + +emigRules Species::getEmigRules(void) { + emigRules e; + e.densDep = densDepEmig; + e.stgDep = stgDepEmig; + e.sexDep = sexDepEmig; + e.indVar = indVarEmig; + e.emigStage = emigStage; + return e; +} + +void Species::setSpEmigTraits(const short stg, const short sex, const emigTraits e) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + if (e.d0 >= 0.0 && e.d0 <= 1.0) d0[stg][sex] = e.d0; + alphaEmig[stg][sex] = e.alpha; + betaEmig[stg][sex] = e.beta; + } +} + +emigTraits Species::getSpEmigTraits(short stg, short sex) { + emigTraits e; + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + e.d0 = d0[stg][sex]; + e.alpha = alphaEmig[stg][sex]; + e.beta = betaEmig[stg][sex]; + } + else { + e.d0 = e.alpha = e.beta = 0.0; + } + return e; +} + +float Species::getSpEmigD0(short stg, short sex) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + return d0[stg][sex]; + } + else { + return 0.0; + } +} + +//--------------------------------------------------------------------------- + +// Transfer functions + +void Species::setTrfrRules(const transferRules t) { + usesMovtProcess = t.usesMovtProc; + stgDepTrfr = t.stgDep; + sexDepTrfr = t.sexDep; + distMort = t.distMort; + indVarTrfr = t.indVar; + twinKern = t.twinKern; + habMort = t.habMort; + moveType = t.moveType; + costMap = t.costMap; +} + +transferRules Species::getTransferRules(void) { + transferRules t; + t.usesMovtProc = usesMovtProcess; t.stgDep = stgDepTrfr; t.sexDep = sexDepTrfr; + t.distMort = distMort; t.indVar = indVarTrfr; + t.twinKern = twinKern; + t.habMort = habMort; + t.moveType = moveType; t.costMap = costMap; + return t; +} + +void Species::setFullKernel(bool k) { + fullKernel = k; +} + +bool Species::useFullKernel(void) { return fullKernel; } + +void Species::setSpKernTraits(const short stg, const short sex, + const trfrKernelParams k, const int resol) +{ + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + if (k.meanDist1 > 0.0 && k.meanDist1 >= (float)resol) meanDist1[stg][sex] = k.meanDist1; + if (k.meanDist2 >= (float)resol) meanDist2[stg][sex] = k.meanDist2; + if (k.probKern1 >= 0.0 && k.probKern1 <= 1.0) probKern1[stg][sex] = k.probKern1; + } +} + +trfrKernelParams Species::getSpKernTraits(short stg, short sex) { + trfrKernelParams k; + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + k.meanDist1 = meanDist1[stg][sex]; + k.meanDist2 = meanDist2[stg][sex]; + k.probKern1 = probKern1[stg][sex]; + } + else { + k.meanDist1 = 0.0; k.meanDist2 = 0.0; k.probKern1 = 1.0; + } + return k; +} + +void Species::setMortParams(const trfrMortParams m) { + if (m.fixedMort >= 0.0 && m.fixedMort <= 1.0) fixedMort = m.fixedMort; + mortAlpha = m.mortAlpha; + mortBeta = m.mortBeta; +} + +trfrMortParams Species::getMortParams(void) { + trfrMortParams m; + m.fixedMort = fixedMort; m.mortAlpha = mortAlpha; m.mortBeta = mortBeta; + return m; +} + +void Species::setSpMovtTraits(const trfrMovtParams m) { + if (m.pr >= 1) pr = m.pr; + if (m.prMethod >= 1 && m.prMethod <= 3) prMethod = m.prMethod; + if (m.memSize >= 1 && m.memSize <= 14) memSize = m.memSize; + if (m.goalType >= 0 && m.goalType <= 2) goalType = m.goalType; + if (m.dp >= 1.0) dp = m.dp; + if (m.gb >= 1.0) gb = m.gb; + if (m.alphaDB > 0.0) alphaDB = m.alphaDB; + if (m.betaDB > 0) betaDB = m.betaDB; + if (m.stepMort >= 0.0 && m.stepMort <= 1.0) stepMort = m.stepMort; + if (m.stepLength > 0.0) stepLength = m.stepLength; + if (m.rho > 0.0 && m.rho <= 1.0) rho = m.rho; + straightenPath = m.straightenPath; +} + +trfrMovtParams Species::getSpMovtTraits(void) { + trfrMovtParams m; + m.pr = pr; m.prMethod = prMethod; m.memSize = memSize; m.goalType = goalType; + m.dp = dp; m.gb = gb; m.alphaDB = alphaDB; m.betaDB = betaDB; + m.stepMort = stepMort; m.stepLength = stepLength; m.rho = rho; + return m; +} + +trfrCRWTraits Species::getSpCRWTraits(void) { + trfrCRWTraits m; + m.stepMort = stepMort; m.stepLength = stepLength; m.rho = rho; + m.straightenPath = straightenPath; + return m; +} + +trfrSMSTraits Species::getSpSMSTraits(void) { + trfrSMSTraits m; + m.pr = pr; m.prMethod = prMethod; m.memSize = memSize; m.goalType = goalType; + m.dp = dp; m.gb = gb; m.alphaDB = alphaDB; m.betaDB = betaDB; m.stepMort = stepMort; + m.straightenPath = straightenPath; + return m; +} + +short Species::getMovtHabDim() { return habDimTrfr; } + +void Species::createHabCostMort(short nhab) { + if (nhab >= 0) { + habDimTrfr = nhab; + if (habCost != 0 || habStepMort != 0) deleteHabCostMort(); + habCost = new int[nhab]; + habStepMort = new double[nhab]; + for (int i = 0; i < nhab; i++) { + habCost[i] = 1; habStepMort[i] = 0.0; + } + } +} + +void Species::setHabCost(short hab, int cost) { + if (hab >= 0 && hab < habDimTrfr) { + if (cost >= 1) habCost[hab] = cost; + } +} + +void Species::setHabMort(short hab, double mort) { + if (hab >= 0 && hab < habDimTrfr) { + if (mort >= 0.0 && mort < 1.0) habStepMort[hab] = mort; + } +} + +int Species::getHabCost(short hab) { + int cost = 0; + if (hab >= 0 && hab < habDimTrfr) cost = habCost[hab]; + return cost; +} + +double Species::getHabMort(short hab) { + double pmort = 0.0; + if (hab >= 0 && hab < habDimTrfr) pmort = habStepMort[hab]; + return pmort; +} + +void Species::deleteHabCostMort(void) { + if (habCost != 0) { + delete[] habCost; habCost = 0; + } + if (habStepMort != 0) { + delete[] habStepMort; habStepMort = 0; + } +} + +//--------------------------------------------------------------------------- + +// Settlement functions + +void Species::setSettle(const settleType s) { + stgDepSett = s.stgDep; sexDepSett = s.sexDep; indVarSett = s.indVar; +} + +settleType Species::getSettle(void) { + settleType s; + s.stgDep = stgDepSett; s.sexDep = sexDepSett; s.indVar = indVarSett; + return s; +} + +void Species::setSettRules(const short stg, const short sex, const settleRules s) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + densDepSett[stg][sex] = s.densDep; wait[stg][sex] = s.wait; + go2nbrLocn[stg][sex] = s.go2nbrLocn; findMate[stg][sex] = s.findMate; + } +} + +settleRules Species::getSettRules(short stg, short sex) { + settleRules s; + s.densDep = false; + s.findMate = false; + s.go2nbrLocn = false; + s.wait = false; + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + s.densDep = densDepSett[stg][sex]; s.wait = wait[stg][sex]; + s.go2nbrLocn = go2nbrLocn[stg][sex]; s.findMate = findMate[stg][sex]; + } + return s; +} + +void Species::setSteps(const short stg, const short sex, const settleSteps s) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + if (s.maxStepsYr >= 1) maxStepsYr[stg][sex] = s.maxStepsYr; + else maxStepsYr[stg][sex] = 99999999; + if (s.minSteps >= 0) minSteps[stg][sex] = s.minSteps; + else minSteps[stg][sex] = 0; + if (s.maxSteps >= 1) maxSteps[stg][sex] = s.maxSteps; + else maxSteps[stg][sex] = 99999999; + } +} + +settleSteps Species::getSteps(short stg, short sex) { + settleSteps s; + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + s.maxStepsYr = maxStepsYr[stg][sex]; + s.minSteps = minSteps[stg][sex]; + s.maxSteps = maxSteps[stg][sex]; + } + else { + s.maxStepsYr = 99999999; + s.minSteps = 0; + s.maxSteps = 99999999; + } + return s; +} + +void Species::setSpSettTraits(const short stg, const short sex, const settleTraits dd) { + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + if (dd.s0 > 0.0 && dd.s0 <= 1.0) s0[stg][sex] = dd.s0; + alphaS[stg][sex] = dd.alpha; betaS[stg][sex] = dd.beta; + } +} + +settleTraits Species::getSpSettTraits(short stg, short sex) { + settleTraits dd; + if (stg >= 0 && stg < gMaxNbStages && sex >= 0 && sex < gMaxNbSexes) { + dd.s0 = s0[stg][sex]; dd.alpha = alphaS[stg][sex]; dd.beta = betaS[stg][sex]; + } + else { dd.s0 = 1.0; dd.alpha = dd.beta = 0.0; } + return dd; +} + +void Species::setGeneticParameters(const std::set& chromosomeEnds, const int genomeSize, const float recombinationRate, + const std::set& samplePatchList, const string nIndsToSample, const std::set& stagesToSampleFrom, int nPatchesToSampleFrom) +{ + this->genomeSize = genomeSize; + this->chromosomeEnds = chromosomeEnds; + this->recombinationRate = recombinationRate; + this->samplePatchList = samplePatchList; + this->nPatchesToSample = nPatchesToSampleFrom; + this->nIndsToSample = nIndsToSample; + this->stagesToSampleFrom = stagesToSampleFrom; +} + +// only called for cell based landscape +void Species::setSamplePatchList(const set& samplePatchList) { + this->samplePatchList = samplePatchList; +} + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + +#ifdef UNIT_TESTS +// For testing purposes only + +Species* createDefaultSpecies() { + short repType = 0; + short repSeasons = 1; + bool stagestruct = false; + int nStages = 2; + bool usesMovtProc = false; + short movtType = 1; + Species* pSpecies = new Species(repType, repSeasons, stagestruct, nStages, usesMovtProc, movtType); + return pSpecies; +} + +// Set kernel parameters, but ignore constraints on values +// Used to test dispersal with values < resolution +void Species::overrideKernels(const short stg, const short sex, + const trfrKernelParams k) +{ + meanDist1[stg][sex] = k.meanDist1; + meanDist2[stg][sex] = k.meanDist2; + probKern1[stg][sex] = k.probKern1; +} + +demogrParams createDefaultHaploidDemogrParams() { + demogrParams d; + d.repType = 0; + d.repSeasons = 1; + d.stageStruct = false; + d.propMales = 0.0; + d.harem = 1.0; + d.bc = 1.0; + d.lambda = 2.0; + return d; +} + +demogrParams createDefaultDiploidDemogrParams() { + demogrParams d; + d.repType = 1; + d.repSeasons = 1; + d.stageStruct = false; + d.propMales = 0.5; + d.harem = 1.0; + d.bc = 1.0; + d.lambda = 2.0; + return d; +} + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/Species.h b/RangeShiftR/src/RScore/Species.h new file mode 100644 index 0000000..eebd544 --- /dev/null +++ b/RangeShiftR/src/RScore/Species.h @@ -0,0 +1,688 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + + /*------------------------------------------------------------------------------ + + RangeShifter v2.0 Species + + Implements the Species class + + There is ONE instance of a Species for each species within the Community + AND THIS IS CURRENTLY LIMITED TO A SINGLE SPECIES. + The class holds all the demographic and dispersal parameters of the species. + + For full details of RangeShifter, please see: + Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. + and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial + eco-evolutionary dynamics and species’ responses to environmental changes. + Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + + Authors: Greta Bocedi & Steve Palmer, University of Aberdeen + + Last updated: 28 July 2021 by Greta Bocedi + + ------------------------------------------------------------------------------*/ + +#ifndef SpeciesH +#define SpeciesH + +#include +#include +#include +#include + +#include "Parameters.h" +#include "SpeciesTrait.h" +#include "QuantitativeTrait.h" + +class SpeciesTrait; + + // structures for demographic parameters + +struct demogrParams { + short repType; + short repSeasons; + float propMales; + float harem; + float bc; + float lambda; + bool stageStruct; +}; +struct stageParams { + short nStages; + short repInterval; + short maxAge; + short survival; + float probRep; + bool fecDens; + bool fecStageDens; + bool devDens; + bool devStageDens; + bool survDens; + bool survStageDens; + bool disperseOnLoss; +}; +struct densDepParams { + float devCoeff; + float survCoeff; +}; + +// structures for emigration parameters + +struct emigRules { + bool densDep; + bool stgDep; + bool sexDep; + bool indVar; + short emigStage; + short emigTrait[2]; +}; +struct emigTraits { + float d0; + float alpha; + float beta; + + emigTraits() : d0(0.0), alpha(0.0), beta(0.0) {}; + + emigTraits(const emigTraits& e) : d0(e.d0), alpha(e.alpha), beta(e.beta) {}; + + emigTraits* clone() { return new emigTraits(*this); } + + void divideTraitsBy(int i) { + + d0 /= i; + alpha /= i; + beta /= i; + } +}; + +// structures for transfer parameters + +struct transferRules { + bool usesMovtProc; + bool stgDep; + bool sexDep; + bool distMort; + bool indVar; + bool twinKern; + bool habMort; + short moveType; + bool costMap; + short movtTrait[2]; +}; +struct trfrKernelParams { + float meanDist1; + float meanDist2; + float probKern1; +}; +struct trfrMortParams { + float fixedMort; + float mortAlpha; + float mortBeta; +}; +struct trfrMovtParams { + short pr; + short prMethod; + short memSize; + short goalType; + float dp; + float gb; + float alphaDB; + int betaDB; + float stepMort; + float stepLength; + float rho; + bool straightenPath; +}; +struct trfrCRWTraits { + float stepMort; + float stepLength; + float rho; + bool straightenPath; +}; +struct trfrSMSTraits { + short pr; + short prMethod; + short memSize; + short goalType; + float dp; + float gb; + float alphaDB; + int betaDB; + float stepMort; + bool straightenPath; +}; + +// structures for settlement parameters + +struct settleType { + bool stgDep; + bool sexDep; + bool indVar; + short settTrait[2]; +}; +struct settleRules { + bool densDep; + bool wait; + bool go2nbrLocn; + bool findMate; +}; +struct settleSteps { + int minSteps; + int maxSteps; + int maxStepsYr; +}; +struct settleTraits { + float s0; + float alpha; + float beta; + + settleTraits() : s0(0.0), alpha(0.0), beta(0.0) {}; + + settleTraits(const settleTraits& e) : s0(e.s0), alpha(e.alpha), beta(e.beta) {}; + + void divideTraitsBy(int i) { + s0 /= i; + alpha /= i; + beta /= i; + } +}; + + +//--------------------------------------------------------------------------- + +class Species { + +public: + Species( + const short& repro = 0, + const short& nbRepSeasons = 1, + const bool& hasStgStruct = false, + const short& nStg = 2, + const bool& usesMovtProc = false, + const short& movementType = 1 + ); + ~Species(void); + short getSpNum(void); + + // demographic parameter functions + + void createHabK( // Create habitat carrying capacity table + short // no. of habitats + ); + void setHabK( + short, // habitat index no. (NB may differ from habitat no. supplied by user) + float // carrying capacity (inds/cell) + ); + float getHabK( + short // habitat index no. (NB may differ from habitat no. supplied by user) + ); + float getMaxK(void); // return highest carrying capacity over all habitats + void deleteHabK(void); // Delete habitat carrying capacity table + void setStage( // Set stage structure parameters + const stageParams // structure holding stage structure parameters + ); + stageParams getStageParams(void); // Get stage structure parameters + void setDemogr( // Set general demographic parameters + const demogrParams // structure holding general demographic parameters + ); + demogrParams getDemogrParams(void); // Get general demographic parameters + short getRepType(void); + bool stageStructured(void); + void setDensDep( // Set demographic density dependence coefficients + float, // development coefficient + float // survival coefficient + ); + densDepParams getDensDep(void); // Get development and survival coefficients + + void setFec( // Set fecundity + short, // stage (must be > 0) + short, // sex + float // fecundity + ); + float getFec( // Get fecundity + short, // stage + short // sex + ); + void setDev( // Set development probability + short, // stage + short, // sex + float // development probability + ); + float getDev( // Get development probability + short, // stage + short // sex + ); + void setSurv( // Set survival probability + short, // stage + short, // sex + float // survival probability + ); + float getSurv( // Get survival probability + short, // stage + short // sex + ); + + void setFecSpatial(bool); + bool getFecSpatial(void){return fecSpatial;}; + void setDevSpatial(bool); + bool getDevSpatial(void){return devSpatial;}; + void setSurvSpatial(bool); + bool getSurvSpatial(void){return survSpatial;}; + void setFecLayer( // set the layer of the spatial demographic scaling used for fecundity + short, // stage + short, // sex + short // layer + ); + + short getFecLayer( // get the layer of the spatial demographic scaling used for fecundity + short, // stage + short // sex + ); + + void setDevLayer( // set the layer of the spatial demographic scaling used for development + short, // stage + short, // sex + short // layer + ); + + short getDevLayer( // get the layer of the spatial demographic scaling used for development + short, // stage + short // sex + ); + + void setSurvLayer( // set the layer of the spatial demographic scaling used for survival + short, // stage + short, // sex + short // layer + ); + + short getSurvLayer( // get the layer of the spatial demographic scaling used for survival + short, // stage + short // sex + ); + + float getMaxFec(void); // Get highest fecundity of any stage + void setMinAge( // Set minimum age + short, // stage + short, // sex + int // minimum age (years) (must be zero for stages 0 and 1) + ); + short getMinAge( // Get minimum age + short, // stage + short // sex + ); + void createDDwtFec( // Create fecundity weights matrix + short // matrix dimension - no. of stages * no. of sexes + ); + void setDDwtFec( // Set fecundity weights matrix element + short, // row + short, // column + float // weight + ); + float getDDwtFec( // Get fecundity weights matrix element + short, // row + short // column + ); + void deleteDDwtFec(void); // Delete fecundity weights matrix + void createDDwtDev( // Create development weights matrix + short // matrix dimension - no. of stages * no. of sexes + ); + void setDDwtDev( // Set development weights matrix element + short, // row + short, // column + float // weight + ); + float getDDwtDev( // Get development weights matrix element + short, // row + short // column + ); + void deleteDDwtDev(void); // Delete development weights matrix + void createDDwtSurv( // Create survival weights matrix + short // matrix dimension - no. of stages * no. of sexes + ); + void setDDwtSurv( // Set survival weights matrix element + short, // row + short, // column + float // weight + ); + float getDDwtSurv( // Get survival weights matrix element + short, // row + short // column + ); + void deleteDDwtSurv(void); // Delete survival weights matrix + // Functions to handle min/max R or K (under environmental stochasticity) + void setMinMax( // Set min and max values + float, // min + float // max + ); + float getMinMax( // Get min/max value + short // option: 0 = return minimum, otherwise = return maximum + ); + + std::set& getSamplePatches() { + return samplePatchList; + }; + + string getNIndsToSample() { + return nIndsToSample; + }; + + std::set& getStagesToSample() { + return stagesToSampleFrom; + } + + int getNbPatchesToSample() { + return nPatchesToSample; + } + + // Genetic functions + void resetGeneticParameters(); + bool areMutationsOn(void); + bool isDiploid() const; + int incrNbGenLoadTraits(); + int getNbGenLoadTraits() const; + + // emigration parameter functions + + void setEmigRules( // Set emigration rules + const emigRules // structure holding emigration rules + ); + emigRules getEmigRules(void); // Get emigration rules + void setSpEmigTraits( // Set emigration trait parameters + const short, // stage + const short, // sex + const emigTraits // structure holding emigration trait parameters + ); + emigTraits getSpEmigTraits( // Get emigration trait parameters + short, // stage + short // sex + ); + float getSpEmigD0( // Get (maximum) emigration probability + short, // stage + short // sex + ); + + // transfer parameter functions + + void setTrfrRules( // Set transfer rules + const transferRules // structure holding transfer rules + ); + transferRules getTransferRules(void); // Get transfer rules + void setFullKernel( // Set fullKernel condition + bool // fullKernel value + ); + bool useFullKernel(void); + void setSpKernTraits( // Set transfer by kernel parameters + const short, // stage + const short, // sex + const trfrKernelParams, // structure holding transfer by kernel parameters + const int // Landscape resolution + ); + +#ifdef UNIT_TESTS + // Testing: set dispersal but ignore resolution + void overrideKernels(const short stg, const short sex, + const trfrKernelParams k); +# endif // UNIT_TESTS + + trfrKernelParams getSpKernTraits( // Get transfer by kernel parameters + short, // stage + short // sex + ); + void setMortParams( // Set transfer mortality parameters + const trfrMortParams // structure holding transfer mortality parameters + ); + trfrMortParams getMortParams(void); // Get transfer mortality parameters + void setSpMovtTraits( // Set transfer movement model parameters + const trfrMovtParams // structure holding transfer movement model parameters + ); + trfrMovtParams getSpMovtTraits(void); // Get transfer movement model traits + trfrCRWTraits getSpCRWTraits(void); // Get CRW traits + trfrSMSTraits getSpSMSTraits(void); // Get SMS traits + // Return dimension of habitat-dependent step mortality and costs matrices + short getMovtHabDim(void); + void createHabCostMort( // Create habitat-dependent costs and mortality matrices + short // no. of habitats + ); + void setHabCost( // Set habitat-dependent cost + short, // habitat index no. + int // cost value + ); + void setHabMort( // Set habitat-dependent per-step mortality + short, // habitat index no. + double // mortality rate + ); + int getHabCost( // Get habitat-dependent cost + short // habitat index no. + ); + double getHabMort( // Get habitat-dependent per-step mortality + short // habitat index no. + ); + void deleteHabCostMort(void); // Delete habitat-dependent costs and mortality matrices + + // settlement parameter functions + + void setSettle( // Set settlement type + const settleType // structure holding settlement type (stage- and/or sex-dependent) + ); + settleType getSettle(void); // Get settlement type + void setSettRules( // Set settlement rules + const short, // stage + const short, // sex + const settleRules // structure holding settlement rules + ); + settleRules getSettRules( // Get settlement rules + short, // stage + short // sex + ); + void setSteps( // Set path step limit parameters + const short, // stage + const short, // sex + const settleSteps // structure holding path step limit parameters + ); + settleSteps getSteps( // Set path step limit parameters + short, // stage + short // sex + ); + void setSpSettTraits( // Set settlement density dependence traits + const short, // stage + const short, // sex + const settleTraits // structure holding density dependence traits + ); + settleTraits getSpSettTraits( // Get settlement density dependence traits + short, // stage + short // sex + ); + + void addTrait(TraitType traitType, const SpeciesTrait& trait); + + void clearTraitTable(); + + SpeciesTrait* getSpTrait(TraitType trait) const; + + std::set getTraitTypes(); + + int getNTraits() const; + int getNPositionsForTrait(const TraitType trait) const; + int getGenomeSize() const; + float getRecombinationRate() const; + std::set getChromosomeEnds() const; + void setGeneticParameters(const std::set& chromosomeEnds, const int genomeSize, const float recombinationRate, + const std::set& samplePatchList, const string nIndsToSample, const std::set& stagesToSampleFrom, int nPatchesToSampleFrom); + void setSamplePatchList(const std::set& samplePatchList); + +private: + + // NOTE: SEQUENCE OF PARAMETER VARIABLES MAY NEED TO BE ALTERED FOR EFFICIENTCY ... + // ... but that is of low importance, as there will only be one (or a few) instance(s) + + // demographic parameters + + short repType; // 0 = asexual, 1 = simple two sex, 2 = complex two sex + short nStages; // no. of stages (incl. juveniles) in structured population + float propMales; // proportion of males at birth in sexual model + float harem; // max harem size in complex sexual model + float bc; // competition coefficient for non-structured population + float lambda; // max intrinsic growth rate for non-structured population + float probRep; // probability of reproducing in subsequent seasons + short repSeasons; // no. of reproductive seasons per year + short repInterval; // no. of reproductive seasons between subsequent reproductions + short maxAge; // max age in structured population + short survival; // survival timing: 0 = at reprodn, 1 = between reprodns, 2 = anually + bool stageStruct; + bool fecDens; + bool fecStageDens; + bool devDens; + bool devStageDens; + bool survDens; + bool survStageDens; + bool disperseOnLoss; // individuals disperse on complete loss of patch + // (otherwise they die) + bool fecSpatial, devSpatial, survSpatial; + short habDimK; // dimension of carrying capacities matrix + float* habK; // habitat-specific carrying capacities (inds/cell) + float devCoeff; // density-dependent development coefficient + float survCoeff; // density-dependent survival coefficient + float** ddwtFec; // density-dependent weights matrix for fecundity + float** ddwtDev; // density-dependent weights matrix for development + float** ddwtSurv; // density-dependent weights matrix for survival + // NB for the following arrays, sex 0 is females, sex 1 is males + float fec[gMaxNbStages][gMaxNbSexes]; // fecundities + float dev[gMaxNbStages][gMaxNbSexes]; // development probabilities + float surv[gMaxNbStages][gMaxNbSexes]; // survival probabilities + short minAge[gMaxNbStages][gMaxNbSexes]; // minimum age to enter stage + int fecLayer[gMaxNbStages][gMaxNbSexes]; // layer for spatial varying fecundity + int devLayer[gMaxNbStages][gMaxNbSexes]; // layer for spatial varying development + int survLayer[gMaxNbStages][gMaxNbSexes]; // layer for spatial varying survival + // NOTE - IN THEORY, NEXT 3 VARIABLES COULD BE COMMON, BUT WE WOULD NEED TO ENSURE THAT + // ALL MATRICES ARE DELETED IF THERE IS A CHANGE IN NO. OF STAGES OR REPRODUCTION TYPE + // ***** TO BE RECONSIDERED LATER ***** + short ddwtFecDim; // dimension of density-dependent weights matrix for fecundity + short ddwtDevDim; // dimension of density-dependent weights matrix for fecundity + short ddwtSurvDim; // dimension of density-dependent weights matrix for fecundity + float minRK; // minimum ) growth rate OR carrying capacity + float maxRK; // maximum ) (under environmental stochasticity) + + // genome parameters + + /**The traits table.*/ + std::map> spTraitTable; + std::set chromosomeEnds; + int genomeSize; + bool diploid; + bool mutationsOn; + int nbGeneticFitnessTraits; + float recombinationRate; + std::set samplePatchList; + int nPatchesToSample; //for cell based landscape + std::set stagesToSampleFrom; + string nIndsToSample; //could be integer or 'all', all means in in selected patches not necessarily all in population + + // emigration parameters + + bool densDepEmig; // density-dependent emigration + bool stgDepEmig; // stage-dependent emigration + bool sexDepEmig; // sex-dependent emigration + bool indVarEmig; // individual variation in emigration + short emigStage; // stage which emigrates (used for stage-strucutred population + // having individual variability in emigration probability) +// NB for the following arrays, sex 0 is females, sex 1 is males + float d0[gMaxNbStages][gMaxNbSexes]; // maximum emigration probability + float alphaEmig[gMaxNbStages][gMaxNbSexes]; // slope of density-dependent reaction norm + float betaEmig[gMaxNbStages][gMaxNbSexes]; // inflection point of reaction norm (in terms of N/K) + // NB Initialisation parameters are made double to avoid conversion errors (reason unclear) + // on traits maps using FloatToStr() + + // transfer parameters + + bool usesMovtProcess; + bool stgDepTrfr; + bool sexDepTrfr; + bool distMort; + bool indVarTrfr; + bool twinKern; + bool habMort; // habitat-dependent mortality + float meanDist1[gMaxNbStages][gMaxNbSexes]; // mean of 1st dispersal kernel (m) + float meanDist2[gMaxNbStages][gMaxNbSexes]; // mean of 2nd dispersal kernel (m) + float probKern1[gMaxNbStages][gMaxNbSexes]; // probability of dispersing with the 1st kernel + // NB INITIAL limits are made double to avoid conversion errors (reason unclear) + // on traits maps using FloatToStr() + // As evolving traits are are not stage-dependent, no. of rows can be 1 + float fixedMort; // constant mortality probability + float mortAlpha; // slope for mortality distance dependence function + float mortBeta; // inflection point for mortality distance dependence function + short moveType; // 1 = SMS, 2 = CRW + short pr; // SMS perceptual range (cells) + short prMethod; // SMS perceptual range evaluation method: + // 1 = arith. mean, 2 = harmonic mean, 3 = inverse weighted arith. mean + short memSize; // SMS memory size (1-14 steps) + short goalType; // SMS goal bias type: 0 = none, 1 = towards goal, 2 = dispersal bias + float dp; // SMS directional persistence + float gb; // SMS goal bias + float alphaDB; // SMS dispersal bias decay rate + int betaDB; // SMS dispersal bias decay inflection point (no. of steps) + float stepMort; // constant per-step mortality probability for movement models + double* habStepMort; // habitat-dependent per-step mortality probability + float stepLength; // CRW step length (m) + float rho; // CRW correlation coefficient + short habDimTrfr; // dimension of habitat-dependent step mortality and costs matrices + int* habCost; // habitat costs + bool costMap; // import cost map from file? + bool straightenPath; // straighten path after decision not to settle + bool fullKernel; // used to indicate special case when density-independent emigration + // is 1.0, and kernel-based movement within the natal cell is used + // to determine philopatry + +// settlement parameters + + bool stgDepSett; + bool sexDepSett; + bool indVarSett; // individual variation in settlement + bool densDepSett[gMaxNbStages][gMaxNbSexes]; + bool wait[gMaxNbStages][gMaxNbSexes]; // wait to continue moving next season (stage-structured model only) + bool go2nbrLocn[gMaxNbStages][gMaxNbSexes]; // settle in neighbouring cell/patch if available (ditto) + bool findMate[gMaxNbStages][gMaxNbSexes]; + int minSteps[gMaxNbStages][gMaxNbSexes]; // minimum no. of steps + int maxSteps[gMaxNbStages][gMaxNbSexes]; // maximum total no. of steps + int maxStepsYr[gMaxNbStages][gMaxNbSexes]; // maximum no. of steps in any one dispersal period + float s0[gMaxNbStages][gMaxNbSexes]; // maximum settlement probability + float alphaS[gMaxNbStages][gMaxNbSexes]; // slope of the settlement reaction norm to density + float betaS[gMaxNbStages][gMaxNbSexes]; // inflection point of the settlement reaction norm to density + + // other attributes + int spNum; + +}; + + +//--------------------------------------------------------------------------- + +#ifdef UNIT_TESTS +// For testing purposes only +Species* createDefaultSpecies(); +demogrParams createDefaultHaploidDemogrParams(); +demogrParams createDefaultDiploidDemogrParams(); +#endif // UNIT_TESTS + +//--------------------------------------------------------------------------- +#endif diff --git a/RangeShiftR/src/RScore/SpeciesTrait.cpp b/RangeShiftR/src/RScore/SpeciesTrait.cpp new file mode 100644 index 0000000..418c222 --- /dev/null +++ b/RangeShiftR/src/RScore/SpeciesTrait.cpp @@ -0,0 +1,299 @@ + +#include "SpeciesTrait.h" + +// Species trait constructor +SpeciesTrait::SpeciesTrait( + const TraitType& trType, + const sex_t& sx, + const set& pos, + const ExpressionType& expr, + const set& initialPositions, + const DistributionType& initDist, + const map initParams, + const DistributionType& initDomDist, + const map initDomParams, + bool isInherited, + const float& mutRate, + const DistributionType& mutationDist, + const map mutationParams, + const DistributionType& dominanceDist, + const map dominanceParams, + const int nPloidy, + const bool isOutput) : + traitType{ trType }, + sex{ sx }, + genePositions{ pos }, + expressionType{ expr }, + initPositions{ initialPositions }, + initialDistribution{ initDist }, + initialParameters{ initParams }, + initialDomDistribution{ initDomDist }, + initialDomParameters{ initDomParams }, + dominanceDistribution{ dominanceDist }, + dominanceParameters{ dominanceParams }, + inherited{ isInherited }, + mutationDistribution{ mutationDist }, + mutationParameters{ mutationParams }, + mutationRate{ mutRate }, + ploidy{ nPloidy }, + traitIsOutput{ isOutput } +{ + // Check distribution parameters + // Initial allele distribution + for (auto [paramType, paramVal] : initParams) { + switch (paramType) + { + case MIN: case MAX: case MEAN: + if (!isValidTraitVal(paramVal)) + throw logic_error("Invalid parameter value: initial parameter " + to_string(paramType) + " must have a valid value for trait " + to_string(traitType) + "."); + break; + case SD: + if (paramVal <= 0.0) + throw logic_error("Invalid parameter value: initial parameter " + to_string(paramType) + " must be strictly positive"); + break; + default: + break; + } + } + + // Initial dominance distribution + for (auto [paramType, paramVal] : initDomParams) { + switch (paramType) + { + case MIN: case MAX: case MEAN: + if (paramVal < 0.0) + throw logic_error("Invalid parameter value: initial dominance parameter " + to_string(paramType) + " must not be negative."); + break; + case SD: case SHAPE: case SCALE: + if (paramVal <= 0.0) + throw logic_error("Invalid parameter value: initial dominance parameter " + to_string(paramType) + " must be strictly positive"); + break; + default: + break; + } + } + + // Mutation distribution + for (auto [paramType, paramVal] : mutationParams) { + switch (paramType) + { + case MIN: case MAX: case MEAN: + if ( + (trType == NEUTRAL || trType == GENETIC_LOAD || trType == GENETIC_LOAD1 || + trType == GENETIC_LOAD2 || trType == GENETIC_LOAD3 || trType == GENETIC_LOAD4 || trType == GENETIC_LOAD5) + && !isValidTraitVal(paramVal) + // dispersal traits are cumulative so no value is invalid + ) + throw logic_error("Invalid parameter value: mutation parameter " + to_string(paramType) + " must have a valid value for trait " + to_string(traitType) + "."); + break; + case SD: case SHAPE: case SCALE: + if (paramVal <= 0.0) + throw logic_error("Invalid parameter value: mutation parameter " + to_string(paramType) + " must be strictly positive"); + break; + default: + break; + } + } + + // Dominance distribution + for (auto [paramType, paramVal] : dominanceParams) { + switch (paramType) + { + case MIN: case MAX: case MEAN: + if (paramVal < 0.0) + throw logic_error("Invalid parameter value: dominance parameter " + to_string(paramType) + " must not be negative."); + break; + case SD: case SHAPE: case SCALE: + if (paramVal <= 0.0) + throw logic_error("Invalid parameter value: dominance parameter " + to_string(paramType) + " must be strictly positive"); + break; + default: + break; + } + } +} + +bool SpeciesTrait::isValidTraitVal(const float& val) const { + switch (traitType) + { + // Neutral trait + case NEUTRAL: // only need to check for input parameters + { + return val >= 0.0 && val <= 255.0; + } + // Genetic Load + case GENETIC_LOAD: case GENETIC_LOAD1: case GENETIC_LOAD2: case GENETIC_LOAD3: case GENETIC_LOAD4: case GENETIC_LOAD5: + { + return val >= -1.0 // genetic fitness traits can be beneficial + && val <= 1.0; + break; + } + // Dispersal traits + /// Emigration + case E_D0_F: case E_D0_M: case E_D0: { + return val >= 0.0 && val <= 1.0; // is a probability + break; + } + case E_ALPHA_F: case E_ALPHA_M: case E_ALPHA: + case E_BETA_F: case E_BETA_M: case E_BETA: + { + return true; // slope and inflexion point can be any value + break; + } + /// Settlement + case S_S0_F: case S_S0_M: case S_S0: + { + return val >= 0.0 && val <= 1.0; + break; + } + case S_ALPHA_F: case S_ALPHA_M: case S_ALPHA: + case S_BETA_F: case S_BETA_M: case S_BETA: + { + return true; // slope and inflection point can be any value + break; + } + /// Transfer - Kernels + case KERNEL_MEANDIST_1_F: case KERNEL_MEANDIST_1_M: case KERNEL_MEANDIST_1: + case KERNEL_MEANDIST_2_F: case KERNEL_MEANDIST_2_M: case KERNEL_MEANDIST_2: + { + return val >= 0.0; // is a distance + break; + } + case KERNEL_PROBABILITY_F: case KERNEL_PROBABILITY_M: case KERNEL_PROBABILITY: + { + return val >= 0.0 && val <= 1.0; + break; + } + /// Transfer - Correlated random walk + case CRW_STEPLENGTH: + { + return val >= 0.0; + break; + } + case CRW_STEPCORRELATION: + { + return val >= 0.0 && val <= 1.0; + break; + } + /// Transfer - Stochastic Movement Simulator + case SMS_DP: + { + return val >= 1.0; // according to parameter doc + break; + } + case SMS_GB: + { + return val >= 1.0; // according to parameter doc + break; + } + case SMS_ALPHADB: + { + return val > 0.0; + break; + } + case SMS_BETADB: + { + return true; + break; + } + default: + throw logic_error("Invalid trait type " + to_string(traitType) + " passed to isValidTraitVal()."); + break; + } +} + +#ifdef UNIT_TESTS // Testing only + +// Create a default set of gene positions ranging from zero to genome size +set createTestGenePositions(const int genomeSz) { + set genePositions; + for (int i = 0; i < genomeSz; i++) genePositions.insert(i); + return genePositions; +} + +SpeciesTrait* createTestEmigSpTrait(const set& genePositions, const bool& isDiploid) { + // Create species trait + const map distParams{ + pair{GenParamType::MIN, 0.0}, + pair{GenParamType::MAX, 1.0} + }; + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::E_D0, + sex_t::NA, + genePositions, + ExpressionType::ADDITIVE, + genePositions, + DistributionType::UNIFORM, + distParams, + DistributionType::NONE, // no dominance + distParams, + true, // isInherited + 0.0, // mutation rate + DistributionType::UNIFORM, + distParams, + DistributionType::NONE, // no dominance + distParams, + isDiploid ? 2 : 1, + false + ); + return spTr; +} + +SpeciesTrait* createTestGenLoadTrait(const set& genePositions, const bool& isDiploid) { + // Create species trait + const map distParams{ + pair{GenParamType::MIN, 0.0}, + pair{GenParamType::MAX, 1.0} + }; + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::GENETIC_LOAD, + sex_t::NA, + genePositions, + ExpressionType::MULTIPLICATIVE, + genePositions, + DistributionType::NONE, + distParams, + DistributionType::NONE, // initialise dominance to zero + distParams, + true, // isInherited + 0.0, // mutation rate + DistributionType::UNIFORM, + distParams, + DistributionType::UNIFORM, + distParams, + isDiploid ? 2 : 1, + false + ); + return spTr; +} + +SpeciesTrait* createTestNeutralSpTrait(const float& maxAlleleVal, const set& genePositions, const bool& isDiploid) { + + const map distParams{ + // Set max allele value + pair{GenParamType::MAX, maxAlleleVal} + }; + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::NEUTRAL, + sex_t::NA, + genePositions, + ExpressionType::NOTEXPR, + genePositions, + // Sample initial values from uniform(0, max) + DistributionType::UNIFORM, distParams, + DistributionType::NONE, // No dominance + map{}, + true, // isInherited + 0.0, // mutation rate + // Mutation sampled from a uniform(0, max) + DistributionType::KAM, + distParams, + DistributionType::NONE, // No dominance + map{}, + isDiploid ? 2 : 1, + false + ); + return spTr; +} + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/SpeciesTrait.h b/RangeShiftR/src/RScore/SpeciesTrait.h new file mode 100644 index 0000000..69b1313 --- /dev/null +++ b/RangeShiftR/src/RScore/SpeciesTrait.h @@ -0,0 +1,106 @@ +#ifndef SPECIESTRAITH +#define SPECIESTRAITH + +#include "Parameters.h" +#include "Species.h" + +#include +#include +#include +#include + +class Species; // forward declaration to overcome circularity issue + +// Species-level traits +// Features of traits that are shared across all individuals in the same species +class SpeciesTrait { +public: + SpeciesTrait( + const TraitType& traitType, + const sex_t& sex, + const set& pos, + const ExpressionType& expr, + const set& initialPositions, + const DistributionType& initDist, + const map initParams, + const DistributionType& initDomDist, + const map initDomParams, + bool isInherited, + const float& mutationRate, + const DistributionType& mutationDist, + const map mutationParams, + const DistributionType& dominanceDist, + const map dominanceParams, + const int ploidy, + const bool isOutput + ); + + bool isValidTraitVal(const float& val) const; + TraitType getTraitType() const { return traitType; } + bool isOutput() const { return traitIsOutput; } + + // Getters + sex_t getSex() const { return sex; } + float getMutationRate() const { return mutationRate; } + short getPloidy() const { return ploidy; } + set& getGenePositions() { return genePositions; } // returning by reference, make sure receiver is const + set getInitPositions() const { return initPositions; } + int getPositionsSize() const { return static_cast(genePositions.size()); } + bool isInherited() const { return inherited; } + + DistributionType getInitialDistribution() const { return initialDistribution; }; + map getInitialParameters() const { return initialParameters; }; + DistributionType getInitDomDistribution() const { return initialDomDistribution; }; + map getInitDomParameters() const { return initialDomParameters; }; + DistributionType getMutationDistribution() const { return mutationDistribution; }; + map getMutationParameters() const { return mutationParameters; }; + DistributionType getDominanceDistribution() const { return dominanceDistribution; }; + map getDominanceParameters() const { return dominanceParameters; }; + + ExpressionType getExpressionType() const { return expressionType; }; + + int getNbNeutralAlleles() const { + if (!traitType == NEUTRAL) throw logic_error("getNbNeutralAlleles() should only be called for neutral traits."); + else { + int maxAlleleVal = max( + getMutationParameters().find(MAX)->second + 1, + getInitialParameters().find(MAX)->second + 1 + ); // possible values range from 0 to MAX + return maxAlleleVal; + } + } + +private: + + int ploidy; + float mutationRate; + TraitType traitType; + bool traitIsOutput; + sex_t sex; + + // Positions in the genome of all genes (loci) pertaining to this trait + // The genome itself is not modelled explicitly + set genePositions; + set initPositions; + + ExpressionType expressionType; + DistributionType initialDistribution; + map initialParameters; + DistributionType initialDomDistribution; + map initialDomParameters; + DistributionType dominanceDistribution; + map dominanceParameters; + bool inherited; + DistributionType mutationDistribution; + map mutationParameters; +}; + +#ifdef UNIT_TESTS // Testing only +// Create a default set of gene positions ranging from zero to genome size +set createTestGenePositions(const int genomeSz); +SpeciesTrait* createTestEmigSpTrait(const set& genePositions, const bool& isDiploid); +SpeciesTrait* createTestGenLoadTrait(const set& genePositions, const bool& isDiploid); +SpeciesTrait* createTestNeutralSpTrait(const float& maxAlleleVal, const set& genePositions, const bool& isDiploid); +#endif // UNIT_TESTS + +#endif // SPECIESTRAITH diff --git a/RangeShiftR/src/RScore/SubCommunity.cpp b/RangeShiftR/src/RScore/SubCommunity.cpp new file mode 100644 index 0000000..94b00c4 --- /dev/null +++ b/RangeShiftR/src/RScore/SubCommunity.cpp @@ -0,0 +1,1475 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + --------------------------------------------------------------------------*/ + + + //--------------------------------------------------------------------------- + +#include "SubCommunity.h" +//--------------------------------------------------------------------------- + +ofstream outtraits; + +//--------------------------------------------------------------------------- + +SubCommunity::SubCommunity(Patch* pPch, int num) { + subCommNum = num; + pPatch = pPch; + // record the new sub-community no. in the patch + pPatch->setSubComm(this); + initial = false; + occupancy = 0; +} + +SubCommunity::~SubCommunity() { + pPatch->setSubComm(nullptr); + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + delete popns[i]; + } + popns.clear(); + if (occupancy != 0) delete[] occupancy; +} + +int SubCommunity::getNum(void) { return subCommNum; } + +Patch* SubCommunity::getPatch(void) { return pPatch; } + +locn SubCommunity::getLocn(void) { + locn loc = pPatch->getCellLocn(0); + return loc; +} + +void SubCommunity::setInitial(bool b) { initial = b; } + +void SubCommunity::initialise(Landscape* pLandscape, Species* pSpecies) +{ + int ncells; + landParams ppLand = pLandscape->getLandParams(); + initParams init = paramsInit->getInit(); + + // determine size of initial population + int nInds = 0; + if (subCommNum == 0 // matrix patch + || !initial) // not in initial region or distribution + nInds = 0; + else { + float k = pPatch->getK(); + if (k > 0.0) { // patch is currently suitable for this species + switch (init.initDens) { + case 0: // at carrying capacity + nInds = (int)k; + break; + case 1: // at half carrying capacity + nInds = (int)(k / 2.0); + break; + case 2: // specified no. per cell or density + ncells = pPatch->getNCells(); + if (ppLand.patchModel) { + nInds = (int)(init.indsHa * (float)(ncells * ppLand.resol * ppLand.resol) / 10000.0); + } + else { + nInds = init.indsCell * ncells; + } + break; + } + } + else nInds = 0; + } + + // create new population only if it is non-zero or the matrix popn + if (subCommNum == 0 || nInds > 0) { + newPopn(pLandscape, pSpecies, pPatch, nInds); + } + +} + +// initialise a specified individual +void SubCommunity::initialInd(Landscape* pLandscape, Species* pSpecies, + Patch* pPatch, Cell* pCell, int ix) +{ + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); + settleType sett = pSpecies->getSettle(); + short stg, age, repInt; + Individual* pInd; + float probmale; + + // create new population if not already in existence + int npopns = (int)popns.size(); + if (npopns < 1) { + newPopn(pLandscape, pSpecies, pPatch, 0); + } + + // create new individual + initInd iind = paramsInit->getInitInd(ix); + if (dem.stageStruct) { + stg = iind.stage; age = iind.age; repInt = sstruct.repInterval; + } + else { + age = stg = 1; repInt = 0; + } + if (dem.repType == 0) { + probmale = 0.0; + } + else { + if (iind.sex == 1) probmale = 1.0; else probmale = 0.0; + } + pInd = new Individual(pSpecies, pCell, pPatch, stg, age, repInt, probmale, trfr.usesMovtProc, trfr.moveType); + + if (pSpecies->getNTraits() > 0) { + // individual variation - set up genetics + landData land = pLandscape->getLandData(); + pInd->setUpGenes(pSpecies, land.resol); + } + + popns[0]->recruit(pInd); +} + +// Create a new population, and return its address +Population* SubCommunity::newPopn(Landscape* pLandscape, Species* pSpecies, + Patch* pPatch, int nInds) +{ + landParams land = pLandscape->getLandParams(); + int npopns = (int)popns.size(); + popns.push_back(new Population(pSpecies, pPatch, nInds, land.resol)); + return popns[npopns]; +} + +popStats SubCommunity::getPopStats(void) { + popStats p, pop; + p.pSpecies = 0; p.spNum = 0; p.nInds = p.nAdults = p.nNonJuvs = 0; p.breeding = false; + p.pPatch = pPatch; + // FOR SINGLE SPECIES IMPLEMENTATION, THERE IS ONLY ONE POPULATION IN THE PATCH + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + pop = popns[i]->getStats(pPatch->getDemoScaling()); + p.pSpecies = pop.pSpecies; + p.spNum = pop.spNum; + p.nInds += pop.nInds; + p.nNonJuvs += pop.nNonJuvs; + p.nAdults += pop.nAdults; + p.breeding = pop.breeding; + } + return p; +} + +void SubCommunity::resetPopns(void) { + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + delete popns[i]; + } + popns.clear(); + // clear the list of populations in the corresponding patch + pPatch->resetPopn(); +} + +void SubCommunity::resetPossSettlers(void) { + if (subCommNum == 0) return; // not applicable in the matrix + pPatch->resetPossSettlers(); +} + +// Extirpate all populations according to +// option 0 - random local extinction probability +// option 1 - local extinction probability gradient +// NB only applied for cell-based model +void SubCommunity::localExtinction(int option) { + double pExtinct = 0.0; + if (option == 0) { + envStochParams env = paramsStoch->getStoch(); + if (env.localExt) pExtinct = env.locExtProb; + } + else { + envGradParams grad = paramsGrad->getGradient(); + Cell* pCell = pPatch->getRandomCell(); // get only cell in the patch + // extinction prob is complement of cell gradient value plus any non-zero prob at the optimum + pExtinct = 1.0 - pCell->getEnvVal() + grad.extProbOpt; + if (pExtinct > 1.0) pExtinct = 1.0; + } + if (pRandom->Bernoulli(pExtinct)) { + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + popns[i]->extirpate(); + } + } +} + +// Action in event of patch becoming unsuitable owing to landscape change +void SubCommunity::patchChange(void) { + if (subCommNum == 0) return; // no reproduction in the matrix + Species* pSpecies; + float localK = 0.0; + int npops = (int)popns.size(); + // THE FOLLOWING MAY BE MORE EFFICIENT WHILST THERE IS ONLY ONE SPECIES ... + if (npops < 1) return; + localK = pPatch->getK(); + if (localK <= 0.0) { // patch in dynamic landscape has become unsuitable + for (int i = 0; i < npops; i++) { // all populations + pSpecies = popns[i]->getSpecies(); + demogrParams dem = pSpecies->getDemogrParams(); + if (dem.stageStruct) { + stageParams sstruct = pSpecies->getStageParams(); + if (sstruct.disperseOnLoss) popns[i]->allEmigrate(); + else popns[i]->extirpate(); + } + else { // non-stage-structured species is destroyed + popns[i]->extirpate(); + } + } + } +} + +void SubCommunity::reproduction(int resol, float epsGlobal, short rasterType, bool patchModel) +{ + if (subCommNum == 0) return; // no reproduction in the matrix + float localK, envval; + std::vector localDemoScaling; + Cell* pCell; + envGradParams grad = paramsGrad->getGradient(); + envStochParams env = paramsStoch->getStoch(); + + int npops = (int)popns.size(); + // THE FOLLOWING MAY BE MORE EFFICIENT WHILST THERE IS ONLY ONE SPECIES ... + if (npops < 1) return; + + localK = pPatch->getK(); + localDemoScaling = pPatch->getDemoScaling(); + if (localK > 0.0) { + if (patchModel) { + envval = 1.0; // environmental gradient is currently not applied for patch-based model + } + else { // cell-based model + if (grad.gradient && grad.gradType == 2) + { // gradient in fecundity + Cell* pCell = pPatch->getRandomCell(); // locate the only cell in the patch + envval = pCell->getEnvVal(); + } + else envval = 1.0; + } + if (env.stoch && !env.inK) { // stochasticity in fecundity + if (env.local) { + if (!patchModel) { // only permitted for cell-based model + pCell = pPatch->getRandomCell(); + if (pCell != 0) envval += pCell->getEps(); + } + } + else { // global stochasticity + envval += epsGlobal; + } + } + for (int i = 0; i < npops; i++) { // all populations + popns[i]->reproduction(localK, envval, resol, localDemoScaling); + popns[i]->fledge(); + } + } +} + +void SubCommunity::emigration(void) +{ + if (subCommNum == 0) return; // no emigration from the matrix + int npops = static_cast(popns.size()); + if (npops < 1) return; + float localK = pPatch->getK(); + // NOTE that even if K is zero, it could have been >0 in previous time-step, and there + // might be emigrants if there is non-juvenile emigration + for (int i = 0; i < npops; i++) { // all populations + popns[i]->emigration(localK); + } +} + +// Remove emigrants from their natal patch and add to a map of vectors +void SubCommunity::recruitDispersers(std::map>& disperserPool) { + if (subCommNum == 0) return; // no dispersal initiation in the matrix + popStats pop; + disperser disp; + + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + pop = popns[i]->getStats(pPatch->getDemoScaling()); + Species* pSpecies = popns[i]->getSpecies(); + for (int j = 0; j < pop.nInds; j++) { + disp = popns[i]->extractDisperser(j); + if (disp.yes) { // disperser - has already been removed from natal population + disperserPool[pSpecies].push_back(disp.pInd); + } + } + // remove pointers to emigrants + popns[i]->clean(); + } +} + +// Add all individuals in the matrix to the disperser pool +void SubCommunity::disperseMatrix(std::map> &inds_map) { + if (subCommNum != 0) return; + popStats pop; + + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { + pop = popns[i]->getStats(pPatch->getDemoScaling()); + Species* pSpecies = popns[i]->getSpecies(); +#pragma omp for schedule(static) + for (int j = 0; j < pop.nInds; j++) { + Individual *pInd = popns[i]->extractIndividual(j); + inds_map[pSpecies].push_back(pInd); +} +#pragma omp single + popns[i]->clean(); + } + +} + +// Add an individual into the local population of its species in the patch +void SubCommunity::recruit(Individual* pInd, Species* pSpecies) { + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + if (pSpecies == popns[i]->getSpecies()) { + popns[i]->recruit(pInd); + } + } +} + +// Add individuals into the local population of their species in the patch +void SubCommunity::recruitMany(std::vector& inds, Species* pSpecies) { + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + if (pSpecies == popns[i]->getSpecies()) { + popns[i]->recruitMany(inds); + } + } +} + +// Transfer through the matrix - run for a per-species map of vectors of individuals +int SubCommunity::resolveTransfer(std::map>& dispersingInds, Landscape* pLandscape, short landIx) +{ + int nbStillDispersing = 0; + int disperser; + Patch* pPatch = nullptr; + Cell* pCell = nullptr; + simParams sim = paramsSim->getSim(); + + for (auto & it : dispersingInds) { // all species + + Species* const& pSpecies = it.first; + short reptype = pSpecies->getRepType(); + transferRules trfr = pSpecies->getTransferRules(); + + vector& inds = it.second; + + // each individual takes one step + // for dispersal by kernel, this should be the only step taken + for (auto& pInd : inds) { + if (trfr.usesMovtProc) { + disperser = pInd->moveStep(pLandscape, pSpecies, landIx, sim.absorbing); + } + else { + disperser = pInd->moveKernel(pLandscape, pSpecies, sim.absorbing); + } + nbStillDispersing += disperser; + if (disperser) { + if (reptype > 0) + { // sexual species - record as potential settler in new patch + if (pInd->getStatus() == 2) + { // disperser has found a patch + pCell = pInd->getCurrCell(); + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { // not no-data area + pPatch->incrPossSettler(pSpecies, pInd->getSex()); + } + } + } + } + } + } + return nbStillDispersing; +} + + +// Determine whether there is a potential mate present in a patch which a potential +// settler has reached +bool SubCommunity::matePresent(Species* pSpecies, Cell* pCell, short othersex) +{ + Patch* pPatch; + Population* pNewPopn; + int popsize = 0; + bool matefound = false; + + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { + if (pPatch->getPatchNum() > 0) { // not the matrix patch + if (pPatch->getK() > 0.0) + { // suitable + pNewPopn = pPatch->getPopn(pSpecies); + if (pNewPopn != nullptr) { + const stageParams sstruct = pSpecies->getStageParams(); + // count members of other sex already resident in the patch + for (int stg = 0; stg < sstruct.nStages; stg++) { + popsize += pNewPopn->getNbInds(stg, othersex); + } + } + if (popsize < 1) { + // add any potential settlers of the other sex + popsize += pPatch->getPossSettlers(pSpecies, othersex); + } + } + } + } + if (popsize > 0) matefound = true; + return matefound; +} + +// Transfer is run for populations in the matrix only +#if RS_RCPP // included also SEASONAL +int SubCommunity::resolveSettlement(std::map>& dispersingInds, Landscape* pLandscape, short nextseason) +#else +int SubCommunity::resolveSettlement(std::map>& dispersingInds, Landscape* pLandscape) +#endif +{ + int nbStillDispersing = 0; + short othersex; + bool mateOK, densdepOK; + int patchnum; + double localK, popsize, settprob; + Patch* pPatch = 0; + Cell* pCell = 0; + indStats ind; + Population* pNewPopn = 0; + locn newloc, nbrloc; + + landData ppLand = pLandscape->getLandData(); + settleRules sett; + settleTraits settDD; + settlePatch settle; + simParams sim = paramsSim->getSim(); + + for (auto& it : dispersingInds) { // all species + Species* const& pSpecies = it.first; + transferRules trfr = pSpecies->getTransferRules(); + settleType settletype = pSpecies->getSettle(); + + vector& inds = it.second; + + // each individual which has reached a potential patch decides whether to settle + for (auto& pInd : inds) { + ind = pInd->getStats(); + if (ind.sex == 0) othersex = 1; else othersex = 0; + if (settletype.stgDep) { + if (settletype.sexDep) sett = pSpecies->getSettRules(ind.stage, ind.sex); + else sett = pSpecies->getSettRules(ind.stage, 0); + } + else { + if (settletype.sexDep) sett = pSpecies->getSettRules(0, ind.sex); + else sett = pSpecies->getSettRules(0, 0); + } + if (ind.status == 2) + { // awaiting settlement + pCell = pInd->getCurrCell(); + if (pCell == 0) { + // this condition can occur in a patch-based model at the time of a dynamic landscape + // change when there is a range restriction in place, since a patch can straddle the + // range restriction and an individual forced to disperse upon patch removal could + // start its trajectory beyond the boundary of the restrictyed range - such a model is + // not good practice, but the condition must be handled by killing the individual conceerned + ind.status = 6; + } + else { + mateOK = false; + if (sett.findMate) { + // determine whether at least one individual of the opposite sex is present in the + // new population + if (matePresent(pSpecies, pCell, othersex)) mateOK = true; + } + else { // no requirement to find a mate + mateOK = true; + } + + densdepOK = false; + settle = pInd->getSettPatch(); + if (sett.densDep) + { + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { // not no-data area + if (settle.settleStatus == 0 + || settle.pSettPatch != pPatch) + // note: second condition allows for having moved from one patch to another + // adjacent one + { + // determine whether settlement occurs in the (new) patch + localK = (double)pPatch->getK(); + pNewPopn = pPatch->getPopn(pSpecies); + if (pNewPopn == nullptr) { // population has not been set up in the new patch + popsize = 0.0; + } + else { + popsize = (double)pNewPopn->getNbInds(); + } + if (localK > 0.0) { + // make settlement decision + if (settletype.indVar) settDD = pInd->getIndSettTraits(); +#if RS_RCPP + else settDD = pSpecies->getSpSettTraits(ind.stage, ind.sex); +#else + else { + if (settletype.sexDep) { + if (settletype.stgDep) + settDD = pSpecies->getSpSettTraits(ind.stage, ind.sex); + else + settDD = pSpecies->getSpSettTraits(0, ind.sex); + } + else { + if (settletype.stgDep) + settDD = pSpecies->getSpSettTraits(ind.stage, 0); + else + settDD = pSpecies->getSpSettTraits(0, 0); + } + } +#endif //RS_RCPP + settprob = settDD.s0 / + (1.0 + exp(-(popsize / localK - (double)settDD.beta) * (double)settDD.alpha)); + + if (pRandom->Bernoulli(settprob)) { // settlement allowed + densdepOK = true; + settle.settleStatus = 2; + } + else { // settlement procluded + settle.settleStatus = 1; + } + settle.pSettPatch = pPatch; + } + pInd->setSettPatch(settle); + } + else { + if (settle.settleStatus == 2) { // previously allowed to settle + densdepOK = true; + } + } + } + } + else { // no density-dependent settlement + densdepOK = true; + settle.settleStatus = 2; + settle.pSettPatch = pPatch; + pInd->setSettPatch(settle); + } + + if (mateOK && densdepOK) { // can recruit to patch + ind.status = 4; + nbStillDispersing--; + } + else { // does not recruit + if (trfr.usesMovtProc) { + ind.status = 1; // continue dispersing, unless ... + // ... maximum steps has been exceeded + pathSteps steps = pInd->getSteps(); + settleSteps settsteps = pSpecies->getSteps(ind.stage, ind.sex); + if (steps.year >= settsteps.maxStepsYr) { + ind.status = 3; // waits until next year + } + if (steps.total >= settsteps.maxSteps) { + ind.status = 6; // dies + } + } + else { // dispersal kernel + if (sett.wait) { + ind.status = 3; // wait until next dispersal event + } + else { + ind.status = 6; // (dies unless a neighbouring cell is suitable) + } + nbStillDispersing--; + } + } + } + + pInd->setStatus(ind.status); + } +#if RS_RCPP + // write each individuals current movement step and status to paths file + if (trfr.usesMovtProc && sim.outPaths) { + if (nextseason >= sim.outStartPaths && nextseason % sim.outIntPaths == 0) { + pInd->outMovePath(nextseason); + } + } +#endif + + if (!trfr.usesMovtProc && sett.go2nbrLocn && (ind.status == 3 || ind.status == 6)) + { + // for kernel-based transfer only ... + // determine whether recruitment to a neighbouring cell is possible + + pCell = pInd->getCurrCell(); + newloc = pCell->getLocn(); + vector nbrlist; + for (int dx = -1; dx < 2; dx++) { + for (int dy = -1; dy < 2; dy++) { + if (dx != 0 || dy != 0) { //cell is not the current cell + nbrloc.x = newloc.x + dx; nbrloc.y = newloc.y + dy; + if (nbrloc.x >= 0 && nbrloc.x <= ppLand.maxX + && nbrloc.y >= 0 && nbrloc.y <= ppLand.maxY) { // within landscape + // add to list of potential neighbouring cells if suitable, etc. + pCell = pLandscape->findCell(nbrloc.x, nbrloc.y); + if (pCell != 0) { // not no-data area + pPatch = pCell->getPatch(); + if (pPatch != nullptr) { // not no-data area + patchnum = pPatch->getPatchNum(); + if (patchnum > 0 && pPatch != pInd->getNatalPatch()) + { // not the matrix or natal patch + if (pPatch->getK() > 0.0) + { // suitable + if (sett.findMate) { + if (matePresent(pSpecies, pCell, othersex)) nbrlist.push_back(pCell); + } + else + nbrlist.push_back(pCell); + } + } + } + } + } + } + } + } + int listsize = (int)nbrlist.size(); + if (listsize > 0) { // there is at least one suitable neighbouring cell + if (listsize == 1) { + pInd->moveto(nbrlist[0]); + } + else { // select at random from the list + int rrr = pRandom->IRandom(0, listsize - 1); + pInd->moveto(nbrlist[rrr]); + } + } + // else list empty - do nothing - individual retains its current location and status + } + + } // loop through inds + + } // loop through disperser map + + return nbStillDispersing; +} + +//--------------------------------------------------------------------------- + +// Remove emigrants from the vectors map and transfer to sub-community +// in which their destination co-ordinates fall + +void SubCommunity::completeDispersal(std::map>& inds_map, Landscape* pLandscape, bool connect) +{ + Population* pPop; + Patch* pPrevPatch; + Patch* pNewPatch; + Cell* pPrevCell; + SubCommunity* pSubComm; + + for (auto & it : inds_map) { // all species + Species* const& pSpecies = it.first; + vector& inds = it.second; + for (Individual*& pInd : inds) { + indStats ind = pInd->getStats(); + bool settled = ind.status == 4 || ind.status == 5; + if (settled) { + // find new patch + pNewPatch = pInd->getCurrCell()->getPatch(); + // find population within the patch (if there is one) + { +#ifdef _OPENMP + const std::unique_lock lock = pNewPatch->lockPopns(); +#endif // _OPENMP + pPop = pNewPatch->getPopn(pSpecies); + if (pPop == 0) { // settler is the first in a previously uninhabited patch + // create a new population in the corresponding sub-community + pSubComm = pNewPatch->getSubComm(); + pPop = pSubComm->newPopn(pLandscape, pSpecies, pNewPatch, 0); + } + } + pPop->recruit(pInd); + if (connect) { // increment connectivity totals + int newpatch = pNewPatch->getSeqNum(); + pPrevCell = pInd->getPrevCell(); + pPrevPatch = pPrevCell->getPatch(); + if (pPrevPatch != nullptr) { + int prevpatch = pPrevPatch->getSeqNum(); + pLandscape->incrConnectMatrix(prevpatch, newpatch); + } + } + pInd = nullptr; + } + else { // for group dispersal only + } + } + // remove settled individuals + inds.erase(std::remove(inds.begin(), inds.end(), (Individual *)nullptr), inds.end()); + } +} + +//--------------------------------------------------------------------------- + +void SubCommunity::survival0(short option0, short option1) +{ + int npops = (int)popns.size(); + std::vector localDemoScaling; + localDemoScaling = pPatch->getDemoScaling(); + float localK = pPatch->getK(); + for (int i = 0; i < npops; i++) { // all populations + popns[i]->survival0(localK, option0, option1, localDemoScaling); + } +} + +void SubCommunity::survival1() +{ + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + popns[i]->survival1(); + } +} + +void SubCommunity::survival(short part, short option0, short option1 +) { + if (part == 0) { + return survival0(option0, option1); +} + else { + return survival1(); + } +} + +void SubCommunity::ageIncrement(void) { + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + popns[i]->ageIncrement(); + } +} + +// Find the population of a given species in a given patch +Population* SubCommunity::findPop(Species* pSp, Patch* pPch) { + + Population* pPop = 0; + popStats pop; + int npops = (int)popns.size(); + + for (int i = 0; i < npops; i++) { // all populations + pop = popns[i]->getStats(pPatch->getDemoScaling()); + if (pop.pSpecies == pSp && pop.pPatch == pPch) { // population located + pPop = popns[i]; + break; + } + else pPop = 0; + } + return pPop; +} + +//--------------------------------------------------------------------------- + +void SubCommunity::createOccupancy(int nrows) { + if (occupancy != 0) deleteOccupancy(); + if (nrows > 0) { + occupancy = new int[nrows]; + for (int i = 0; i < nrows; i++) occupancy[i] = 0; + } +} + +void SubCommunity::updateOccupancy(int row) { + popStats pop; + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { + pop = popns[i]->getStats(pPatch->getDemoScaling()); + if (pop.nInds > 0 && pop.breeding) { + occupancy[row]++; + i = npops; + } + } +} + +int SubCommunity::getOccupancy(int row) { + if (row >= 0) return occupancy[row]; + else return 0; +} + +void SubCommunity::deleteOccupancy(void) { + delete[] occupancy; + occupancy = 0; +} + +//--------------------------------------------------------------------------- +// Close population file +bool SubCommunity::outPopFinishLandscape() +{ + bool fileOK; + Population* pPop; + + // as all populations may have been deleted, set up a dummy one + // species is not necessary + pPop = new Population(); + fileOK = pPop->outPopFinishLandscape(); + delete pPop; + return fileOK; +} + +//--------------------------------------------------------------------------- +// Open population file and write header record +bool SubCommunity::outPopStartLandscape(Landscape* pLandscape, Species* pSpecies) +{ + bool fileOK; + Population* pPop; + landParams land = pLandscape->getLandParams(); + + // as no population has yet been created, set up a dummy one + // species is necessary, as columns depend on stage and sex structure + pPop = new Population(pSpecies, pPatch, 0, land.resol); + fileOK = pPop->outPopStartLandscape(land.landNum, land.patchModel); + delete pPop; + return fileOK; +} + +// Write records to population file +void SubCommunity::outPop(Landscape* pLandscape, int rep, int yr, int gen) +{ + landParams land = pLandscape->getLandParams(); + envGradParams grad = paramsGrad->getGradient(); + envStochParams env = paramsStoch->getStoch(); + bool writeEnv = false; + bool gradK = false; + if (grad.gradient) { + writeEnv = true; + if (grad.gradType == 1) gradK = true; // ... carrying capacity + } + if (env.stoch) writeEnv = true; + + // generate output for each population within the sub-community (patch) + // provided that the patch is suitable (i.e. non-zero carrying capacity) + // or the population is above zero (possible if there is stochasticity or a moving gradient) + // or it is the matrix patch in a patch-based model + int npops = (int)popns.size(); + int patchnum; + Cell* pCell; + float localK; + float eps = 0.0; + if (env.stoch) { + if (env.local) { + pCell = pPatch->getRandomCell(); + if (pCell != 0) eps = pCell->getEps(); + } + else { + eps = pLandscape->getGlobalStoch(yr); + } + } + + patchnum = pPatch->getPatchNum(); + for (int i = 0; i < npops; i++) { // all populations + localK = pPatch->getK(); + if (localK > 0.0 || (land.patchModel && patchnum == 0)) { + popns[i]->outPopulation(rep, yr, gen, eps, land.patchModel, writeEnv, gradK); + } + else { + if (popns[i]->getNbInds() > 0) { + popns[i]->outPopulation(rep, yr, gen, eps, land.patchModel, writeEnv, gradK); + } + } + } +} + +// Close individuals file +void SubCommunity::outIndsFinishReplicate() { + // as all populations have been deleted, set up a dummy one + Population* pPop = new Population(); + pPop->outIndsFinishReplicate(); + delete pPop; + return; +} + +// Open individuals file and write header record +void SubCommunity::outIndsStartReplicate(Landscape* pLandscape, int rep, int landNr) { + landParams ppLand = pLandscape->getLandParams(); + popns[0]->outIndsStartReplicate(rep, landNr, ppLand.patchModel); +} + +// Write records to individuals file +void SubCommunity::outIndividuals(Landscape* pLandscape, int rep, int yr, int gen) { + // generate output for each population within the sub-community (patch) + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + popns[i]->outIndividual(pLandscape, rep, yr, gen, pPatch->getPatchNum()); + } +} + + +// Population size of a specified stage +int SubCommunity::getNbInds(int stage) const { + int popsize = 0; + int npops = (int)popns.size(); + for (int i = 0; i < npops; i++) { // all populations + popsize += popns[i]->getNbInds(stage); + } + return popsize; +} + +// Close traits file +bool SubCommunity::outTraitsFinishLandscape() +{ + if (outtraits.is_open()) outtraits.close(); + outtraits.clear(); + return true; +} + +// Open traits file and write header record +bool SubCommunity::outTraitsStartLandscape(Landscape* pLandscape, Species* pSpecies, int landNr) +{ + landParams land = pLandscape->getLandParams(); + string name; + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); + settleType sett = pSpecies->getSettle(); + simParams sim = paramsSim->getSim(); + + string DirOut = paramsSim->getDir(2); + if (sim.batchMode) { + if (land.patchModel) { + name = DirOut + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + to_string(landNr) + + "_TraitsXpatch.txt"; + } + else { + name = DirOut + + "Batch" + to_string(sim.batchNum) + "_" + + "Sim" + to_string(sim.simulation) + "_Land" + to_string(landNr) + + "_TraitsXcell.txt"; + } + } + else { + if (land.patchModel) { + name = DirOut + "Sim" + to_string(sim.simulation) + "_TraitsXpatch.txt"; + } + else { + name = DirOut + "Sim" + to_string(sim.simulation) + "_TraitsXcell.txt"; + } + } + outtraits.open(name.c_str()); + + outtraits << "Rep\tYear\tRepSeason"; + if (land.patchModel) outtraits << "\tPatchID"; + else + outtraits << "\tx\ty"; + + if (emig.indVar) { + if (emig.sexDep) { + if (emig.densDep) { + outtraits << "\tF_meanD0\tF_stdD0\tM_meanD0\tM_stdD0"; + outtraits << "\tF_meanAlpha\tF_stdAlpha\tM_meanAlpha\tM_stdAlpha"; + outtraits << "\tF_meanBeta\tF_stdBeta\tM_meanBeta\tM_stdBeta"; + } + else { + outtraits << "\tF_meanEP\tF_stdEP\tM_meanEP\tM_stdEP"; + } + } + else { + if (emig.densDep) { + outtraits << "\tmeanD0\tstdD0\tmeanAlpha\tstdAlpha"; + outtraits << "\tmeanBeta\tstdBeta"; + } + else { + outtraits << "\tmeanEP\tstdEP"; + } + } + } + if (trfr.indVar) { + if (trfr.usesMovtProc) { + if (trfr.moveType == 1) { + outtraits << "\tmeanDP\tstdDP\tmeanGB\tstdGB"; + outtraits << "\tmeanAlphaDB\tstdAlphaDB\tmeanBetaDB\tstdBetaDB"; + } + if (trfr.moveType == 2) { + outtraits << "\tmeanStepLength\tstdStepLength\tmeanRho\tstdRho"; + } + } + else { + if (trfr.sexDep) { + outtraits << "\tF_mean_distI\tF_std_distI\tM_mean_distI\tM_std_distI"; + if (trfr.twinKern) + outtraits << "\tF_mean_distII\tF_std_distII\tM_mean_distII\tM_std_distII" + << "\tF_meanPfirstKernel\tF_stdPfirstKernel" + << "\tM_meanPfirstKernel\tM_stdPfirstKernel"; + } + else { + outtraits << "\tmean_distI\tstd_distI"; + if (trfr.twinKern) + outtraits << "\tmean_distII\tstd_distII\tmeanPfirstKernel\tstdPfirstKernel"; + } + } + } + if (sett.indVar) { + if (sett.sexDep) { + outtraits << "\tF_meanS0\tF_stdS0\tM_meanS0\tM_stdS0"; + outtraits << "\tF_meanAlphaS\tF_stdAlphaS\tM_meanAlphaS\tM_stdAlphaS"; + outtraits << "\tF_meanBetaS\tF_stdBetaS\tM_meanBetaS\tM_stdBetaS"; + } + else { + outtraits << "\tmeanS0\tstdS0"; + outtraits << "\tmeanAlphaS\tstdAlphaS"; + outtraits << "\tmeanBetaS\tstdBetaS"; + } + } + if (pSpecies->getNbGenLoadTraits() > 0) { + if (pSpecies->getDemogrParams().repType > 0) { + outtraits << "\tF_meanGenFitness\tF_stdGenFitness\tM_meanGenFitness\tM_stdGenFitness"; + } + else { + outtraits << "\tmeanGenFitness\tstdGenFitness"; + } + } + + outtraits << endl; + + return outtraits.is_open(); +} + +// Write records to traits file and return aggregated sums +traitsums SubCommunity::outTraits(Landscape* pLandscape, int rep, int yr, int gen, bool commlevel) +{ + landParams land = pLandscape->getLandParams(); + simParams sim = paramsSim->getSim(); + traitsums ts, indTraitsSums; + for (int i = 0; i < gMaxNbSexes; i++) { + ts.ninds[i] = 0; + ts.sumD0[i] = ts.ssqD0[i] = 0.0; + ts.sumAlpha[i] = ts.ssqAlpha[i] = 0.0; ts.sumBeta[i] = ts.ssqBeta[i] = 0.0; + ts.sumDist1[i] = ts.ssqDist1[i] = 0.0; ts.sumDist2[i] = ts.ssqDist2[i] = 0.0; + ts.sumProp1[i] = ts.ssqProp1[i] = 0.0; + ts.sumDP[i] = ts.ssqDP[i] = 0.0; + ts.sumGB[i] = ts.ssqGB[i] = 0.0; + ts.sumAlphaDB[i] = ts.ssqAlphaDB[i] = 0.0; + ts.sumBetaDB[i] = ts.ssqBetaDB[i] = 0.0; + ts.sumStepL[i] = ts.ssqStepL[i] = 0.0; ts.sumRho[i] = ts.ssqRho[i] = 0.0; + ts.sumS0[i] = ts.ssqS0[i] = 0.0; + ts.sumAlphaS[i] = ts.ssqAlphaS[i] = 0.0; ts.sumBetaS[i] = ts.ssqBetaS[i] = 0.0; + ts.sumGeneticFitness[i] = ts.ssqGeneticFitness[i] = 0.0; + } + + // generate output for each population within the sub-community (patch) + // provided that the patch is suitable (i.e. non-zero carrying capacity) + int npops = (int)popns.size(); + Species* pSpecies; + + for (int iPop = 0; iPop < npops; iPop++) { // all populations + + if (pPatch->getK() > 0.0 && popns[iPop]->getNbInds() > 0) { + pSpecies = popns[iPop]->getSpecies(); + demogrParams dem = pSpecies->getDemogrParams(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); + settleType sett = pSpecies->getSettle(); + indTraitsSums = popns[iPop]->getIndTraitsSums(pSpecies); + + // Sum over populations + for (int iSex = 0; iSex < gMaxNbSexes; iSex++) { + ts.ninds[iSex] += indTraitsSums.ninds[iSex]; + ts.sumD0[iSex] += indTraitsSums.sumD0[iSex]; + ts.ssqD0[iSex] += indTraitsSums.ssqD0[iSex]; + ts.sumAlpha[iSex] += indTraitsSums.sumAlpha[iSex]; + ts.ssqAlpha[iSex] += indTraitsSums.ssqAlpha[iSex]; + ts.sumBeta[iSex] += indTraitsSums.sumBeta[iSex]; + ts.ssqBeta[iSex] += indTraitsSums.ssqBeta[iSex]; + ts.sumDist1[iSex] += indTraitsSums.sumDist1[iSex]; + ts.ssqDist1[iSex] += indTraitsSums.ssqDist1[iSex]; + ts.sumDist2[iSex] += indTraitsSums.sumDist2[iSex]; + ts.ssqDist2[iSex] += indTraitsSums.ssqDist2[iSex]; + ts.sumProp1[iSex] += indTraitsSums.sumProp1[iSex]; + ts.ssqProp1[iSex] += indTraitsSums.ssqProp1[iSex]; + ts.sumDP[iSex] += indTraitsSums.sumDP[iSex]; + ts.ssqDP[iSex] += indTraitsSums.ssqDP[iSex]; + ts.sumGB[iSex] += indTraitsSums.sumGB[iSex]; + ts.ssqGB[iSex] += indTraitsSums.ssqGB[iSex]; + ts.sumAlphaDB[iSex] += indTraitsSums.sumAlphaDB[iSex]; + ts.ssqAlphaDB[iSex] += indTraitsSums.ssqAlphaDB[iSex]; + ts.sumBetaDB[iSex] += indTraitsSums.sumBetaDB[iSex]; + ts.ssqBetaDB[iSex] += indTraitsSums.ssqBetaDB[iSex]; + ts.sumStepL[iSex] += indTraitsSums.sumStepL[iSex]; + ts.ssqStepL[iSex] += indTraitsSums.ssqStepL[iSex]; + ts.sumRho[iSex] += indTraitsSums.sumRho[iSex]; + ts.ssqRho[iSex] += indTraitsSums.ssqRho[iSex]; + ts.sumS0[iSex] += indTraitsSums.sumS0[iSex]; + ts.ssqS0[iSex] += indTraitsSums.ssqS0[iSex]; + ts.sumAlphaS[iSex] += indTraitsSums.sumAlphaS[iSex]; + ts.ssqAlphaS[iSex] += indTraitsSums.ssqAlphaS[iSex]; + ts.sumBetaS[iSex] += indTraitsSums.sumBetaS[iSex]; + ts.ssqBetaS[iSex] += indTraitsSums.ssqBetaS[iSex]; + ts.sumGeneticFitness[iSex] += indTraitsSums.sumGeneticFitness[iSex]; + ts.ssqGeneticFitness[iSex] += indTraitsSums.ssqGeneticFitness[iSex]; + } + + // Produce trait-per-cell output + if (sim.outTraitsCells && yr % sim.outIntTraitCell == 0 + && !commlevel) { + + outtraits << rep << "\t" << yr << "\t" << gen; + if (land.patchModel) { + outtraits << "\t" << pPatch->getPatchNum(); + } + else { + locn loc = pPatch->getCellLocn(0); + outtraits << "\t" << loc.x << "\t" << loc.y; + } + + if (emig.indVar) { + if (emig.sexDep) { + vector mnD0(2, 0.0), mnAlpha(2, 0.0), mnBeta(2, 0.0), sdD0(2, 0.0), sdAlpha(2, 0.0), sdBeta(2, 0.0); + for (int sex = 0; sex < gMaxNbSexes; sex++) { + + double popsize = static_cast(indTraitsSums.ninds[sex]); + + if (popsize > 0) { + + mnD0[sex] = indTraitsSums.sumD0[sex] / popsize; + mnAlpha[sex] = indTraitsSums.sumAlpha[sex] / popsize; + mnBeta[sex] = indTraitsSums.sumBeta[sex] / popsize; + + if (popsize > 1) { + sdD0[sex] = indTraitsSums.ssqD0[sex] / popsize - mnD0[sex] * mnD0[sex]; + if (sdD0[sex] > 0.0) sdD0[sex] = sqrt(sdD0[sex]); else sdD0[sex] = 0.0; + sdAlpha[sex] = indTraitsSums.ssqAlpha[sex] / popsize - mnAlpha[sex] * mnAlpha[sex]; + if (sdAlpha[sex] > 0.0) sdAlpha[sex] = sqrt(sdAlpha[sex]); else sdAlpha[sex] = 0.0; + sdBeta[sex] = indTraitsSums.ssqBeta[sex] / popsize - mnBeta[sex] * mnBeta[sex]; + if (sdBeta[sex] > 0.0) sdBeta[sex] = sqrt(sdBeta[sex]); else sdBeta[sex] = 0.0; + } + else { + sdD0[sex] = sdAlpha[sex] = sdBeta[sex] = 0.0; + } + } + } + outtraits << "\t" << mnD0[0] << "\t" << sdD0[0]; + outtraits << "\t" << mnD0[1] << "\t" << sdD0[1]; + if (emig.densDep) { + outtraits << "\t" << mnAlpha[0] << "\t" << sdAlpha[0]; + outtraits << "\t" << mnAlpha[1] << "\t" << sdAlpha[1]; + outtraits << "\t" << mnBeta[0] << "\t" << sdBeta[0]; + outtraits << "\t" << mnBeta[1] << "\t" << sdBeta[1]; + } + } + else { // not sex-dependent + double mnD0 = 0, mnAlpha = 0, mnBeta = 0, popsize = 0; + double sdD0 = 0, sdAlpha = 0, sdBeta = 0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + mnD0 += indTraitsSums.sumD0[sex]; + mnAlpha += indTraitsSums.sumAlpha[sex]; + mnBeta += indTraitsSums.sumBeta[sex]; + popsize += indTraitsSums.ninds[sex]; + sdD0 += indTraitsSums.ssqD0[sex]; + sdAlpha += indTraitsSums.ssqAlpha[sex]; + sdBeta += indTraitsSums.ssqBeta[sex]; + } + mnD0 /= popsize; + mnAlpha /= popsize; + mnBeta /= popsize; + if (popsize > 1) { + sdD0 = sdD0 / popsize - mnD0 * mnD0; + sdAlpha = sdAlpha / popsize - mnAlpha * mnAlpha; + sdBeta = sdBeta / popsize - mnBeta * mnBeta; + sdD0 = sdD0 == 0.0 ? 0.0 : sqrt(sdD0); + sdAlpha = sdAlpha == 0.0 ? 0.0 : sqrt(sdAlpha); + sdBeta = sdBeta == 0.0 ? 0.0 : sqrt(sdBeta); + } + else { + sdD0 = 0.0; + sdAlpha = 0.0; + sdBeta = 0.0; + } + + outtraits << "\t" << mnD0 << "\t" << sdD0; + if (emig.densDep) { + outtraits << "\t" << mnAlpha << "\t" << sdAlpha; + outtraits << "\t" << mnBeta << "\t" << sdBeta; + } + } + } + + if (trfr.indVar) { + + if (trfr.usesMovtProc) { // not sex-dependent + if (trfr.moveType == 1) { // SMS + double mnDP = 0.0, mnGB = 0.0, mnAlphaDB = 0.0, mnBetaDB = 0.0; + double sdDP = 0.0, sdGB = 0.0, sdAlphaDB = 0.0, sdBetaDB = 0.0; + double popsize = 0.0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + mnDP += indTraitsSums.sumDP[sex]; + mnGB += indTraitsSums.sumGB[sex]; + mnAlphaDB += indTraitsSums.sumAlphaDB[sex]; + mnBetaDB+= indTraitsSums.sumBetaDB[sex]; + popsize += indTraitsSums.ninds[sex]; + sdDP += indTraitsSums.ssqDP[sex]; + sdGB += indTraitsSums.ssqGB[sex]; + sdAlphaDB += indTraitsSums.ssqAlphaDB[sex]; + sdBetaDB += indTraitsSums.ssqBetaDB[sex]; + } + mnDP /= popsize; + mnGB /= popsize; + mnAlphaDB /= popsize; + mnBetaDB /= popsize; + if (popsize > 1) { + sdDP = sdDP / popsize - mnDP * mnDP; + sdGB = sdGB / popsize - mnGB * mnGB; + sdAlphaDB = sdAlphaDB / popsize - mnAlphaDB * mnAlphaDB; + sdBetaDB = sdBetaDB / popsize - mnBetaDB * mnBetaDB; + sdDP = sdDP == 0.0 ? 0.0 : sqrt(sdDP); + sdGB = sdGB == 0.0 ? 0.0 : sqrt(sdGB); + sdAlphaDB = sdAlphaDB == 0.0 ? 0.0 : sqrt(sdAlphaDB); + sdBetaDB = sdBetaDB == 0.0 ? 0.0 : sqrt(sdBetaDB); + } + else { + sdDP = 0.0; + sdGB = 0.0; + sdAlphaDB = 0.0; + sdBetaDB = 0.0; + } + outtraits << "\t" << mnDP << "\t" << sdDP; + outtraits << "\t" << mnGB << "\t" << sdGB; + outtraits << "\t" << mnAlphaDB << "\t" << sdAlphaDB; + outtraits << "\t" << mnBetaDB << "\t" << sdBetaDB; + } + if (trfr.moveType == 2) { // CRW + double mnStepL = 0.0, mnRho = 0.0, sdStepL = 0.0, sdRho = 0.0; + double popsize = 0.0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + mnStepL += indTraitsSums.sumStepL[sex]; + mnRho += indTraitsSums.sumRho[sex]; + popsize += indTraitsSums.ninds[sex]; + sdStepL += indTraitsSums.ssqStepL[sex]; + sdRho += indTraitsSums.ssqRho[sex]; + } + mnStepL /= popsize; + mnRho /= popsize; + if (popsize > 1) { + sdStepL = sdStepL / popsize - mnStepL * mnStepL; + sdRho = sdRho / popsize - mnRho * mnRho; + sdStepL = sdStepL == 0.0 ? 0.0 : sqrt(sdStepL); + sdRho = sdRho == 0.0 ? 0.0 : sqrt(sdRho); + } + else { + sdStepL = 0.0; + sdRho = 0.0; + } + outtraits << "\t" << mnStepL << "\t" << sdStepL; + outtraits << "\t" << mnRho << "\t" << sdRho; + } + } + else { // kernels + if (trfr.sexDep) { + + vector mnDist1(2, 0.0), mnDist2(2, 0.0), mnProp1(2, 0.0), mnStepL(2, 0.0), mnRho(2, 0.0); + vector sdDist1(2, 0.0), sdDist2(2, 0.0), sdProp1(2, 0.0), sdStepL(2, 0.0), sdRho(2, 0.0); + + for (int sex = 0; sex < gMaxNbSexes; sex++) { + + // individuals may have been counted by sex if there was + // sex dependency in another dispersal phase + double popsize = static_cast(indTraitsSums.ninds[sex]); + + if (popsize > 0) { + mnDist1[sex] = indTraitsSums.sumDist1[sex] / popsize; + mnDist2[sex] = indTraitsSums.sumDist2[sex] / popsize; + mnProp1[sex] = indTraitsSums.sumProp1[sex] / popsize; + if (popsize > 1) { + sdDist1[sex] = indTraitsSums.ssqDist1[sex] / popsize - mnDist1[sex] * mnDist1[sex]; + if (sdDist1[sex] > 0.0) sdDist1[sex] = sqrt(sdDist1[sex]); else sdDist1[sex] = 0.0; + sdDist2[sex] = indTraitsSums.ssqDist2[sex] / popsize - mnDist2[sex] * mnDist2[sex]; + if (sdDist2[sex] > 0.0) sdDist2[sex] = sqrt(sdDist2[sex]); else sdDist2[sex] = 0.0; + sdProp1[sex] = indTraitsSums.ssqProp1[sex] / popsize - mnProp1[sex] * mnProp1[sex]; + if (sdProp1[sex] > 0.0) sdProp1[sex] = sqrt(sdProp1[sex]); else sdProp1[sex] = 0.0; + sdStepL[sex] = indTraitsSums.ssqStepL[sex] / popsize - mnStepL[sex] * mnStepL[sex]; + } + } + } + outtraits << "\t" << mnDist1[0] << "\t" << sdDist1[0]; + outtraits << "\t" << mnDist1[1] << "\t" << sdDist1[1]; + if (trfr.twinKern) { + outtraits << "\t" << mnDist2[0] << "\t" << sdDist2[0]; + outtraits << "\t" << mnDist2[1] << "\t" << sdDist2[1]; + outtraits << "\t" << mnProp1[0] << "\t" << sdProp1[0]; + outtraits << "\t" << mnProp1[1] << "\t" << sdProp1[1]; + } + } + else { // sex-independent + double mnDist1 = 0.0, mnDist2 = 0.0, mnProp1 = 0.0, popsize = 0.0; + double sdDist1 = 0.0, sdDist2 = 0.0, sdProp1 = 0.0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + mnDist1 += indTraitsSums.sumDist1[sex]; + mnDist2 += indTraitsSums.sumDist2[sex]; + mnProp1 += indTraitsSums.sumProp1[sex]; + popsize += indTraitsSums.ninds[sex]; + sdDist1 += indTraitsSums.ssqDist1[sex]; + sdDist2 += indTraitsSums.ssqDist2[sex]; + sdProp1 += indTraitsSums.ssqProp1[sex]; + } + mnDist1 /= popsize; + mnDist2 /= popsize; + mnProp1 /= popsize; + if (popsize > 1) { + sdDist1 = sdDist1 / popsize - mnDist1 * mnDist1; + sdDist2 = sdDist2 / popsize - mnDist2 * mnDist2; + sdProp1 = sdProp1 / popsize - mnProp1 * mnProp1; + sdDist1 = sdDist1 == 0.0 ? 0.0 : sqrt(sdDist1); + sdDist2 = sdDist2 == 0.0 ? 0.0 : sqrt(sdDist2); + sdProp1 = sdProp1 == 0.0 ? 0.0 : sqrt(sdProp1); + } + else { + sdDist1 = 0.0; + sdDist2 = 0.0; + sdProp1 = 0.0; + } + outtraits << "\t" << mnDist1 << "\t" << sdDist1; + if (trfr.twinKern) { + outtraits << "\t" << mnDist2 << "\t" << sdDist2; + outtraits << "\t" << mnProp1 << "\t" << sdProp1; + } + } + } + } + + if (sett.indVar) { + + if (sett.sexDep) { + + vector mnS0(2, 0.0), mnAlpha(2, 0.0), mnBeta(2, 0.0), sdS0(2, 0.0), sdAlpha(2, 0.0), sdBeta(2, 0.0); + + for (int sex = 0; sex < gMaxNbSexes; sex++) { + + // individuals may have been counted by sex if there was + // sex dependency in another dispersal phase + double popsize = static_cast(indTraitsSums.ninds[sex]); + + if (popsize > 0) { + + mnS0[sex] = indTraitsSums.sumS0[sex] / popsize; + mnAlpha[sex] = indTraitsSums.sumAlphaS[sex] / popsize; + mnBeta[sex] = indTraitsSums.sumBetaS[sex] / popsize; + + if (popsize > 1) { + sdS0[sex] = indTraitsSums.ssqS0[sex] / popsize - mnS0[sex] * mnS0[sex]; + if (sdS0[sex] > 0.0) sdS0[sex] = sqrt(sdS0[sex]); else sdS0[sex] = 0.0; + sdAlpha[sex] = indTraitsSums.ssqAlphaS[sex] / popsize - mnAlpha[sex] * mnAlpha[sex]; + if (sdAlpha[sex] > 0.0) sdAlpha[sex] = sqrt(sdAlpha[sex]); else sdAlpha[sex] = 0.0; + sdBeta[sex] = indTraitsSums.ssqBetaS[sex] / popsize - mnBeta[sex] * mnBeta[sex]; + if (sdBeta[sex] > 0.0) sdBeta[sex] = sqrt(sdBeta[sex]); else sdBeta[sex] = 0.0; + } + else { + sdS0[sex] = sdAlpha[sex] = sdBeta[sex] = 0.0; + } + } + } + + outtraits << "\t" << mnS0[0] << "\t" << sdS0[0]; + outtraits << "\t" << mnS0[1] << "\t" << sdS0[1]; + outtraits << "\t" << mnAlpha[0] << "\t" << sdAlpha[0]; + outtraits << "\t" << mnAlpha[1] << "\t" << sdAlpha[1]; + outtraits << "\t" << mnBeta[0] << "\t" << sdBeta[0]; + outtraits << "\t" << mnBeta[1] << "\t" << sdBeta[1]; + } + else { // sex-independent + double mnS0 = 0, mnAlpha = 0, mnBeta = 0, popsize = 0; + double sdS0 = 0, sdAlpha = 0, sdBeta = 0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + mnS0 += indTraitsSums.sumS0[sex]; + mnAlpha += indTraitsSums.sumAlphaS[sex]; + mnBeta += indTraitsSums.sumBetaS[sex]; + popsize += indTraitsSums.ninds[sex]; + sdS0 += indTraitsSums.ssqS0[sex]; + sdAlpha += indTraitsSums.ssqAlphaS[sex]; + sdBeta += indTraitsSums.ssqBetaS[sex]; + } + mnS0 /= popsize; + mnAlpha /= popsize; + mnBeta /= popsize; + if (popsize > 1) { + sdS0 = sdS0 / popsize - mnS0 * mnS0; + sdAlpha = sdAlpha / popsize - mnAlpha * mnAlpha; + sdBeta = sdBeta / popsize - mnBeta * mnBeta; + sdS0 = sdS0 == 0.0 ? 0.0 : sqrt(sdS0); + sdAlpha = sdAlpha == 0.0 ? 0.0 : sqrt(sdAlpha); + sdBeta = sdBeta == 0.0 ? 0.0 : sqrt(sdBeta); + } + else { + sdS0 = 0.0; + sdAlpha = 0.0; + sdBeta = 0.0; + } + outtraits << "\t" << mnS0 << "\t" << sdS0; + outtraits << "\t" << mnAlpha << "\t" << sdAlpha; + outtraits << "\t" << mnBeta << "\t" << sdBeta; + } + } + + // Genetic load + if (pSpecies->getNbGenLoadTraits() > 0) { + + if (pSpecies->getDemogrParams().repType > 0) { // sexual model + vector mnGenFitness(2, 0.0), sdGenFitness(2, 0.0); + + for (int sex = 0; sex < gMaxNbSexes; sex++) { + double popsize = static_cast(indTraitsSums.ninds[sex]); + mnGenFitness[sex] = indTraitsSums.sumGeneticFitness[sex] + / popsize; + if (popsize > 1) { + sdGenFitness[sex] = indTraitsSums.ssqGeneticFitness[sex] + / popsize - mnGenFitness[sex] + * mnGenFitness[sex]; + if (sdGenFitness[sex] > 0.0) + sdGenFitness[sex] = sqrt(sdGenFitness[sex]); + else sdGenFitness[sex] = 0.0; + } + else { + sdGenFitness[sex] = 0.0; + } + } + outtraits << "\t" << mnGenFitness[0] << "\t" << sdGenFitness[0]; + outtraits << "\t" << mnGenFitness[1] << "\t" << sdGenFitness[1]; + } + else { // asexual + + double mnGenFitness = 0.0, popsize = 0.0, sdGenFitness= 0.0; + for (int sex = 0; sex < gMaxNbSexes; sex++) { + mnGenFitness += indTraitsSums.sumGeneticFitness[sex]; + popsize += indTraitsSums.ninds[sex]; + sdGenFitness += indTraitsSums.ssqGeneticFitness[sex]; + } + mnGenFitness /= popsize; + if (popsize > 1) { + sdGenFitness = sdGenFitness / popsize - mnGenFitness * mnGenFitness; + sdGenFitness = sdGenFitness == 0.0 ? 0.0 : sqrt(sdGenFitness); + } + else sdGenFitness = 0.0; + outtraits << "\t" << mnGenFitness << "\t" << sdGenFitness; + } + } + outtraits << endl; + } // end trait-per-cell output + + } + } // end population loop + return ts; +} + +//--------------------------------------------------------------------------- + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + + diff --git a/SubCommunity.h b/RangeShiftR/src/RScore/SubCommunity.h similarity index 66% rename from SubCommunity.h rename to RangeShiftR/src/RScore/SubCommunity.h index 3eef73a..bfc421d 100644 --- a/SubCommunity.h +++ b/RangeShiftR/src/RScore/SubCommunity.h @@ -1,6 +1,6 @@ /*---------------------------------------------------------------------------- * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell * * This file is part of RangeShifter. * @@ -39,7 +39,7 @@ Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 Authors: Greta Bocedi & Steve Palmer, University of Aberdeen -Last updated: 26 October 2021 by Steve Palmer + Last updated: 25 June 2021 by Greta Bocedi ------------------------------------------------------------------------------*/ @@ -48,6 +48,7 @@ Last updated: 26 October 2021 by Steve Palmer #include #include +#include using namespace std; #include "Parameters.h" @@ -56,16 +57,12 @@ using namespace std; //--------------------------------------------------------------------------- -struct traitCanvas { // canvases for drawing variable traits - int *pcanvas[NTRAITS]; // dummy variables for batch version -}; - class SubCommunity { public: SubCommunity(Patch*,int); ~SubCommunity(void); - intptr getNum(void); + int getNum(void); Patch* getPatch(void); locn getLocn(void); @@ -94,35 +91,66 @@ class SubCommunity { bool // TRUE for a patch-based model, FALSE for a cell-based model ); void emigration(void); - // Remove emigrants from their natal patch and add to patch 0 (matrix) - void initiateDispersal( - SubCommunity* // pointer to matrix SubCommunity + + // Remove emigrants from the matrix subcommunity and add to a map of vectors + void disperseMatrix( + std::map>& ); -// Add an individual into the local population of its species in the patch + // Remove emigrants from their natal patch and add to a map of vectors + void recruitDispersers( + std::map>& + ); + // Add an individual into the local population of its species in the patch void recruit( Individual*, // pointer to Individual Species* // pointer to Species ); -#if RS_RCPP - int transfer( // Transfer through matrix - run for matrix SubCommunity only - Landscape*, // pointer to Landscape - short, // landscape change index - short // season / year + // Add individuals into the local population of their species in the patch + void recruitMany( + std::vector&, // vector of pointers to Individuals + Species* // pointer to Species ); -#else - int transfer( // Transfer through matrix - run for matrix SubCommunity only + + // Determine whether there is a potential mate present in a patch which a potential + // settler has reached + static bool matePresent( + Species* pSpecies, + Cell*, // pointer to the Cell which the potential settler has reached + short // sex of the required mate (0 = female, 1 = male) + ); + + static int resolveTransfer( // Executed for a given vector of individuals + std::map>& dispersingInds, Landscape*, // pointer to Landscape short // landscape change index ); + +#if RS_RCPP + static int resolveSettlement( // Executed for a given vector of individuals + std::map>& dispersingInds, + Landscape* pLandscape, + short // year + ); +#else + static int resolveSettlement( // Executed for a given vector of individuals + std::map>& dispersingInds, + Landscape* pLandscape + ); #endif // RS_RCPP - // Remove emigrants from patch 0 (matrix) and transfer to SubCommunity in which - // their destination co-ordinates fall (executed for the matrix patch only) - void completeDispersal( + + // Remove emigrants from the vectors map and transfer to SubCommunity in which + // their destination co-ordinates fall + static void completeDispersal( + std::map>&, // per-species map of vectors of individuals Landscape*, // pointer to Landscape bool // TRUE to increment connectivity totals ); + + void survival0(short option0, short option1); + void survival1(); + void survival( - short, // part: 0 = determine survival & development, + short, // part: 0 = determine survival & development, // 1 = apply survival changes to the population short, // option0: 0 = stage 0 (juveniles) only ) // 1 = all stages ) used by part 0 only @@ -130,9 +158,12 @@ class SubCommunity { short // option1: 0 - development only (when survival is annual) // 1 - development and survival ); + void ageIncrement(void); + // Find the population of a given species in a given patch Population* findPop(Species*,Patch*); + void createOccupancy( int // no. of rows = (no. of years / interval) + 1 ); @@ -144,10 +175,10 @@ class SubCommunity { ); void deleteOccupancy(void); - bool outPopHeaders( // Open population file and write header record + bool outPopFinishLandscape(); // Close population file + bool outPopStartLandscape( // Open population file and write header record Landscape*, // pointer to Landscape - Species*, // pointer to Species - int // option: -999 to close the file + Species* // pointer to Species ); void outPop( // Write records to population file Landscape*, // pointer to Landscape @@ -156,41 +187,44 @@ class SubCommunity { int // generation ); - void outInds( // Write records to individuals file + void outIndsFinishReplicate(); // Close individuals file + void outIndsStartReplicate( // Open individuals file and write header record Landscape*, // pointer to Landscape int, // replicate - int, // year - int, // generation - int // Landscape number (>= 0 to open the file, -999 to close the file - // -1 to write data records) + int // Landscape number ); - void outGenetics( // Write records to genetics file + void outIndividuals( // Write records to individuals file + Landscape*, // pointer to Landscape int, // replicate int, // year - int, // generation - int // Landscape number (>= 0 to open the file, -999 to close the file - // -1 to write data records) + int // generation ); bool outTraitsHeaders( // Open traits file and write header record Landscape*, // pointer to Landscape Species*, // pointer to Species - int // Landscape number (-999 to close the file) + int // Landscape number ); + + + // Close traits file + bool outTraitsFinishLandscape(); + + // Open traits file and write header record + bool outTraitsStartLandscape(Landscape* pLandscape, Species* pSpecies, int landNr); + traitsums outTraits( // Write records to traits file and return aggregated sums - traitCanvas, // pointers to canvases for drawing variable traits - // in the batch version, these are replaced by integers set to zero Landscape*, // pointer to Landscape int, // replicate int, // year int, // generation bool // true if called to summarise data at community level ); - int stagePop( // Population size of a specified stage + int getNbInds( // Population size of a specified stage int // stage - ); + ) const; private: - intptr subCommNum; // SubCommunity number + int subCommNum; // SubCommunity number // 0 is reserved for the SubCommunity in the inter-patch matrix Patch *pPatch; int *occupancy; // pointer to occupancy array diff --git a/RangeShiftR/src/RScore/TraitFactory.h b/RangeShiftR/src/RScore/TraitFactory.h new file mode 100644 index 0000000..2735d49 --- /dev/null +++ b/RangeShiftR/src/RScore/TraitFactory.h @@ -0,0 +1,55 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + * + * File Created by Roslyn Henry March 2023. Code adapted from NEMO (https://nemo2.sourceforge.io/) + --------------------------------------------------------------------------*/ +#ifndef TRAITFACTORYH +#define TRAITFACTORYH + +#include + +#include "SpeciesTrait.h" +#include "NeutralTrait.h" +#include "DispersalTrait.h" +#include "GeneticFitnessTrait.h" + +// Create handled pointers to a new trait +class TraitFactory +{ +public: + TraitFactory() {}; + + unique_ptr Create(const TraitType traitType, SpeciesTrait* pSpTrait) + { + if (traitType == NEUTRAL) { + return make_unique(pSpTrait); + } + else if (traitType == GENETIC_LOAD1 + || traitType == GENETIC_LOAD2 + || traitType == GENETIC_LOAD3 + || traitType == GENETIC_LOAD4 + || traitType == GENETIC_LOAD5) { + return make_unique(pSpTrait); + } + else { + return make_unique(pSpTrait); + } + } +}; +#endif diff --git a/RangeShiftR/src/RScore/Utils.cpp b/RangeShiftR/src/RScore/Utils.cpp new file mode 100644 index 0000000..e5f6f9c --- /dev/null +++ b/RangeShiftR/src/RScore/Utils.cpp @@ -0,0 +1,28 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * + * This file is part of RangeShifter. + * + * RangeShifter is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShifter. If not, see . + --------------------------------------------------------------------------*/ +#include "Utils.h" + +// Evaluate a lambda and assert we get the correct error +void assert_error(const string& exptd_err_msg, void (*lambda)(void)) { + string err_msg{ "No error.\n" }; + try { lambda(); } // evaluate + catch (exception& e) { err_msg = e.what(); } + assert(err_msg == exptd_err_msg); +} diff --git a/RandomCheck.h b/RangeShiftR/src/RScore/Utils.h similarity index 63% rename from RandomCheck.h rename to RangeShiftR/src/RScore/Utils.h index b4992d2..2f93e82 100644 --- a/RandomCheck.h +++ b/RangeShiftR/src/RScore/Utils.h @@ -1,40 +1,33 @@ /*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * + * + * Copyright (C) 2026 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Roslyn Henry, Théo Pannetier, Jette Wolff, Damaris Zurell + * * This file is part of RangeShifter. - * + * * RangeShifter is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. - * + * * RangeShifter is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. - * + * * You should have received a copy of the GNU General Public License * along with RangeShifter. If not, see . - * --------------------------------------------------------------------------*/ - - -//--------------------------------------------------------------------------- +#ifndef UtilsH +#define UtilsH -#ifndef RandomCheckH -#define RandomCheckH +#include +#include +#include -#include +#include using namespace std; -#include "Parameters.h" -#include "RSrandom.h" +// Evaluate a lambda and assert we get the correct error +void assert_error(const string& exptd_err_msg, void (*x)(void)); -void randomCheck(void); - -extern paramSim *paramsSim; -extern RSrandom *pRandom; - -//--------------------------------------------------------------------------- -#endif +#endif // UtilsH diff --git a/RangeShiftR/src/RScore/branches.png b/RangeShiftR/src/RScore/branches.png new file mode 100644 index 0000000..12e3a96 Binary files /dev/null and b/RangeShiftR/src/RScore/branches.png differ diff --git a/git_cheatsheet.md b/RangeShiftR/src/RScore/git_cheatsheet.md similarity index 100% rename from git_cheatsheet.md rename to RangeShiftR/src/RScore/git_cheatsheet.md diff --git a/RangeShiftR/src/RScore/unit_tests/testIndividual.cpp b/RangeShiftR/src/RScore/unit_tests/testIndividual.cpp new file mode 100644 index 0000000..2955609 --- /dev/null +++ b/RangeShiftR/src/RScore/unit_tests/testIndividual.cpp @@ -0,0 +1,1406 @@ +#ifdef UNIT_TESTS + +#include "../Individual.h" +#include "../Population.h" + +void testTransferKernels() { + + // Simple 3*3 cell-based landscape layout + const int lsDim = 3; + landParams ls_params = createDefaultLandParams(lsDim); + + // Set dispersal distances that are almost guaranteed + // to reach or fail to reach final cell + const float meanDistSuccess = static_cast(ls_params.dimX); // > 99% success + const float meanDistFailure = 0.1; // 0% success + + Landscape ls; + ls.setLandParams(ls_params, true); + + // Two suitable cells in opposite corners + Cell* init_cell = new Cell(0, 0, 0, 0); + Cell* final_cell = new Cell(ls_params.dimX - 1, ls_params.dimY - 1, 0, 0); + ls.setCellArray(); + ls.addCellToLand(init_cell); + ls.addCellToLand(final_cell); + + // Set up species + Species sp; + // Habitat codes + sp.createHabK(1); + sp.setHabK(0, 100.0); // one habitat with K = 100 + // Demography + demogrParams d; + d.stageStruct = false; + sp.setDemogr(d); + // Transfer rules + transferRules trfr; + trfr.indVar = trfr.sexDep = trfr.stgDep = false; + trfr.twinKern = trfr.distMort = false; + sp.setTrfrRules(trfr); + sp.setFullKernel(false); + + // Transfer mortality params + trfrMortParams mort; + mort.fixedMort = 0.0; + sp.setMortParams(mort); + // Settlement + settleRules sett; + sett.wait = false; + sp.setSettRules(0, 0, sett); + + // Set up patches + ls.allocatePatches(&sp); + ls.updateCarryingCapacity(&sp, 0, 0); + Patch* init_patch = init_cell->getPatch(); + + // Default distances + trfrKernelParams kern; + kern.meanDist1 = meanDistSuccess; + sp.setSpKernTraits(0, 0, kern, ls_params.resol); + Individual ind1(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); + int isDispersing = ind1.moveKernel(&ls, &sp, false); + + // After moving, individual should be in the only available cell + Cell* curr_cell = ind1.getCurrCell(); + assert(curr_cell != init_cell); + assert(curr_cell == final_cell); + assert(ind1.getStatus() == 2); // potential settler + + // If no cell within reasonable dispersal reach, individual does not move and dies + kern.meanDist1 = meanDistFailure; + sp.overrideKernels(0, 0, kern); + Individual ind2(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); // reset individual + isDispersing = ind2.moveKernel(&ls, &sp, false); + curr_cell = ind2.getCurrCell(); + assert(ind2.getStatus() == 6); // RIP in peace + assert(curr_cell == init_cell); + + // Twin kernels + trfr.twinKern = true; + sp.setTrfrRules(trfr); + kern.meanDist1 = meanDistFailure; + kern.meanDist2 = meanDistSuccess; + kern.probKern1 = 1.0; // 2nd kernel never used + sp.overrideKernels(0, 0, kern); + Individual ind3(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); + isDispersing = ind3.moveKernel(&ls, &sp, false); + assert(ind3.getStatus() == 6); // dead, could not reach destination cell + kern.probKern1 = 0.0; // always use 2nd kernel + sp.overrideKernels(0, 0, kern); + Individual ind4(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); + isDispersing = ind4.moveKernel(&ls, &sp, false); + assert(ind4.getStatus() == 2); + // reset + trfr.twinKern = false; + sp.setTrfrRules(trfr); + kern.probKern1 = 1.0; + sp.overrideKernels(0, 0, kern); + + // Sex-dependent dispersal distances + // female very unlikely to reach suitable cell + // male easily reaches suitable cell + trfr.sexDep = true; + sp.setTrfrRules(trfr); + trfrKernelParams kern_f = kern; + kern_f.meanDist1 = meanDistFailure; + sp.overrideKernels(0, 0, kern_f); + trfrKernelParams kern_m = kern; + kern_m.meanDist1 = meanDistSuccess; + sp.overrideKernels(0, 1, kern_m); + + Individual ind5(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); // female as default + isDispersing = ind5.moveKernel(&ls, &sp, false); + assert(ind5.getStatus() == 6); // dead, could not reach destination + + Individual ind6(&sp, init_cell, init_patch, 1, 0, 0, 1.0, false, 0); // male + assert(ind6.getSex() == 1); + isDispersing = ind6.moveKernel(&ls, &sp, false); + assert(ind6.getStatus() == 2); + // reset + trfr.sexDep = false; + sp.setTrfrRules(trfr); + + // Stage-dependent + trfr.stgDep = true; + sp.setTrfrRules(trfr); + trfrKernelParams kern_juv = kern; + kern_juv.meanDist1 = meanDistFailure; // juveniles very unlikely to reach suitable cell + sp.overrideKernels(0, 0, kern_juv); + trfrKernelParams kern_adult = kern; + kern_adult.meanDist1 = meanDistSuccess; // adults easily reach suitable cell + sp.overrideKernels(1, 0, kern_adult); + + Individual ind7(&sp, init_cell, init_patch, 0, 0, 0, 0.0, false, 0); // juvenile + isDispersing = ind7.moveKernel(&ls, &sp, false); + assert(ind7.getStatus() == 6); + + Individual ind8(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); // adult by default + isDispersing = ind8.moveKernel(&ls, &sp, false); + assert(ind8.getStatus() == 2); + // reset + trfr.stgDep = false; + sp.setTrfrRules(trfr); + + /* Boundaries: dispersal distance overshoots + Only adjacent cells are available + ----- + -ooo- + -oio- + -ooo- + ----- + */ + ls.resetLand(); + ls_params = createDefaultLandParams(5); + ls.setLandParams(ls_params, true); + ls.setCellArray(); // reset cells + + vector cells; + // Set central cell and all adjacent + for (int x = ls_params.minX + 1; x < ls_params.maxX; ++x) { + for (int y = ls_params.minY + 1; y < ls_params.maxY; ++y) { + cells.push_back(new Cell(x, y, 0, 0)); + } + } + + for (auto c : cells) ls.addCellToLand(c); + ls.allocatePatches(&sp); + ls.updateCarryingCapacity(&sp, 0, 0); + init_cell = cells[4]; // central cell + init_patch = init_cell->getPatch(); + + kern.meanDist1 = 100; // overshoots *most* of the time... + sp.setSpKernTraits(0, 0, kern, ls_params.resol); + Individual ind9(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); // reset individual + + // Non-absorbing boundaries + bool absorbing_boundaries{ false }; + isDispersing = ind9.moveKernel(&ls, &sp, absorbing_boundaries); + curr_cell = ind9.getCurrCell(); + assert(curr_cell != init_cell); // ...should be able to move eventually + assert(ind9.getStatus() == 2); + + // Absorbing boundaries + absorbing_boundaries = true; + Individual ind10(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); // reset individual + isDispersing = ind10.moveKernel(&ls, &sp, absorbing_boundaries); + curr_cell = ind10.getCurrCell(); + assert(ind10.getStatus() == 6); + assert(curr_cell == 0); // out of the landscape + + // Dispersal-related mortality + + // Fixed mortality + mort.fixedMort = 1.0; // Individual *will* die after any step + sp.setMortParams(mort); + trfr.distMort = false; + sp.setTrfrRules(trfr); + Individual ind11(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); + isDispersing = ind11.moveKernel(&ls, &sp, false); + assert(ind11.getStatus() == 7); + + // Distance-dependent mortality + trfr.distMort = true; + sp.setTrfrRules(trfr); + mort.mortAlpha = 1000.0; // very steep threshold + mort.mortBeta = 0.001; // very small distance + sp.setMortParams(mort); + kern.meanDist1 = 5; // very likely to go over threshold + absorbing_boundaries = true; + sp.setSpKernTraits(0, 0, kern, ls_params.resol); + Individual ind12(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); + isDispersing = ind12.moveKernel(&ls, &sp, absorbing_boundaries); + assert(ind12.getStatus() == 7); + + mort.mortBeta = 30; // very large distance, unlikely to draw + sp.setMortParams(mort); + Individual ind13(&sp, init_cell, init_patch, 1, 0, 0, 0.0, false, 0); + isDispersing = ind13.moveKernel(&ls, &sp, false); + assert(ind13.getStatus() != 7); + + // Reset mortality params + trfr.distMort = false; + mort.fixedMort = 0.0; + sp.setTrfrRules(trfr); + sp.setMortParams(mort); +} + +void testTransferCRW() { + + // Simple 5*5 cell-based landscape layout + int lsDim = 5; + landParams ls_params = createDefaultLandParams(lsDim); + double cellDiagLength = ls_params.resol * SQRT2; + + Landscape ls; + ls.setLandParams(ls_params, true); + + // All cells are suitable + const int hab_index = 0; + vector cell_vec; + for (int x = ls_params.minX; x < ls_params.dimX; ++x) { + for (int y = ls_params.minY; y < ls_params.dimY; ++y) { + cell_vec.push_back(new Cell(x, y, 0, hab_index)); + } + } + Cell* init_cell = cell_vec[12]; // central + ls.setCellArray(); + for (auto c : cell_vec) ls.addCellToLand(c); + + // Set up species + Species sp; + + // Habitat codes + sp.createHabK(1); + sp.setHabK(hab_index, 100.0); // one habitat with K = 100 + + // Habitat-dependent mortality + sp.createHabCostMort(1); + + // Transfer rules + transferRules trfr; + trfr.indVar = false; + trfr.habMort = false; + trfr.moveType = 2; // CRW + sp.setTrfrRules(trfr); + + // Transfer CRW traits + trfrMovtParams m; + m.stepMort = 0.0; + m.stepLength = cellDiagLength; // guaranteed to move out + m.rho = 1.0; + m.straightenPath = false; + sp.setSpMovtTraits(m); + + // Settlement rules + settleRules sett; + sett.wait = false; + sp.setSettRules(0, 0, sett); + settleSteps steps; + steps.maxSteps = 1; + steps.minSteps = 1; + steps.maxStepsYr = 1; + sp.setSteps(0, 0, steps); + + // Set up patches + ls.allocatePatches(&sp); + ls.updateCarryingCapacity(&sp, 0, 0); + Patch* init_patch = init_cell->getPatch(); + + // Create and set up individual + Individual ind0(&sp, init_cell, init_patch, 1, 0, 0, 0.0, true, 2); + + // Set status + assert(ind0.getStatus() == 0); // default status, not emigrating + int isDispersing = ind0.moveStep(&ls, &sp, hab_index, false); + assert(ind0.getStatus() == 0); // status didn't change + assert(ind0.getCurrCell() == init_cell); // not emigrating so didn't move + + //---------------------// + // Test per-step mortality + //---------------------// + + m.stepMort = 1.0; // should die + sp.setSpMovtTraits(m); + Individual ind1(&sp, init_cell, init_patch, 0, 0, 0, 0.0, true, 2); + // force-set path bc for some reason path gets deallocated upon exiting constructor?? + ind1.setStatus(1); + isDispersing = ind1.moveStep(&ls, &sp, hab_index, false); + // Individual begins in natal patch so mortality is disabled + assert(ind1.getStatus() != 7); + // Individual should be in a different patch + Cell* first_step_cell = ind1.getCurrCell(); + assert(first_step_cell != init_cell); + assert(first_step_cell->getPatch() != init_patch); + + ind1.setStatus(1); // emigrating again + + // Individual should die on second step + isDispersing = ind1.moveStep(&ls, &sp, hab_index, false); + assert(ind1.getCurrCell() == first_step_cell); // shouldn't have moved + assert(ind1.getStatus() == 7); // died by transfer + m.stepMort = 0.0; // not dying + sp.setSpMovtTraits(m); + + // Test habitat-depdt mortality + // ... + + //----------------// + // Test step size + //----------------// + + ls = Landscape(); + ls.setLandParams(ls_params, true); + sp.createHabK(2); + const int hab_suitable = 0; + const int hab_unsuitable = 1; + sp.setHabK(hab_suitable, 100.0); + sp.setHabK(hab_unsuitable, 0.0); + + // Initial cell unsuitable, suitable cell in opposite corner + init_cell = new Cell(0, 0, 0, hab_unsuitable); + Cell* final_cell = new Cell(ls_params.dimX - 1, ls_params.dimY - 1, 0, hab_suitable); + ls.setCellArray(); + ls.addCellToLand(init_cell); + ls.addCellToLand(final_cell); + ls.allocatePatches(&sp); + ls.updateCarryingCapacity(&sp, 0, 0); + // Init cell is NOT in natal patch + Patch* natalPatch = new Patch(0, 0); + init_patch = init_cell->getPatch(); + + // Step length is too short + m.stepLength = 0.1; // will not reach final cell + m.rho = 0.0; // random angle + sp.setSpMovtTraits(m); + steps.minSteps = 1; + steps.maxStepsYr = 2; + steps.maxSteps = 3; + sp.setSteps(0, 0, steps); + Individual ind2(&sp, init_cell, natalPatch, 0, 0, 0, 0.0, true, 2); + ind2.setStatus(1); // dispersing + // First step - still in unsuitable cell so still dispersing + isDispersing = ind2.moveStep(&ls, &sp, hab_index, false); + assert(ind2.getCurrCell() == init_cell); + assert(ind2.getStatus() == 1); // still dispersing + // Second step - reaching max steps this year, wait next year + isDispersing = ind2.moveStep(&ls, &sp, hab_index, false); + assert(ind2.getCurrCell() == init_cell); + assert(ind2.getStatus() == 3); // waiting for next year + ind2.setStatus(1); // dispersing again + // Third step - reaching max steps, dies in unsuitable cell + isDispersing = ind2.moveStep(&ls, &sp, hab_index, false); + assert(ind2.getCurrCell() == init_cell); + assert(ind2.getStatus() == 6); // died while dispersing + + // Step length too long + m.stepLength = ls_params.dimX * SQRT2 * 1.5; // overshoots + sp.setSpMovtTraits(m); + Individual ind3(&sp, init_cell, init_patch, 0, 0, 0, 0.0, true, 2); + ind3.setStatus(1); // dispersing + steps.minSteps = 1; + steps.maxStepsYr = 1; + steps.maxSteps = 1; // no need to test more than one step this time + sp.setSteps(0, 0, steps); + isDispersing = ind3.moveStep(&ls, &sp, hab_index, false); + assert(ind3.getCurrCell() == init_cell); + assert(ind3.getStatus() == 6); + + // Adequate step length + m.stepLength = (ls_params.dimX - 1) * SQRT2; + sp.setSpMovtTraits(m); + Individual ind4(&sp, init_cell, natalPatch, 0, 0, 0, 0.0, true, 2); + ind4.setStatus(1); // dispersing + // Initial angle still random but should eventually reach the suitable cell + isDispersing = ind4.moveStep(&ls, &sp, hab_index, false); + assert(ind4.getStatus() == 2); + assert(ind4.getCurrCell() == final_cell); + + // If boundaries are absorbing however, most likely to die + Individual ind5(&sp, init_cell, natalPatch, 0, 0, 0, 0.0, true, 2); + ind5.setStatus(1); // dispersing + bool absorbing_boundaries = true; + isDispersing = ind5.moveStep(&ls, &sp, hab_index, absorbing_boundaries); + assert(ind5.getStatus() == 6); + assert(ind5.getCurrCell() == 0); // deref apparently + + // Correlation parameter + // If rho = 1 should move in a straight line + // Many cells, all suitable + lsDim = 10; + ls_params = createDefaultLandParams(lsDim); + ls = Landscape(); + ls.setLandParams(ls_params, true); + cell_vec.clear(); + for (int x = ls_params.minX; x < ls_params.dimX; ++x) { + for (int y = ls_params.minY; y < ls_params.dimY; ++y) { + cell_vec.push_back(new Cell(x, y, 0, hab_suitable)); + } + } + ls.setCellArray(); + for (auto c : cell_vec) ls.addCellToLand(c); + ls.allocatePatches(&sp); + ls.updateCarryingCapacity(&sp, 0, 0); + // Individual moves by 1 along the diagonal + m.stepLength = cellDiagLength; // 1 diagonal cell + m.rho = 1; // angle = previous angle + sp.setSpMovtTraits(m); + steps.maxStepsYr = steps.maxSteps = ls_params.dimX; + sp.setSteps(0, 0, steps); + Individual ind6(&sp, cell_vec[0], natalPatch, 0, 0, 0, 0.0, true, 2); + const float diag_angle = PI / 4.0; // 45 degrees + ind6.setInitAngle(diag_angle); + // Individual moves only along diagonal cells + for (int i = 1; i < ls_params.dimX; ++i) { + ind6.setStatus(1); // dispersing + isDispersing = ind6.moveStep(&ls, &sp, hab_index, false); + assert(ind6.getStatus() == 2); + assert(ind6.getCurrCell() == cell_vec[i * (ls_params.dimX + 1)]); + } +} + +void testGenetics() { + + // Individuals inherit alleles from their parents + { + // 1 - Diploid case, 2 parents with diff. alleles + { + const int genomeSz = 5; + const bool isDiploid{ true }; + SpeciesTrait* spTr = createTestEmigSpTrait(createTestGenePositions(genomeSz), isDiploid); + + // Heterozygote parent genotypes + const float valAlleleMotherA(1.0), valAlleleMotherB(2.0); + const float valAlleleFatherA(3.0), valAlleleFatherB(4.0); + auto motherGenotype = createTestGenotype(genomeSz, isDiploid, valAlleleMotherA, valAlleleMotherB); + auto fatherGenotype = createTestGenotype(genomeSz, isDiploid, valAlleleFatherA, valAlleleFatherB); + const int startMotherChr = 0; // Strand A + const int startFatherChr = 1; // Strand B + + // Create individual trait objects + DispersalTrait dispTrParent(spTr); // initialisation constructor + DispersalTrait dispTrChild(dispTrParent); // inheritance constructor + + set recomSites{}; // no recombination + + dispTrChild.triggerInherit(true, motherGenotype, recomSites, startMotherChr); + dispTrChild.triggerInherit(false, fatherGenotype, recomSites, startFatherChr); + + // Child should have inherited strand A from mother and strand B from father + float valChildAlleleA, valChildAlleleB; + for (int i = 0; i < genomeSz; i++) { + valChildAlleleA = dispTrChild.getAlleleValueAtLocus(0, i); + assert(valChildAlleleA == valAlleleMotherA); + valChildAlleleB = dispTrChild.getAlleleValueAtLocus(1, i); + assert(valChildAlleleB == valAlleleFatherB); + } + } + + // 2 - Haploid case, simply copy parent + { + const int genomeSz = 5; + const bool isDiploid{ false }; + SpeciesTrait* spTr = createTestEmigSpTrait(createTestGenePositions(genomeSz), isDiploid); + + // Heterozygote parent genotypes + const float valAlleleMother(5.0); + auto motherGenotype = createTestGenotype(genomeSz, isDiploid, valAlleleMother); + const int startMotherChr = 999; // doesn't matter, not used + + // Create individual trait objects + DispersalTrait dispTrParent(spTr); // initialisation constructor + DispersalTrait dispTrChild(dispTrParent); // inheritance constructor + + set recomSites; + for (unsigned int i = 0; i < genomeSz; i++) + recomSites.insert(i); // recombination should be ignored + + dispTrChild.triggerInherit(true, motherGenotype, recomSites, startMotherChr); + + // Child should have inherited strand B from mother + float valChildAllele; + for (int i = 0; i < genomeSz; i++) { + valChildAllele = dispTrChild.getAlleleValueAtLocus(0, i); + assert(valChildAllele == valAlleleMother); + } + } + } + + // Recombination occurs just after selected recombination site + { + const int genomeSz = 3; + const bool isDiploid{ true }; + SpeciesTrait* spTr = createTestEmigSpTrait(createTestGenePositions(genomeSz), isDiploid); + + // Create individual trait objects + DispersalTrait dispTrParent(spTr); // initialisation constructor + + // Fill mother gene sequence + const float valAlleleA(0.0), valAlleleB(1.0); + // Mother genotype: + // 000 + // 111 + auto motherGenotype = createTestGenotype(genomeSz, isDiploid, valAlleleA, valAlleleB); + + // Trigger inheritance from mother + const vector recombinationSites{0, 1, genomeSz - 1}; // should work for any position + const int startingChr{0}; // Chromosome A + + for (unsigned int site : recombinationSites) { + DispersalTrait dispTrChild(dispTrParent); // inheritance constructor + dispTrChild.triggerInherit(true, motherGenotype, set{site}, startingChr); + // for this test we ignore inheritance from father + + // Mother-inherited alleles should have value of chr A before recombination site, chr B after + float valMotherAllele; + for (int i = 0; i < genomeSz; i++) { + valMotherAllele = dispTrChild.getAlleleValueAtLocus(0, i); + assert(valMotherAllele == (i <= site ? valAlleleA : valAlleleB)); + // don't check other chromosome, empty bc we did not resolve father inheritance + } + } + } + + // Traits that are not inherited sample their mutations in initial distribution + { + const float initialAlleleVal = 0.5; + const float parentAlleleVal = 0.8; + const bool isInherited = false; + + const int genomeSz = 5; + const bool isDiploid{ false }; + + // Create species trait + const map distParams{ + // all alleles initialised at a single value + pair{GenParamType::MIN, initialAlleleVal}, + pair{GenParamType::MAX, initialAlleleVal} + }; + + const set genePositions = createTestGenePositions(genomeSz); + + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::E_D0, + sex_t::NA, + genePositions, + ExpressionType::ADDITIVE, + genePositions, // initial positions (all) + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, not used + isInherited, + 0.0, // no mutations + DistributionType::UNIFORM, distParams, // ignored + DistributionType::NONE, distParams, // no dominance, not used + isDiploid ? 2 : 1, + false + ); + + // Create individual trait objects + DispersalTrait dispTrParent(spTr); // initialisation constructor + auto parentGenotype = createTestGenotype(genomeSz, isDiploid, parentAlleleVal); + const int startMotherChr = 999; // doesn't matter, not used + dispTrParent.overwriteGenes(parentGenotype); + assert(dispTrParent.getAlleleValueAtLocus(0, 0) == parentAlleleVal); + + DispersalTrait dispTrChild(dispTrParent); // inheritance constructor + + set recomSites{genomeSz - 1}; + dispTrChild.triggerInherit(true, parentGenotype, recomSites, startMotherChr); + + // Child does not inherit from mother, + // instead allele value is initial value + float valChildAllele; + for (int i = 0; i < genomeSz; i++) { + valChildAllele = dispTrChild.getAlleleValueAtLocus(0, i); + assert(valChildAllele == initialAlleleVal); + } + } + + // Genetic fitness mutations are constrained between -1 or 1 + // + sampled dominance coefficients are always positive + { + { + // Most likely (~96%) to sample a mutation > 1 + const float gammaMutShapeParam = 5.0; + const float gammaMutScaleParam = 1.0; + // Normal centered on 0 : ~50% of sampling negative dominance coefficient + const float dominanceMeanParam = 0.0; + const float dominanceSdParam = 1.0; + + const int genomeSz = 5; + const bool isDiploid{ false }; + + // Create species trait + const map mutationParams{ + pair{GenParamType::SHAPE, gammaMutShapeParam}, + pair{GenParamType::SCALE, gammaMutScaleParam} + }; + const map dominanceParams{ + pair{GenParamType::MEAN, dominanceMeanParam}, + pair{GenParamType::SD, dominanceSdParam} + }; + const map placeholderParams = mutationParams; + + const set genePositions = createTestGenePositions(genomeSz); + + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::GENETIC_LOAD1, + sex_t::NA, + genePositions, + ExpressionType::MULTIPLICATIVE, + genePositions, + DistributionType::NONE, placeholderParams, // not used for genetic load + DistributionType::NONE, dominanceParams, + true, + 1.0, // every site mutates + DistributionType::GAMMA, mutationParams, + DistributionType::NORMAL, dominanceParams, + isDiploid ? 2 : 1, + false + ); + + // Create individual trait object + GeneticFitnessTrait traitInd(spTr); // initialisation constructor + traitInd.mutate(); + for (int i = 0; i < genomeSz; i++) { + float valAllele = traitInd.getAlleleValueAtLocus(0, i); + assert(valAllele <= 1.0); + float domCoef = traitInd.getDomCoefAtLocus(0, i); + assert(domCoef >= 0.0); + } + } + + { + // 1/2 chance to sample a mutation < -1 + const float normalMutMeanParam = 0; + const float normalMutSdParam = 1.0; + + const int genomeSz = 10; + const bool isDiploid{ false }; + + // Create species trait + const map mutationParams{ + // all alleles initialised at a single value + pair{GenParamType::MEAN, normalMutMeanParam}, + pair{GenParamType::SD, normalMutSdParam} + }; + const map placeholderParams = mutationParams; + + const set genePositions = createTestGenePositions(genomeSz); + + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::GENETIC_LOAD1, + sex_t::NA, + genePositions, + ExpressionType::MULTIPLICATIVE, + genePositions, + DistributionType::NONE, placeholderParams, // not used for genetic load + DistributionType::NONE, placeholderParams, // doesn't matter for this test + true, + 1.0, // every site mutates + DistributionType::NORMAL, mutationParams, + DistributionType::NORMAL, placeholderParams, // doesn't matter for this test + isDiploid ? 2 : 1, + false + ); + + // Create individual trait object + GeneticFitnessTrait traitInd(spTr); // initialisation constructor + traitInd.mutate(); + for (int i = 0; i < genomeSz; i++) { + float valAllele = traitInd.getAlleleValueAtLocus(0, i); + assert(valAllele > -1.0); + } + } + } +} + +bool haveSameEmigD0Allele(const Individual& indA, const Individual& indB, const int& position, short whichHaplo = 0) { + return indA.getTrait(E_D0)->getAlleleValueAtLocus(whichHaplo, position) + == indB.getTrait(E_D0)->getAlleleValueAtLocus(whichHaplo, position); +} + +void testIndividual() { + + // Kernel-based transfer + testTransferKernels(); + + // Correlated random walk (CRW) + testTransferCRW(); + + testGenetics(); + + // Genetic linkage + Chromosome breaks + // Considering diallelic genes A, B, C, D with: + // A, B, C are on chr.1, D is on chr.2 + // A, B are adjacent, C sits on the other end of chr.1 + // C, D have adjacent positions in genome (but are on separate chr.) + // AB------------C//D + // We simulate 100 inheritance + recombination processes and expect that: + // 1. freq(A,B have same alleles) >> freq(A,C have same alleles) + // 2. 0.65 > freq(C,D have same alleles) > 0.35 despite being adjacent because of chrom. break + // (both freq. have p < 0.001 from a binomial with p 0.5 and 100 trials) + { + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + const float recombinationRate = 0.01; + const int genomeSz = 10; + + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz-2, genomeSz - 1}, // two chromosomes + genomeSz, + recombinationRate, + set{}, "none", set{}, 0 // no output so no sampling + ); + + int posA = 0; + int posB = 1; + int posC = genomeSz - 2; + int posD = genomeSz - 1; + const set genePositions = {posA, posB, posC, posD}; + const bool isDiploid{ true }; + SpeciesTrait* spTr = createTestEmigSpTrait(genePositions, isDiploid); + pSpecies->addTrait(TraitType::E_D0, *spTr); + + Individual indMother = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + Individual indFather = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 1.0, false, 0); + indMother.setUpGenes(pSpecies, 1.0); + indFather.setUpGenes(pSpecies, 1.0); + + int countRecombineTogetherAB = 0; + int countRecombineTogetherAC = 0; + int countRecombineTogetherCD = 0; + + const int nbTrials = 100; + for (int i = 0; i < nbTrials; ++i) + { + Individual indChild = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + indChild.inheritTraits(pSpecies, &indMother, &indFather, 1.0); + + bool hasInheritedA0 = haveSameEmigD0Allele(indChild, indMother, posA); + bool hasInheritedB0 = haveSameEmigD0Allele(indChild, indMother, posB); + bool hasInheritedC0 = haveSameEmigD0Allele(indChild, indMother, posC); + bool hasInheritedD0 = haveSameEmigD0Allele(indChild, indMother, posD); + + countRecombineTogetherAB += (hasInheritedA0 && hasInheritedB0) + || (!hasInheritedA0 && !hasInheritedB0); + countRecombineTogetherAC += (hasInheritedA0 && hasInheritedC0) + || (!hasInheritedA0 && !hasInheritedC0); + countRecombineTogetherCD += (hasInheritedC0 && hasInheritedD0) + || (!hasInheritedC0 && !hasInheritedD0); + } + assert(countRecombineTogetherAB > countRecombineTogetherAC); + assert(35 < countRecombineTogetherCD && countRecombineTogetherCD < 65); + } + + // Sex-specific traits use the correct genes + /// Set up a sex-dependent emigration probability with male and female loci + /// Emigration probability is 1 initially, but female trait mutates. + { + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Species-level paramters + const int genomeSz = 6; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + emigRules emig; + emig.indVar = true; + emig.sexDep = true; + emig.densDep = false; + pSpecies->setEmigRules(emig); + + // Create species trait + //// Shared params + const map initParams{ + // all values are 1 + pair{GenParamType::MIN, 1.0}, + pair{GenParamType::MAX, 1.0} + }; + const map mutationParams{ + // reduction of emigration probability + pair{GenParamType::MIN, -0.5}, + pair{GenParamType::MAX, -0.25} + }; + const bool isDiploid{ true }; + + //// Sex-specific params + const set maleGenePositions = { 0, 2, 4 }; + const set femaleGenePositions = { 1, 3, 5 }; + const float maleMutationRate = 0.0; + const float femaleMutationRate = 1.0; + + SpeciesTrait* spTrM = new SpeciesTrait( + TraitType::E_D0_M, + sex_t::MAL, + maleGenePositions, + ExpressionType::AVERAGE, + maleGenePositions, + // Set all initial alleles values to 1 + DistributionType::UNIFORM, initParams, + DistributionType::NONE, initParams, // no dominance, params are ignored + true, // isInherited + maleMutationRate, // does not mutate + DistributionType::UNIFORM, mutationParams, // not used + DistributionType::NONE, initParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + pSpecies->addTrait(TraitType::E_D0_M, *spTrM); + + SpeciesTrait* spTrF = new SpeciesTrait( + TraitType::E_D0_F, + sex_t::FEM, + femaleGenePositions, + ExpressionType::AVERAGE, + femaleGenePositions, + // Set all initial alleles values to 1 + DistributionType::UNIFORM, initParams, + DistributionType::NONE, initParams, // no dominance, params are ignored + true, // isInherited + femaleMutationRate, // does mutate + DistributionType::UNIFORM, mutationParams, // not used + DistributionType::NONE, initParams, + isDiploid ? 2 : 1, + false + ); + pSpecies->addTrait(TraitType::E_D0_F, *spTrF); + + // Set up male and female individuals, trigger mutations + Individual indFemale = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + Individual indMale = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 1.0, false, 0); + indFemale.setUpGenes(pSpecies, 1.0); + indMale.setUpGenes(pSpecies, 1.0); + indFemale.triggerMutations(pSpecies); + indMale.triggerMutations(pSpecies); + + // Male should use male trait, still 1 + // Female should use female trait, has mutated + emigTraits femaleEmig = indFemale.getIndEmigTraits(); + emigTraits maleEmig = indMale.getIndEmigTraits(); + assert(femaleEmig.d0 != 1.0); + assert(maleEmig.d0 == 1.0); + } + + // Individuals use species-level trait when not individual variable, + // and individual-level trait when trait is individual variable + { + float spEmigProb = 1.0; + float indEmigProb = 0.0; + + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Species-level paramters + const int genomeSz = 1; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + emigRules emig; + emig.indVar = false; + emig.stgDep = false; emig.sexDep = false; emig.densDep = false; + pSpecies->setEmigRules(emig); + + emigTraits spEmigTraits; spEmigTraits.d0 = spEmigProb; + pSpecies->setSpEmigTraits(0, 0, spEmigTraits); + + // Create species trait + const map initParams{ + // Emigration probability is always 0 + pair{GenParamType::MIN, indEmigProb}, + pair{GenParamType::MAX, indEmigProb} + }; + const map mutationParams = initParams; // doesn't matter, not used + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::E_D0, + sex_t::NA, + set{ 0 }, // only one locus + ExpressionType::AVERAGE, + set{ 0 }, // initial positions + DistributionType::UNIFORM, initParams, + DistributionType::NONE, initParams, // no dominance, params are ignored + true, // isInherited + 0.0, // no mutation + DistributionType::UNIFORM, mutationParams, // not used + DistributionType::NONE, initParams, // no dominance, params are ignored + 2, // diploid + false + ); + pSpecies->addTrait(TraitType::E_D0, *spTr); + + Individual ind = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + ind.setUpGenes(pSpecies, 1.0); + + // Create population to trigger emigration selection + Population pop(pSpecies, pPatch, 0, 1.0); + pop.recruit(&ind); + assert(ind.getStatus() == 0); + pop.emigration(100.0); + + // Individual is using the species-wide emigration prob, + // so should be selected to emigrate (status 1) + assert(ind.getStatus() == 1); + + // Change rules to use individual-variable trait + ind.setStatus(0); + emig.indVar = true; + pSpecies->setEmigRules(emig); + pop.emigration(100.0); + + // Individual-level emig prob is zero, must not be emigrating; + assert(ind.getStatus() == 0); + + pop.clearInds(); // empty inds vector to not deallocate individual twice + } + + // Individuals with genetic fitness = 1 are always viable + // Individuals with genetic fitness = 0 are never viable + { + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Species-level paramters + const int genomeSz = 1; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + + // Create species trait + const map mutationParams{ + // Always sample 1 = a lethal mutation + pair{GenParamType::MIN, 1.0}, + pair{GenParamType::MAX, 1.0} + }; + const map domParams = mutationParams; // all dominance parameters are equal + const map initParams = mutationParams; // doesn't matter, not used + + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::GENETIC_LOAD1, + sex_t::NA, + set{ 0 }, // only one locus + ExpressionType::MULTIPLICATIVE, + set{ 0 }, + DistributionType::NONE, initParams, + DistributionType::UNIFORM, domParams, + true, // isInherited + 1.0, // will mutate + DistributionType::UNIFORM, mutationParams, // lethal mutation + DistributionType::UNIFORM, domParams, + 2, // diploid + false + ); + + pSpecies->addTrait(TraitType::GENETIC_LOAD1, *spTr); + + Individual ind = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + ind.setUpGenes(pSpecies, 1.0); + + // By default, all loci are initialised at 0 so individual is viable + assert(ind.getGeneticFitness() == 1.0); + assert(ind.isViable()); + + ind.triggerMutations(pSpecies); + + // Individual now bears a lethal allele + assert(ind.getGeneticFitness() == 0.0); + assert(!ind.isViable()); + } + + // A largely dominant allele overrides the expression of its homologue + { + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Species-level paramters + const int genomeSz = 1; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + + // Create template species trait + const map distParams{ + pair{GenParamType::MIN, 0.0}, + pair{GenParamType::MAX, 0.0} + }; + // Pretty empty, actual values are set below + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::GENETIC_LOAD1, + sex_t::NA, + set{ 0 }, // only one locus + ExpressionType::MULTIPLICATIVE, + set{ 0 }, + DistributionType::NONE, distParams, + DistributionType::UNIFORM, distParams, + true, // isInherited + 0.0, // no mutation + DistributionType::UNIFORM, distParams, + DistributionType::UNIFORM, distParams, + 2, // diploid + false + ); + pSpecies->addTrait(TraitType::GENETIC_LOAD1, *spTr); + + Individual ind = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + ind.setUpGenes(pSpecies, 1.0); + + const float valAlleleA = 1.0; // lethal + const float valAlleleB = 0.0; // mild + float domCoefA = 0.00001; // highly recessive + float domCoefB = 1.0; + auto viableGenotype = createTestGenotype(genomeSz, true, valAlleleA, valAlleleB, domCoefA, domCoefB); + ind.overrideGenotype(GENETIC_LOAD1, viableGenotype); + ind.triggerMutations(pSpecies); // no mutations (rate = 0) but updates genetic fitness + assert(ind.isViable()); + + domCoefA = 10000.0; // oh gosh now it's lethal AND dominant + auto lethalGenotype = createTestGenotype(genomeSz, true, valAlleleA, valAlleleB, domCoefA, domCoefB); + ind.overrideGenotype(GENETIC_LOAD1, lethalGenotype); + ind.triggerMutations(pSpecies); + assert(!ind.isViable()); + } + + // Dispersal trait alleles can take any value, but + // phenotypes are constrained to valid values + { + // Case 1 - Settlement + Kernel-based transfer + { + const int genomeSz = 4; + + const bool isDiploid{ true }; // haploid, simpler check + const float mutationRate = 0.0; // no mutations + + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Genome-level settings + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + + settleType sett; + sett.indVar = true; + sett.sexDep = false; + sett.stgDep = false; + pSpecies->setSettle(sett); + settleRules settRules; + settRules.densDep = true; + pSpecies->setSettRules(0, 0, settRules); + + transferRules trfr; + trfr.indVar = true; + trfr.usesMovtProc = false; + trfr.moveType = 0; // kernels + trfr.twinKern = false; + trfr.sexDep = false; + trfr.stgDep = false; + pSpecies->setTrfrRules(trfr); + + // Species-level traits + const map distParams{ + // prameters don't matter, allele values are overwritten below + pair{GenParamType::MIN, 1.0}, + pair{GenParamType::MAX, 1.0} + }; + SpeciesTrait* trSettProb = new SpeciesTrait( + TraitType::S_S0, + sex_t::NA, + set{ 0 }, + ExpressionType::AVERAGE, + set{ 0 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trSettAlpha = new SpeciesTrait( + TraitType::S_ALPHA, + sex_t::NA, + set{ 1 }, + ExpressionType::AVERAGE, + set{ 1 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trSettBeta = new SpeciesTrait( + TraitType::S_BETA, + sex_t::NA, + set{ 2 }, + ExpressionType::AVERAGE, + set{ 2 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trMeanKern = new SpeciesTrait( + TraitType::KERNEL_MEANDIST_1, + sex_t::NA, + set{ 3 }, + ExpressionType::ADDITIVE, + set{ 3 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + + pSpecies->addTrait(TraitType::S_S0, *trSettProb); + pSpecies->addTrait(TraitType::S_ALPHA, *trSettAlpha); + pSpecies->addTrait(TraitType::S_BETA, *trSettBeta); + pSpecies->addTrait(TraitType::KERNEL_MEANDIST_1, *trMeanKern); + + Individual ind = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, false, 0); + ind.setUpGenes(pSpecies, 1.0); + + // Overwrite genotypes with alleles resulting in invalid phenotypes + auto sProbGenotype = createTestGenotype(genomeSz, true, 1.1, 1.2); + auto sAlphaGenotype = createTestGenotype(genomeSz, true, -1.5, -0.5); + auto kernelDistGenotype = createTestGenotype(genomeSz, true, -0.2, -0.4); + ind.overrideGenotype(S_S0, sProbGenotype); + ind.overrideGenotype(S_ALPHA, sAlphaGenotype); + ind.overrideGenotype(KERNEL_MEANDIST_1, kernelDistGenotype); + // any value is valid for settlement beta + + ind.triggerMutations(pSpecies); // no mutations, but trigger expression + + settleTraits settTr = ind.getIndSettTraits(); + assert(settTr.s0 <= 1.0); + assert(settTr.alpha > 0.0); + kernelData trfrTr = *(static_cast(ind.getTrfrData())); + assert(trfrTr.meanDist1 >= 0.0); + } + + // Case 2 - Correlated random walk transfer + { + const int genomeSz = 2; + + const bool isDiploid{ true }; // haploid, simpler check + const float mutationRate = 0.0; // no mutations + + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Genome-level settings + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + + settleType sett; + sett.indVar = false; + pSpecies->setSettle(sett); + + transferRules trfr; + trfr.indVar = true; + trfr.usesMovtProc = true; + trfr.moveType = 2; // CRW + pSpecies->setTrfrRules(trfr); + + // Species-level traits + const map distParams{ + // prameters don't matter, allele values are overwritten below + pair{GenParamType::MIN, 1.0}, + pair{GenParamType::MAX, 1.0} + }; + SpeciesTrait* trCRWLen = new SpeciesTrait( + TraitType::CRW_STEPLENGTH, + sex_t::NA, + set{ 0 }, + ExpressionType::ADDITIVE, + set{ 0 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trCRWCorr = new SpeciesTrait( + TraitType::CRW_STEPCORRELATION, + sex_t::NA, + set{ 1 }, + ExpressionType::AVERAGE, + set{ 1 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + + pSpecies->addTrait(TraitType::CRW_STEPLENGTH, *trCRWLen); + pSpecies->addTrait(TraitType::CRW_STEPCORRELATION, *trCRWCorr); + + bool usesMovtProcess = true; + short whichMovtProcess = 2; // CRW + Individual ind = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, usesMovtProcess, whichMovtProcess); + ind.setUpGenes(pSpecies, 1.0); + + // Overwrite genotypes with alleles resulting in invalid phenotypes + auto crwLenGenotype = createTestGenotype(genomeSz, true, -1.1, -1.2); + auto crwCorrGenoType = createTestGenotype(genomeSz, true, 1.5, 2.0); + ind.overrideGenotype(CRW_STEPLENGTH, crwLenGenotype); + ind.overrideGenotype(CRW_STEPCORRELATION, crwCorrGenoType); + + ind.triggerMutations(pSpecies); // no mutations, but trigger expression + + crwData trfrTr = *(static_cast(ind.getTrfrData())); + assert(trfrTr.stepLength >= 0.0); + assert(trfrTr.rho <= 1.0); + } + + // Case 3 - Transfer with Stochastic Movement Simulator + { + const int genomeSz = 2; + const bool isDiploid{ true }; // haploid, simpler check + const float mutationRate = 0.0; // no mutations + + Patch* pPatch = new Patch(0, 0); + Cell* pCell = new Cell(0, 0, pPatch, 0); + + // Genome-level settings + Species* pSpecies = createDefaultSpecies(); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // one chromosome + genomeSz, + 0.0, // no recombination + set{}, "none", set{}, 0 // no output so no sampling + ); + + settleType sett; + sett.indVar = false; + pSpecies->setSettle(sett); + + transferRules trfr; + trfr.indVar = true; + trfr.usesMovtProc = true; + trfr.moveType = 1; // SMS + pSpecies->setTrfrRules(trfr); + + // Species-level traits + const map distParams{ + // prameters don't matter, allele values are overwritten below + pair{GenParamType::MIN, 1.0}, + pair{GenParamType::MAX, 1.0} + }; + SpeciesTrait* trSmsDirPers = new SpeciesTrait( + TraitType::SMS_DP, + sex_t::NA, + set{ 0 }, + ExpressionType::ADDITIVE, + set{ 0 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trSmsGoalBias = new SpeciesTrait( + TraitType::SMS_GB, + sex_t::NA, + set{ 1 }, + ExpressionType::AVERAGE, + set{ 1 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trSmsAlpha = new SpeciesTrait( + TraitType::SMS_ALPHADB, + sex_t::NA, + set{ 0 }, + ExpressionType::ADDITIVE, + set{ 0 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + SpeciesTrait* trSmsBeta = new SpeciesTrait( + TraitType::SMS_BETADB, + sex_t::NA, + set{ 1 }, + ExpressionType::AVERAGE, + set{ 1 }, + DistributionType::UNIFORM, distParams, + DistributionType::NONE, distParams, // no dominance, params are ignored + true, // isInherited + mutationRate, // does not mutate + DistributionType::UNIFORM, distParams, // not used + DistributionType::NONE, distParams, // no dominance, params are ignored + isDiploid ? 2 : 1, + false + ); + + pSpecies->addTrait(TraitType::SMS_DP, *trSmsDirPers); + pSpecies->addTrait(TraitType::SMS_GB, *trSmsGoalBias); + pSpecies->addTrait(TraitType::SMS_ALPHADB, *trSmsAlpha); + pSpecies->addTrait(TraitType::SMS_BETADB, *trSmsBeta); + + bool usesMovtProcess = true; + short whichMovtProcess = 1; // SMS + Individual ind = Individual(pSpecies, pCell, pPatch, 0, 0, 0, 0.0, usesMovtProcess, whichMovtProcess); + ind.setUpGenes(pSpecies, 1.0); + + // Overwrite genotypes with alleles resulting in invalid phenotypes + auto smsDPGenotype = createTestGenotype(genomeSz, true, 0.1, 0.2); + auto smsGBGenotype = createTestGenotype(genomeSz, true, 0.5, 0.0); + auto smsAlphaGenotype = createTestGenotype(genomeSz, true, 0.0, 0.0); + ind.overrideGenotype(SMS_DP, smsDPGenotype); + ind.overrideGenotype(SMS_GB, smsGBGenotype); + ind.overrideGenotype(SMS_ALPHADB, smsAlphaGenotype); + // any value is valid for SMS beta + + ind.triggerMutations(pSpecies); // no mutations, but trigger expression + + smsData trfrTr = *(static_cast(ind.getTrfrData())); + assert(trfrTr.dp >= 1.0); + assert(trfrTr.gb >= 1.0); + assert(trfrTr.alphaDB > 0.0); + } + } + +} + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/unit_tests/testNeutralStats.cpp b/RangeShiftR/src/RScore/unit_tests/testNeutralStats.cpp new file mode 100644 index 0000000..50999c2 --- /dev/null +++ b/RangeShiftR/src/RScore/unit_tests/testNeutralStats.cpp @@ -0,0 +1,1072 @@ +#ifdef UNIT_TESTS + +#include "../Community.h" + +void testNeutralStats() { + + // In haploid settings, Ho is always zero + { + // Create empty 1-patch, 1-cell landscape + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(0); + const set patchList{ pPatch->getPatchNum() }; + const string indSampling = "all"; + const set stgToSample = { 1 }; + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + // Create genetic structure + const int genomeSz = 4; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultHaploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const set genePositions = { 0, 1, 3 }; // arbitrary + const bool isDiploid{ false }; + const float maxAlleleVal = 0; // sample in uniform(0,0) so every individual is homozygote + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise population + const int nbInds = 2; + Population* pPop = new Population(pSpecies, pPatch, nbInds, 1); + pPop->sampleIndsWithoutReplacement(indSampling, stgToSample); + + // Calculate heterozygosity + auto pNeutralStatistics = make_unique(patchList.size(), genePositions.size()); + pNeutralStatistics->calculateHo( + patchList, + nbInds, + genePositions.size(), + pSpecies, + pLandscape + ); + assert(pNeutralStatistics->getHo() == 0.0); + } + + // If every individual in a sample is homozygote, Ho is zero + { + // Create empty 1-patch, 1-cell landscape + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(0); + const set patchList{ pPatch->getPatchNum() }; + const string indSampling = "all"; + const set stgToSample = { 1 }; + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + // Create genetic structure + const int genomeSz = 4; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const set genePositions = { 0, 1, 3 }; // arbitrary + const bool isDiploid{ true }; + const float maxAlleleVal = 0; // sample in uniform(0,0) so every individual is homozygote + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise population + const int nbInds = 2; + Population* pPop = new Population(pSpecies, pPatch, nbInds, 1); + pPop->sampleIndsWithoutReplacement(indSampling, stgToSample); + + // Calculate heterozygosity + auto pNeutralStatistics = make_unique(patchList.size(), genePositions.size()); + pNeutralStatistics->calculateHo( + patchList, + nbInds, + genePositions.size(), + pSpecies, + pLandscape + ); + assert(pNeutralStatistics->getHo() == 0.0); + } + + // If every individual in a sample is heterozygote, Ho is one. + { + // Create empty 1-patch, 1-cell landscape + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(0); + const set patchList{ pPatch->getPatchNum() }; + const string indSampling = "all"; + const set stgToSample = { 1 }; + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + // Create genetic structure + const int genomeSz = 4; + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const set genePositions = { 0, 2 }; // arbitrary + const bool isDiploid{ true }; + const float maxAlleleVal = 255; // highly unlikely that same value sampled twice + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise population + const int nbInds = 2; + Population* pPop = new Population(pSpecies, pPatch, nbInds, 1); + pPop->sampleIndsWithoutReplacement(indSampling, stgToSample); + + // Calculate heterozygosity + auto pNeutralStatistics = make_unique(patchList.size(), genePositions.size()); + pNeutralStatistics->calculateHo( + patchList, + nbInds, + genePositions.size(), + pSpecies, + pLandscape + ); + assert(pNeutralStatistics->getHo() == 1.0); + } + + // The correct number of individuals is sampled + { + const int nbIndsPopA = 15; + const int nbIndsPopB = 11; + const string indSampling = "13"; + const set stgToSample = { 1 }; + + // Patch setup + const int nbPatches = 2; + // Genetic setup + const int genomeSz = 2; + const bool isDiploid{ true }; + const set genePositions = { 0, 1 }; + const float maxAlleleVal = 1; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + Population* pPopA = new Population(pSpecies, patches[0], nbIndsPopA, 1); + Population* pPopB = new Population(pSpecies, patches[1], nbIndsPopB, 1); + pPopA->sampleIndsWithoutReplacement(indSampling, { indStg }); + pPopB->sampleIndsWithoutReplacement(indSampling, { indStg }); + + assert(pPopA->sampleSize() == stoi(indSampling)); // the correct nb of individuals has been sampled + assert(pPopB->sampleSize() == nbIndsPopB); // too small; all individuals have been sampled + } + + // If the sample is too small, Fst evaluates to zero + // More importantly, the neutral stats module still runs without error + { + // 1 - if there is zero population in the sample + { + // Patch setup + const int nbPatches = 2; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + const bool isDiploid = true; + const set genePositions = { 0 }; + const float maxAlleleVal = 0; + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Oops, no populations in patches + + // Compute F-stats + const int nbLoci = 0; + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = 0; + pNeutralStatistics->calculateFstatWC( + patchList, + 0, + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() == 0.0); + } // end case 1 - zero pop in sample + + // 2 - If there is only one population in the sample + { + // Patch setup + const int nbPatches = 2; + const int nbPops = nbPatches - 1; // oops, 1 population is missing + const int nbIndsPerPop = 5; + // Genetic setup + const int genomeSz = 2; + const bool isDiploid{ true }; + const set genePositions = { 0, 1 }; + const float maxAlleleVal = 0; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < nbPops; p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() == 0.0); + } // end case 2, only one population in sample + + // 3 - Two empty populations + { + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 0; // oops + + // Genetic setup + const int genomeSz = 2; + const bool isDiploid{ true }; + const set genePositions = { 0, 1 }; + const float maxAlleleVal = 0; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < nbPatches; p++) { + Population* pPop = new Population(pSpecies, patches[p], nbIndsPerPop, 1); + // create individuals and add to pop + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() == 0.0); + } + } + + // If two sampled pops are monomorphic for different alleles, + // then Fst is 1 + { + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 2; + // Genetic setup + const int genomeSz = 2; + const bool isDiploid{ true }; + const set genePositions = { 0, 1 }; + const float maxAlleleVal = 1; + unsigned char alleleValPopA = char(0); + unsigned char alleleValPopB = char(1); + auto popAGenotype = createTestNeutralGenotype(genomeSz, true, alleleValPopA, alleleValPopA); + auto popBGenotype = createTestNeutralGenotype(genomeSz, true, alleleValPopB, alleleValPopB); + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + vector>> genotypes = { popAGenotype, popBGenotype }; + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, genotypes[p]); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() == 1.0); + +// pNeutralStatistics->calcPairwiseWeightedFst( +// patchList, +// nbIndsPerPop* patchList.size(), +// nbLoci, +// pSpecies, +// pLandscape +// ); +// assert(pNeutralStatistics->getPairwiseFst(0, 1) == 0.0); + } + + double refWeirCockerhamDiploidFst; // for use in further tests below + + // In strictly homozygote samples: + // 1. Fis = 1 (maximum inbreeding) + // 2. The sign of the Fst depends on the ratio of variation within vs between populations + // 3. (if sample sizes are equal) The Weir&Cockerham 1984, Weir&Hill 2002 estimators yield the same values + { + // Case 1/2: variation within > between + // Within: frequencies of allele A and B are quite different + // Between: no variation + { + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 10; + // Genetic setup + const int genomeSz = 1; + const bool isDiploid{ true }; + const set genePositions = { 0 }; + const float maxAlleleVal = 1; + unsigned char alleleValPopA = char(0); + unsigned char alleleValPopB = char(1); + const auto genotypeAA = createTestNeutralGenotype(genomeSz, true, alleleValPopA, alleleValPopA); + const auto genotypeBB = createTestNeutralGenotype(genomeSz, true, alleleValPopB, alleleValPopB); + vector>> genotypes = { + // 8 AA, 2 BB (no heterozygotes) + genotypeAA, genotypeAA, genotypeAA, genotypeAA, genotypeBB, + genotypeAA, genotypeAA, genotypeAA, genotypeAA, genotypeBB + }; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, genotypes[i]); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() < 0.0); + assert(pNeutralStatistics->getFisWC() == 1.0); + + // pNeutralStatistics->calcPairwiseWeightedFst( + // patchList, + // nbIndsPerPop * patchList.size(), + // nbLoci, + // pSpecies, + // pLandscape + // ); + // const double tol = 0.000001; + // assert(abs(pNeutralStatistics->getWeightedFst() - pNeutralStatistics->getFstWC()) < tol); + + refWeirCockerhamDiploidFst = pNeutralStatistics->getFstWC(); // for use in further tests below + } + + // Case 2/2: variation within < between + // Within: no variation for pop1, same allelic frequencies + // Between: larger variation + { + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 10; + // Genetic setup + const int genomeSz = 1; + const bool isDiploid{ true }; + const set genePositions = { 0 }; + const float maxAlleleVal = 1; + unsigned char alleleValPopA = char(0); + unsigned char alleleValPopB = char(1); + const auto genotypeAA = createTestNeutralGenotype(genomeSz, true, alleleValPopA, alleleValPopA); + const auto genotypeBB = createTestNeutralGenotype(genomeSz, true, alleleValPopB, alleleValPopB); + vector>>> genotypeList = { + { // Pop 1: 5 AA, 5 BB (no heterozygotes) + genotypeAA, genotypeAA, genotypeAA, genotypeAA, genotypeAA, + genotypeBB, genotypeBB, genotypeBB, genotypeBB, genotypeBB + }, + { // Pop 2: 8 AA, 2 BB (no heterozygotes) + genotypeAA, genotypeAA, genotypeAA, genotypeAA, genotypeAA, + genotypeAA, genotypeAA, genotypeAA, genotypeBB, genotypeBB + } + }; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, genotypeList[p][i]); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop* patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() > 0.0); + assert(pNeutralStatistics->getFisWC() == 1.0); + + // // Weir & Hill population-specific estimates average to the (Weir & Hill) global estimator + // pNeutralStatistics->calcPairwiseWeightedFst( + // patchList, + // nbIndsPerPop* patchList.size(), + // nbLoci, + // pSpecies, + // pLandscape + // ); + // const double pop1Fst = pNeutralStatistics->getPairwiseFst(0, 0); + // const double pop2Fst = pNeutralStatistics->getPairwiseFst(1, 1); + // assert((pop1Fst + pop2Fst) / 2.0 == pNeutralStatistics->getWeightedFst()); + + } + } + + // In a strictly heterozygote sample, + // 1. Fis = -1 + // 2. If there is no variation between individuals, Fst = 0 + // 3. Weir & Cockerham 1984 estimator > Weir & Hill 2002 + { + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 10; + // Genetic setup + const int genomeSz = 1; + const bool isDiploid{ true }; + const set genePositions = { 0 }; + const float maxAlleleVal = 1; + unsigned char alleleValPopA = char(0); + unsigned char alleleValPopB = char(1); + const auto genotypeAB = createTestNeutralGenotype(genomeSz, true, alleleValPopA, alleleValPopB); + // all individuals have genotype AB + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, genotypeAB); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop* patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() == 0.0); + assert(pNeutralStatistics->getFisWC() == -1.0); + + // pNeutralStatistics->calcPairwiseWeightedFst( + // patchList, + // nbIndsPerPop* patchList.size(), + // nbLoci, + // pSpecies, + // pLandscape + // ); + // assert(pNeutralStatistics->getWeightedFst() < pNeutralStatistics->getFstWC()); + // Weir and Hill is still equal to Weir and Cockerham full homozygote case + // const double tol = 0.000001; + // assert(abs(pNeutralStatistics->getWeightedFst() - refWeirCockerhamDiploidFst) < tol); + } + + // Fst calculation is correct for an ordinary sample + { + // Two 10-individual pops, + // 1 tri-allelic locus + + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 10; + + // Genetic setup + const int genomeSz = 1; + const bool isDiploid{ true }; + const set genePositions = { 0 }; + const float maxAlleleVal = 2; + unsigned char alleleA = char(0); + unsigned char alleleB = char(1); + unsigned char alleleC = char(2); + // Create genotypes + auto genotypeAA = createTestNeutralGenotype(genomeSz, true, alleleA, alleleA); + auto genotypeAB = createTestNeutralGenotype(genomeSz, true, alleleA, alleleB); + auto genotypeAC = createTestNeutralGenotype(genomeSz, true, alleleA, alleleC); + auto genotypeBB = createTestNeutralGenotype(genomeSz, true, alleleB, alleleB); + auto genotypeBC = createTestNeutralGenotype(genomeSz, true, alleleB, alleleC); + auto genotypeCC = createTestNeutralGenotype(genomeSz, true, alleleC, alleleC); + vector>>> genotypeList = { + { // Genotypes of population 1 + genotypeAA, genotypeAA, genotypeAB, genotypeAB, genotypeAB, + genotypeAB, genotypeAC, genotypeAC, genotypeBB, genotypeCC + }, + { // Genotypes of population 2 + genotypeAA, genotypeAB, genotypeAC, genotypeBB, genotypeBC, + genotypeBC, genotypeBC, genotypeBC, genotypeCC, genotypeCC + } + }; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, genotypeList[p][i]); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + const double expectedFst = 0.0583; // calculated by hand from Weir and Cockerham 1984 + double calcError = abs(pNeutralStatistics->getFstWC() - expectedFst); + assert(calcError < 0.0001); + } + + // The Fst is a haploid sample equals that of a diploid sample if: + // 1 - allelic frequencies are equal + // 2 - the diploid sample has no heterozygotes + // (reference diploid Fst has already been calculated above) + { + const bool isDiploid{ false }; + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 10; + // Genetic setup + const int genomeSz = 1; + const set genePositions = { 0 }; + const float maxAlleleVal = 1; + unsigned char alleleValPopA = char(0); + unsigned char alleleValPopB = char(1); + const auto genotypeA = createTestNeutralGenotype(genomeSz, true, alleleValPopA); + const auto genotypeB = createTestNeutralGenotype(genomeSz, true, alleleValPopB); + vector>> genotypes = { + // 8 A, 2B (no heterozygotes) + genotypeA, genotypeA, genotypeA, genotypeA, genotypeB, + genotypeA, genotypeA, genotypeA, genotypeA, genotypeB + }; + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultHaploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, genotypes[i]); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getFstWC() == refWeirCockerhamDiploidFst); + } + + // Multi-locus case + // First locus has no variation between individuals, all heterozygotes (Fst = 0) + // Second locus has different fixed alleles between both populations (Fst = 1) + { + // Patch setup + const int nbPatches = 2; + const int nbIndsPerPop = 10; + // Genetic setup + const int genomeSz = 3; + const bool isDiploid{ true }; + const set genePositions = { 0, 2 }; // position 1 is arbitrarily empty + const float maxAlleleVal = 1; + unsigned char alleleValPopA = char(0); + unsigned char alleleValPopB = char(1); + map> genotypePop1; + map> genotypePop2; + // First locus: all heterozygotes, same genotype + genotypePop1.emplace(0, vector{alleleValPopA, alleleValPopB}); + genotypePop2.emplace(0, vector{alleleValPopA, alleleValPopB}); + // Second locus: different fixed alleles + genotypePop1.emplace(2, vector{alleleValPopA, alleleValPopA}); + genotypePop2.emplace(2, vector{alleleValPopB, alleleValPopB}); + + // Create two-patches landscape + Landscape* pLandscape = new Landscape; + vector patches(nbPatches); + vector cells(nbPatches); + set patchList; + for (int i = 0; i < nbPatches; i++) { + patches[i] = pLandscape->newPatch(i); + cells[i] = new Cell(0, 0, patches[i], 0); + patches[i]->addCell(cells[i], 0, 0); + patchList.insert(patches[i]->getPatchNum()); + } + const string indSampling = "all"; + const set stgToSample = { 1 }; + + // Create species trait structure + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + patchList, + indSampling, + stgToSample, + 1 + ); + const int nbLoci = genePositions.size(); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise populations + const int indStg = 1; + for (int p = 0; p < patches.size(); p++) { + Population* pPop = new Population(pSpecies, patches[p], 0, 1); + // create individuals and add to pop + for (int i = 0; i < nbIndsPerPop; i++) { + Individual* pInd = new Individual(pSpecies, cells[p], patches[p], indStg, 0, 0, 0.0, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + pInd->overrideGenotype(NEUTRAL, p == 0 ? genotypePop1 : genotypePop2); + pPop->recruit(pInd); + } + pPop->sampleIndsWithoutReplacement(indSampling, { indStg }); + } + + // Compute F-stats + auto pNeutralStatistics = make_unique(nbPatches, nbLoci); + pNeutralStatistics->updateAllNeutralTables( + pSpecies, + pLandscape, + patchList + ); + const int maxNbNeutralAlleles = static_cast(maxAlleleVal) + 1; + pNeutralStatistics->calculateFstatWC( + patchList, + nbIndsPerPop * patchList.size(), + nbLoci, + maxNbNeutralAlleles, + pSpecies, + pLandscape, + false + ); + assert(pNeutralStatistics->getPerLocusFst(0) == 0.0); + assert(pNeutralStatistics->getPerLocusFst(1) == 1.0); + } +} + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RScore/unit_tests/testPopulation.cpp b/RangeShiftR/src/RScore/unit_tests/testPopulation.cpp new file mode 100644 index 0000000..c8dda07 --- /dev/null +++ b/RangeShiftR/src/RScore/unit_tests/testPopulation.cpp @@ -0,0 +1,307 @@ +#ifdef UNIT_TESTS + +#include "../Individual.h" +#include "../Population.h" + +void testPopulation() +{ + // Given a genetic load trait, offspring + // Survival is (inversely) proportional to the mutation rate + { + vector mutationRates = { 0.0, 0.1, 0.2 }; + vector survivingInds; + const int initialNbInds = 1000; + const float localK = 10000; // not limiting + vector localScaling = {1.0}; + + // Simple genetic layout + const bool isDiploid{ false }; // haploid suffices + const int genomeSz = 1; + const set genePositions = { 0 }; + + // All mutations are dominant lethal + const map mutParams{ + pair{GenParamType::MIN, 1}, + pair{GenParamType::MAX, 1} + }; + const map domParams{ + pair{GenParamType::MIN, 1}, + pair{GenParamType::MAX, 1} + }; + + for (float mutationRate : mutationRates) { + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(1); + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + Species* pSpecies = createDefaultSpecies(); + pSpecies->setDemogr(createDefaultHaploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + { }, "none", { }, 0 // no sampling + ); + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::GENETIC_LOAD, + sex_t::NA, + genePositions, + ExpressionType::MULTIPLICATIVE, + genePositions, // initial positions (all) + DistributionType::NONE, map{}, + DistributionType::UNIFORM, domParams, + true, // isInherited + mutationRate, // mutation rate + DistributionType::UNIFORM, mutParams, + DistributionType::UNIFORM, domParams, + isDiploid ? 2 : 1, + false + ); + pSpecies->addTrait(TraitType::GENETIC_LOAD, *spTr); + + Population pop = Population(pSpecies, pPatch, initialNbInds, 1); + pop.reproduction(localK, 1, 1, localScaling); // juveniles are checked for viability at birth + pop.fledge(); // non-overlapping: adults are replaced with juveniles + survivingInds.push_back(pop.getNbInds()); + } + assert(survivingInds[0] > survivingInds[1] + && survivingInds[1] > survivingInds[2]); + } + + // Dispersal is proportional to the mutation rate + { + vector mutationRates = { 0.0, 0.05, 0.1 }; + vector emigratingInds; + const int initialNbInds = 1000; + const float localK = 10000; // not limiting + vector localScaling = {1.0}; + + // Simple genetic layout + const bool isDiploid{ false }; // haploid suffices + const int genomeSz = 1; + const set genePositions = { 0 }; + + // Wild-types never emigrate, mutants always do + const map initParams{ + pair{GenParamType::MIN, 0}, + pair{GenParamType::MAX, 0} + }; + const map mutParams{ + pair{GenParamType::MIN, 1}, + pair{GenParamType::MAX, 1} + }; + + for (float mutationRate : mutationRates) { + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(1); + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + Species* pSpecies = createDefaultSpecies(); + emigRules emig; + emig.indVar = true; + emig.sexDep = false; + emig.densDep = false; + emig.stgDep = false; + pSpecies->setEmigRules(emig); + stageParams stg; + stg.nStages = 2; + pSpecies->setStage(stg); + pSpecies->setDemogr(createDefaultHaploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + { }, "none", { }, 0 // no sampling + ); + SpeciesTrait* spTr = new SpeciesTrait( + TraitType::E_D0, + sex_t::NA, + genePositions, + ExpressionType::ADDITIVE, + genePositions, // initial positions (all) + DistributionType::UNIFORM, initParams, // initial distribution and params + DistributionType::NONE, map{}, // initial dominance (none) + true, // isInherited + mutationRate, // mutation rate + DistributionType::UNIFORM, mutParams, // mutation dist and params + DistributionType::NONE, map{}, // no dominance + isDiploid ? 2 : 1, + false + ); + pSpecies->addTrait(TraitType::E_D0, *spTr); + + Population pop = Population(pSpecies, pPatch, initialNbInds, 1); + pop.reproduction(localK, 1, 1, localScaling); + pop.fledge(); // replace initial pop with juveniles + pop.emigration(localK); // select and flag emigrants + int popSize = pop.getNbInds(); + for (int i = 0; i < popSize; i++) { + pop.extractDisperser(i); // rm emigrants from pop + } + pop.clean(); + int nbEmigrating = popSize - pop.getNbInds(); // diff is nb of emigrants + if (mutationRate == 0.0) + assert(nbEmigrating == 0); + emigratingInds.push_back(nbEmigrating); + } + assert(emigratingInds[0] < emigratingInds[1] && emigratingInds[1] < emigratingInds[2]); + } + + // In the absence of selection, drift is solely responsible + // for changes in allele frequencies + { + const float tolerance = 0.02; + const float hetzTolerance = 0.05; + + float mutationRate = 0.0; + const float localK = 10000.0; + vector localScaling = {1.0}; + const int initialNbInds = localK; + const float initFreqA = 0.30; + const float exptdFreqHeteroZ = 2 * initFreqA * (1 - initFreqA); // according to HW + const int nbGens = 50; + float obsFreqA = initFreqA; + float obsFreqHeteroZ; + int nbInds = static_cast(localK); + + // Simple genetic layout + // 1 locus with two alleles A and B + const bool isDiploid{ true }; + const int genomeSz = 1; + const set genePositions = { 0 }; + const float maxAlleleVal = 1; + unsigned char alleleA = char(0); + unsigned char alleleB = char(1); + auto genotypeAA = createTestNeutralGenotype(genomeSz, true, alleleA, alleleA); + auto genotypeBB = createTestNeutralGenotype(genomeSz, true, alleleB, alleleB); + + // Landscape is a single cell + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(1); + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + Species* pSpecies = new Species(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + { }, "none", { }, 0 // no sampling + ); + SpeciesTrait* spTr = createTestNeutralSpTrait(maxAlleleVal, genePositions, isDiploid); + pSpecies->addTrait(TraitType::NEUTRAL, *spTr); + + // Initialise population with initial frequencies for AA and BB + Population pop = Population(pSpecies, pPatch, 0, 1); + for (int i = 0; i < initialNbInds; i++) { + Individual* pInd = new Individual(pSpecies, pCell, pPatch, 1, 0, 0, 0.5, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + if (i < initialNbInds * initFreqA) + pInd->overrideGenotype(NEUTRAL, genotypeAA); + else + pInd->overrideGenotype(NEUTRAL, genotypeBB); + pop.recruit(pInd); + } + + // Check allele frequencies conform to expectation through generations + float prevGenFreqA; + for (int yr = 0; yr < nbGens; yr++) { + pop.reproduction(localK, 1, 1, localScaling); + pop.fledge(); // replace initial pop with juveniles + pop.survival0(localK, 0, 0, localScaling); // flag juveniles for development + pop.survival1(); // develop to stage 1 (breeders) + pop.shuffleInds(); + + // Calculate expected allele frequency change from + // drift and previous generation frequencies + prevGenFreqA = obsFreqA; + float exptdChg = 2 * sqrt(prevGenFreqA * (1 - prevGenFreqA) / 2 * nbInds); + // ^ eq. 6.1 in Conservation and the Genomics of Populations, Allendorf et al. + // 95% CI for the allele frequency change + + // Check allele frequency change match equation + pop.sampleIndsWithoutReplacement("all", { 1 }); + pop.updatePopNeutralTables(); + obsFreqA = pop.getAlleleFrequency(0, alleleA); + float freqChg = abs(prevGenFreqA - obsFreqA); + assert(abs(freqChg) < tolerance); + + // If population is very large, heterozygosity should be roughly constant, + // i.e. inbreeding is negligible + nbInds = pop.getNbInds(); + // couldn't find a source for exptd change in heterozygosity so + // we assume Hardy-Weinberg equilibrium + obsFreqHeteroZ = static_cast(pop.getHeteroTally(0, alleleA)) / nbInds; + assert(abs(obsFreqHeteroZ - exptdFreqHeteroZ) < hetzTolerance); + } + } + + // Genetic load meets Hardy-Weinberg expectation on first generation + // If a lethal (s = 1) recessive (h = 0) allele starts at freq 0.6, + // then (if no mutations) next gen should have 0.6^2 = 0.36 homozygotes dying at birth + { + const float tolerance = 0.05; // high tolerance, still a lot of stochasticity + + const float initFreqA = 0.23; + const float sA = 1.0; // lethal + const float hA = 0.0; // fully recessive + const float sB = 0.0; // benign + const float hB = 1.0; // fully dominant + float mutationRate = 0.0; + const float localK = 10000.0; + vector localScaling = {1.0}; + + const int initialNbInds = localK; + const float expectedFreqAA = initFreqA * initFreqA; + + // Simple genetic layout + const bool isDiploid{ true }; // HW only applies to diploids + const int genomeSz = 1; + const set genePositions = { 0 }; + const float maxAlleleVal = 1; + unsigned char alleleA = char(0); + unsigned char alleleB = char(1); + auto genotypeAA = createTestGenotype(genomeSz, true, sA, sA, hA, hA); + auto genotypeBB = createTestGenotype(genomeSz, true, sB, sB, hB, hB); + + Landscape* pLandscape = new Landscape; + Patch* pPatch = pLandscape->newPatch(1); + Cell* pCell = new Cell(0, 0, pPatch, 0); + pPatch->addCell(pCell, 0, 0); + + Species* pSpecies = new Species(); + pSpecies->setDemogr(createDefaultDiploidDemogrParams()); + pSpecies->setGeneticParameters( + set{genomeSz - 1}, // single chromosome + genomeSz, + 0.0, // no recombination + { }, "none", { }, 0 // no sampling + ); + SpeciesTrait* spTr = createTestGenLoadTrait(genePositions, isDiploid); + pSpecies->addTrait(TraitType::GENETIC_LOAD, *spTr); + + // Initialise population with + Population pop = Population(pSpecies, pPatch, 0, 1); + for (int i = 0; i < initialNbInds; i++) { + Individual* pInd = new Individual(pSpecies, pCell, pPatch, 1, 0, 0, 0.5, false, 1); + pInd->setUpGenes(pSpecies, 1.0); + if (i < initialNbInds * initFreqA) + pInd->overrideGenotype(GENETIC_LOAD1, genotypeAA); + else + pInd->overrideGenotype(GENETIC_LOAD1, genotypeBB); + pop.recruit(pInd); + } + + // Check allele frequencies conform to HW + pop.shuffleInds(); + pop.reproduction(localK, 1, 1, localScaling); + pop.fledge(); // replace initial pop with juveniles + double obsFreqUnviable = 1 - pop.getNbInds() / localK; + assert(abs(obsFreqUnviable - expectedFreqAA) < tolerance); + } +} + +#endif // UNIT_TESTS diff --git a/RangeShiftR/src/RcppExports.cpp b/RangeShiftR/src/RcppExports.cpp new file mode 100644 index 0000000..5d10a14 --- /dev/null +++ b/RangeShiftR/src/RcppExports.cpp @@ -0,0 +1,34 @@ +// Generated by using Rcpp::compileAttributes() -> do not edit by hand +// Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393 + +#include + +using namespace Rcpp; + +#ifdef RCPP_USE_GLOBAL_ROSTREAM +Rcpp::Rostream& Rcpp::Rcout = Rcpp::Rcpp_cout_get(); +Rcpp::Rostream& Rcpp::Rcerr = Rcpp::Rcpp_cerr_get(); +#endif + +// BatchMainR +Rcpp::List BatchMainR(std::string dirpath, Rcpp::S4 ParMaster); +RcppExport SEXP _RangeShiftR_BatchMainR(SEXP dirpathSEXP, SEXP ParMasterSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< std::string >::type dirpath(dirpathSEXP); + Rcpp::traits::input_parameter< Rcpp::S4 >::type ParMaster(ParMasterSEXP); + rcpp_result_gen = Rcpp::wrap(BatchMainR(dirpath, ParMaster)); + return rcpp_result_gen; +END_RCPP +} + +static const R_CallMethodDef CallEntries[] = { + {"_RangeShiftR_BatchMainR", (DL_FUNC) &_RangeShiftR_BatchMainR, 2}, + {NULL, NULL, 0} +}; + +RcppExport void R_init_RangeShiftR(DllInfo *dll) { + R_registerRoutines(dll, NULL, CallEntries, NULL, NULL); + R_useDynamicSymbols(dll, FALSE); +} diff --git a/RangeShiftR/src/Rinterface.cpp b/RangeShiftR/src/Rinterface.cpp new file mode 100644 index 0000000..afd3ff9 --- /dev/null +++ b/RangeShiftR/src/Rinterface.cpp @@ -0,0 +1,6037 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2020 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell + * + * This file is part of RangeShiftR. + * + * RangeShiftR is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShiftR. If not, see . + * + --------------------------------------------------------------------------*/ + + +/*------------------------------------------------------------------------------ + +RangeShifter v2.0 Main + +Entry level function for the R-package RangeshiftR. + +For compilation with GCC g++ + +For full details of RangeShifter, please see: +Bocedi G., Palmer S.C.F., Pe'er G., Heikkinen R.K., Matsinos Y.G., Watts K. +and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial +eco-evolutionary dynamics and species' responses to environmental changes. +Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 + +Author: Anne-Kathleen Malchow, Humboldt University Berlin + Jette Wolff, University of Potsdam + large parts modified from 'Main.cpp' and 'BatchMode.cpp' created by + Steve Palmer, Roslyn Henry and Théo Pannetier, University of Aberdeen + +------------------------------------------------------------------------------*/ + +#include "Rinterface.h" + +class msghdrs1; + +string habmapname, patchmapname, distnmapname; // req'd for compilation, but not used +string costmapname, genfilename; // ditto +vector hfnames; // ditto + +paramGrad* paramsGrad; // pointer to environmental gradient parameters +paramStoch* paramsStoch; // pointer to environmental stochasticity parameters +paramInit* paramsInit; // pointer to initialisation parameters +paramSim* paramsSim; // pointer to simulation parameters + +Species* pSpecies; // pointer to species +Community* pComm; // pointer to community +RSrandom* pRandom; // pointer to random number routines +Management* pManagement; // pointer to management routines + +#if RSDEBUG +ofstream DEBUGLOG; +ofstream MUTNLOG; +#endif +// ofstream batchlog; +ofstream rsLog; // performance log for recording simulation times, etc. + + +// global variables passed between parsing functions... +int batchnum; +int fixreplicateseed; +int patchmodel, resolution, landtype, maxNhab, speciesdist, distresolution; +int reproductn; +int repseasons; +int stagestruct, stages, gTransferType; +int sexesDem; // no. of explicit sexes for demographic model +int gNbSexesDisp; // no. of explicit sexes for dispersal model +int gFirstSimulNb; +int fileNtraits; // no. of traits defined in genetic architecture file +bool gHasGenetics; // instead of static bool anyIndVar; +bool gHasNeutralGenetics; // instead of static bool anyIndVar; +bool gHasGeneticLoad; // instead of static bool anyIndVar; +DispersalTraitInputOptions gDispTraitOpt; +//vector gNbTraitFileRows; + +int translocation; + +bool threadsafe; +bool spatial_demography; + +rasterdata landraster,patchraster,spdistraster,costsraster,demograster; + +string name_landscape, name_patch, name_sp_dist, name_costfile; +short nDSlayer=gMaxNbLayers; + + +string msgnlines = "No. of lines for final Simulation "; +string msgshldbe = " should be "; +string msgresol0 = "*** Resolution of "; +string msgresol1 = " does not match set Resolution "; +string msgresol2 = " does not match set Distribution Resolution "; +string msghdrs0 = "*** Headers of "; +string msghdrs1 = " do not match headers of LandscapeFile"; +string msgpatch = " is required for patch-based model"; +string msgmatch = " must match the specification exactly"; +string msgcase = " case-sensitive parameter names"; + + + +//--------------------------------------------------------------------------- +// Returns input value less next highest power of 2 (for x > 2) +int power2check(int x) { + if (x < 2) return 0; + int r = x % 2; + while (r == 0) { + x /= 2; r = x % 2; + } + return x; + } + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//------ R interface -------------------------------------------------------- +//--------------------------------------------------------------------------- + + +//[[Rcpp::export(name = "run_from_R")]] +Rcpp::List BatchMainR(std::string dirpath, Rcpp::S4 ParMaster) +{ + // int i,t0,t1,Nruns; + int t0, t1; + int nSimuls, nLandscapes; // no. of simulations and landscapes in batch + + t0 = time(0); + //clear_outPop(); + + // set up parameter objects + paramsGrad = new paramGrad; + paramsStoch = new paramStoch; + paramsInit = new paramInit; + paramsSim = new paramSim(dirpath); + + // set up working directory and log file names + // paramsSim->setDir(dirpath); + +#if RSDEBUG + Rcpp::Rcout << endl << "Working directory: " << paramsSim->getDir(0) << endl; +#endif + + bool errorfolder = CheckDirectory(dirpath); + // if(errorfolder) { + // Rcpp::Rcout << endl << "***** Invalid working directory: " << paramsSim->getDir(0) << endl << endl; + // Rcpp::Rcout << "***** Working directory must contain Inputs, Outputs and Output_Maps folders" << endl << endl; + // Rcpp::Rcout << "*****" << endl; + // Rcpp::Rcout << "***** Simulation ABORTED " << endl; + // Rcpp::Rcout << "*****" << endl; + // return Rcpp::List::create(Rcpp::Named("Errors") = 666); + // } + +#if RSDEBUG + // set up debugging log file + string logname = paramsSim->getDir(2) + "DebugLog.txt"; + DEBUGLOG.open(logname.c_str()); + logname = paramsSim->getDir(2) + "MutnLog.txt"; + MUTNLOG.open(logname.c_str()); + if(DEBUGLOG.is_open()) + Rcpp::Rcout << endl << "Main(): DEBUGLOG is open" << endl << endl; + else + Rcpp::Rcout << endl << "Main(): DEBUGLOG is NOT open" << endl << endl; +#else +#endif + + + // set global variables + Rcpp::S4 control("ControlParams"); + // ParMaster = global.get(ParMaster_name); + control = Rcpp::as(ParMaster.slot("control")); + setglobalvarsR(control); + nSimuls = 1; + nLandscapes = 1; + + //////////////////////// batchfiles ParseControlR(string dirpath) /////////////////// + + //string indir = dirpath + "Inputs/"; + string outdir = dirpath + "Outputs/"; + + // Doublecheck global variables + Rcpp::Rcout << "Checking Control parameters " << endl; + + int errors = 0; + string filetype = "Control parameters"; + + if(batchnum < 0) { + BatchErrorR(filetype, -999, 19, "BatchNum"); + errors++; + } + + if(patchmodel < 0 || patchmodel > 1) { + BatchErrorR(filetype, -999, 1, "PatchModel"); + errors++; + } + + if(resolution < 1) { + BatchErrorR(filetype, -999, 11, "Resolution"); + errors++; + } + + if(landtype != 0 && landtype != 2 && landtype != 9) { + BatchErrorR(filetype, -999, 0, "LandType"); + Rcpp::Rcout << "LandType must be 0, 2 or 9" << endl; + errors++; + } else { + if(landtype == 9 && patchmodel) { + BatchErrorR(filetype, -999, 0, "LandType"); + Rcpp::Rcout << "LandType may not be 9 for a patch-based model" << endl; + errors++; + } + } + + if(landtype == 0) { // raster with unique habitat codes + if(maxNhab < 2) { + BatchErrorR(filetype, -999, 12, "MaxHabitats"); + errors++; + } + } else { // raster with habitat quality OR artificial landscape + if(maxNhab != 1) { + BatchErrorR(filetype, -999, 0, " "); + errors++; + Rcpp::Rcout << "MaxHabitats must be 1 for LandType = " << landtype << endl; + } + /*else + { + if (landtype == 9) // artificial landscape + // although the user enters 1, the actual number of habitats is 2 + b.maxNhab = 2; // only changes maxNhab in batchfile b, the global variable remains maxNhab=1 + }*/ + } + + if(speciesdist < 0 || speciesdist > 1) { + BatchErrorR(filetype, -999, 1, "SpeciesDist"); + errors++; + } else { + if(speciesdist != 0 && landtype == 9) { + BatchErrorR(filetype, -999, 0, "SpeciesDist"); + Rcpp::Rcout << "SpeciesDist must be 0 for an artificial landscape" << endl; + errors++; + } + } + + if(speciesdist == 1) { // distribution resolution is required + if(distresolution < resolution) { + BatchErrorR(filetype, -999, 0, "DistResolution"); + Rcpp::Rcout << "DistResolution may not be less than Resolution" << endl; + errors++; + } else { + if(distresolution % resolution) { + BatchErrorR(filetype, -999, 0, "DistResolution"); + Rcpp::Rcout << "DistResolution must be an integer multiple of Resolution" << endl; + errors++; + } + } + } + + if(reproductn < 0 || reproductn > 2) { + BatchErrorR(filetype, -999, 2, "Reproduction"); + errors++; + } + else { + switch(reproductn) { + case 0: { + sexesDem = 1; + gNbSexesDisp = 1; + break; + } + case 1: { + sexesDem = 1; + gNbSexesDisp = 2; + break; + } + case 2: { + sexesDem = 2; + gNbSexesDisp = 2; + break; + } + } + } + + if(repseasons < 1) { + BatchErrorR(filetype, -999, 11, "RepSeasons"); + errors++; + } + + if(stagestruct < 0 || stagestruct > 1) { + BatchErrorR(filetype, -999, 1, "StageStruct"); + errors++; + } + + if(stagestruct) { + if(stages < 2 || stages > gMaxNbStages) { + BatchErrorR(filetype, -999, 0, " "); + errors++; + Rcpp::Rcout << "Stages must be between 2 and " << gMaxNbStages << endl; + } + } else { // non-stage-structured model must have 2 stages + stages = 2; + } + + if( gTransferType < 0 || gTransferType > 2) { + BatchErrorR(filetype, -999, 2, "Transfer"); + errors++; + } + + if(errors > 0) { // terminate batch error checking + + Rcpp::Rcout << endl << "*** Control parameters must be corrected before proceeding" << endl; + return Rcpp::List::create(Rcpp::Named("Errors") = errors); + } + + ////////////////////////////////////// + + + // set up species + // FOR MULTI-SPECIES MODEL, THERE WILL BE AN ARRAY OF SPECIES POINTERS + // OR A COMMUNITY CLASS TO HOLD THE SPECIES + pSpecies = new Species; + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + transferRules trfr = pSpecies->getTransferRules(); + + // create new Management + pManagement = new Management; + managementParams m = pManagement->getManagementParams(); + + if(errors == 0) { + // nSimuls = b.nSimuls; + // nLandscapes = b.nLandscapes; + dem.repType = reproductn; + dem.repSeasons = repseasons; + if(stagestruct == 0) + dem.stageStruct = false; + else + dem.stageStruct = true; + sstruct.nStages = stages; + if( gTransferType == 0) + trfr.usesMovtProc = false; + else { + trfr.usesMovtProc = true; + trfr.moveType = gTransferType; + } + if(translocation == 0) + m.translocation = false; + else + m.translocation = true; + + pSpecies->setDemogr(dem); + pSpecies->setStage(sstruct); + pSpecies->setTrfrRules(trfr); + pManagement->setManagementParams(m); + + simParams sim = paramsSim->getSim(); + sim.batchMode = true; + sim.batchNum = batchnum; + sim.fixReplicateSeed = fixreplicateseed; + paramsSim->setSim(sim); + Rcpp::Rcout << endl << "Control Parameters checked" << endl; + } else { + Rcpp::Rcout << endl << "Error in parsing parameters - " << endl; + } + +#if RSDEBUG + DEBUGLOG << "BatchMainR(): dem.repType = " << dem.repType << endl; +#endif + + // set up random number stream + std::int64_t seed = Rcpp::as(control.slot("seed")); + + if(seed == 0) { // don't set seed from R +#if RSDEBUG + pRandom = new RSrandom(666); // fixed debug seed +#else + pRandom = new RSrandom(-1); // random seed +#endif + } + else pRandom = new RSrandom(seed); + + //Rcpp::RNGScope rngScope; + + Rcpp::List list_outPop; + if(errors == 0) { + Rcpp::Rcout << endl << "Run Simulation(s)"; + if(seed > 0) { + Rcpp::Rcout << " with seed " << seed; + }else{ + Rcpp::Rcout << " with random seed"; + } + Rcpp::Rcout << " ..." << endl; + + list_outPop = RunBatchR(nSimuls, nLandscapes, ParMaster); + } + +#if RSDEBUG + if(DEBUGLOG.is_open()) { + DEBUGLOG.close(); + DEBUGLOG.clear(); + } + if(MUTNLOG.is_open()) { + MUTNLOG.close(); + MUTNLOG.clear(); + } +#endif + + simParams sim = paramsSim->getSim(); + + delete paramsGrad; + delete paramsStoch; + delete paramsInit; + delete paramsSim; + delete pSpecies; + delete pManagement; + delete pRandom; + + t1 = time(0); + Rcpp::Rcout << endl << "***** Elapsed time: " << t1 - t0 << " seconds" << endl << endl; + + Rcpp::Rcout << "*****" << endl; + Rcpp::Rcout << "***** Simulation completed " << endl; + Rcpp::Rcout << "***** Outputs folder: " << outdir << endl; + Rcpp::Rcout << "*****" << endl; + + if((sim.ReturnPopMatrix || sim.ReturnPopDataFrame) && sim.outIntPop > 0) { + // return Rcpp::List::create(Rcpp::Named("runs") = errors); + return list_outPop; + } else { + return Rcpp::List::create(Rcpp::Named("Errors") = errors); + } +} + +//--------------------------------------------------------------------------- +// TODO: Change return value to integer code: error codes as negative values! +bool ReadLandParamsR(Landscape* pLandscape, Rcpp::S4 ParMaster) +{ + landParams ppLand = pLandscape->getLandParams(); + genLandParams ppGenLand = pLandscape->getGenLandParams(); + + Rcpp::S4 LandParamsR("LandParams"); + LandParamsR = Rcpp::as(ParMaster.slot("land")); + + int errors = 0; + + if(landtype == 9) { // artificial landscape +#if RSDEBUG + DEBUGLOG << "ReadLandParamsR(): artificial: " << endl; +#endif + ppLand.nHab = 2; + ppLand.rasterType = 9; + ppLand.landNum = Rcpp::as(LandParamsR.slot("LandNum")); + ppGenLand.fractal = Rcpp::as(LandParamsR.slot("fractal")); + ppGenLand.continuous = Rcpp::as(LandParamsR.slot("continuous")); + ppLand.dimX = Rcpp::as(LandParamsR.slot("dimX")); + ppLand.dimY = Rcpp::as(LandParamsR.slot("dimY")); + ppGenLand.minPct = Rcpp::as(LandParamsR.slot("minPct")); + ppGenLand.maxPct = Rcpp::as(LandParamsR.slot("maxPct")); + ppGenLand.propSuit = Rcpp::as(LandParamsR.slot("propSuit")); + ppGenLand.hurst = Rcpp::as(LandParamsR.slot("hurst")); + ppLand.maxX = ppLand.dimX - 1; + ppLand.maxY = ppLand.dimY - 1; + + // check dimensions --> these shouldn't occur, as already checked for on R-level + if(ppGenLand.fractal && ppLand.maxX > ppLand.maxY) { + //return -901; + // fix it by swapping X and Y: + ppLand.maxX = ppLand.dimY - 1; + ppLand.maxY = ppLand.dimX - 1; + ppLand.dimX = ppLand.maxX + 1; + ppLand.dimY = ppLand.maxY + 1; + } + if(ppGenLand.fractal) { + if((ppLand.dimX < 3 || ppLand.dimX % 2 != 1) // why only check for uneven number, not ((power of 2)-1) ? + || (ppLand.dimY < 3 || ppLand.dimY % 2 != 1)) { + //return -902; // -> no action, should be covered on R-level + } + } + // SCFP 26/9/13 - min and max habitat percentages need to be set for all types of + // fractal landscape (including discrete), as they are passed to the fractal generator + // NOTE that will not have been checked for a discrete landscape + if(ppGenLand.fractal && !ppGenLand.continuous) { + ppGenLand.minPct = 1; + ppGenLand.maxPct = 100; + } + } else { // imported raster map + + ppLand.landNum = Rcpp::as(LandParamsR.slot("LandNum")); + ppLand.nHab = Rcpp::as(LandParamsR.slot("Nhabitats")); // no longer necessary to read no. of habitats from landFile + if(landtype == 2) + ppLand.nHab = 1; // habitat quality landscape has one habitat class + Rcpp::IntegerVector dynland_years; + Rcpp::StringVector habitatmaps, patchmaps, costmaps, spdistmap; // for landscape file input + Rcpp::List habitatmatrix, patchmatrix, costmatrix, spdistmatrix; // for matrix input + + dynland_years = Rcpp::as(LandParamsR.slot("DynamicLandYears")); + if(dynland_years.size() == 1 && dynland_years[0] == 0 ) ppLand.dynamic = false; + else ppLand.dynamic = true; + if (threadsafe){ + Rcpp::Rcout << "Using landscape matrices..." << endl; + habitatmatrix = Rcpp::as(LandParamsR.slot("LandscapeMatrix")); + patchmatrix = Rcpp::as(LandParamsR.slot("PatchMatrix")); + costmatrix = Rcpp::as(LandParamsR.slot("CostsMatrix")); + spdistmatrix = Rcpp::as(LandParamsR.slot("SpDistMatrix")); + if(!patchmodel && patchmatrix.size() != 0) Rcpp::Rcout << "PatchMatrix must be empty in a cell-based model!" << endl; + // new slot for coordinates of lower left corner + Rcpp::NumericVector origin_coords; + origin_coords = Rcpp::as(LandParamsR.slot("OriginCoords")); + landOrigin origin; + origin.minEast = origin_coords[0]; + origin.minNorth = origin_coords[1]; + pLandscape->setOrigin(origin); // only used with matrix input + } else { + if(ppLand.dynamic) { + if(LandParamsR.slot("LandscapeFile") != R_NilValue) { + habitatmaps = Rcpp::as(LandParamsR.slot("LandscapeFile")); + } else{ + habitatmaps = "NULL"; + } + if(LandParamsR.slot("PatchFile") != R_NilValue) { + patchmaps = Rcpp::as(LandParamsR.slot("PatchFile")); + } else{ + patchmaps = "NULL"; + } + if(LandParamsR.slot("CostsFile") != R_NilValue) { + costmaps = Rcpp::as(LandParamsR.slot("CostsFile")); + } else{ + costmaps = "NULL"; + } + // add spatial scaling layers here + // they are lists of string vectors + name_landscape = habitatmaps(0); + name_patch = patchmaps(0); + name_costfile = costmaps(0); + } else { + if(LandParamsR.slot("LandscapeFile") != R_NilValue) { + name_landscape = Rcpp::as(LandParamsR.slot("LandscapeFile")); + } else { + name_landscape = "NULL"; + } + + if(LandParamsR.slot("PatchFile") != R_NilValue) { + name_patch = Rcpp::as(LandParamsR.slot("PatchFile")); + } else { + name_patch = "NULL"; + } + + if(LandParamsR.slot("CostsFile") != R_NilValue) { + name_costfile = Rcpp::as(LandParamsR.slot("CostsFile")); + } else { + name_costfile = "NULL"; + } + // add spatial scaling here + // should be a StringVector + } + if(LandParamsR.slot("SpDistFile") != R_NilValue){ + name_sp_dist = Rcpp::as(LandParamsR.slot("SpDistFile")); + } else { + name_sp_dist = "NULL"; + } + + if(!patchmodel && name_patch != "NULL") Rcpp::Rcout << "PatchFile must be NULL in a cell-based model!" << endl; + } + + int nrDemogScaleLayers = 0; + Rcpp::List demogScaleLayers; + if (landtype == 2) { // habitat quality + nrDemogScaleLayers = Rcpp::as(LandParamsR.slot("nrDemogScaleLayers")); + if(nrDemogScaleLayers) { + Rcpp::Rcout << "Spatial demography is active..." << endl; + ppLand.spatialdemog = true; + nDSlayer = nrDemogScaleLayers; + if (threadsafe) + demogScaleLayers = Rcpp::as(LandParamsR.slot("demogScaleLayersMatrix")); + else + demogScaleLayers = Rcpp::as(LandParamsR.slot("demogScaleLayersFile")); + Rcpp::Rcout << "Detected spatial demog:" << nDSlayer << " layers." << endl; + } + else { + ppLand.spatialdemog = false; // just to be sure + nDSlayer = 0; + } + } + + if (nrDemogScaleLayers && !stagestruct) { + BatchErrorR("LandFile", -999, 0, " "); + errors++; + Rcpp::Rcout << "Spatially varying demographic layers are only supported for stage-structured models" << endl; + } + + + if(threadsafe){ + if(patchmatrix.size() == 0) { + if(patchmodel) { + BatchErrorR("LandMatrix", -999, 0, " "); + errors++; + Rcpp::Rcout << "PatchMatrix" << msgpatch << endl; + } + } + if (costmatrix.size() == 0) { + if (gTransferType == 1) { // SMS + if (landtype == 2) { // habitat quality + BatchErrorR("LandMatrix", -999, 0, " "); + errors++; + Rcpp::Rcout << "CostsMatrix is required for a habitat quality landscape" << endl; + } + } + }else{ + if (gTransferType != 1) { // not SMS + BatchErrorR("LandMatrix", -999, 0, " "); + errors++; + Rcpp::Rcout << "CostsMatrix must be empty if transfer model is not SMS" << endl; + } + } + + if(ppLand.dynamic) { + int nlayers_hab; + nlayers_hab = habitatmatrix.size(); + // check valid years + if(dynland_years[0]!=0) { + errors++; + Rcpp::Rcout << "First year in dynamic landscape must be 0." << endl; + } else { + for(int i=1; i= dynland_years[i]) { + errors++; + Rcpp::Rcout << "Years in dynamic landscape must strictly increase." << endl; + } + } + } + if(dynland_years.size() != nlayers_hab) { + errors++; + Rcpp::Rcout << "Dynamic landscape: DynamicLandYears must have as many elements as habitat matrices." << endl; + } + if(patchmodel) { + if( dynland_years.size() != patchmatrix.size() || nlayers_hab != patchmatrix.size() ) { + errors++; + Rcpp::Rcout << "Dynamic landscape: Patchmatrices must have as many elements as DynamicLandYears and habitat maatrices." << endl; + } + } + if (costmatrix.size() != 0) { + if( dynland_years.size() != costmatrix.size() || nlayers_hab != costmatrix.size() ) { + errors++; + Rcpp::Rcout << "Dynamic landscape: Costmatrices must have as many elements as DynamicLandYears and habitat matrices." << endl; + } + } + + if (nrDemogScaleLayers) { + if( dynland_years.size() != demogScaleLayers.size() || nlayers_hab != demogScaleLayers.size() ) { + errors++; + Rcpp::Rcout << "Dynamic landscape: demogScaleLayers must have as many elements as DynamicLandYears and habitat maps." << endl; + } + } + + if(errors==0) { + // store land changes + landChange chg; + for(int i=1; iaddLandChange(chg); + } + } + } // end dynamic landscapes + + if(spdistmatrix.size() == 0) { + if(speciesdist) { + BatchErrorR("LandMatrix", -999, 0, " "); + errors++; + Rcpp::Rcout << "Species Distribution matrix is required as SpeciesDist is 1 in Control" << endl; + } + } + + if(nrDemogScaleLayers) { // test consistent number of layers (nrDemogScaleLayers) per dynland year + Rcpp::NumericVector yearLayers = Rcpp::as(demogScaleLayers[0]); + // get dimensions of landscape + Rcpp::IntegerVector DimsA = yearLayers.attr("dim"); + // test for correct size of demogr. layers array + if(DimsA[2] != nrDemogScaleLayers){ + errors++; + } + if(ppLand.dynamic) { + for(int i=1; i(demogScaleLayers[i]); + DimsA = yearLayers.attr("dim"); + if(DimsA[2] != nrDemogScaleLayers){ + errors++; + Rcpp::Rcout << "demogScaleLayers in dynamic year " << i << " has an incorrect amount of layers" << endl; + } + } + } + } + + + } + else{ // end threadsafe + + // CHECK IMPORTED RASTER FILES + string indir = paramsSim->getDir(1); + string ftype, fname; + string filetype = "LandFile"; + //rasterdata patchraster, spdistraster; //declared globally + + // check landscape filename + ftype = "LandscapeFile"; + fname = indir + name_landscape; + landraster = ParseRasterHead(fname); + if(landraster.ok) { + if(landraster.cellsize == resolution) + Rcpp::Rcout << ftype << " headers OK: " << fname << endl; + else { + errors++; + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msgresol1 << endl; + } + } else { + errors++; + if(landraster.errors == -111) + OpenErrorR(ftype, fname); + else + FormatErrorR(fname, landraster.errors); + } + + // check patch map filename + ftype = "PatchFile"; + if(name_patch == "NULL") { + if(patchmodel) { + BatchErrorR(filetype, -999, 0, " "); + errors++; + Rcpp::Rcout << ftype << msgpatch << endl; + } + } else { + if(patchmodel) { + fname = indir + name_patch; + patchraster = ParseRasterHead(fname); + if(patchraster.ok) { + // check resolutions match + if(patchraster.cellsize == resolution) { + if(!errors) { + if(patchraster.cellsize == landraster.cellsize) { + // check that extent matches landscape extent + if(patchraster.ncols == landraster.ncols && patchraster.nrows == landraster.nrows) { + // check origins match + if((int)patchraster.xllcorner == (int)landraster.xllcorner && + (int)patchraster.yllcorner == (int)landraster.yllcorner) { + Rcpp::Rcout << ftype << " headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << ftype << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Extent of " << ftype << " " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msghdrs1 << endl; + errors++; + } + } + } else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msgresol1 << endl; + errors++; + } + } else { + errors++; + if(patchraster.errors == -111) + OpenErrorR(ftype, fname); + else + FormatErrorR(fname, patchraster.errors); + } + } + } + + // check cost map filename + ftype = "CostMapFile"; + if (name_costfile == "NULL") { + if ( gTransferType == 1) { // SMS + if (landtype == 2) { // habitat quality + BatchErrorR(filetype, -999, 0, " "); + errors++; + Rcpp::Rcout << ftype << " is required for a habitat quality landscape" << endl; + } + } + } + else { + if ( gTransferType == 1) { // SMS + fname = indir + name_costfile; + costsraster = ParseRasterHead(fname); + if(costsraster.ok) { + // check resolutions match + if(costsraster.cellsize == resolution) { + if(!errors) { + if(costsraster.cellsize == landraster.cellsize) { + // check that extent matches landscape extent + if(costsraster.ncols == landraster.ncols && costsraster.nrows == landraster.nrows) { + // check origins match + if((int)costsraster.xllcorner == (int)landraster.xllcorner && + (int)costsraster.yllcorner == (int)landraster.yllcorner) { + Rcpp::Rcout << ftype << " headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << ftype << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Extent of " << ftype << " " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msghdrs1 << endl; + errors++; + } + } + } else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msgresol1 << endl; + errors++; + } + } else { + errors++; + if(costsraster.errors == -111) + OpenErrorR(ftype, fname); + else + FormatErrorR(fname, costsraster.errors); + } + } + else { + BatchErrorR(filetype, -999, 0, " "); + errors++; + Rcpp::Rcout << ftype << " must be NULL if transfer model is not SMS" << endl; + } + } + + // check dimensions of demog scaling list + if (nrDemogScaleLayers) { + if( dynland_years.size() != demogScaleLayers.size()) { + errors++; + Rcpp::Rcout << "Dynamic landscape: demogScaleLayers must have as many elements as DynamicLandYears and habitat maps." << endl; + } + } + + // check dynamic landscape filename + // ...most checks are done at reading time in ReadDynLandR() + ftype = "Dynamic landscape"; + if(ppLand.dynamic) { + // check valid years + if(dynland_years[0]!=0) { + errors++; + Rcpp::Rcout << "First year in dynamic landscape must be 0." << endl; + } else { + for(int i=1; i= dynland_years[i]) { + errors++; + Rcpp::Rcout << "Years in dynamic landscape must strictly increase." << endl; + } + } + } + if(dynland_years.size() != habitatmaps.size()) { + errors++; + Rcpp::Rcout << "Dynamic landscape: Years must have as many elements as habitat maps." << endl; + } + if(patchmodel) { + if( dynland_years.size() != patchmaps.size() || + habitatmaps.size() != patchmaps.size() ) { + errors++; + Rcpp::Rcout << "Dynamic landscape: Patchmaps must have as many elements as Years and habitat maps." << endl; + } + } + if (name_costfile != "NULL") { + if( dynland_years.size() != costmaps.size() || + habitatmaps.size() != costmaps.size() ) { + errors++; + Rcpp::Rcout << "Dynamic landscape: Costmaps must have as many elements as Years and habitat maps." << endl; + } + } + if(errors==0) { + // store land changes + string landchangefile,patchchangefile; + landChange chg; + for(int i=1; iaddLandChange(chg); + // also add the spatial demo layers here?? + } + } + } // end dynamic landscapes + + if(nrDemogScaleLayers) { // test consistent number of layers (nrDemogScaleLayers) per dynland year + Rcpp::StringVector yearLayers_fname = Rcpp::as(demogScaleLayers[0]); + // test for correct size of demogr. layer files + if(yearLayers_fname.size() != nrDemogScaleLayers){ + errors++; + } + + // also test here whether all raster headers are correct + for (int i=0; i yearLayers[i]; + fname = indir + yearLayers_fname[i]; + ftype = "Demographic scaling layer"; + demograster = ParseRasterHead(fname); + if(demograster.ok) { + if(demograster.cellsize == resolution) { + if(!errors) { + if(demograster.cellsize == landraster.cellsize) { + // check that extent matches landscape extent + if(demograster.ncols == landraster.ncols && demograster.nrows == landraster.nrows) { + // check origins match + if((int)demograster.xllcorner == (int)landraster.xllcorner && + (int)demograster.yllcorner == (int)landraster.yllcorner) { + Rcpp::Rcout << ftype << " headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << ftype << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Extent of " << ftype << " " << fname << msghdrs1 << endl; + errors++; + } + } + else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msghdrs1 << endl; + errors++; + } + } + } else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msgresol1 << endl; + errors++; + } + } else { + errors++; + if(demograster.errors == -111) + OpenErrorR(ftype, fname); + else + FormatErrorR(fname, demograster.errors); + } + } + + if(ppLand.dynamic) { + for(int i=1; i(demogScaleLayers[i]); + if(yearLayers_fname.size() != nrDemogScaleLayers){ + errors++; + Rcpp::Rcout << "demogScaleLayers in dynamic year " << i << " has an incorrect amount of layers" << endl; + } + } + } + } + + // check initial distribution map filename + ftype = "Species Distribution map"; + if(name_sp_dist == "NULL") { + if(speciesdist) { + BatchErrorR(filetype, -999, 0, " "); + errors++; + Rcpp::Rcout << ftype << " is required as SpeciesDist is 1 in Control" << endl; + } + } else { + if(speciesdist) { + fname = indir + name_sp_dist; + spdistraster = ParseRasterHead(fname); + if(spdistraster.ok) { + if(spdistraster.cellsize == distresolution) { + if(!errors) { + // check origins match + if((int)spdistraster.xllcorner == (int)landraster.xllcorner && (int)spdistraster.yllcorner == (int)landraster.yllcorner) { + // check extents match + if(spdistraster.cellsize == landraster.cellsize) { + // same resolution + if(spdistraster.ncols == landraster.ncols && spdistraster.nrows == landraster.nrows) { + Rcpp::Rcout << ftype << " headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Extents of " << ftype << msghdrs1 << endl; + errors++; + } + } else { // different resolution + if((spdistraster.cellsize % landraster.cellsize)==0) { + double coarse = spdistraster.cellsize/landraster.cellsize; + double rightx = ceil(landraster.ncols/coarse); + double righty = ceil(landraster.nrows/coarse); + if( spdistraster.ncols == int(rightx) && spdistraster.nrows == int(righty) ) { + Rcpp::Rcout << ftype << " headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Extents of " << ftype << msghdrs1 << endl; + errors++; + } + } else { + BatchErrorR(filetype, -999, 0, "DistResolution"); + Rcpp::Rcout << "Resolution of initial distribution must be an integer multiple of Landscape resolution" << endl; + errors++; + } + } + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << ftype << msghdrs1 << endl; + errors++; + } + } + } else { + Rcpp::Rcout << msgresol0 << ftype << " " << fname << msgresol2 << endl; + errors++; + } + } else { + errors++; + if(spdistraster.errors == -111) + OpenErrorR(ftype, fname); + else + FormatErrorR(fname, spdistraster.errors); + } + } + } + } // end else (not threadsafe) + + } // end else (imported raster map) + + + pLandscape->setLandParams(ppLand, true); + pLandscape->setGenLandParams(ppGenLand); + +#if RSDEBUG +// DEBUGLOG << "ReadLandParamsR(): NHab=" << ppLand.nHab << endl; + DEBUGLOG << "ReadLandParamsR(): ppLand.landNum=" << ppLand.landNum << endl; +#endif + + if(errors) return false; //=landOK + else return true; +} + +//--------------------------------------------------------------------------- + +int ReadDynLandR(Landscape *pLandscape, Rcpp::S4 LandParamsR) +{ + // threadsafe + Rcpp::List habitatmatrix; + Rcpp::List patchmatrix; + Rcpp::List costmatrix; + //threadsafe + Rcpp::NumericMatrix hraster; + Rcpp::NumericMatrix praster; + Rcpp::NumericMatrix craster; + + // !threadsafe + Rcpp::StringVector habitatmaps, patchmaps, costmaps; + + // general + bool costs = false; + + // threadsafe + if(threadsafe){ + habitatmatrix = Rcpp::as(LandParamsR.slot("LandscapeMatrix")); + if (patchmodel) patchmatrix = Rcpp::as(LandParamsR.slot("PatchMatrix")); + else praster = Rcpp::NumericMatrix(0); + costmatrix = Rcpp::as(LandParamsR.slot("CostsMatrix")); + if (costmatrix.size() > 0) costs = true; + else craster = Rcpp::NumericMatrix(0); + } else { + // file + habitatmaps = Rcpp::as(LandParamsR.slot("LandscapeFile")); + if (patchmodel) { + patchmaps = Rcpp::as(LandParamsR.slot("PatchFile")); + } + if(LandParamsR.slot("CostsFile") != R_NilValue){ + costmaps = Rcpp::as(LandParamsR.slot("CostsFile")); + if (costmaps(0) != "NULL") costs = true; + } + } + + + // spatial demography (independent of landscape input) + int nrDemogScaleLayers = 0; + Rcpp::List demogScaleLayers; + Rcpp::NumericVector yearLayers = Rcpp::NumericVector::create(-1); + Rcpp::StringVector yearLayers_fname = Rcpp::StringVector::create(""); + + if (landtype == 2) { // habitat quality + nrDemogScaleLayers = Rcpp::as(LandParamsR.slot("nrDemogScaleLayers")); + if(nrDemogScaleLayers) { + if (threadsafe) + demogScaleLayers = Rcpp::as(LandParamsR.slot("demogScaleLayersMatrix")); + else + demogScaleLayers = Rcpp::as(LandParamsR.slot("demogScaleLayersFile")); + } + } + + string indir = paramsSim->getDir(1); + string fname,ftype; + wstring header; + wifstream hfile,pfile,cfile; + int errors,ncols,nrows,cellsize,habnodata,pchnodata,costnodata; + double xllcorner,yllcorner; + + errors = ncols = nrows = cellsize = habnodata = pchnodata = costnodata = 0; + xllcorner = yllcorner = 0.0; + + if (patchmodel) { + pLandscape->createPatchChgMatrix(); + } + if (costs) { + pLandscape->createCostsChgMatrix(); + } + + int nb_landscapes; + if(threadsafe) { + nb_landscapes = habitatmatrix.size(); + Rcpp::Rcout << "Number of dynamic landscapes: " << nb_landscapes << endl; + } else { + nb_landscapes = habitatmaps.size(); + Rcpp::Rcout << "Number of dynamic landscapes: " << nb_landscapes << endl; + } + + + // nb_landscapes = 1; + + for(int i=1; i < nb_landscapes; i++ ) { + // Now read raster data of Habitat and, if applicable, Patch and/or Cost maps: + int imported = 0; + if (threadsafe) { + hraster = Rcpp::as(habitatmatrix[i]); + if (patchmodel) praster = Rcpp::as(patchmatrix[i]); + if (costs) craster = Rcpp::as(costmatrix[i]); + } else { + // for file inputs + + // Habitat change file + fname = indir + habitatmaps(i); + + // open file +#if RSWIN64 + hfile.open(fname.c_str()); +#else + hfile.open(fname, std::ios::binary); +#endif + if(!hfile.is_open()) { + OpenErrorR("Dynamic landscape habitat map ", fname); +#if RSDEBUG + DEBUGLOG << "Dynamic landscape habitat map failed to open: " << fname << std::endl; +#endif + hfile.clear(); + return -212; + } else { +#if RSDEBUG + DEBUGLOG << "Dynamic landscape habitat map #" << i << " open to read" << std::endl; +#endif +#if !RSWIN64 + // check BOM for UTF-16 + if(check_bom(fname) == "utf16") + // apply BOM-sensitive UTF-16 facet + hfile.imbue(std::locale(hfile.getloc(), new std::codecvt_utf16)); +#endif + // ASCII header + hfile >> header; + if (!hfile.good()) { +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): failed to read landscape habitat map #" << i << ": " << fname << std::endl; +#endif + errors = -1112; + hfile.close(); + hfile.clear(); + return errors; + } + if (header != L"ncols" && header != L"NCOLS") errors++; + hfile >> ncols; + + hfile >> header >> nrows; + if (header != L"nrows" && header != L"NROWS") errors++; + + hfile >> header >> xllcorner; + if (header != L"xllcorner" && header != L"XLLCORNER") errors++; + + hfile >> header >> yllcorner; + if (header != L"yllcorner" && header != L"YLLCORNER") errors++; + double tmpcellsize; + hfile >> header >> tmpcellsize; + cellsize = (int) tmpcellsize; + if (header != L"cellsize" && header != L"CELLSIZE") errors++; + + hfile >> header >> habnodata; + if (header != L"NODATA_value" && header != L"NODATA_VALUE") errors++; + + if (errors > 0) { + FormatErrorR(fname,errors); +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): failed to read Raster header of landscape habitat map #" << i << ": " << fname << std::endl; +#endif + hfile.close(); + hfile.clear(); + } else { + // check resolution match + if (cellsize == resolution) { + // check that extent matches landscape extent + if(ncols == landraster.ncols && nrows == landraster.nrows) { + // check origins match + if((int)xllcorner == (int)landraster.xllcorner && + (int)yllcorner == (int)landraster.yllcorner) { + Rcpp::Rcout << "Dynamic landscape habitat map #" << i << ", headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Extent of " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Resolution of " << fname << msghdrs1 << endl; + errors++; + } + if (errors > 0) { + FormatErrorR(fname,errors); +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): Errors in raster header of landscape habitat map #" << i << ": " << fname << std::endl; +#endif + hfile.close(); + hfile.clear(); + } + } // end of reading ASCII header + } + + // Do the same for corresponding patch map, if applicable + if (patchmodel) { + // Patch change file + fname = indir + patchmaps(i); + + // open file +#if RSWIN64 + pfile.open(fname.c_str()); +#else + pfile.open(fname, std::ios::binary); +#endif + if(!pfile.is_open()) { + OpenErrorR("Dynamic landscape patch map ", fname); +#if RSDEBUG + DEBUGLOG << "Dynamic landscape patch map failed to open: " << fname << std::endl; +#endif + pfile.clear(); + return -213; + } else { +#if RSDEBUG + DEBUGLOG << "Dynamic landscape patch map #" << i << " open to read" << std::endl; +#endif +#if !RSWIN64 + // check BOM for UTF-16 + if(check_bom(fname) == "utf16") + // apply BOM-sensitive UTF-16 facet + pfile.imbue(std::locale(pfile.getloc(), new std::codecvt_utf16)); +#endif + // ASCII header + pfile >> header; + if (!pfile.good()) { +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): failed to read landscape patch map #" << i << ": " << fname << std::endl; +#endif + errors = -1113; + pfile.close(); + pfile.clear(); + return errors; + } + if (header != L"ncols" && header != L"NCOLS") errors++; + pfile >> ncols; + + pfile >> header >> nrows; + if (header != L"nrows" && header != L"NROWS") errors++; + + pfile >> header >> xllcorner; + if (header != L"xllcorner" && header != L"XLLCORNER") errors++; + + pfile >> header >> yllcorner; + if (header != L"yllcorner" && header != L"YLLCORNER") errors++; + + double tmpcellsize; + pfile >> header >> tmpcellsize; + cellsize = (int) tmpcellsize; + if (header != L"cellsize" && header != L"CELLSIZE") errors++; + + pfile >> header >> pchnodata; + if (header != L"NODATA_value" && header != L"NODATA_VALUE") errors++; + + if (errors > 0) { + FormatErrorR(fname,errors); +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): failed to read Raster header of landscape patch map #" << i << ": " << fname << std::endl; +#endif + pfile.close(); + pfile.clear(); + } else { + // check resolution match + if (cellsize == resolution) { + // check that extent matches landscape extent + if(ncols == landraster.ncols && nrows == landraster.nrows) { + // check origins match + if((int)xllcorner == (int)landraster.xllcorner && + (int)yllcorner == (int)landraster.yllcorner) { + Rcpp::Rcout << "Dynamic landscape patch map #" << i << ", headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Extent of " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Resolution of " << fname << msghdrs1 << endl; + errors++; + } + if (errors > 0) { + FormatErrorR(fname,errors); +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): Errors in raster header of landscape patch map #" << i << ": " << fname << std::endl; +#endif + pfile.close(); + pfile.clear(); + } + } // end of reading ASCII header + } + } // end of if(patchmodel) + else { + pfile.clear(); + } + + // Do the same for corresponding cost map, if applicable + if (costs) { + // Cost change file + fname = indir + costmaps(i); + + // open file +#if RSWIN64 + cfile.open(fname.c_str()); +#else + cfile.open(fname, std::ios::binary); +#endif + if(!cfile.is_open()) { + OpenErrorR("Dynamic SMS cost map ", fname); +#if RSDEBUG + DEBUGLOG << "Dynamic SMS cost map failed to open: " << fname << std::endl; +#endif + cfile.clear(); + return -214; + } else { +#if RSDEBUG + DEBUGLOG << "Dynamic SMS cost map #" << i << " open to read" << std::endl; +#endif +#if !RSWIN64 + // check BOM for UTF-16 + if(check_bom(fname) == "utf16") + // apply BOM-sensitive UTF-16 facet + cfile.imbue(std::locale(cfile.getloc(), new std::codecvt_utf16)); +#endif + // ASCII header + cfile >> header; + if (!cfile.good()) { +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): failed to read SMS cost map #" << i << ": " << fname << std::endl; +#endif + errors = -1113; + cfile.close(); + cfile.clear(); + return errors; + } + if (header != L"ncols" && header != L"NCOLS") errors++; + cfile >> ncols; + + cfile >> header >> nrows; + if (header != L"nrows" && header != L"NROWS") errors++; + + cfile >> header >> xllcorner; + if (header != L"xllcorner" && header != L"XLLCORNER") errors++; + + cfile >> header >> yllcorner; + if (header != L"yllcorner" && header != L"YLLCORNER") errors++; + + double tmpcellsize; + cfile >> header >> tmpcellsize; + cellsize = (int) tmpcellsize; + if (header != L"cellsize" && header != L"CELLSIZE") errors++; + + cfile >> header >> costnodata; + if (header != L"NODATA_value" && header != L"NODATA_VALUE") errors++; + + if (errors > 0) { + FormatErrorR(fname,errors); +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): failed to read Raster header of SMS cost map #" << i << ": " << fname << std::endl; +#endif + cfile.close(); + cfile.clear(); + } else { + // check resolution match + if (cellsize == resolution) { + // check that extent matches landscape extent + if(ncols == landraster.ncols && nrows == landraster.nrows) { + // check origins match + if((int)xllcorner == (int)landraster.xllcorner && + (int)yllcorner == (int)landraster.yllcorner) { + Rcpp::Rcout << "Dynamic SMS cost map #" << i << ", headers OK: " << fname << endl; + } else { + Rcpp::Rcout << "*** Origin co-ordinates of " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Extent of " << fname << msghdrs1 << endl; + errors++; + } + } else { + Rcpp::Rcout << "*** Resolution of " << fname << msghdrs1 << endl; + errors++; + } + if (errors > 0) { + FormatErrorR(fname,errors); +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): Errors in raster header of SMS cost map #" << i << ": " << fname << std::endl; +#endif + cfile.close(); + cfile.clear(); + } + } // end of reading ASCII header + } + } // end of if(costs) + else { + cfile.clear(); + } + } + + if (nrDemogScaleLayers) { + if (threadsafe) + yearLayers = Rcpp::as(demogScaleLayers[i]); + else + yearLayers_fname = Rcpp::as(demogScaleLayers[i]); + } + + if (errors == 0) { + if (threadsafe){ + imported = pLandscape->readLandChange(i-1, hraster, praster, craster, yearLayers); + } else { + // file input + std::vector scaling_vec; + if(nrDemogScaleLayers){ + for (int i = 0; i < yearLayers_fname.size(); ++i) { + string scaling_fname =Rcpp::as(yearLayers_fname[i]); + scaling_fname = paramsSim->getDir(1) + scaling_fname; // prepend input directory to the file name + scaling_vec.push_back(scaling_fname); + } + } + + imported = pLandscape->readLandChange(i-1, costs, hfile, pfile, cfile, habnodata, pchnodata, costnodata, scaling_vec); + } + + if (imported != 0) { + if (!threadsafe){ + // close files + if(hfile.is_open()) hfile.close(); + hfile.clear(); + if(patchmodel) { + if(pfile.is_open()) pfile.close(); + pfile.clear(); + } + if (costs) { + if(cfile.is_open()) cfile.close(); + cfile.clear(); + } + } + return imported; + } + if (patchmodel) { + pLandscape->recordPatchChanges(i); + } + if (costs) { + pLandscape->recordCostChanges(i); + } + } + if (!threadsafe){ + // Close files + if(hfile.is_open()) hfile.close(); + hfile.clear(); + if(patchmodel) { + if(pfile.is_open()) pfile.close(); + pfile.clear(); + } + if (costs) { + if(cfile.is_open()) cfile.close(); + cfile.clear(); + } + } + } // end of loop over landscape changes i + + if(patchmodel) { + // record changes back to original landscape for multiple replicates + pLandscape->recordPatchChanges(0); + pLandscape->deletePatchChgMatrix(); + } + if (costs) { + pLandscape->recordCostChanges(0); + pLandscape->deleteCostsChgMatrix(); + } +#if RSDEBUG + DEBUGLOG << "ReadDynLandR(): finished" << endl; +#endif + return 0; +} + + + +//--------------------------------------------------------------------------- + +int ReadParametersR(Landscape* pLandscape, Rcpp::S4 ParMaster) +{ + Rcpp::S4 ParamParamsR("SimulationParams"); + ParamParamsR = Rcpp::as(ParMaster.slot("simul")); + + Rcpp::S4 DemogParamsR("DemogParams"); + DemogParamsR = Rcpp::as(ParMaster.slot("demog")); + + Rcpp::S4 LandParamsR("LandParams"); + LandParamsR = Rcpp::as(ParMaster.slot("land")); + + int error = 0; + landParams paramsLand = pLandscape->getLandParams(); + envStochParams env = paramsStoch->getStoch(); + demogrParams dem = pSpecies->getDemogrParams(); + simParams sim = paramsSim->getSim(); + + sim.simulation = Rcpp::as(ParamParamsR.slot("Simulation")); + sim.reps = Rcpp::as(ParamParamsR.slot("Replicates")); + sim.years = Rcpp::as(ParamParamsR.slot("Years")); +#if RSDEBUG + DEBUGLOG << "ReadParametersR(): paramsSim = " << paramsSim << endl; + DEBUGLOG << "ReadParametersR(): simulation = " << sim.simulation << " reps = " << sim.reps + << " years = " << sim.years << endl; +#endif + + int iiii, gradType, shift_begin, shift_stop; + float grad_inc, opt_y, f, optEXT, shift_rate; + bool shifting; + + // Landscape boundary and any 'no-data' areas are absorbing?: + sim.absorbing = Rcpp::as(ParamParamsR.slot("Absorbing")); + + // Environmental gradient: 0 = none, 1 = carrying capacity (or 1/b), 2 = growth rate (or fecundity), 3 = local + // extinction probability. Must be 0 for patch-based models. NOTE: change in code numbers from v1.0 + gradType = Rcpp::as(ParamParamsR.slot("Gradient")); + // following not required for Gradient = 0 + grad_inc = Rcpp::as(ParamParamsR.slot("GradSteep")); + opt_y = Rcpp::as(ParamParamsR.slot("Optimum")); + f = Rcpp::as(ParamParamsR.slot("f")); + optEXT = Rcpp::as(ParamParamsR.slot("ExtinctOptim")); + paramsGrad->setGradient(gradType, grad_inc, opt_y, f, optEXT); + + shifting = Rcpp::as(ParamParamsR.slot("Shifting")); + shift_rate = Rcpp::as(ParamParamsR.slot("ShiftRate")); + shift_begin = Rcpp::as(ParamParamsR.slot("ShiftStart")); + shift_stop = Rcpp::as(ParamParamsR.slot("ShiftEnd")); + if(shifting) + paramsGrad->setShifting(shift_rate, shift_begin, shift_stop); + else + paramsGrad->noShifting(); + + // Environmental stochasticity: 0 = none, 1 = global, 2 = local: + iiii = Rcpp::as(ParamParamsR.slot("EnvStoch")); + if(iiii == 0) + env.stoch = false; + else { + env.stoch = true; + if(iiii == 2) + env.local = true; + else + env.local = false; + } + // For a patch-based model, EnvStoch = 2 is NOT allowed: + if(paramsLand.patchModel && env.local) + error = 101; + + // Environmental stochasticity type: 0 = in growth rate, 1 = in carrying capacity + // Not required for EnvStoch = 0; stochasticity in carrying capacity is allowed for an artificial landscape only + env.inK = Rcpp::as(ParamParamsR.slot("EnvStochType")); + + // as from v1.1, there is just one pair of min & max values, + // which are attributes of the species + // ULTIMATELY, THE PARAMETER FILE SHOULD HAVE ONLY TWO COLUMNS ... + env.ac = Rcpp::as(ParamParamsR.slot("ac")); // Temporal autocorrelation coefficient + env.std = Rcpp::as(ParamParamsR.slot( + "std")); // Amplitude of stochastic fluctuations: standard deviation of a normal distribution (having mean 0) + float minR, maxR, minK, maxK; + minR = Rcpp::as(ParamParamsR.slot("minR")); // not required for EnvStoch = 0 or EnvStochType = 1 + maxR = Rcpp::as(ParamParamsR.slot("maxR")); // -"- + minK = Rcpp::as(ParamParamsR.slot("minK")); // not required for EnvStoch = 0 or EnvStochType = 0 + maxK = Rcpp::as(ParamParamsR.slot("maxK")); // -"- + if(env.inK) { + float minKK, maxKK; + minKK = minK * (((float)(pow(paramsLand.resol, double(2)))) / 10000.0); + maxKK = maxK * (((float)(pow(paramsLand.resol, double(2)))) / 10000.0); + pSpecies->setMinMax(minKK, maxKK); + } else + pSpecies->setMinMax(minR, maxR); + + env.localExt = Rcpp::as(ParamParamsR.slot("LocalExt")); + // For a patch-based model no LocalExt allowed: + if(paramsLand.patchModel && env.localExt) + error = 102; + env.locExtProb = Rcpp::as(ParamParamsR.slot("LocalExtProb")); + paramsStoch->setStoch(env); + + dem.propMales = Rcpp::as(DemogParamsR.slot("PropMales")); + dem.harem = Rcpp::as(DemogParamsR.slot("Harem")); + dem.bc = Rcpp::as(DemogParamsR.slot("bc")); + dem.lambda = Rcpp::as(DemogParamsR.slot("Rmax")); + + pSpecies->setDemogr(dem); + + float k; + if(landtype == 9) { // artificial landscape + // only one value of K is read, but the first 'habitat' is the matrix where K = 0 + pSpecies->createHabK(2); + k = Rcpp::as(LandParamsR.slot("K_or_DensDep")); + k *= ((double)(pow(paramsLand.resol, double(2)))) / 10000.0; + pSpecies->setHabK(0,0); + pSpecies->setHabK(1,k); + } else { + pSpecies->createHabK(paramsLand.nHabMax); + Rcpp::NumericVector k_vec; + k_vec = Rcpp::as(LandParamsR.slot("K_or_DensDep")); + for (int i = 0; i < paramsLand.nHabMax; i++) { + k = k_vec[i] * ((double)(pow(paramsLand.resol, double(2)))) / 10000.0; + pSpecies->setHabK(i,k); + } + } + +#if RSDEBUG + DEBUGLOG << "ReadParametersR(): dem.lambda = " << dem.lambda + << " habK[0] = " << pSpecies->getHabK(0) + << " nHabMax = " << paramsLand.nHabMax << endl; +#endif + + + // Output start years + sim.outStartPop = Rcpp::as(ParamParamsR.slot("OutStartPop")); + sim.outStartInd = Rcpp::as(ParamParamsR.slot("OutStartInd")); + sim.outStartTraitCell = Rcpp::as(ParamParamsR.slot("OutStartTraitCell")); + sim.outStartTraitRow = Rcpp::as(ParamParamsR.slot("OutStartTraitRow")); + sim.outStartConn = Rcpp::as(ParamParamsR.slot("OutStartConn")); + sim.outStartPaths = Rcpp::as(ParamParamsR.slot("OutStartPaths")); + // Output intervals + sim.outIntRange = Rcpp::as(ParamParamsR.slot("OutIntRange")); + sim.outIntOcc = Rcpp::as(ParamParamsR.slot("OutIntOcc")); + sim.outIntPop = Rcpp::as(ParamParamsR.slot("OutIntPop")); + sim.outIntInd = Rcpp::as(ParamParamsR.slot("OutIntInd")); + + if(sim.outIntRange > 0) + sim.outRange = true; + else + sim.outRange = false; + if(sim.outIntOcc > 0) + sim.outOccup = true; + else + sim.outOccup = false; + if(sim.outIntPop > 0) + sim.outPop = true; + else + sim.outPop = false; + if(sim.outIntInd > 0) + sim.outInds = true; + else + sim.outInds = false; + + sim.outIntTraitCell = Rcpp::as(ParamParamsR.slot("OutIntTraitCell")); + sim.outIntTraitRow = Rcpp::as(ParamParamsR.slot("OutIntTraitRow")); + sim.outIntConn = Rcpp::as(ParamParamsR.slot("OutIntConn")); + sim.outIntPaths = Rcpp::as(ParamParamsR.slot("OutIntPaths")); + if(sim.outIntTraitCell > 0) + sim.outTraitsCells = true; + else + sim.outTraitsCells = false; + if(sim.outIntTraitRow > 0) + sim.outTraitsRows = true; + else + sim.outTraitsRows = false; + if(sim.outIntConn > 0) + sim.outConnect = true; + else + sim.outConnect = false; + if(sim.outIntPaths > 0) + sim.outPaths = true; + else + sim.outPaths = false; + + if(sim.outOccup && sim.reps < 2) + error = 103; + if(paramsLand.patchModel) { + if(sim.outTraitsRows) + error = 104; + } else { + if(sim.outConnect) + error = 105; + } +#if RSDEBUG + DEBUGLOG << "ReadParametersR(): outRange = " << sim.outRange << " outInt = " << sim.outIntRange << endl; +#endif + + //sim.saveMaps = Rcpp::as(ParamParamsR.slot("SaveMaps")); + //sim.mapInt = Rcpp::as(ParamParamsR.slot("MapsInterval")); + sim.saveVisits = Rcpp::as(ParamParamsR.slot("SMSHeatMap")); + // sim.drawLoaded = Rcpp::as(ParamParamsR.slot("DrawLoadedSp")); +// sim.saveInitMap = false; +#if RS_RCPP + sim.ReturnPopMatrix = Rcpp::as(ParamParamsR.slot("ReturnPopMatrix")); + sim.ReturnPopDataFrame = Rcpp::as(ParamParamsR.slot("ReturnPopDataFrame")); + sim.ReturnStages = + Rcpp::as( + ParamParamsR.slot("ReturnStages") + ); + // sim.ReturnStages = Rcpp::LogicalVector(ParamParamsR.slot("ReturnStages")); + // loop over sim.ReturnStages to check if it is a logical vector + for(int i = 0; i < sim.ReturnStages.length(); i++) { + bool ReturnStage = sim.ReturnStages[i] == 1; + if(ReturnStage) { + Rcpp::Rcout << "Return Stage Nb. " << i << endl; + } + } + if(stagestruct){ + // size of sim.ReturnStages should not be larger than the number of stages + if(sim.ReturnStages.length() > stages){ + Rcpp::Rcout << "Error: ReturnStages should not have more entries than the number of stages." << endl; + error++; + } + }else { + if(sim.ReturnStages.length() != 1 || sim.ReturnStages[0] != false){ + Rcpp::Rcout << "Error: ReturnStages should be FALSE" << endl; + error++; + } + } + sim.CreatePopFile = Rcpp::as(ParamParamsR.slot("CreatePopFile")); +#endif + + paramsSim->setSim(sim); + + return error; +} + +//--------------------------------------------------------------------------- + + +int ReadStageStructureR(Rcpp::S4 ParMaster) +{ + Rcpp::S4 DemogParamsR("DemogParams"); + DemogParamsR = Rcpp::as(ParMaster.slot("demog")); + Rcpp::S4 StagesParamsR("StagesParams"); + StagesParamsR = Rcpp::as(DemogParamsR.slot("StageStruct")); + + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + int matrixsize, i, j, stg; + int errors = 0; + float ss, dd, devCoeff, survCoeff; + Rcpp::NumericMatrix trmatrix, wtsmatrix; + Rcpp::IntegerVector minAge; + +#if RSDEBUG + DEBUGLOG << "ReadStageStructureR(): sstruct.nStages = " << sstruct.nStages << endl; +#endif + // int simulation; + // simulation = Rcpp::as(StagesParamsR.slot("Simulation")); //Must match simulation numbers in ParamParams + sstruct.disperseOnLoss = Rcpp::as(StagesParamsR.slot("PostDestructn")); + sstruct.probRep = Rcpp::as(StagesParamsR.slot("PRep")); + sstruct.repInterval = Rcpp::as(StagesParamsR.slot("RepInterval")); + sstruct.maxAge = Rcpp::as(StagesParamsR.slot("MaxAge")); + trmatrix = Rcpp::as(StagesParamsR.slot("TransMatrix")); + // parsing is done on R-level + minAge = Rcpp::as(StagesParamsR.slot("MinAge")); + + // Store Transition matrix: + if(dem.repType != 2) { // asexual or implicit sexual model + matrixsize = sstruct.nStages; + for(i = 0; i < matrixsize; i++) { + // set minimum ages + pSpecies->setMinAge(i, 0, minAge(i)); + // set fecundities + pSpecies->setFec(i, 0, (float)trmatrix(0, i)); + // set survival and development probalities + ss = (float)trmatrix(i, i); // survival prob + if((i + 1) != matrixsize) { + dd = (float)trmatrix(i + 1, i); + } // development prob + else { + dd = 0.0; + } + pSpecies->setSurv(i, 0, ss + dd); + pSpecies->setDev(i, 0, dd / (ss + dd)); + } + } else { // complex sexual model + matrixsize = sstruct.nStages * 2; // juv (i=0) sex-independent as ending stage -> columns = rows + 1 + stg = 1; + for(i = 1; i < (matrixsize - 1); i++) { // loop over rows + // set minAge and fecundities + if(i % 2) { // odd columns -> males (1) + pSpecies->setMinAge(stg, 1, minAge(i)); + pSpecies->setFec(stg, 1, (float)trmatrix(0, i + 1)); + } else { // even columns -> females (0) + pSpecies->setMinAge(stg, 0, minAge(i)); + pSpecies->setFec(stg, 0, (float)trmatrix(0, i + 1)); + stg++; + } + } + stg = 0; + for(i = 0; i < matrixsize; i++) { // loop over columns + // survival and development + if(i != 0) + ss = (float)trmatrix(i - 1, i); // survival prob + else + ss = (float)trmatrix(i, i); + if((i + 2) != matrixsize && (i + 1) != matrixsize) + dd = (float)trmatrix(i + 1, i); // development prob + else + dd = 0.0; + if(i % 2 == 0) { // even rows -> males (1) + pSpecies->setSurv(stg, 1, ss + dd); + pSpecies->setDev(stg, 1, dd / (ss + dd)); + } else { // odd rows -> females (0) + pSpecies->setSurv(stg, 0, ss + dd); + pSpecies->setDev(stg, 0, dd / (ss + dd)); + stg++; + } + } + } +#if RSDEBUG + DEBUGLOG << "Read_Transition Matrix: matrix = " << trmatrix << endl; +#endif + + // Survival schedule: 0 = At reproduction; 1 = Between reproductive events; 2 = Annually + sstruct.survival = Rcpp::as(StagesParamsR.slot("SurvSched")); + + if(dem.repType != 2) + matrixsize = sstruct.nStages; + else + matrixsize = sstruct.nStages * gMaxNbSexes; + // Fecundity + sstruct.fecDens = Rcpp::as(StagesParamsR.slot("FecDensDep")); // Density-dependence in reproduction + sstruct.fecStageDens = + Rcpp::as(StagesParamsR.slot("FecStageWts")); // stage-specific density dependence of fecundity + if(sstruct.fecStageDens) { + wtsmatrix = Rcpp::as(StagesParamsR.slot("FecStageWtsMatrix")); + pSpecies->createDDwtFec(matrixsize); + for(i = 0; i < matrixsize; i++) { + for(j = 0; j < matrixsize; j++) { + pSpecies->setDDwtFec(i, j, wtsmatrix(i, j)); + } + } +#if RSDEBUG + DEBUGLOG << "Read_StageWeights(): completed reading fecundity weights matrix " << endl; +#endif + } + + // Development + sstruct.devDens = Rcpp::as(StagesParamsR.slot("DevDensDep")); // Density-dependence in development + devCoeff = Rcpp::as(StagesParamsR.slot("DevDensCoeff")); + sstruct.devStageDens = + Rcpp::as(StagesParamsR.slot("DevStageWts")); // stage-specific density dependence of development + if(sstruct.devStageDens) { + wtsmatrix = Rcpp::as(StagesParamsR.slot("DevStageWtsMatrix")); + pSpecies->createDDwtDev(matrixsize); + for(i = 0; i < matrixsize; i++) { + for(j = 0; j < matrixsize; j++) { + pSpecies->setDDwtDev(i, j, wtsmatrix(i, j)); + } + } +#if RSDEBUG + DEBUGLOG << "Read_StageWeights(): completed reading development weights matrix " << endl; +#endif + } + + // Survival + sstruct.survDens = Rcpp::as(StagesParamsR.slot("SurvDensDep")); // Density-dependence in survival + survCoeff = Rcpp::as(StagesParamsR.slot("SurvDensCoeff")); + sstruct.survStageDens = + Rcpp::as(StagesParamsR.slot("SurvStageWts")); // stage-specific density dependence of survival + if(sstruct.survStageDens) { + wtsmatrix = Rcpp::as(StagesParamsR.slot("SurvStageWtsMatrix")); + pSpecies->createDDwtSurv(matrixsize); + for(i = 0; i < matrixsize; i++) { + for(j = 0; j < matrixsize; j++) { + pSpecies->setDDwtSurv(i, j, wtsmatrix(i, j)); + } + } +#if RSDEBUG + DEBUGLOG << "Read_StageWeights(): completed reading survival weights matrix " << endl; +#endif + } + + + if (spatial_demography){ + if (landtype == 2) { // habitat quality + // index of input layer corresponding to each spatially varying demographic rate + short layercols,layerrows,layerix; + Rcpp::IntegerMatrix feclayerMatrix, devlayerMatrix, survlayerMatrix; + + feclayerMatrix = Rcpp::as(StagesParamsR.slot("FecLayer")); + devlayerMatrix = Rcpp::as(StagesParamsR.slot("DevLayer")); + survlayerMatrix = Rcpp::as(StagesParamsR.slot("SurvLayer")); + + if(dem.repType == 2) {layercols = gMaxNbSexes;} else {layercols = 1;} + layerrows = sstruct.nStages; + + if(layercols == feclayerMatrix.ncol() && layerrows == feclayerMatrix.nrow() ) { + for(i = 0; i < layerrows; i++) { // stages in rows + for(j = 0; j < layercols; j++) { // sexes in columns + if( !R_IsNA( feclayerMatrix(i,j) ) ){ + layerix = feclayerMatrix(i,j); + pSpecies->setFecLayer(i, j, (layerix-1) ); // subtract 1 to account for different indexing in R and C + pSpecies->setFecSpatial(true); + } + } + } + } else { + Rcpp::Rcout << "Dimensions of FecLayer matrix do not match; default values are used instead." << endl; + } + + if(layercols == devlayerMatrix.ncol() && layerrows == devlayerMatrix.nrow() ) { + for(i = 0; i < layerrows; i++) { // stages in rows + for(j = 0; j < layercols; j++) { // sexes in columns + if( !R_IsNA( devlayerMatrix(i,j) ) ){ + layerix = devlayerMatrix(i,j); + pSpecies->setDevLayer(i, j, (layerix-1) ); // subtract 1 to account for different indexing in R and C + pSpecies->setDevSpatial(true); + } + } + } + } else { + Rcpp::Rcout << "Dimensions of DevLayer matrix do not match; default values are used instead." << endl; + } + + if(layercols == survlayerMatrix.ncol() && layerrows == survlayerMatrix.nrow() ) { + for(i = 0; i < layerrows; i++) { // stages in rows + for(j = 0; j < layercols; j++) { // sexes in columns + if( !R_IsNA( survlayerMatrix(i,j) ) ){ + layerix = survlayerMatrix(i,j); + pSpecies->setSurvLayer(i, j, (layerix-1) ); // subtract 1 to account for different indexing in R and C + pSpecies->setSurvSpatial(true); + } + } + } + } else { + Rcpp::Rcout << "Dimensions of SurvLayer matrix do not match; default values are used instead." << endl; + } + } + } + + pSpecies->setStage(sstruct); + if(sstruct.devDens || sstruct.survDens) { + pSpecies->setDensDep(devCoeff, survCoeff); + } + + return 0; +} + +//--------------------------------------------------------------------------- + +int ReadEmigrationR(Rcpp::S4 ParMaster) +{ + + Rcpp::S4 DispParamsR("DispersalParams"); + DispParamsR = Rcpp::as(ParMaster.slot("dispersal")); + Rcpp::S4 EmigParamsR("EmigrationParams"); + EmigParamsR = Rcpp::as(DispParamsR.slot("Emigration")); + + int error = 0; + int Nlines, emigstage, stage, sex, offset; + Rcpp::NumericMatrix EmigMatrix; + Rcpp::NumericVector EmigScalesVec; + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + emigRules emig = pSpecies->getEmigRules(); + emigTraits emigrationTraits; + + emig.densDep = Rcpp::as(EmigParamsR.slot("DensDep")); + pSpecies->setFullKernel(Rcpp::as(EmigParamsR.slot("UseFullKern"))); // Emigration rate derived from kernel. Only for kernel-based transfer and DensDep = 0 + emig.stgDep = Rcpp::as(EmigParamsR.slot("StageDep")); // Stage-dependent emigration. Must be 0 if IndVar is 1 + emig.sexDep = Rcpp::as(EmigParamsR.slot("SexDep")); // Sex-dependent emigration. + emig.indVar = + Rcpp::as(EmigParamsR.slot("IndVar")); // Inter-individual variability. Must be 0 if StageDep is 1 + if(stagestruct && emig.indVar){ + emigstage = Rcpp::as(EmigParamsR.slot("EmigStage")); // Stage which emigrates. Required for stage-strucutred population having IndVar = 1 + if(emigstage >= 0 && emigstage < sstruct.nStages) + emig.emigStage = emigstage; + else + emig.emigStage = 0; + } else { + emig.emigStage = 0; + } + + pSpecies->setEmigRules(emig); + + if(!dem.repType && emig.sexDep) + error = 301; + if(!dem.stageStruct && emig.stgDep) + error = 303; + + // no.of lines according to known stage- and sex-dependency and corresponding column offset + if(emig.stgDep) { + if(emig.sexDep) { + Nlines = sstruct.nStages * gNbSexesDisp; + offset = 2; + } else { + Nlines = sstruct.nStages; + offset = 1; + } + } else { + if(emig.sexDep) { + Nlines = gNbSexesDisp; + offset = 1; + } else { + Nlines = 1; + offset = 0; + } + } + +#if RSDEBUG + DEBUGLOG << "ReadEmigrationR(): Nlines = " << Nlines << " emig.densDep = " << emig.densDep + << " emig.indVar = " << emig.indVar << " sexesDisp = " << sexesDisp << endl; +#endif + + if (!emig.indVar){ + EmigMatrix = Rcpp::as(EmigParamsR.slot("EmigProb")); + + for(int line = 0; line < Nlines; line++) { + + if(emig.stgDep) { + if(emig.sexDep) { + stage = (int)EmigMatrix(line, 0); + sex = (int)EmigMatrix(line, 1); + } else { + stage = (int)EmigMatrix(line, 0); + sex = 0; + } + } else { + if(emig.sexDep) { + stage = 0; + sex = (int)EmigMatrix(line, 0); + } else { + stage = 0; + sex = 0; + } + } + + if(emig.densDep) { + emigrationTraits.d0 = (float)EmigMatrix(line, offset + 0); + emigrationTraits.alpha = (float)EmigMatrix(line, offset + 1); + emigrationTraits.beta = (float)EmigMatrix(line, offset + 2); + + pSpecies->setSpEmigTraits(stage, sex, emigrationTraits); + } else { + emigrationTraits.d0 = (float)EmigMatrix(line, offset + 0); + emigrationTraits.alpha = emigrationTraits.beta = 0.0; + + pSpecies->setSpEmigTraits(stage, sex, emigrationTraits); + } + } // end of Nlines for loop + + } else { + gHasGenetics = true; + + // set the emigration probability parameters to -9 + if(emig.stgDep) { // it should not go in here because it cannot be stage dependent for individual variability + if(emig.sexDep) { + for (int i = 0; i < sstruct.nStages; i++) { + for (int j = 0; j < gNbSexesDisp; j++) { + if(emig.densDep){ + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = -9.0; + emigrationTraits.beta = -9.0; + pSpecies->setSpEmigTraits(i, j, emigrationTraits); + } else{ + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = emigrationTraits.beta = 0.0; + pSpecies->setSpEmigTraits(i, j, emigrationTraits); + } + } + } + } else { + for (int i = 0; i < sstruct.nStages; i++) { + if(emig.densDep){ + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = -9.0; + emigrationTraits.beta = -9.0; + pSpecies->setSpEmigTraits(i, 0, emigrationTraits); + } else{ + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = emigrationTraits.beta = 0.0; + pSpecies->setSpEmigTraits(i, 0, emigrationTraits); + } + + } + } + } else { + if(emig.sexDep) { + for (int j = 0; j < gNbSexesDisp; j++) { + if(emig.densDep) { + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = -9.0; + emigrationTraits.beta = -9.0; + pSpecies->setSpEmigTraits(0, j, emigrationTraits); + } else { + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = emigrationTraits.beta = 0.0; + pSpecies->setSpEmigTraits(0, j, emigrationTraits); + } + } + } else { + if(emig.densDep){ + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = -9.0; + emigrationTraits.beta = -9.0; + pSpecies->setSpEmigTraits(0, 0, emigrationTraits); + } else{ + emigrationTraits.d0 = -9.0; + emigrationTraits.alpha = emigrationTraits.beta = 0.0; + pSpecies->setSpEmigTraits(0, 0, emigrationTraits); + } + } + } + } // if indVar + + return error; +} + +//--------------------------------------------------------------------------- + +int ReadTransferR(Landscape* pLandscape, Rcpp::S4 ParMaster) +{ + Rcpp::S4 DispParamsR("DispersalParams"); + DispParamsR = Rcpp::as(ParMaster.slot("dispersal")); + + int Nlines, offset, stage, sex; + int error = 0; + + landParams paramsLand = pLandscape->getLandParams(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + transferRules trfr = pSpecies->getTransferRules(); + +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): TransferType=" << trfr.moveModel + << " paramsLand.generated=" << paramsLand.generated + << " paramsLand.rasterType=" << paramsLand.rasterType + << " trfr.moveModel=" << trfr.moveModel + << " trfr.twinKern=" << trfr.twinKern + << endl; +#endif + + // Create Costs vector of species + if(trfr.usesMovtProc) { +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): creating cost/mortality matrix, dimension="; + if(paramsLand.generated) + DEBUGLOG << paramsLand.nHab; + else + DEBUGLOG << paramsLand.nHabMax; + DEBUGLOG << endl; +#endif + if(paramsLand.generated) { + pSpecies->createHabCostMort(paramsLand.nHab); + } else { + pSpecies->createHabCostMort(paramsLand.nHabMax); + } + } + + int TransferType; // new local variable to replace former global variable + if(trfr.usesMovtProc) + TransferType = trfr.moveType; + else + TransferType = 0; + + // trfrKernTraits k; // andere Implementierung für individuelle Variabilität + // trfrMovtTraits movt; // andere Implementierung für individuelle Variabilität + trfrKernelParams kparams; + trfrMortParams mort; + // trfrScales scale; // andere Implementierung für individuelle Variabilität + string CostsFile; + trfrMovtParams smsparams; + trfrMovtParams mparams; + Rcpp::NumericVector ReadVec; + + switch(TransferType) { + case 0: { // dispersal kernel + + Rcpp::S4 TransParamsR("DispersalKernel"); + TransParamsR = Rcpp::as(DispParamsR.slot("Transfer")); + + Rcpp::NumericMatrix DispMatrix; + // Rcpp::NumericVector DispScalesVec; + + // simulation = Rcpp::as(TransParamsR.slot("Simulation")); // REMOVED in R-interface //Must match + // simulation numbers in ParamParams + trfr.stgDep = Rcpp::as(TransParamsR.slot("StageDep")); // Stage-dependent transfer. Must be 0 if IndVar is 1 + trfr.sexDep = Rcpp::as(TransParamsR.slot("SexDep")); // Sex-dependent transfer. + trfr.twinKern = Rcpp::as(TransParamsR.slot("DoubleKernel")); // 0 = negative exponential; 1 = double negative exponential + trfr.distMort = Rcpp::as(TransParamsR.slot("DistMort")); // Distance-dependent mortality + trfr.indVar = Rcpp::as(TransParamsR.slot("IndVar")); + + // some error checks + if(dem.repType == 0) { + if(trfr.sexDep) { + error = 401; + } + } + if(dem.stageStruct) { + } // if (trfr.indVar) error = 402; + else { + if(trfr.stgDep) { + error = 403; + } + } + + // set no. of lines according to known stage- and sex-dependency and corresponding column offset + if(trfr.stgDep) { + if(trfr.sexDep) { + Nlines = sstruct.nStages * gNbSexesDisp; + offset = 2; + } else { + Nlines = sstruct.nStages; + offset = 1; + } + } else { + if(trfr.sexDep) { + Nlines = gNbSexesDisp; + offset = 1; + } else { + Nlines = 1; + offset = 0; + } + } + + if(trfr.indVar){ + // parameters for individual variability are set in ReadTraits() + stage = 0; + kparams.meanDist1 = -9; + kparams.meanDist2 = -9; + kparams.probKern1 = -9; + if(trfr.sexDep) { + for (sex=0; sexsetSpKernTraits(stage, sex, kparams, paramsLand.resol); + } + } else { + pSpecies->setSpKernTraits(stage, 0, kparams, paramsLand.resol); + } + } + else { + DispMatrix = Rcpp::as(TransParamsR.slot("Distances")); // only if not indVar + + for(int line = 0; line < Nlines; line++) { + + if(trfr.stgDep) { + if(trfr.sexDep) { + stage = (int)DispMatrix(line, 0); + sex = (int)DispMatrix(line, 1); + } else { + stage = (int)DispMatrix(line, 0); + sex = 0; + } + } else { + if(trfr.sexDep) { + stage = 0; + sex = (int)DispMatrix(line, 0); + } else { + stage = 0; + sex = 0; + } + } + + if(trfr.twinKern) { + kparams.meanDist1 = (float)DispMatrix(line, offset + 0); + kparams.meanDist2 = (float)DispMatrix(line, offset + 1); + kparams.probKern1 = (float)DispMatrix(line, offset + 2); + + pSpecies->setSpKernTraits(stage, sex, kparams, paramsLand.resol); + } else { // single kernel + kparams.meanDist1 = (float)DispMatrix(line, offset + 0); + kparams.meanDist2 = kparams.meanDist1; + kparams.probKern1 = 1.0; + + pSpecies->setSpKernTraits(stage, sex, kparams, paramsLand.resol); + } + } // end of Nlines for-loop + } + + // mortality + mort.fixedMort = Rcpp::as(TransParamsR.slot("MortProb")); + mort.mortAlpha = Rcpp::as(TransParamsR.slot("Slope")); + mort.mortBeta = Rcpp::as(TransParamsR.slot("InflPoint")); + pSpecies->setMortParams(mort); + + pSpecies->setTrfrRules(trfr); + + } + break; // end of dispersal kernel + + case 1: { // SMS + + Rcpp::S4 TransParamsR("StochMove"); + TransParamsR = Rcpp::as(DispParamsR.slot("Transfer")); + + // simulation = Rcpp::as(TransParamsR.slot("Simulation")); // REMOVED in R-interface // Must match simulation numbers in ParamParams + smsparams.pr = Rcpp::as(TransParamsR.slot("PR")); // Perceptual range (cells) + smsparams.prMethod = Rcpp::as(TransParamsR.slot("PRMethod")); // Perceptual range method: 1 = arithmetic mean; 2 = harmonic mean; 3 = weighted arithmtic mean + smsparams.memSize = Rcpp::as(TransParamsR.slot("MemSize")); // No. of previous steps over which to calculate current direction to apply DP [1-14] + smsparams.goalType = Rcpp::as(TransParamsR.slot("GoalType")); // Goal type: 0 (none) or 2 (dispersal bias) + trfr.indVar = Rcpp::as(TransParamsR.slot("IndVar")); + + if(trfr.indVar) { + smsparams.dp = -9; + } else { + ReadVec = Rcpp::as(TransParamsR.slot("DP")); // Directional persistence, Must be >= 1.0 + if(ReadVec.size() == 1) { + smsparams.dp = (float)ReadVec[0]; + } else { + error = 436; + } + } + if(trfr.indVar) { + smsparams.gb = -9; + } else { + ReadVec = Rcpp::as(TransParamsR.slot("GoalBias")); // Goal bias strength, Must be >= 1.0 + if(ReadVec.size() == 1) { + smsparams.gb = (float)ReadVec[0]; + } else { + error = 436; + } + } + if(smsparams.goalType == 2) { // dispersal bias + if(trfr.indVar) { + smsparams.alphaDB = -9; + } else { + ReadVec = Rcpp::as(TransParamsR.slot("AlphaDB")); // Dispersal bias decay rate (> 0) + if(ReadVec.size() == 1) { + smsparams.alphaDB = (float)ReadVec[0]; + } else { + error = 436; + } + } + if(trfr.indVar) { + smsparams.betaDB = -9; + } else { + ReadVec = Rcpp::as(TransParamsR.slot("BetaDB")); // Dispersal bias decay inflection point (no. of steps) (> 0) + if(ReadVec.size() == 1) { + smsparams.betaDB = (float)ReadVec[0]; + } else { + error = 436; + } + } + } +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): SMS" << endl + << " indVar=" << trfr.indVar << " PR=" << movt.pr << " PRmethod=" << movt.prMethod << endl; + DEBUGLOG << "ReadTransferR(): dp=" << movt.dp << " MemSize=" << movt.memSize << " gb=" << movt.gb + << " goaltype=" << movt.goalType << endl; +#endif + + smsparams.straightenPath = Rcpp::as(TransParamsR.slot("StraightenPath")); // Straighten path after decision not to settle? + + // Mortality + Rcpp::NumericVector HabMortVec; + HabMortVec = Rcpp::as(TransParamsR.slot("StepMort")); + if(HabMortVec.size() == 1) { + trfr.habMort = false; // Per-step mortality type: 0 = constant + smsparams.stepMort = (float)HabMortVec[0]; // Constant per-step mortality probability + } else { + trfr.habMort = true; // Per-step mortality type: 1 = habitat-dependent + smsparams.stepMort = -9; + if(paramsLand.generated) { + // values are for habitat (hab=1) then for matrix (hab=0) + pSpecies->setHabMort(1, (double)HabMortVec[1]); + pSpecies->setHabMort(0, (double)HabMortVec[0]); +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): Generated Landscpae with MortHabitat=" << pSpecies->getHabMort(1) + << " MortMatrix=" << pSpecies->getHabMort(0) << endl; +#endif + } + if(paramsLand.rasterType == 0) { +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): nHabMax = " << paramsLand.nHabMax << endl; +#endif + for(int i = 0; i < paramsLand.nHabMax; i++) { + pSpecies->setHabMort(i, (double)HabMortVec[i]); +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): Habitat #" << i << ": mortality = " << pSpecies->getHabMort(i) + << endl; +#endif + } + } + } + + +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): SMtype=" << trfr.habMort << " SMconst=" << movt.stepMort << endl; +#endif + + // Costs + trfr.costMap = Rcpp::as(TransParamsR.slot("CostMap")); + + // read habitat costs for land types + Rcpp::NumericVector HabCostVec; + if(!trfr.costMap) { + HabCostVec = Rcpp::as(TransParamsR.slot("Costs")); +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): Read Habitat Cost vector of length " << HabCostVec.size() << endl; +#endif + } + + if(!paramsLand.generated) { // real landscape + if(paramsLand.rasterType == 0) { // habitat codes + if(!trfr.costMap) { // habitat costs + for(int i = 0; i < paramsLand.nHabMax; i++) { + pSpecies->setHabCost(i, (int)HabCostVec[i]); +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): Habitat #" << i << ": cost = " << pSpecies->getHabCost(i) << endl; +#endif + } + } + } else { // habitat quality + // should have trfr.costMap = 1 + } + } else { // artificial landscape + if(trfr.costMap) { // should not occur + // should have trfr.costMap = 0 + } else { // habitat costs + // costs are for habitat (hab=1) then for matrix (hab=0) + pSpecies->setHabCost(1, (int)HabCostVec[1]); + pSpecies->setHabCost(0, (int)HabCostVec[0]); + } + } + pSpecies->setTrfrRules(trfr); + pSpecies->setSpMovtTraits(smsparams); + } + break; // end of SMS + + case 2: { // CRW + + Rcpp::S4 TransParamsR("CorrRW"); + TransParamsR = Rcpp::as(DispParamsR.slot("Transfer")); + + // simulation = Rcpp::as(TransParamsR.slot("Simulation"));// REMOVED in R-interface //Must match + // simulation numbers in ParamParams + trfr.indVar = Rcpp::as(TransParamsR.slot("IndVar")); + + if(trfr.indVar) { + mparams.stepLength = -9; // Step length initial mean (m); Required for IndVar = 1 + } else { + ReadVec = Rcpp::as(TransParamsR.slot("StepLength")); // Step length params + if(ReadVec.size() == 1) { + mparams.stepLength = (float)ReadVec[0]; // Step length (m); Required for IndVar = 0; must be > 0 + } else { + error = 436; + } + } + + if(trfr.indVar) { + mparams.rho = -9; // Step correlation coefficient initial mean (m); Required for IndVar = 1 + } else { + ReadVec = Rcpp::as(TransParamsR.slot("Rho")); // Step correlation coefficient params + if(ReadVec.size() == 1) { + mparams.rho = + (float)ReadVec[0]; // Step correlation coefficient; Required for IndVar = 0; must be > 0.0 and < 1.0 + } else { + error = 436; + } + } + + mparams.straightenPath = Rcpp::as(TransParamsR.slot("StraightenPath")); // Straighten path after decision not to settle? + // pSpecies->setTrfrScales(scale); + +#if RSDEBUG + DEBUGLOG << "ReadTransferR():" + << " paramsLand.rasterType=" << paramsLand.rasterType << " trfr.indVar=" << trfr.indVar + << " move.stepLength=" << movt.stepLength << " move.rho=" << movt.rho + << " mparams.stepLgthMean=" << mparams.stepLgthMean << " mparams.rhoMean=" << mparams.rhoMean + << " move.straigtenPath=" << movt.straigtenPath << endl; +#endif + + // Mortality + Rcpp::NumericVector HabMortVec; + HabMortVec = Rcpp::as(TransParamsR.slot("StepMort")); + + if(HabMortVec.size() == 1) { + trfr.habMort = 0; // Per-step mortality type: 0 = constant + mparams.stepMort = (float)HabMortVec[0]; // Constant per-step mortality probability + } else { + trfr.habMort = 1; // Per-step mortality type: 1 = habitat-dependent + mparams.stepMort = -9; + if(paramsLand.generated) { + // values are for habitat (hab=1) then for matrix (hab=0) + pSpecies->setHabMort(1, (double)HabMortVec[1]); + pSpecies->setHabMort(0, (double)HabMortVec[0]); +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): Generated Landscpae with MortHabitat=" << pSpecies->getHabMort(1) + << " MortMatrix=" << pSpecies->getHabMort(0) << endl; +#endif + } + if(paramsLand.rasterType == 0) { +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): nHabMax = " << paramsLand.nHabMax << endl; +#endif + for(int i = 0; i < paramsLand.nHabMax; i++) { + pSpecies->setHabMort(i, (double)HabMortVec[i]); +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): Habitat #" << i << ": mortality = " << pSpecies->getHabMort(i) + << endl; +#endif + } + } + } + if(trfr.habMort && paramsLand.rasterType != 0) + error = 434; // habitat percentage landscape cant have habitat-dependent mortality + +#if RSDEBUG + DEBUGLOG << "ReadTransferR(): SMtype=" << trfr.habMort << " SMconst=" << movt.stepMort << endl; +#endif + + pSpecies->setTrfrRules(trfr); + pSpecies->setSpMovtTraits(mparams); + + } + break; // end of CRW + + default: + error = 440; + } // end of switch (TransferType) + + if(trfr.indVar) gHasGenetics = true; + + return error; +} + +//--------------------------------------------------------------------------- +// NOTE that stage- and sex-dependent settlement parameters are set for +// ALL stage/sex combinations, even if the species has stage- and/or +// sex-independent settlement rules +int ReadSettlementR(Rcpp::S4 ParMaster) +{ + + Rcpp::S4 DispParamsR("DispersalParams"); + DispParamsR = Rcpp::as(ParMaster.slot("dispersal")); + Rcpp::S4 SettleParamsR("SettlementParams"); + SettleParamsR = Rcpp::as(DispParamsR.slot("Settlement")); + + int Nlines, stage, sex, offset, sexSettle, settType; + int error = 0; + bool findmate, densdep; + + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + transferRules trfr = pSpecies->getTransferRules(); + settleType sett = pSpecies->getSettle(); + settleRules srules; + settleSteps ssteps; // = pSpecies->getSteps(0,0); + settleTraits settleDD; // = pSpecies->getSpSettTraits(0,0); + sett.stgDep = Rcpp::as(SettleParamsR.slot("StageDep")); // Stage-dependent settlement. + sett.sexDep = Rcpp::as(SettleParamsR.slot("SexDep")); // Sex-dependent settlement. + if ( gTransferType == 0) { + // dispersal kernel // dispersal kernel + sett.indVar = false; + if(dem.repType == 0) { + if(sett.sexDep) + error = 501; // sex-dependent settlement is not possible with asexual models + } + if(!dem.stageStruct) { + if(sett.stgDep) + error = 502; // stage-dependent settlement is not possible without stage structure + } + } else { // movement process + sett.indVar = Rcpp::as(SettleParamsR.slot("IndVar")); + densdep = Rcpp::as(SettleParamsR.slot("DensDep")); + if(dem.repType == 0) { + if(sett.sexDep) + error = 508; // sex-dependent settlement is not possible with asexual models + } + if(!dem.stageStruct) { + if(sett.stgDep) + error = 509; // stage-dependent settlement is not possible without stage structure + } + } + pSpecies->setSettle(sett); + + // no.of lines according to known stage- and sex-dependency and corresponding column offset + if(sett.stgDep) { + if(sett.sexDep) { + Nlines = sstruct.nStages * gNbSexesDisp; + offset = 2; + } else { + Nlines = sstruct.nStages; + offset = 1; + } + } else { + if(sett.sexDep) { + Nlines = gNbSexesDisp; + offset = 1; + } else { + Nlines = 1; + offset = 0; + } + } +#if RSDEBUG + DEBUGLOG << "ReadSettlementR(): sett.stgDep = " << sett.stgDep << ", sett.sexDep = " << sett.sexDep + << ", sett.indVar = " << sett.indVar << endl; +#endif + // check if SettleParamsR.slots are single values or a matrix and assign them accordingly: + Rcpp::NumericMatrix FindMate; + bool constFindMate = false; + if(Rf_isMatrix(SettleParamsR.slot("FindMate"))){ + FindMate = Rcpp::as(SettleParamsR.slot("FindMate")); + } else { + int singleValue = Rcpp::as(SettleParamsR.slot("FindMate")); + FindMate = Rcpp::NumericMatrix(1, 1); + FindMate(0, 0) = singleValue; + constFindMate = true; + } + + Rcpp::NumericMatrix MinSteps; + bool constMinSteps = false; + if(Rf_isMatrix(SettleParamsR.slot("MinSteps"))){ + MinSteps = Rcpp::as(SettleParamsR.slot("MinSteps")); + } else { + int singleValue = Rcpp::as(SettleParamsR.slot("MinSteps")); + MinSteps = Rcpp::NumericMatrix(1, 1); + MinSteps(0, 0) = singleValue; + constMinSteps = true; + } + + + Rcpp::NumericMatrix MaxSteps; + bool constMaxSteps = false; + if(Rf_isMatrix(SettleParamsR.slot("MaxSteps"))){ + MaxSteps = Rcpp::as(SettleParamsR.slot("MaxSteps")); + } else { + int singleValue = Rcpp::as(SettleParamsR.slot("MaxSteps")); + MaxSteps = Rcpp::NumericMatrix(1, 1); + MaxSteps(0, 0) = singleValue; + constMaxSteps = true; + } + + Rcpp::NumericMatrix MaxStepsYr; + bool constMaxStepsYr = false; + if(Rf_isMatrix(SettleParamsR.slot("MaxStepsYear"))){ + MaxStepsYr = Rcpp::as(SettleParamsR.slot("MaxStepsYear")); + } else { + int singleValue = Rcpp::as(SettleParamsR.slot("MaxStepsYear")); + MaxStepsYr = Rcpp::NumericMatrix(1, 1); + MaxStepsYr(0, 0) = singleValue; + constMaxStepsYr = true; + } + + Rcpp::NumericMatrix SettleCondMatrix; + + if(Rf_isMatrix(SettleParamsR.slot("Settle"))){ + SettleCondMatrix = Rcpp::as(SettleParamsR.slot("Settle")); + } else { + int singleValue = Rcpp::as(SettleParamsR.slot("Settle")); + SettleCondMatrix = Rcpp::NumericMatrix(1, 1); + SettleCondMatrix(0, 0) = singleValue; + } + + sexSettle = 2 * sett.stgDep + sett.sexDep; + + for(int line = 0; line < Nlines; line++) { + // determine stage and sex of this line + if(sett.stgDep) { + if(sett.sexDep) { + stage = (int)FindMate(line, 0); + sex = (int)FindMate(line, 1); + } else { + stage = (int)FindMate(line, 0); + sex = 0; + } + } else { + if(sett.sexDep) { + stage = 0; + sex = (int)FindMate(line, 0); + } else { + stage = 0; + sex = 0; + } + } + + if(trfr.usesMovtProc) { // ...movement process + // FindMate + if(constFindMate) { + findmate = (bool)FindMate(0, 0); + } else { + findmate = (bool)FindMate(line, offset); + } + if(findmate && dem.repType == 0) + error = 504; + + // MinSteps + if(constMinSteps) { + ssteps.minSteps = (int)MinSteps(0, 0); + } else { + ssteps.minSteps = (int)MinSteps(line, offset); + } + + // MaxSteps + if(constMaxSteps) { + ssteps.maxSteps = (int)MaxSteps(0, 0); + } else { + ssteps.maxSteps = (int)MaxSteps(line, offset); + } + + // MaxStepsYr + if(constMaxStepsYr) { + ssteps.maxStepsYr = (int)MaxStepsYr(0, 0); + } else { + ssteps.maxStepsYr = (int)MaxStepsYr(line, offset); + } + + // SettleCondMatrix + if(densdep) { + if (sett.indVar) { // values are provided via SettleTraits + gHasGenetics = true; + settleDD.s0 = -9; + settleDD.alpha = -9; + settleDD.beta = -9; + } else { + settleDD.s0 = (float)SettleCondMatrix( + line, offset + 0); // Max. settlement probability for density reaction norm. Required for + // DensDep = 1 and IndVar = 0; 0.0 < S0 <= 1.0 + settleDD.alpha = + (float)SettleCondMatrix(line, offset + 1); // Required for DensDep = 1 and IndVar = 0 + settleDD.beta = + (float)SettleCondMatrix(line, offset + 2); // Required for DensDep = 1 and IndVar = 0 + } + } else { // only s0 needs to be provided + settleDD.s0 = (float)SettleCondMatrix( + line, offset + 0); // Max. settlement probability for density reaction norm. Required for + // DensDep = 1 and IndVar = 0; 0.0 < S0 <= 1.0 + settleDD.alpha = -9; + settleDD.beta = -9; + } + + switch(sexSettle) { + + case 0: { // no sex- / stage-dependence + srules = pSpecies->getSettRules(0, 0); + srules.densDep = densdep; + srules.findMate = findmate; + + if(dem.stageStruct) { // model is structured - also set parameters for all stages + for(int i = 0; i < sstruct.nStages; i++) { + pSpecies->setSettRules(i, 0, srules); + pSpecies->setSteps(i, 0, ssteps); + if(srules.densDep) { + pSpecies->setSpSettTraits(i, 0, settleDD); + } + if(dem.repType > 0) { // model is sexual - also set parameters for males + pSpecies->setSettRules(i, 1, srules); + pSpecies->setSteps(i, 1, ssteps); + if (srules.densDep) { + pSpecies->setSpSettTraits(i, 1, settleDD); + } + } + } + } else { // see comment above (at case label) + if(dem.repType > 0) { // model is sexual - set parameters for both sexes + pSpecies->setSettRules(0, 0, srules); + pSpecies->setSteps(0, 0, ssteps); + if (srules.densDep) { + pSpecies->setSpSettTraits(0, 0, settleDD); + } + pSpecies->setSettRules(0, 1, srules); + pSpecies->setSteps(0, 1, ssteps); + if(srules.densDep) { + pSpecies->setSpSettTraits(0, 1, settleDD); + } + } else { // asexual - set parameters only for females + pSpecies->setSettRules(0, 0, srules); + pSpecies->setSteps(0, 0, ssteps); + if (srules.densDep) { + pSpecies->setSpSettTraits(0, 0, settleDD); + } + } + } + } + break; + + case 1: { // sex-dependent + srules = pSpecies->getSettRules(0, sex); + srules.densDep = densdep; + srules.findMate = findmate; + + pSpecies->setSettRules(0, sex, srules); + pSpecies->setSteps(0, sex, ssteps); + if(srules.densDep) { + pSpecies->setSpSettTraits(0, sex, settleDD); + } + + if(dem.stageStruct) { // model is structured - also set parameters for all stages + for(int i = 1; i < sstruct.nStages; i++) { + pSpecies->setSettRules(i, sex, srules); + pSpecies->setSteps(i, sex, ssteps); + if (srules.densDep) { + pSpecies->setSpSettTraits(i, sex, settleDD); + } + } + } + + } + break; + + case 2: { // stage-dependent + srules = pSpecies->getSettRules(stage, 0); + srules.densDep = densdep; + srules.findMate = findmate; + + pSpecies->setSettRules(stage, 0, srules); + pSpecies->setSteps(stage, 0, ssteps); + if(srules.densDep) { + pSpecies->setSpSettTraits(stage, 0, settleDD); + } + if(dem.repType > 0) { // model is sexual - also set parameters for males + pSpecies->setSettRules(stage, 1, srules); + pSpecies->setSteps(stage, 1, ssteps); + if(srules.densDep) { + pSpecies->setSpSettTraits(stage, 0, settleDD); + } + } + + } + break; + + case 3: { // sex- & stage-dependent + srules = pSpecies->getSettRules(stage, sex); + srules.densDep = densdep; + srules.findMate = findmate; + pSpecies->setSettRules(stage, sex, srules); + pSpecies->setSteps(stage, sex, ssteps); + if(srules.densDep) { + pSpecies->setSpSettTraits(stage, sex, settleDD); + } + } + break; + } // end sexSettle + } + else { // ...dispersal kernel + if(constFindMate) { + findmate = (bool)FindMate(0, 0); + } // Mating requirements to settle, required for a sexual population only + else { + findmate = (bool)FindMate(line, offset); + } + if(findmate && dem.repType == 0) + error = 504; + + settType = (int)SettleCondMatrix(line, + offset); // Settlement rule if the arrival cell/patch is unsuitable: 0 = die, 1 = wait, 2 = randomly choose a suitable cell/patch or die, 3 = randomly choose a suitable cell/patch or wait. + // Options 1 and 3 may be chosen for a stage-structured population only + + + switch(sexSettle) { + case 0: { // no sex / stage dependence + if(findmate && dem.repType == 0) + error = 504; + srules = pSpecies->getSettRules(0, 0); + srules.findMate = findmate; + + if((settType == 1 || settType == 3) && !dem.stageStruct) + error = 503; + switch(settType) { + case 0: + srules.wait = false; + srules.go2nbrLocn = false; + break; + case 1: + srules.wait = true; + srules.go2nbrLocn = false; + break; + case 2: + srules.wait = false; + srules.go2nbrLocn = true; + break; + case 3: + srules.wait = true; + srules.go2nbrLocn = true; + break; + } + + if(dem.stageStruct) { // model is structured - also set parameters for all stages + for(int i = 0; i < sstruct.nStages; i++) { + pSpecies->setSettRules(i, 0, srules); + if(dem.repType > 0) { // model is sexual - also set parameters for males + pSpecies->setSettRules(i, 1, srules); + } + } + } else { + pSpecies->setSettRules(0, 0, srules); + if(dem.repType > 0) { // model is sexual - also set parameters for males + pSpecies->setSettRules(0, 1, srules); + } + } + + } + break; + + case 1: { // sex dependent + srules = pSpecies->getSettRules(0, sex); + srules.findMate = findmate; + + if((settType == 1 || settType == 3) && dem.stageStruct == false) + error = 505; + + switch(settType) { + case 0: + srules.wait = false; + srules.go2nbrLocn = false; + break; + case 1: + srules.wait = true; + srules.go2nbrLocn = false; + break; + case 2: + srules.wait = false; + srules.go2nbrLocn = true; + break; + case 3: + srules.wait = true; + srules.go2nbrLocn = true; + break; + } + + pSpecies->setSettRules(0, sex, srules); + if(dem.stageStruct) { // model is structured - also set parameters for all stages + for(int i = 1; i < sstruct.nStages; i++) { + pSpecies->setSettRules(i, sex, srules); + } + } + } + break; + + case 2: { // stage dependent + if(findmate && dem.repType == 0) + error = 507; + srules = pSpecies->getSettRules(stage, 0); + srules.findMate = findmate; + + switch(settType) { + case 0: + srules.wait = false; + srules.go2nbrLocn = false; + break; + case 1: + srules.wait = true; + srules.go2nbrLocn = false; + break; + case 2: + srules.wait = false; + srules.go2nbrLocn = true; + break; + case 3: + srules.wait = true; + srules.go2nbrLocn = true; + break; + } + + pSpecies->setSettRules(stage, 0, srules); + if(dem.repType > 0) { // model is sexual - also set parameters for males + pSpecies->setSettRules(stage, 1, srules); + } + } + break; + + case 3: { // sex & stage dependent + srules = pSpecies->getSettRules(stage, sex); + srules.findMate = findmate; + switch(settType) { + case 0: + srules.wait = false; + srules.go2nbrLocn = false; + break; + case 1: + srules.wait = true; + srules.go2nbrLocn = false; + break; + case 2: + srules.wait = false; + srules.go2nbrLocn = true; + break; + case 3: + srules.wait = true; + srules.go2nbrLocn = true; + break; + } + pSpecies->setSettRules(stage, sex, srules); + } + break; + + } // end of switch (sexSettle) + + } // end of dispersal kernel + + } // end of for line loop + + return error; +} + + +//--------------------------------------------------------------------------- + +int ReadInitialisationR(Landscape* pLandscape, Rcpp::S4 ParMaster) +{ + + Rcpp::S4 InitParamsR("InitialisationParams"); + InitParamsR = Rcpp::as(ParMaster.slot("init")); + + Rcpp::NumericVector PropStages; + + landParams paramsLand = pLandscape->getLandParams(); + demogrParams dem = pSpecies->getDemogrParams(); + stageParams sstruct = pSpecies->getStageParams(); + initParams init = paramsInit->getInit(); + string Inputs = paramsSim->getDir(1); + + int maxcells; //,simulation + float p, check; + int error = 0; + + // simulation = Rcpp::as(InitParamsR.slot("Simulation"));// REMOVED in R-interface + init.seedType = Rcpp::as( + InitParamsR.slot("InitType")); // Initialisation type: 0 = free initialisation, 1 = from species distribution, 2 + // = from initial individuals file. Must be 0 for artificial landscapes. + init.freeType = Rcpp::as(InitParamsR.slot( + "FreeType")); // If SeedType = 0: Type of free initialisation (i.e. not from specified distribution): 0 = Random + // (given no. of cells/patches), 1 = All suitable cells/patches. + init.spDistType = Rcpp::as( + InitParamsR.slot("SpType")); // If SeedType = 1: Type of initialisation from species distribution: 0 = All + // suitable cells/patches within the distribution cells, 1 = Some randomly chosen + // suitable cells/patches within distribution cells + if(init.seedType == 1 && paramsLand.spDist == false) + error = 601; + + if(paramsLand.patchModel) { + init.initDens = Rcpp::as(InitParamsR.slot( + "InitDens")); // Initial density of individuals in each patch: 0 = at carrying capacity; 1 + // = at half carrying capacity; 2 = specified density. Patch carrying capacity + // is determined by the carrying capacities of the cells forming the patch. + init.indsHa = + Rcpp::as(InitParamsR.slot("IndsHaCell")); // If initDens = 2: Density of individuals to initialise + // per hectare; required for initDens = 2. + } else { + init.initDens = Rcpp::as( + InitParamsR.slot("InitDens")); // Initial no. of individuals in each cell: 0 = at carrying capacity; 1 = at + // half carrying capacity; 2 = specified no. of individuals + init.indsCell = + Rcpp::as(InitParamsR.slot("IndsHaCell")); // If initDens = 2: No. of individuals to initialise in each + // cell; required for initDens = 2, otherwise set to -9 + } + + init.minSeedX = + Rcpp::as(InitParamsR.slot("minX")); // Required for SeedType = 0 only; minX and minY may not be less than + // 0, maxX and maxY may not be less than corresponding minimum + init.maxSeedX = Rcpp::as(InitParamsR.slot("maxX")); // -"- + init.minSeedY = Rcpp::as(InitParamsR.slot("minY")); // -"- + init.maxSeedY = Rcpp::as(InitParamsR.slot("maxY")); // -"- + init.nSeedPatches = Rcpp::as( + InitParamsR.slot("NrCells")); // If SeedType = 0 and FreeType = 0: No. of cells/patches to initialise + init.nSpDistPatches = Rcpp::as(InitParamsR.slot( + "NrCells")); // If SeedType = 1 and SpType = 1: No. of species dist cells/patches to initialise + init.initFrzYr = + Rcpp::as(InitParamsR.slot("InitFreezeYear")); // Year until which species is confined to initial range + // limits. Must be >= 0 for SeedType = 0. + init.restrictRows = + Rcpp::as(InitParamsR.slot("RestrictRows")); // No. of rows at northern front to restrict range. Must be >0 + // if applied for SeedType = 0, otherwise 0. + init.restrictFreq = + Rcpp::as(InitParamsR.slot("RestrictFreq")); // Frequency (years) at which range is restricted to northern + // front. Must be > 0 if RestrictRows is > 0. + init.finalFrzYr = + Rcpp::as(InitParamsR.slot("FinalFreezeYear")); // Year after which species is confined to current range + // limits. Must be > InitFreezeYear if applied, otherwise 0. + if(InitParamsR.slot("InitIndsFile") != R_NilValue){ + init.indsFile = Rcpp::as(InitParamsR.slot("InitIndsFile")); // Name of the initial individuals file (*.txt). Required for SeedType = 2, otherwise NULL. + }else{ + init.indsFile = "NULL"; + } +#if RSDEBUG + DEBUGLOG << "ReadInitialisationR():" + //<< " simulation=" << simulation + << " seedType=" << init.seedType + << " freeType=" << init.freeType << " spDistType=" << init.spDistType << " maxSeedX=" << init.maxSeedX + << " maxSeedY=" << init.maxSeedY << " initFrzYr=" << init.initFrzYr + << " restrictRows=" << init.restrictRows << " restrictFreq=" << init.restrictFreq + << " finalFrzYr=" << init.finalFrzYr << " indsFile=" << init.indsFile << endl; +#endif + init.restrictRange = false; + if(init.seedType == 0 && init.restrictRows > 0) + init.restrictRange = true; + + if(dem.stageStruct) { + init.initAge = Rcpp::as(InitParamsR.slot("InitAge")); // Initial age distribution within each stage: 0 = lowest possible age, 1 = randomised, 2 = + // quasi-equilibrium. Required for StageStruct = 1 only - otherwise OMIT COLUMNS. + PropStages = Rcpp::as(InitParamsR.slot("PropStages")); // Proportion of the initial individuals in stage class i>0 (No juveniles + // are initialized). Required for StageStruct = 1 only (number of columns + // is one less than number of stages) - otherwise OMIT COLUMNS + if(init.seedType != 2) { + check = 0.0; + for(int i = 1; i < sstruct.nStages; i++) { + p = (float)PropStages(i); + check += p; + paramsInit->setProp(i, p); + } + if(check < 1.0 || check > 1.0) { + // this condition should not occur - WHAT COULD BE DONE?? ABORT WITH ERROR CODE ... +#if RSDEBUG + DEBUGLOG << "ReadInitialisation(): check = " << check << endl; +#endif + throw logic_error("The proportion of initial individuals in each stage doesn not sum to 1."); + } + } + } + paramsInit->setInit(init); + switch(init.seedType) { + case 0: { // free initialisation + if(init.minSeedX < 0) + init.minSeedX = 0; + if(init.minSeedY < 0) + init.minSeedY = 0; + if(init.maxSeedX < 0 || init.maxSeedX > paramsLand.maxX) + init.maxSeedX = paramsLand.maxX; // added upper boundary checks + if(init.maxSeedY < 0 || init.maxSeedY > paramsLand.maxY) + init.maxSeedY = paramsLand.maxY; // added upper boundary checks + if(init.minSeedY > init.maxSeedY || init.minSeedX > init.maxSeedX) { +#if RSDEBUG + DEBUGLOG << "ReadInitialisationR(): maxSeedX=" << init.maxSeedX << " paramsLand.maxX=" << paramsLand.maxX + << " maxSeedY=" << init.maxSeedY << " paramsLand.maxY=" << paramsLand.maxY << endl; +#endif + error = 603; + } + maxcells = (init.maxSeedY - init.minSeedY) * (init.maxSeedX - init.minSeedX); + if(init.freeType == 0 && init.nSeedPatches > maxcells) + error = 602; + } + break; + case 1: // from species distribution + break; + case 2: { // from initial individuals file + // if (init.indsFile != prevInitialIndsFile) { + // read and store the list of individuals to be initialised + + if(init.indsFile=="NULL"){ + simParams sim = paramsSim->getSim(); + Rcpp::List InitIndsList = Rcpp::as(InitParamsR.slot("InitIndsList")); + if(InitIndsList.size() != sim.reps) error = 603; + else error = ReadInitIndsFileR(0, pLandscape, Rcpp::as(InitIndsList[0])); // parse dataframe header and read lines, store in vector "initinds" + }else + error = ReadInitIndsFileR(0, pLandscape); //open, parse, read header and lines, store in vector "initinds" + // prevInitialIndsFile = init.indsFile; + //} + } + break; + default: + ; + } + return error; +} + +//--------------------------------------------------------------------------- + +int ReadGeneticsR(Rcpp::S4 GeneParamsR, Landscape* pLandscape) +{ + bool outputGeneValues, outputGlobalFst, outputPairwiseFst, outputPerLocusFst; // what should be calculated in the output? + int outputGenesStart, outputGenesInterval; // when should the output be calculated? + int outputGlobalFstStart, outputGlobalFstInterval; // when should global Fst be calculated? + int outputPairwiseFstStart, outputPairwiseFstInterval; // when should pairwise Fst be calculated? + + setpatchList; // for which patches should the output be calculated? + + //not ideal to reset these in here + pSpecies->resetGeneticParameters(); + + int genomeSize = Rcpp::as(GeneParamsR.slot("GenomeSize")); // how many loci are there? + + set chrEnds; + + if(GeneParamsR.slot("ChromosomeEnds") != R_NilValue){ + Rcpp::IntegerVector ChromosomeEnds = Rcpp::as(GeneParamsR.slot("ChromosomeEnds")); // where do the chromosomes end? + for (int i = 0; i < ChromosomeEnds.size(); i++) { + chrEnds.insert(ChromosomeEnds[i]); + } + } + else { + chrEnds.insert(genomeSize - 1); + } + + + float recombinationRate = Rcpp::as(GeneParamsR.slot("RecombinationRate")); + + outputGeneValues = Rcpp::as(GeneParamsR.slot("OutputGeneValues")); + outputGlobalFst = Rcpp::as(GeneParamsR.slot("OutputGlobalFst")); + outputPairwiseFst = Rcpp::as(GeneParamsR.slot("OutputPairwiseFst")); + outputPerLocusFst = Rcpp::as(GeneParamsR.slot("OutputPerLocusFst")); + + + if(GeneParamsR.slot("OutputGenesStart") != R_NilValue){ + outputGenesStart = Rcpp::as(GeneParamsR.slot("OutputGenesStart")); + } else { + outputGenesStart = -9; + } + if(GeneParamsR.slot("OutputGenesInterval") != R_NilValue){ + outputGenesInterval = Rcpp::as(GeneParamsR.slot("OutputGenesInterval")); + } else { + outputGenesInterval = -9; + } + + if(GeneParamsR.slot("OutputGlobalFstStart") != R_NilValue){ + outputGlobalFstStart = Rcpp::as(GeneParamsR.slot("OutputGlobalFstStart")); + } else { + outputGlobalFstStart = -9; + } + if(GeneParamsR.slot("OutputGlobalFstInterval") != R_NilValue){ + outputGlobalFstInterval = Rcpp::as(GeneParamsR.slot("OutputGlobalFstInterval")); + } else { + outputGlobalFstInterval = -9; + } + + if(GeneParamsR.slot("OutputPairwiseFstStart") != R_NilValue){ + outputPairwiseFstStart = Rcpp::as(GeneParamsR.slot("OutputPairwiseFstStart")); + } else { + outputPairwiseFstStart = -9; + } + if(GeneParamsR.slot("OutputPairwiseFstInterval") != R_NilValue){ + outputPairwiseFstInterval = Rcpp::as(GeneParamsR.slot("OutputPairwiseFstInterval")); + } else { + outputPairwiseFstInterval = -9; + } + + + Rcpp::StringVector inPatches; + string patchSamplingOption; + int nPatchesToSample = 0; + + if(GeneParamsR.slot("PatchList") != R_NilValue){ + + inPatches = Rcpp::as(GeneParamsR.slot("PatchList")); + + if (inPatches[0] != "all" && inPatches[0] != "random" && inPatches[0] != "random_occupied") { + // then must be a list of indices + patchSamplingOption = "list"; + Rcpp::IntegerVector inPatchesInt = Rcpp::as(GeneParamsR.slot("PatchList")); + for (int i = 0; i < inPatchesInt.size(); i++) { + patchList.insert(inPatchesInt[i]); + } + if (patchList.contains(0)) throw logic_error("Patch sampling: ID 0 is reserved for the matrix and should not be sampled."); + } + else { + patchSamplingOption = inPatches[0]; + if (inPatches[0] == "random" || inPatches[0] == "random_occupied"){ + if(GeneParamsR.slot("NbrPatchesToSample") != R_NilValue) + nPatchesToSample = Rcpp::as(GeneParamsR.slot("NbrPatchesToSample")); + else throw logic_error("You must provide the number of patches to sample if PatchList is random or random_occupied."); + // patchList remains empty, filled when patches are sampled every gen + } + } + } + + string NbInds; + if (GeneParamsR.slot("nIndividualsToSample") != R_NilValue){ + if (Rf_isNumeric(GeneParamsR.slot("nIndividualsToSample"))){ + int NbIndsInt = Rcpp::as(GeneParamsR.slot("nIndividualsToSample")); + NbInds = to_string(NbIndsInt); + } + else { + NbInds = Rcpp::as(GeneParamsR.slot("nIndividualsToSample")); + } + } + + const string strNbInds = NbInds; + + const int nbStages = pSpecies->getStageParams().nStages; + set stagesToSampleFrom; + Rcpp::StringVector Stages; + + if (GeneParamsR.slot("Stages") != R_NilValue) { + Stages = Rcpp::as(GeneParamsR.slot("Stages")); + if (Stages[0] == "all") { + for (int i = 0; i < nbStages; i++) { + stagesToSampleFrom.insert(i); +} + } + else { + Rcpp::IntegerVector intStages = Rcpp::as(GeneParamsR.slot("Stages")); + for (int i = 0; i < intStages.size(); i++) { + stagesToSampleFrom.insert(intStages[i]); + } + } + } + pSpecies->setGeneticParameters(chrEnds, genomeSize, recombinationRate, + patchList, strNbInds, stagesToSampleFrom, nPatchesToSample); + + paramsSim->setGeneticSim(patchSamplingOption, outputGeneValues, outputGenesStart, outputGenesInterval, outputPairwiseFst, outputGlobalFst, outputGlobalFstStart, outputGlobalFstInterval, + outputPairwiseFstStart, outputPairwiseFstInterval, outputPerLocusFst); + return 0; +} + +//--------------------------------------------------------------------------- + +int ReadTraitsR(Rcpp::S4 TraitsParamsR) +{ + Rcpp::S4 GeneticLoadParamsR("GeneticLoadParams"); + Rcpp::S4 EmigrationTraitsParamsR("EmigrationTraitsParams"); + Rcpp::S4 KernelTraitsParamsR("KernelTraitsParams"); + Rcpp::S4 CorrRWTraitsParamsR("CorrRWTraitsParams"); + Rcpp::S4 SMSTraitsParamsR("SMSTraitsParams"); + Rcpp::S4 SettlementTraitsParamsR("SettlementTraitsParams"); + + settleType sett = pSpecies->getSettle(); + emigRules emig = pSpecies->getEmigRules(); + transferRules trfr = pSpecies->getTransferRules(); + int TransferType = trfr.usesMovtProc ? trfr.moveType : 0; + + pSpecies->clearTraitTable(); + const int genomeSize = pSpecies->getGenomeSize(); + + string TraitTypeStr; + + if(gHasNeutralGenetics){ + Rcpp::S4 NeutralTraitsParamsR("NeutralTraitsParams"); + NeutralTraitsParamsR = Rcpp::as(TraitsParamsR.slot("Neutral")); + + // TraitType + string TraitTypeR = "neutral";// NEUTRAL; // each column corresponds to a TraitType + + // Positions and number of Positions + set positions; + int NbOfPositionsR = -9; + + if(Rf_isString(NeutralTraitsParamsR.slot("Positions"))){ + string PositionsR = Rcpp::as(NeutralTraitsParamsR.slot("Positions")); + if(PositionsR == "random"){ + NbOfPositionsR = Rcpp::as(NeutralTraitsParamsR.slot("NbOfPositions")); + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + else throw logic_error("NeutralTraits(): If positions are random you must provide the number of positions (>0)."); + } + + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(NeutralTraitsParamsR.slot("Positions")); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("NeutralTraits(): Loci positions must be smaller than genome size"); + } + } + + // Expression type + string ExpressionTypeR = "#"; + + // initial Positions + set initialPositions; + int NbOfInitialPositionsR = -9; + if(Rf_isString(NeutralTraitsParamsR.slot("InitialPositions"))){ + string initialPositionsR = Rcpp::as(NeutralTraitsParamsR.slot("InitialPositions")); + if(initialPositionsR == "random"){ + NbOfInitialPositionsR = Rcpp::as(NeutralTraitsParamsR.slot("InitialNbOfPositions")); + if(NbOfPositionsR > 0){ + initialPositions = selectRandomLociPositions(NbOfInitialPositionsR, genomeSize); + } + else throw logic_error("NeutralTraits(): If initial positions are random you must provide the number of initial positions (>0)."); + } + + if(initialPositionsR == "all"){ + initialPositions = positions; + } + } + else { + Rcpp::NumericVector initialPositionsR = Rcpp::as(NeutralTraitsParamsR.slot("InitialPositions")); // Positions are provided as numeric vector + // use a for loop to insert the values at initialPositionsR into the set positions + for (int i = 0; i < initialPositionsR.size(); i++) { + if (static_cast(initialPositionsR[i]) <= genomeSize) { // not sure if this is needed; initial positions should be checked beforehand and be within positons range + initialPositions.insert(static_cast(initialPositionsR[i])); + } + else throw logic_error("NeutralTraits(): initial loci positions must be smaller than genome size"); + } + } + + + // Initial distribution parameters + string initDistR = Rcpp::as(NeutralTraitsParamsR.slot("InitialAlleleDistribution")); + if(initDistR != "uniform") initDistR == "#"; + + Rcpp::NumericVector initParamsR = {0,Rcpp::as(NeutralTraitsParamsR.slot("InitialAlleleParameters"))}; + + // Initial dominance distribution parameters not applicable for neutral traits + string initDomDistR = "#"; + Rcpp::NumericVector initDomParamsR = {0,0}; + + // Dominance distribution parameters not applicable for neutral traits + string DominanceDistR = "#"; + Rcpp::NumericVector DominanceParamsR = {0,0}; + + // Mutation parameters + bool isInherited = true; + string MutationDistR = Rcpp::as(NeutralTraitsParamsR.slot("MutationDistribution")); + Rcpp::NumericVector MutationParamsR = Rcpp::as(NeutralTraitsParamsR.slot("MutationParameters")); + float MutationRateR = Rcpp::as(NeutralTraitsParamsR.slot("MutationRate")); + + // sex dependency + int sexdep = 2; // NA = 2, FEM = 0 , MAL = 1; depending on row + + // Output values + bool isOutputR = Rcpp::as(NeutralTraitsParamsR.slot("OutputValues")); + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + + if(gHasGeneticLoad){ + Rcpp::S4 GeneticLoadParamsR("GeneticLoadParams"); + GeneticLoadParamsR = Rcpp::as(TraitsParamsR.slot("GeneticLoad")); + + // TraitType + string TraitTypeR = "genetic_load";// each column corresponds to one genetic load + + // nb of loads + int nbLoads = Rcpp::as(GeneticLoadParamsR.slot("NbGeneticLoads")); + + // Positions and number of Positions + Rcpp::List PositionsRList = Rcpp::as(GeneticLoadParamsR.slot("Positions")); + Rcpp::NumericVector NbOfPositionsRvec; + if (GeneticLoadParamsR.slot("NbOfPositions")!= R_NilValue){ + NbOfPositionsRvec = Rcpp::as (GeneticLoadParamsR.slot("NbOfPositions")); + } + + // Expression type + string ExpressionTypeR = "multiplicative"; // not applicable for genetic loads + + // initial Positions and number of Positions + Rcpp::List initialPositionsRList = Rcpp::as(GeneticLoadParamsR.slot("InitialPositions")); + Rcpp::NumericVector NbOfInitialPositionsRvec; + if (GeneticLoadParamsR.slot("InitialNbOfPositions")!= R_NilValue){ + NbOfInitialPositionsRvec = Rcpp::as (GeneticLoadParamsR.slot("InitialNbOfPositions")); + } + + // Initial distribution parameters + Rcpp::StringVector initDistRvec; + if (GeneticLoadParamsR.slot("InitialAlleleDistribution")!= R_NilValue){ + initDistRvec = Rcpp::as(GeneticLoadParamsR.slot("InitialAlleleDistribution")); + } else { + initDistRvec = {"#"}; + } + Rcpp::NumericMatrix initParamsRmat; + if(GeneticLoadParamsR.slot("InitialAlleleParameters")!= R_NilValue){ + initParamsRmat = Rcpp::as(GeneticLoadParamsR.slot("InitialAlleleParameters")); // as a matrix: columns for parameter, rows for load nb + } else { + initParamsRmat = Rcpp::NumericMatrix(0, 0);// empty matrix + } + + // Initial dominance distribution parameters applicable for genetic loads + Rcpp::StringVector initDomDistRvec; + if (GeneticLoadParamsR.slot("InitialDomDistribution")!= R_NilValue){ + initDomDistRvec = Rcpp::as(GeneticLoadParamsR.slot("InitialDomDistribution")); + } else { + initDomDistRvec = {"#"}; + } + + Rcpp::NumericMatrix initDomParamsRmat; + if(GeneticLoadParamsR.slot("InitialDomParameters")!= R_NilValue){ + initDomParamsRmat = Rcpp::as(GeneticLoadParamsR.slot("InitialDomParameters")); // as a matrix: columns for parameter, rows for load nb + } else { + initDomParamsRmat = Rcpp::NumericMatrix(0, 0); + } + + // Dominance distribution parameters + Rcpp::StringVector DominanceDistRvec = Rcpp::as(GeneticLoadParamsR.slot("DominanceDistribution")); // check if values are NA -> then '#' + Rcpp::NumericMatrix DominanceParamsRmat = Rcpp::as(GeneticLoadParamsR.slot("DominanceParameters")); // as a matrix: columns for parameter, rows for load nb + + // Mutation parameters + bool isInherited = true; + Rcpp::StringVector MutationDistRvec = Rcpp::as(GeneticLoadParamsR.slot("MutationDistribution")); + Rcpp::NumericMatrix MutationParamsRmat = Rcpp::as(GeneticLoadParamsR.slot("MutationParameters")); + Rcpp::NumericVector MutationRateRvec = Rcpp::as(GeneticLoadParamsR.slot("MutationRate")); + + // sex dependency + int sexdep = 2; // NA = 2, FEM = 0 , MAL = 1; depending on row + + // Output values + Rcpp::LogicalVector isOutputRvec = Rcpp::as(GeneticLoadParamsR.slot("OutputValues")); + + for (int l = 0; l < nbLoads; l++){ + set positions; + int NbOfPositionsR = -9; + // check if PositionsR[l] is a string + if(Rf_isString(PositionsRList[l])){ + string pos = Rcpp::as(PositionsRList[l]); + if(pos == "random"){ + NbOfPositionsR = (int)NbOfPositionsRvec[l]; // here is the error message + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + else throw logic_error("GeneticLoad(): If positions are random you must provide the number of positions (>0)."); + } + + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(PositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("GeneticLoad(): Loci positions must be smaller than genome size"); + } + } + + set initialPositions; + int NbOfInitialPositionsR = -9; + // check if initialPositionsR[l] is a string + if(Rf_isString(initialPositionsRList[l])){ + string pos = Rcpp::as(initialPositionsRList[l]); + if(pos == "random"){ + NbOfInitialPositionsR = (int)NbOfInitialPositionsRvec[l]; // here is the error message + if(NbOfInitialPositionsR > 0){ + initialPositions = selectRandomLociPositions(NbOfInitialPositionsR, genomeSize); + } + else throw logic_error("GeneticLoad(): If initial positions are random you must provide the number of initial positions (>0)."); + } + if(pos == "all"){ + initialPositions = positions; + } + } + else { + Rcpp::NumericVector initialPositionsR = Rcpp::as(initialPositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < initialPositionsR.size(); i++) { + if (static_cast(initialPositionsR[i]) <= genomeSize) { + initialPositions.insert(static_cast(initialPositionsR[i])); + } + else throw logic_error("GeneticLoad(): Initial loci positions must be smaller than genome size"); + } + } + + string initDistR = "#"; + if (initDistRvec[0] != "#") initDistR = (string)initDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + + Rcpp::NumericVector initParamsR= {0,0}; + if (initParamsRmat.size() > 0) initParamsR = initParamsRmat.row(l); + if (initDistR == "NA") { + initDistR = "#"; + initParamsR = {0,0}; + } + + string initDomDistR = "#"; + if (initDomDistRvec[0] != "#") initDomDistR = (string)initDomDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + + Rcpp::NumericVector initDomParamsR = {0,0}; + if (initDomParamsRmat.size() > 0) initDomParamsR = initDomParamsRmat.row(l); + if (initDomDistR == "NA") { + initDomDistR = "#"; + initDomParamsR = {0,0}; + } + + string DominanceDistR = (string)DominanceDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + Rcpp::NumericVector DominanceParamsR = DominanceParamsRmat.row(l); + + string MutationDistR = (string)MutationDistRvec[l]; + Rcpp::NumericVector MutationParamsR = MutationParamsRmat.row(l); + float MutationRateR = (float) MutationRateRvec[l]; + + bool isOutputR = isOutputRvec[l] == 1; + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + } + + // Dispersal traits + // emigration traits + if(emig.indVar){ + EmigrationTraitsParamsR = Rcpp::as(TraitsParamsR.slot("EmigrationGenes")); + + // number of expected trait types + int nbTraits; + if (emig.densDep) nbTraits = 3; // emigration_d0, emigration_alpha, emigration_beta + else nbTraits = 1; // emigration_d0 + + if (emig.sexDep) nbTraits *= 2; // each sex has a different trait + else nbTraits *= 1; // only one trait for both sexes + + // Positions and number of Positions + Rcpp::List PositionsRList = Rcpp::as(EmigrationTraitsParamsR.slot("Positions")); + Rcpp::NumericVector NbOfPositionsRvec; + if (EmigrationTraitsParamsR.slot("NbOfPositions")!= R_NilValue){ + NbOfPositionsRvec = Rcpp::as (EmigrationTraitsParamsR.slot("NbOfPositions")); + } + + // Expression type + Rcpp::StringVector ExpressionTypeRvec = Rcpp::as (EmigrationTraitsParamsR.slot("ExpressionType")); // not applicable for genetic loads + + // Initial distribution + Rcpp::StringVector InitialDistRvec = Rcpp::as(EmigrationTraitsParamsR.slot("InitialAlleleDistribution")); + Rcpp::NumericMatrix InitialParamsRmat = Rcpp::as(EmigrationTraitsParamsR.slot("InitialAlleleParameters")); // as a matrix: columns for parameter, rows for emigration trait + + Rcpp::LogicalVector isInheritedRvec = Rcpp::as(EmigrationTraitsParamsR.slot("IsInherited")); + + // Initial dominance distribution + string initDomDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector initDomParamsR = {0,0}; // not applicable for dispersal traits + + // Dominance distribution + string DominanceDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector DominanceParamsR = {0,0}; // not applicable for dispersal traits + + // Mutation parameters + Rcpp::StringVector MutationDistRvec = Rcpp::as(EmigrationTraitsParamsR.slot("MutationDistribution")); + Rcpp::NumericMatrix MutationParamsRmat = Rcpp::as(EmigrationTraitsParamsR.slot("MutationParameters")); + Rcpp::NumericVector MutationRateRvec = Rcpp::as(EmigrationTraitsParamsR.slot("MutationRate")); + + // Output values + Rcpp::LogicalVector isOutputRvec = Rcpp::as(EmigrationTraitsParamsR.slot("OutputValues")); + + string TraitTypeR; + int sexdep; + + for (int l = 0; l < nbTraits; l++){ + if (emig.densDep){ + if (emig.sexDep){ + // expecting emigration_d0, emigration_alpha, emigration_beta + if (l == 0 || l == 1) TraitTypeR = "emigration_d0"; + else if (l == 2 || l == 3) TraitTypeR = "emigration_alpha"; + else if (l == 4 || l == 5) TraitTypeR = "emigration_beta"; + //if l is even -> female; sexdep=0 + if(l % 2 == 0) sexdep = 0; // FEM + //if l is odd -> male; sexdep=1 + else sexdep = 1; // MAL + } + else { + // expecting emigration_d0, emigration_alpha, emigration_beta + if (l == 0) TraitTypeR = "emigration_d0"; + else if (l == 1) TraitTypeR = "emigration_alpha"; + else if (l == 2) TraitTypeR = "emigration_beta"; + sexdep=2; + } + + } + else { + // expecting only emigration_d0 + TraitTypeR = "emigration_d0"; + if (emig.sexDep){ + if(l % 2 == 0) sexdep = 0; // FEM + else sexdep = 1; // MAL + } + else { + sexdep=2; + } + } + + set positions; + int NbOfPositionsR = -9; + // check if PositionsR[l] is a string + if(Rf_isString(PositionsRList[l])){ + string pos = Rcpp::as(PositionsRList[l]); + if(pos == "random"){ + NbOfPositionsR = (int)NbOfPositionsRvec[l]; // here is the error message + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + } + else throw logic_error("EmigrationGenes(): If positions are random you must provide the number of positions (>0)."); + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(PositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("EmigrationGenes(): Loci positions must be smaller than genome size"); + } + } + + string ExpressionTypeR = (string)ExpressionTypeRvec[l]; + + string initDistR = (string)InitialDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + Rcpp::NumericVector initParamsR = InitialParamsRmat.row(l); + + bool isInherited = isInheritedRvec[l] == 1; + + string MutationDistR = (string)MutationDistRvec[l]; + Rcpp::NumericVector MutationParamsR = MutationParamsRmat.row(l); + + float MutationRateR = (float) MutationRateRvec[l]; + bool isOutputR = isOutputRvec[l] == 1; + + set initialPositions=positions; // for dispersal traits, initial positions are the same as the general positions for the trait + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + + } + + // settlement traits + if(sett.indVar){ + SettlementTraitsParamsR = Rcpp::as(TraitsParamsR.slot("SettlementGenes")); + + // number of expected trait types + int nbTraits = 3; + + if (sett.sexDep) nbTraits *= 2; // each sex has a different trait + + // Positions and number of Positions + Rcpp::List PositionsRList = Rcpp::as(SettlementTraitsParamsR.slot("Positions")); + Rcpp::NumericVector NbOfPositionsRvec; + if (SettlementTraitsParamsR.slot("NbOfPositions")!= R_NilValue){ + NbOfPositionsRvec = Rcpp::as (SettlementTraitsParamsR.slot("NbOfPositions")); + } + + // Expression type + Rcpp::StringVector ExpressionTypeRvec = Rcpp::as (SettlementTraitsParamsR.slot("ExpressionType")); // not applicable for genetic loads + + // Initial distribution + Rcpp::StringVector InitialDistRvec = Rcpp::as(SettlementTraitsParamsR.slot("InitialAlleleDistribution")); + Rcpp::NumericMatrix InitialParamsRmat = Rcpp::as(SettlementTraitsParamsR.slot("InitialAlleleParameters")); // as a matrix: columns for parameter, rows for Settlement trait + + Rcpp::LogicalVector isInheritedRvec = Rcpp::as(SettlementTraitsParamsR.slot("IsInherited")); + + // Initial dominance distribution + string initDomDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector initDomParamsR = {0,0}; // not applicable for dispersal traits + + // Dominance distribution + string DominanceDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector DominanceParamsR = {0,0}; // not applicable for dispersal traits + + // Mutation parameters + Rcpp::StringVector MutationDistRvec = Rcpp::as(SettlementTraitsParamsR.slot("MutationDistribution")); + Rcpp::NumericMatrix MutationParamsRmat = Rcpp::as(SettlementTraitsParamsR.slot("MutationParameters")); + Rcpp::NumericVector MutationRateRvec = Rcpp::as(SettlementTraitsParamsR.slot("MutationRate")); + + // Output values + Rcpp::LogicalVector isOutputRvec = Rcpp::as(SettlementTraitsParamsR.slot("OutputValues")); + + string TraitTypeR; + int sexdep; + + for (int l = 0; l < nbTraits; l++){ + if (sett.sexDep){ + // expecting emigration_d0, emigration_alpha, emigration_beta + if (l == 0 || l == 1) TraitTypeR = "settlement_s0"; + else if (l == 2 || l == 3) TraitTypeR = "settlement_alpha"; + else if (l == 4 || l == 5) TraitTypeR = "settlement_beta"; + //if l is even -> female; sexdep=0 + if(l % 2 == 0) sexdep = 0; // FEM + //if l is odd -> male; sexdep=1 + else sexdep = 1; // MAL + } + else { + // expecting emigration_d0, emigration_alpha, emigration_beta + if (l == 0) TraitTypeR = "settlement_d0"; + else if (l == 1) TraitTypeR = "settlement_alpha"; + else if (l == 2) TraitTypeR = "settlement_beta"; + sexdep=2; + } + + set positions; + int NbOfPositionsR = -9; + // check if PositionsR[l] is a string + if(Rf_isString(PositionsRList[l])){ + string pos = Rcpp::as(PositionsRList[l]); + if(pos == "random"){ + NbOfPositionsR = (int)NbOfPositionsRvec[l]; // here is the error message + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + } + else throw logic_error("SettlementGenes(): If positions are random you must provide the number of positions (>0)."); + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(PositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("SettlementGenes(): Loci positions must be smaller than genome size"); + } + } + + string ExpressionTypeR = (string)ExpressionTypeRvec[l]; + + string initDistR = (string)InitialDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + Rcpp::NumericVector initParamsR = InitialParamsRmat.row(l); + + bool isInherited = isInheritedRvec[l] == 1; + + string MutationDistR = (string)MutationDistRvec[l]; + Rcpp::NumericVector MutationParamsR = MutationParamsRmat.row(l); + + float MutationRateR = (float) MutationRateRvec[l]; + bool isOutputR = isOutputRvec[l] == 1; + + set initialPositions=positions; // for dispersal traits, initial positions are the same as the general positions for the trait + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + + } + + switch(TransferType){ + case 0: { // kernel + if(trfr.indVar){ + KernelTraitsParamsR = Rcpp::as(TraitsParamsR.slot("KernelGenes")); + + // number of expected traits + int nbTraits; + if(trfr.twinKern){ + nbTraits = 3; + } + else { + nbTraits = 1; + } + if(trfr.sexDep){ + nbTraits *= 2; + } + + // Positions and number of Positions + Rcpp::List PositionsRList = Rcpp::as(KernelTraitsParamsR.slot("Positions")); + Rcpp::NumericVector NbOfPositionsRvec; + if (KernelTraitsParamsR.slot("NbOfPositions")!= R_NilValue){ + NbOfPositionsRvec = Rcpp::as (KernelTraitsParamsR.slot("NbOfPositions")); + } + + // Expression type + Rcpp::StringVector ExpressionTypeRvec = Rcpp::as (KernelTraitsParamsR.slot("ExpressionType")); // not applicable for genetic loads + + // Initial distribution + Rcpp::StringVector InitialDistRvec = Rcpp::as(KernelTraitsParamsR.slot("InitialAlleleDistribution")); + Rcpp::NumericMatrix InitialParamsRmat = Rcpp::as(KernelTraitsParamsR.slot("InitialAlleleParameters")); // as a matrix: columns for parameter, rows for Settlement trait + + Rcpp::LogicalVector isInheritedRvec = Rcpp::as(KernelTraitsParamsR.slot("IsInherited")); + + // Initial dominance distribution + string initDomDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector initDomParamsR = {0,0}; // not applicable for dispersal traits + + // Dominance distribution + string DominanceDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector DominanceParamsR = {0,0}; // not applicable for dispersal traits + + // Mutation parameters + Rcpp::StringVector MutationDistRvec = Rcpp::as(KernelTraitsParamsR.slot("MutationDistribution")); + Rcpp::NumericMatrix MutationParamsRmat = Rcpp::as(KernelTraitsParamsR.slot("MutationParameters")); + Rcpp::NumericVector MutationRateRvec = Rcpp::as(KernelTraitsParamsR.slot("MutationRate")); + + // Output values + Rcpp::LogicalVector isOutputRvec = Rcpp::as(KernelTraitsParamsR.slot("OutputValues")); + + string TraitTypeR; + int sexdep; + + for (int l = 0; l < nbTraits; l++){ + // expecting crw_stepLength, crw_stepCorrelation + if(trfr.twinKern){ + if(trfr.sexDep){ + // should be two lines + if(l==0 || l == 1) TraitTypeR = "kernel_meanDistance1"; + if(l==2 || l == 3) TraitTypeR = "kernel_meanDistance2"; + if(l==4 || l == 5) TraitTypeR = "kernel_probability"; + if(l % 2 == 0) sexdep = 0; // FEML + else sexdep = 1; // MAL + } + else { + if(l==0) TraitTypeR = "kernel_meanDistance1"; + if(l==1) TraitTypeR = "kernel_meanDistance2"; + if(l==2) TraitTypeR = "kernel_probability"; + sexdep = 2; + } + } + else { + if(trfr.sexDep){ + // should be two lines + TraitTypeR = "kernel_meanDistance1"; + if(l % 2 == 0) sexdep = 0; // FEML + else sexdep = 1; // MAL + } + else { + //should only be one line + TraitTypeR = "kernel_meanDistance1"; + sexdep = 2; + } + } + + + set positions; + int NbOfPositionsR = -9; + // check if PositionsR[l] is a string + if(Rf_isString(PositionsRList[l])){ + string pos = Rcpp::as(PositionsRList[l]); + if(pos == "random"){ + NbOfPositionsR = (int)NbOfPositionsRvec[l]; // here is the error message + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + } + else throw logic_error("KernelGenes(): If positions are random you must provide the number of positions (>0)."); + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(PositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("KernelGenes(): Loci positions must be smaller than genome size"); + } + } + + string ExpressionTypeR = (string)ExpressionTypeRvec[l]; + + string initDistR = (string)InitialDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + Rcpp::NumericVector initParamsR = InitialParamsRmat.row(l); + + bool isInherited = isInheritedRvec[l] == 1; + + string MutationDistR = (string)MutationDistRvec[l]; + Rcpp::NumericVector MutationParamsR = MutationParamsRmat.row(l); + + float MutationRateR = (float) MutationRateRvec[l]; + bool isOutputR = isOutputRvec[l] == 1; + + set initialPositions=positions; // for dispersal traits, initial positions are the same as the general positions for the trait + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + } + } + break; + + case 1: { // SMS + // SMS traits + trfrMovtParams smstraits = pSpecies->getSpMovtTraits(); + if(trfr.indVar){ + SMSTraitsParamsR = Rcpp::as(TraitsParamsR.slot("SMSGenes")); + + // number of expected traits + int nbTraits = 1; + if (smstraits.gb==2) nbTraits = 4; + + + // Positions and number of Positions + Rcpp::List PositionsRList = Rcpp::as(SMSTraitsParamsR.slot("Positions")); + Rcpp::NumericVector NbOfPositionsRvec; + if (SMSTraitsParamsR.slot("NbOfPositions")!= R_NilValue){ + NbOfPositionsRvec = Rcpp::as (SMSTraitsParamsR.slot("NbOfPositions")); + } + + // Expression type + Rcpp::StringVector ExpressionTypeRvec = Rcpp::as (SMSTraitsParamsR.slot("ExpressionType")); // not applicable for genetic loads + + // Initial distribution + Rcpp::StringVector InitialDistRvec = Rcpp::as(SMSTraitsParamsR.slot("InitialAlleleDistribution")); + Rcpp::NumericMatrix InitialParamsRmat = Rcpp::as(SMSTraitsParamsR.slot("InitialAlleleParameters")); // as a matrix: columns for parameter, rows for Settlement trait + + Rcpp::LogicalVector isInheritedRvec = Rcpp::as(SMSTraitsParamsR.slot("IsInherited")); + + // Initial dominance distribution + string initDomDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector initDomParamsR = {0,0}; // not applicable for dispersal traits + + // Dominance distribution + string DominanceDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector DominanceParamsR = {0,0}; // not applicable for dispersal traits + + // Mutation parameters + Rcpp::StringVector MutationDistRvec = Rcpp::as(SMSTraitsParamsR.slot("MutationDistribution")); + Rcpp::NumericMatrix MutationParamsRmat = Rcpp::as(SMSTraitsParamsR.slot("MutationParameters")); + Rcpp::NumericVector MutationRateRvec = Rcpp::as(SMSTraitsParamsR.slot("MutationRate")); + + // Output values + Rcpp::LogicalVector isOutputRvec = Rcpp::as(SMSTraitsParamsR.slot("OutputValues")); + + string TraitTypeR; + int sexdep; + + for (int l = 0; l < nbTraits; l++){ + // expecting crw_stepLength, crw_stepCorrelation + if (l == 0) { + TraitTypeR = "sms_directionalPersistence"; + } + else if (l == 1) { + TraitTypeR = "sms_goalBias"; + } + else if (l == 2) { + TraitTypeR = "sms_alphaDB"; + } + else { + TraitTypeR = "sms_betaDB"; + } + + sexdep=2; + + set positions; + int NbOfPositionsR = -9; + // check if PositionsR[l] is a string + if(Rf_isString(PositionsRList[l])){ + string pos = Rcpp::as(PositionsRList[l]); + if(pos == "random"){ + NbOfPositionsR = (int)NbOfPositionsRvec[l]; // here is the error message + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + } + else throw logic_error("SMSGenes(): If positions are random you must provide the number of positions (>0)."); + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(PositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("SMSGenes(): Loci positions must be smaller than genome size"); + } + } + + string ExpressionTypeR = (string)ExpressionTypeRvec[l]; + + string initDistR = (string)InitialDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + Rcpp::NumericVector initParamsR = InitialParamsRmat.row(l); + + bool isInherited = isInheritedRvec[l] == 1; + + string MutationDistR = (string)MutationDistRvec[l]; + Rcpp::NumericVector MutationParamsR = MutationParamsRmat.row(l); + + float MutationRateR = (float) MutationRateRvec[l]; + bool isOutputR = isOutputRvec[l] == 1; + + set initialPositions=positions; // for dispersal traits, initial positions are the same as the general positions for the trait + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + + } + } + break; + + case 2: { //CorrRW + // CorrRW traits + if(trfr.indVar){ + CorrRWTraitsParamsR = Rcpp::as(TraitsParamsR.slot("CorrRWGenes")); + + // number of expected traits + int nbTraits = 2; + + // Positions and number of Positions + Rcpp::List PositionsRList = Rcpp::as(CorrRWTraitsParamsR.slot("Positions")); + Rcpp::NumericVector NbOfPositionsRvec; + if (CorrRWTraitsParamsR.slot("NbOfPositions")!= R_NilValue){ + NbOfPositionsRvec = Rcpp::as (CorrRWTraitsParamsR.slot("NbOfPositions")); + } + + // Expression type + Rcpp::StringVector ExpressionTypeRvec = Rcpp::as (CorrRWTraitsParamsR.slot("ExpressionType")); // not applicable for genetic loads + + // Initial distribution + Rcpp::StringVector InitialDistRvec = Rcpp::as(CorrRWTraitsParamsR.slot("InitialAlleleDistribution")); + Rcpp::NumericMatrix InitialParamsRmat = Rcpp::as(CorrRWTraitsParamsR.slot("InitialAlleleParameters")); // as a matrix: columns for parameter, rows for Settlement trait + + Rcpp::LogicalVector isInheritedRvec = Rcpp::as(CorrRWTraitsParamsR.slot("IsInherited")); + + // Initial dominance distribution + string initDomDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector initDomParamsR = {0,0}; // not applicable for dispersal traits + + // Dominance distribution + string DominanceDistR = "#"; // not applicable for dispersal traits + Rcpp::NumericVector DominanceParamsR = {0,0}; // not applicable for dispersal traits + + // Mutation parameters + Rcpp::StringVector MutationDistRvec = Rcpp::as(CorrRWTraitsParamsR.slot("MutationDistribution")); + Rcpp::NumericMatrix MutationParamsRmat = Rcpp::as(CorrRWTraitsParamsR.slot("MutationParameters")); + Rcpp::NumericVector MutationRateRvec = Rcpp::as(CorrRWTraitsParamsR.slot("MutationRate")); + + // Output values + Rcpp::LogicalVector isOutputRvec = Rcpp::as(CorrRWTraitsParamsR.slot("OutputValues")); + + string TraitTypeR; + int sexdep; + + for (int l = 0; l < nbTraits; l++){ + // expecting crw_stepLength, crw_stepCorrelation + if (l == 0) { + TraitTypeR = "crw_stepLength"; + } + else { + TraitTypeR = "crw_stepCorrelation"; + } + sexdep=2; + + set positions; + int NbOfPositionsR = -9; + // check if PositionsR[l] is a string + if(Rf_isString(PositionsRList[l])){ + string pos = Rcpp::as(PositionsRList[l]); + if(pos == "random"){ + NbOfPositionsR = (int)NbOfPositionsRvec[l]; // here is the error message + if(NbOfPositionsR > 0){ + positions = selectRandomLociPositions(NbOfPositionsR, genomeSize); + } + } + else throw logic_error("CorrRWGenes(): If positions are random you must provide the number of positions (>0)."); + } + else { + Rcpp::NumericVector PositionsR = Rcpp::as(PositionsRList[l]); // Positions are provided as numeric vector + // use a for loop to insert the values at PositionsR into the set positions + for (int i = 0; i < PositionsR.size(); i++) { + if (static_cast(PositionsR[i]) <= genomeSize) { + positions.insert(static_cast(PositionsR[i])); + } + else throw logic_error("CorrRWGenes(): Loci positions must be smaller than genome size"); + } + } + + string ExpressionTypeR = (string)ExpressionTypeRvec[l]; + + string initDistR = (string)InitialDistRvec[l]; // it is checked beforehand whether the correct distributions are provided + Rcpp::NumericVector initParamsR = InitialParamsRmat.row(l); + + bool isInherited = isInheritedRvec[l] == 1; + + string MutationDistR = (string)MutationDistRvec[l]; + Rcpp::NumericVector MutationParamsR = MutationParamsRmat.row(l); + + float MutationRateR = (float) MutationRateRvec[l]; + bool isOutputR = isOutputRvec[l] == 1; + + set initialPositions=positions; // for dispersal traits, initial positions are the same as the general positions for the trait + + setUpSpeciesTrait(TraitTypeR, + positions, + ExpressionTypeR, + initialPositions, + initDistR, + initParamsR, + initDomDistR, + initDomParamsR, + DominanceDistR, + DominanceParamsR, + isInherited, + MutationDistR, + MutationParamsR, + MutationRateR, + sexdep, + isOutputR); + } + + } + } + break; + } + + + // SMS traits + + // Kernel traits + + return 0; + +} +//--------------------------------------------------------------------------- +// Convert integer to corresponding SexType value +const sex_t intToSex(const int& i) { + if (i == 0) return FEM; + else if (i == 1) return MAL; + else return NA; + +} +//--------------------------------------------------------------------------- +// Convert string to corresponding TraitType value, if valid +TraitType stringToTraitType(const std::string& str) { + // Non-dispersal traits + if (str == "neutral") return NEUTRAL; + else if (str == "genetic_load") return GENETIC_LOAD; + // Sex-invariant dispersal traits + else if (str == "emigration_d0") return E_D0; // EP uses d0 for trait data + else if (str == "emigration_alpha") return E_ALPHA; + else if (str == "emigration_beta") return E_BETA; + else if (str == "settlement_s0") return S_S0; + else if (str == "settlement_alpha") return S_ALPHA; + else if (str == "settlement_beta") return S_BETA; + else if (str == "kernel_meanDistance1") return KERNEL_MEANDIST_1; + else if (str == "kernel_meanDistance2") return KERNEL_MEANDIST_2; + else if (str == "kernel_probability") return KERNEL_PROBABILITY; + else if (str == "crw_stepLength") return CRW_STEPLENGTH; + else if (str == "crw_stepCorrelation") return CRW_STEPCORRELATION; + else if (str == "sms_directionalPersistence") return SMS_DP; + else if (str == "sms_goalBias") return SMS_GB; + else if (str == "sms_alphaDB") return SMS_ALPHADB; + else if (str == "sms_betaDB") return SMS_BETADB; + else return INVALID_TRAIT; +} +//--------------------------------------------------------------------------- +// Add sex to TraitType +TraitType addSexDepToTrait(const TraitType& t, const sex_t& sex) { + if (sex == FEM) { + if (t == E_D0) return E_D0_F; // EP uses d0 for trait data + else if (t == E_ALPHA) return E_ALPHA_F; + else if (t == E_BETA) return E_BETA_F; + else if (t == S_S0) return S_S0_F; + else if (t == S_ALPHA) return S_ALPHA_F; + else if (t == S_BETA) return S_BETA_F; + else if (t == KERNEL_MEANDIST_1) return KERNEL_MEANDIST_1_F; + else if (t == KERNEL_MEANDIST_2) return KERNEL_MEANDIST_2_F; + else if (t == KERNEL_PROBABILITY) return KERNEL_PROBABILITY_F; + else return INVALID_TRAIT; + } + else if (sex == MAL) { + if (t == E_D0) return E_D0_M; // EP uses d0 for trait data + else if (t == E_ALPHA) return E_ALPHA_M; + else if (t == E_BETA) return E_BETA_M; + else if (t == S_S0) return S_S0_M; + else if (t == S_ALPHA) return S_ALPHA_M; + else if (t == S_BETA) return S_BETA_M; + else if (t == KERNEL_MEANDIST_1) return KERNEL_MEANDIST_1_M; + else if (t == KERNEL_MEANDIST_2) return KERNEL_MEANDIST_2_M; + else if (t == KERNEL_PROBABILITY) return KERNEL_PROBABILITY_M; + else return INVALID_TRAIT; + } + else return INVALID_TRAIT; +} + +//--------------------------------------------------------------------------- +GenParamType strToGenParamType(const string& str) { + if (str == "mean") + return MEAN; + else if (str == "sd") + return SD; + else if (str == "min") + return MIN; + else if (str == "max") + return MAX; + else if (str == "shape") + return SHAPE; + else if (str == "scale") + return SCALE; + else return INVALID; +} +//--------------------------------------------------------------------------- +map NumericToParameterMap(string distributionString, Rcpp::NumericVector parameter) { + // string is the distribution type; distribution type determines which parameter is in first or second column + + map paramMap; + if (distributionString != "#") { + if (distributionString == "uniform"){ + paramMap.emplace(GenParamType::MIN, (float) parameter[0]); + paramMap.emplace(GenParamType::MAX, (float) parameter[1]); + } + else if (distributionString == "normal"){ + paramMap.emplace(GenParamType::MEAN, (float) parameter[0]); + paramMap.emplace(GenParamType::SD, (float) parameter[1]); + } + else if (distributionString == "gamma"){ + paramMap.emplace(GenParamType::SHAPE, (float) parameter[0]); + paramMap.emplace(GenParamType::SCALE, (float) parameter[1]); + } + else if (distributionString == "scaled"){ + paramMap.emplace(GenParamType::MEAN, (float) parameter[0]); + } + else if (distributionString == "negExp"){ + paramMap.emplace(GenParamType::MEAN, (float) parameter[0]); + } + else if (distributionString == "KAM"){ + paramMap.emplace(GenParamType::MAX, (float) parameter[0]); + } + else if (distributionString == "SSM"){ + paramMap.emplace(GenParamType::MAX, (float) parameter[0]); + } + } + return paramMap; +} + +//--------------------------------------------------------------------------- +// select random loci positions +set selectRandomLociPositions(int nbLoci, const int& genomeSize) { + set positions; + if (nbLoci > genomeSize) throw logic_error("Number of random loci exceeds genome size."); + int rndLocus; + for (int i = 0; i < nbLoci; ++i) + { + do { + rndLocus = pRandom->IRandom(0, genomeSize - 1); + } while (positions.contains(rndLocus)); + positions.insert(rndLocus); + } + return positions; +} +//--------------------------------------------------------------------------- +// Convert string to corresponding ExpressionType value, if valid +ExpressionType stringToExpressionType(const std::string& str) { + if (str == "average") return AVERAGE; + else if (str == "additive") return ADDITIVE; + else if (str == "multiplicative") return MULTIPLICATIVE; + else if (str == "#") return NOTEXPR; + else throw logic_error(str + " is not a valid gene expression type."); +} +//--------------------------------------------------------------------------- +// Convert string to corresponding DistributionType value, if valid +DistributionType stringToDistributionType(const std::string& str) { + if (str == "#") return NONE; + else if (str == "uniform") return UNIFORM; + else if (str == "normal") return NORMAL; + else if (str == "gamma") return GAMMA; + else if (str == "scaled") return SCALED; + else if (str == "negExp") return NEGEXP; + else if (str == "KAM") return KAM; + else if (str == "SSM") return SSM; + else throw logic_error(str + " is not a valid distribution type."); +} +//--------------------------------------------------------------------------- +// set up genes +// Set up a trait from input parameters and add it Species +void setUpSpeciesTrait(string TraitTypeR, + set positions, + string ExpressionTypeR, + set initialPositions, + string initDistR, + Rcpp::NumericVector initParamsR, + string initDominanceDistR, + Rcpp::NumericVector initDominanceParamsR, + string DominanceDistR, + Rcpp::NumericVector DominanceParamsR, + bool isInherited, + string MutationDistR, + Rcpp::NumericVector MutationParamsR, + float MutationRateR, + int sexdep, + bool isOutputR) { + + TraitType traitType = stringToTraitType(TraitTypeR); + const sex_t sex = intToSex(sexdep); + if (sex != NA) traitType = addSexDepToTrait(traitType, sex); + + const ExpressionType expressionType = stringToExpressionType(ExpressionTypeR); // NOTEXPR; + + const DistributionType initDist = stringToDistributionType(initDistR); + const map initParams = NumericToParameterMap(initDistR,initParamsR); + + const DistributionType initDomDist = stringToDistributionType(initDominanceDistR); + const map initDomParams = NumericToParameterMap(initDominanceDistR,initDominanceParamsR); + + const DistributionType dominanceDist = stringToDistributionType(DominanceDistR); + const map dominanceParams = NumericToParameterMap(DominanceDistR,DominanceParamsR); + + DistributionType mutationDistribution = isInherited ? + stringToDistributionType(MutationDistR) : + DistributionType::NONE; + + float mutationRate = isInherited ? MutationRateR : 0.0; + + map mutationParameters; + if (isInherited) { + mutationParameters = NumericToParameterMap(MutationDistR, MutationParamsR); + } + + int ploidy = gNbSexesDisp; + + const bool isOutput = isOutputR; + + // Create species trait + unique_ptr trait(new SpeciesTrait( + traitType, sex, + positions, expressionType, + initialPositions, + initDist, initParams, + initDomDist, initDomParams, + isInherited, + mutationRate, + mutationDistribution, mutationParameters, + dominanceDist, dominanceParams, + ploidy, + isOutput + )); + + pSpecies->addTrait(traitType, *trait); +}; +//--------------------------------------------------------------------------- + + +int ReadTranslocationR(Landscape* pLandscape, Rcpp::S4 ParMaster) +{ + int error = 0; + // create new Management + if(pManagement != NULL) + delete pManagement; + pManagement = new Management; + // get landscape parameter (to distinguish between patch and cell model) + landParams paramsLand = pLandscape->getLandParams(); + // get demographic parameter (to distinguish between sexual and asexual reproduction, and stage structured or not) + demogrParams dem = pSpecies->getDemogrParams(); + // get simulation parameter (to get the number of years) + simParams sim = paramsSim->getSim(); + + // get default values + managementParams m = pManagement->getManagementParams(); + translocationParams t = pManagement->getTranslocationParams(); + + + Rcpp::S4 ManageParamsR("ManagementParams"); + ManageParamsR = Rcpp::as(ParMaster.slot("management")); + Rcpp::S4 TranslocationParamsR("TranslocationParams"); + TranslocationParamsR = Rcpp::as(ManageParamsR.slot("Translocation")); + + double catching_rate_R = Rcpp::as(TranslocationParamsR.slot("catching_rate")); + + Rcpp::IntegerVector translocation_years_R; + translocation_years_R = Rcpp::as(TranslocationParamsR.slot("years")); + + Rcpp::IntegerMatrix translocation_matrix_R; + translocation_matrix_R = Rcpp::as(TranslocationParamsR.slot("TransLocMat")); + + // activate translocation if translocation_years_R is not empty + if(translocation_years_R[0] > 0) m.translocation = true; + + // set and update the management parameters + pManagement->setManagementParams(m); + + if(m.translocation) { + // check if catcing rate as valid value: + if(catching_rate_R > 0 || catching_rate_R <= 1) { + // parse catching_rate_R to catching_rate + t.catching_rate = catching_rate_R; + } else { + Rcpp::Rcout << "ReadTranslocationR(): catching_rate must be between 0 and 1" << std::endl; + error = 600; + return error; + } + + + // parse translocation_years_R to translocation_years + for (int i = 0; i < translocation_years_R.size(); i++) { + // check if the year is within the simulated years + if(translocation_years_R[i] > 0 || translocation_years_R[i] <= sim.years) { + // check if year is not already in the vector + if(std::find(t.translocation_years.begin(), t.translocation_years.end(), translocation_years_R[i]) == t.translocation_years.end()) { + t.translocation_years.push_back(translocation_years_R[i]); + }else{ + Rcpp::Rcout << "ReadTranslocationR(): translocation_years[" << i << "]=" << translocation_years_R[i] << " already exists. Make sure that you only include each year once." << std::endl; + error = 600; + return error; + } + } else{ + Rcpp::Rcout << "ReadTranslocationR(): translocation_years[" << i << "]=" << translocation_years_R[i] << " is not within the simulated years" << std::endl; + error = 600; + return error; + } + + } + + for (int i = 0; i < t.translocation_years.size(); i++) { + Rcpp::Rcout << "ReadTranslocationR(): t.translocation_years[" << i << "]=" << t.translocation_years[i] << std::endl; + } + + + + Rcpp::Rcout << "ReadTranslocationR(): catching_rate: "<< t.catching_rate << std::endl; + + + + for (int i = 0; i < translocation_matrix_R.nrow(); ++i) { + + // extract the year in the first column and initialize the year for each map if needed + int year = translocation_matrix_R(i,0); + if (t.source.find(year) == t.source.end()) { + // not found so add a new key + t.source.insert(std::pair>(year, std::vector())); + t.target.insert(std::pair>(year, std::vector())); + t.nb.insert(std::pair>(year, std::vector())); + // if(dem.stageStruct) { + t.min_age.insert(std::pair>(year, std::vector())); + t.max_age.insert(std::pair>(year, std::vector())); + t.stage.insert(std::pair>(year, std::vector())); + // } + // if(dem.repType!=0) { + t.sex.insert(std::pair>(year, std::vector())); + // } + + } + + // push_back the source to the source map + locn s; + if(paramsLand.patchModel){ // if patch model, the x is the patch ID + // only if patch ID exists? otherwise exit? + if(translocation_matrix_R(i,1) <= pLandscape->patchCount() && translocation_matrix_R(i,1) > 0){ // not sure if I can run this check here + s.x = translocation_matrix_R(i,1); + s.y = -9; + } else{ + Rcpp::Rcout << "ReadTranslocationR(): patch ID of source location " << translocation_matrix_R(i,1) << " is either 0 or greater than the number of overall patches." << std::endl; + error = 600; + return error; + } + + } else { + // if cell-based model + // check if x and y values are inside boundaries + bool data = false; + data = pLandscape->checkDataCell(translocation_matrix_R(i,1), translocation_matrix_R(i,2)); + if(data == false){ // cell is out of boundary + Rcpp::Rcout << "ReadTranslocationR(): source location " << translocation_matrix_R(i,1) << " is outside the landscape." << std::endl; + error = 600; + return error; + } else{ // cell is within landscape + s.x = translocation_matrix_R(i,1); + s.y = translocation_matrix_R(i,2); + }; + }; + + t.source[year].push_back(s); + + // push_back the target to the target map + if(paramsLand.patchModel){ // if patch model, the x is the patch ID + // only if patch ID exists? otherwise exit? + if(translocation_matrix_R(i,2) <= pLandscape->patchCount() && translocation_matrix_R(i,2) > 0){ + s.x = translocation_matrix_R(i,2); + s.y = -9; + } else{ + Rcpp::Rcout << "ReadTranslocationR(): patch ID of target location " << translocation_matrix_R(i,2) << " is either 0 or greater than the number of overall patches." << std::endl; + error = 600; + return error; + } + } else { + // if cell-based model + // check if x and y values are inside boundaries and habitat + if(translocation_matrix_R(i,3) > 0 && translocation_matrix_R(i,3) <= paramsLand.maxX){ + s.x = translocation_matrix_R(i,3); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): x value of target location " << translocation_matrix_R(i,3) << " is either 0 or greater than the maximum x value." << std::endl; + error = 600; + return error; + } + if(translocation_matrix_R(i,4) > 0 && translocation_matrix_R(i,4) <= paramsLand.maxY){ + s.y = translocation_matrix_R(i,4); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): y value of target location " << translocation_matrix_R(i,4) << " is either 0 or greater than the maximum y value." << std::endl; + error = 600; + return error; + } + } + + t.target[year].push_back(s); + + // push_back the number of individuals to the nb map + if(paramsLand.patchModel){ + if((int)translocation_matrix_R(i,3)>0){ + t.nb[year].push_back((int)translocation_matrix_R(i,3)); + } else { + Rcpp::Rcout << "ReadTranslocationR(): number of individuals to be translocated is 0 or a negative value." << std::endl; + error = 600; + return error; + } + } else { + // cell-based + if((int)translocation_matrix_R(i,5)>0){ + t.nb[year].push_back((int)translocation_matrix_R(i,5)); + }else{ + Rcpp::Rcout << "ReadTranslocationR(): number of individuals to be translocated is 0 or a negative value." << std::endl; + error = 600; + return error; + } + } + + // only if stage structured + if(dem.stageStruct) { + // push_back the minimal age of the individuals to the min_age map + // the maximal age of the individuals to the max_age map + // and the stage of the individuals to the stage map + if(paramsLand.patchModel){ + if ((int)translocation_matrix_R(i,4)>=0 || (int)translocation_matrix_R(i,4)==-9){ + t.min_age[year].push_back((int)translocation_matrix_R(i,4)); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): minimal age of the individuals to be translocated is a negative value which is not -9." << std::endl; + error = 600; + return error; + } + if ((int)translocation_matrix_R(i,5)>0 || (int)translocation_matrix_R(i,5)==-9){ + t.max_age[year].push_back((int)translocation_matrix_R(i,5)); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): maximal age of the individuals to be translocated is 0 or a negative value which is not -9." << std::endl; + error = 600; + return error; + } + if ((int)translocation_matrix_R(i,6)>=0 || (int)translocation_matrix_R(i,6)==-9){ + t.stage[year].push_back((int)translocation_matrix_R(i,6)); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): stage of the individuals to be translocated is a negative value which is not -9." << std::endl; + error = 600; + return error; + } + } else { + if ((int)translocation_matrix_R(i,6)>=0 | (int)translocation_matrix_R(i,6)==-9){ + t.min_age[year].push_back((int)translocation_matrix_R(i,6)); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): minimal age of the individuals to be translocated is a negative value which is not -9." << std::endl; + error = 600; + return error; + } + if ((int)translocation_matrix_R(i,7)>0 | (int)translocation_matrix_R(i,7)==-9){ + t.max_age[year].push_back((int)translocation_matrix_R(i,7)); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): maximal age of the individuals to be translocated is 0 or a negative value which is not -9." << std::endl; + error = 600; + return error; + } + if ((int)translocation_matrix_R(i,8)>=0 | (int)translocation_matrix_R(i,8)==-9){ + t.stage[year].push_back((int)translocation_matrix_R(i,8)); + } else{ + Rcpp::Rcout << "ReadTranslocationR(): stage of the individuals to be translocated is a negative value which is not -9." << std::endl; + error = 600; + return error; + } + } + } else{ + t.min_age[year].push_back(-9); + t.max_age[year].push_back(-9); + t.stage[year].push_back(-9); + } + + if(dem.repType!=0) { + // push_back the sex of the individuals to the sex map + if(paramsLand.patchModel){ + if ((int)translocation_matrix_R(i,7) == 0 | (int)translocation_matrix_R(i,7) == 1 | (int)translocation_matrix_R(i,7) == -9){ + t.sex[year].push_back((int)translocation_matrix_R(i,7)); + } else{ + Rcpp::Rcout << "ReadTranslocation(): sex of the individuals to be translocated is not 0, 1 or -9." << std::endl; + error = 600; + return error; + } + } else { + // cell-based + if ((int)translocation_matrix_R(i,9) == 0 | (int)translocation_matrix_R(i,9) == 1 | (int)translocation_matrix_R(i,9) == -9){ + t.sex[year].push_back((int)translocation_matrix_R(i,9)); + } else{ + Rcpp::Rcout << "ReadTranslocation(): sex of the individuals to be translocated is not 0, 1 or -9." << std::endl; + error = 600; + return error; + } + } + } else{ + t.sex[year].push_back(-9); + } + } + + // check input + // loop over t.source map and print out the content + for (std::map>::iterator it = t.source.begin(); it != t.source.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.source[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i].x << " " << it->second[i].y << " "; + } + Rcpp::Rcout << std::endl; + } + + // check input + // loop over t.target map and print out the content + for (std::map>::iterator it = t.target.begin(); it != t.target.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.target[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i].x << " " << it->second[i].y << " "; + } + Rcpp::Rcout << std::endl; + } + + // check input + // loop over t.nb map and print out the content + for (std::map>::iterator it = t.nb.begin(); it != t.nb.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.nb[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i] << " "; + } + Rcpp::Rcout << std::endl; + } + + if(dem.stageStruct) { + // check input + // loop over t.min_age map and print out the content + for (std::map>::iterator it = t.min_age.begin(); it != t.min_age.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.min_age[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i] << " "; + } + Rcpp::Rcout << std::endl; + } + + // check input + // loop over t.max_age map and print out the content + for (std::map>::iterator it = t.max_age.begin(); it != t.max_age.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.max_age[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i] << " "; +} + Rcpp::Rcout << std::endl; + } + + // check input + // loop over t.stage map and print out the content + for (std::map>::iterator it = t.stage.begin(); it != t.stage.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.stage[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i] << " "; + } + Rcpp::Rcout << std::endl; + } + } + + // only if sexual reproduction + if(dem.repType!=0) { + + // check input + // loop over t.stage map and print out the content + for (std::map>::iterator it = t.sex.begin(); it != t.sex.end(); ++it) { + Rcpp::Rcout << "ReadTranslocationR(): t.sex[" << it->first << "]: "; + for (int i = 0; i < it->second.size(); i++) { + Rcpp::Rcout << it->second[i] << " "; + } + Rcpp::Rcout << std::endl; + } + } + + // set and update the translocation parameters + pManagement->setTranslocationParams(t); + + } + return error; +} +//--------------------------------------------------------------------------- + +Rcpp::List RunBatchR(int nSimuls, int nLandscapes, Rcpp::S4 ParMaster) +{ + int land_nr; + int t0, t1, t00, t01; + int read_error; + bool params_ok; + simParams sim = paramsSim->getSim(); + + Rcpp::List list_outPop; + Landscape* pLandscape = NULL; // pointer to landscape + +#if RSDEBUG + DEBUGLOG << endl; + DEBUGLOG << "RunBatchR(): nSimuls=" << nSimuls << " nLandscapes=" << nLandscapes << endl; + DEBUGLOG << "RunBatchR(): landtype=" << landtype << " maxNhab=" << maxNhab << endl; +#endif + + if(!threadsafe){ + t0 = time(0); + } + + + + + // int batch_line = 0; + + string name = paramsSim->getDir(2) + "Batch" + to_string(sim.batchNum) + "_RS_log.csv"; + + if(!threadsafe){ + if(rsLog.is_open()) { + rsLog.close(); + rsLog.clear(); + } + rsLog.open(name.c_str()); + if(!rsLog.is_open()) { + Rcpp::Rcout << endl + << "Error - unable to open Batch" << sim.batchNum << "_RS_log.csv file - aborting batch run" + << endl; + return Rcpp::List::create(Rcpp::Named("Errors") = -678); + } + rsLog << "Event,Number,Reps,Years,Time" << endl; +#if RSDEBUG + rsLog << "WARNING,***** RSDEBUG mode is active *****,,," << endl; +#endif +#if RS_RCPP + rsLog << "RNG SEED,,,," << RS_random_seed << endl; +#endif + } + + // loop over landscapes + + for(int j = 0; j < nLandscapes; j++) { + +#if RSDEBUG + DEBUGLOG << endl; +#endif + // create new landscape + if(pLandscape != NULL) + delete pLandscape; + pLandscape = new Landscape; + bool landOK = true; + + if(!threadsafe){ + t00 = time(0); + } + + landOK = ReadLandParamsR(pLandscape, ParMaster); + Rcpp::Rcout << "ReadLandParamsR() done\n"; + //land_nr = ReadLandParamsR(pLandscape, ParMaster); + land_nr = j; // TODO: ReadLandParamsR() is supposed to return land_nr; this is a temporary replacement; should I adapt this? + + if(!landOK) { + if(!threadsafe){ + rsLog << "Error reading landscape ASCII headers - aborting" << endl; + } + Rcpp::Rcout << "Error reading landscape ASCII headers - aborting" << endl; + } else { +#if RSDEBUG + DEBUGLOG << endl << "RunBatchR(): j=" << j << " land_nr=" << land_nr << " landtype=" << landtype; + if(landtype != 9 && "threadsafe") + DEBUGLOG << " name_landscape=" << name_landscape + << " name_patch=" << name_patch + << " name_costfile=" << name_costfile + << " name_sp_dist=" << name_sp_dist; + DEBUGLOG << endl; +#endif + landParams paramsLand = pLandscape->getLandParams(); + paramsLand.patchModel = patchmodel; + paramsLand.resol = resolution; + paramsLand.rasterType = landtype; + if(landtype == 9) { + paramsLand.generated = true; + paramsLand.nHab = 2; + } else { + paramsLand.generated = false; + /*if(name_dynland == "NULL") + paramsLand.dynamic = false; + else + paramsLand.dynamic = true;*/ + } + paramsLand.nHabMax = maxNhab; + paramsLand.spDist = speciesdist; + paramsLand.spResol = distresolution; + pLandscape->setLandParams(paramsLand, sim.batchMode); + if(landtype != 9) { // imported landscape + + Rcpp::S4 LandParamsR("LandParams"); + LandParamsR = Rcpp::as(ParMaster.slot("land")); + + Rcpp::List habitatmaps; + Rcpp::List patchmaps; + Rcpp::List costmaps; + Rcpp::List spdistmap; + Rcpp::NumericMatrix hraster; + Rcpp::NumericMatrix praster; + Rcpp::NumericMatrix craster; + + string hname; + string cname; + string pname; + string distname; + + int nrDemogScaleLayers = 0; + Rcpp::List demogScaleLayers; // list of lists of layers for each dynamic land year + Rcpp::NumericVector scalinglayers = Rcpp::NumericVector::create(-1); // array of demog scaling layers for a given year (initialise invalid value) + Rcpp::StringVector scalinglayers_fnames = Rcpp::StringVector::create(""); + vector scalinglayers_fnames_vec; // vector of demog scaling layers file names for a given year (initialise empty vector) + + int landcode; + + if(threadsafe){ + habitatmaps = Rcpp::as(LandParamsR.slot("LandscapeMatrix")); + hraster = Rcpp::as(habitatmaps[0]); + + if (patchmodel) { + patchmaps = Rcpp::as(LandParamsR.slot("PatchMatrix")); + praster = Rcpp::as(patchmaps[0]); + } + else{ + praster = Rcpp::NumericMatrix(0); + } + + costmaps = Rcpp::as(LandParamsR.slot("CostsMatrix")); + if (costmaps.size() > 0) craster = Rcpp::as(costmaps[0]); + else craster = Rcpp::NumericMatrix(0); + + if(spatial_demography){ + if(landtype == 2 && stagestruct) { + nrDemogScaleLayers = Rcpp::as(LandParamsR.slot("nrDemogScaleLayers")); + if(nrDemogScaleLayers) { + // if (threadsafe) { + demogScaleLayers = Rcpp::as(LandParamsR.slot("demogScaleLayersMatrix")); + scalinglayers = demogScaleLayers[0]; // get matrix of scaling layers of year 0 (numeric vector) + } + } + } + landcode = pLandscape->readLandscape(0, hraster, praster, craster, scalinglayers); + + + if(landcode != 0) { + Rcpp::Rcout << endl << "Error reading landscape " << land_nr << " - aborting" << endl; + landOK = false; + } + if(paramsLand.dynamic) { + landcode = ReadDynLandR(pLandscape, LandParamsR); + if(landcode != 0) { + Rcpp::Rcout << endl << "Error reading dynamic landscape - aborting" << endl; + landOK = false; + } else { + Rcpp::Rcout << "ReadDynLandR() done" << std::endl; + } + } + if(landtype == 0) { + pLandscape->updateHabitatIndices(); + } + // species distribution + if(paramsLand.spDist) { // read initial species distribution + // WILL NEED TO BE CHANGED FOR MULTIPLE SPECIES ... + + spdistmap = Rcpp::as(LandParamsR.slot("SpDistMatrix")); + landcode = pLandscape->newDistribution(pSpecies, Rcpp::as(spdistmap[0]), distresolution); + if(landcode == 0) { + } else { + Rcpp::Rcout << endl + << "Error reading initial distribution for landscape " << land_nr << " - aborting" + << endl; + landOK = false; + } + } + paramsSim->setSim(sim); + } + else{ + hname = paramsSim->getDir(1) + name_landscape; + + if (name_costfile == "NULL" || name_costfile == "none") cname = "NULL"; + else cname = paramsSim->getDir(1) + name_costfile; + + if(spatial_demography){ + if(landtype == 2 && stagestruct) { + nrDemogScaleLayers = Rcpp::as(LandParamsR.slot("nrDemogScaleLayers")); + if(nrDemogScaleLayers) { + demogScaleLayers = Rcpp::as(LandParamsR.slot("demogScaleLayersFile")); + scalinglayers_fnames = demogScaleLayers[0]; // get vector of scaling layers file names of year 0 (string vector) + for (int i = 0; i < scalinglayers_fnames.size(); ++i) { + string scaling_fname =Rcpp::as(scalinglayers_fnames[i]); + scaling_fname = paramsSim->getDir(1) + scaling_fname; // prepend input directory to the file name + scalinglayers_fnames_vec.push_back(scaling_fname); + } + } + } + } + + if(paramsLand.patchModel) { + pname = paramsSim->getDir(1) + name_patch; + landcode = pLandscape->readLandscape(0, hname, pname, cname, scalinglayers_fnames_vec); + } else + landcode = pLandscape->readLandscape(0, hname, " ", cname, scalinglayers_fnames_vec); + + if(landcode != 0) { + rsLog << "Landscape," << land_nr << ",ERROR,CODE," << landcode << endl; + Rcpp::Rcout << endl << "Error reading landscape " << land_nr << " - aborting" << endl; + landOK = false; + } else{ + Rcpp::Rcout << "ReadLandParamsR(): Landscapes read successfully" << std::endl; + } + if(paramsLand.dynamic) { + landcode = ReadDynLandR(pLandscape, LandParamsR); + if(landcode != 0) { + rsLog << "Landscape," << land_nr << ",ERROR,CODE," << landcode << endl; + Rcpp::Rcout << endl << "Error reading landscape " << land_nr << " - aborting" << endl; + landOK = false; + } else{ + Rcpp::Rcout << "ReadDynLandR(): Dynamic landscapes read successfully" << std::endl; + } + } + if(landtype == 0) { + pLandscape->updateHabitatIndices(); + } +#if RSDEBUG + landParams tempLand = pLandscape->getLandParams(); + DEBUGLOG << "RunBatchR(): j=" << j << " land_nr=" << land_nr << " landcode=" << landcode + << " nHab=" << tempLand.nHab << endl; +#endif + + // species distribution + + if(paramsLand.spDist) { // read initial species distribution + // WILL NEED TO BE CHANGED FOR MULTIPLE SPECIES ... + distname = paramsSim->getDir(1) + name_sp_dist; + landcode = pLandscape->newDistribution(pSpecies, distname); + if(landcode == 0) { + Rcpp::Rcout << "ReadLandParamsR(): Species distribution read successfully" << std::endl; + } else { + rsLog << "Landscape," << land_nr << ",ERROR,CODE," << landcode << endl; + Rcpp::Rcout << endl + << "Error reading initial distribution for landscape " << land_nr << " - aborting" + << endl; + landOK = false; + } + } + paramsSim->setSim(sim); +#if RSDEBUG + DEBUGLOG << "RunBatchR(): j=" << j << " spDist=" << paramsLand.spDist << endl; +#endif + + if(landOK) { + t01 = time(0); + rsLog << "Landscape," << land_nr << ",,," << t01 - t00 << endl; + + } // end of landOK condition + }// end threadsafe + + } // end of imported landscape + } + if(landOK) { + + // Open all other batch files and read header records + + // nSimuls is the total number of lines (simulations) in + // the batch and is set in the control function + string msgsim = "Simulation,"; + string msgerr = ",ERROR CODE,"; + string msgabt = ",simulation aborted"; + for(int i = 0; i < nSimuls; i++) { // this loop is useless at the moment since nSimuls is set to one in R entry function BatchMainR() + if(!threadsafe){ + t00 = time(0); + simParams sim = paramsSim->getSim(); + } + params_ok = true; + read_error = ReadParametersR(pLandscape, ParMaster); + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading simulation parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + } else{ + Rcpp::Rcout << "ReadParametersR() done." << endl; + } + if(stagestruct) { + ReadStageStructureR(ParMaster); // in Spatial_demog: read_error = ReadStageStructureR(ParMaster); + Rcpp::Rcout << "ReadStageStructureR() done." << endl; + } + read_error = ReadEmigrationR(ParMaster); + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading emigration parameters - aborting" << endl; + } else { + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + } else{ + Rcpp::Rcout << "ReadEmigrationR() done." << endl; + } + read_error = ReadTransferR(pLandscape, ParMaster); + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading transfer parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + } else{ + Rcpp::Rcout << "ReadTransferR() done." << endl; + } + read_error = ReadSettlementR(ParMaster); + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading settlement parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + } else{ + Rcpp::Rcout << "ReadSettlementR() done." << endl; + } + if(translocation){ + read_error = ReadTranslocationR(pLandscape, ParMaster); + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading translocation parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + } else{ + Rcpp::Rcout << "ReadTranslocationR() done." << endl; + } + } + if(params_ok) { +#if RSDEBUG + DebugGUI("RunBatchR(): simulation i=" + Int2Str(i)); +#endif + } + read_error = ReadInitialisationR(pLandscape, ParMaster); + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading initialisation parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + } else{ + Rcpp::Rcout << "ReadInitialisationR() done." << endl; + } + + if (gHasGenetics) { // genetics need to be set and traits file need to be provided + Rcpp::S4 GeneParamsR("GeneticsParams"); + GeneParamsR = Rcpp::as(ParMaster.slot("gene")); + + read_error = ReadGeneticsR(GeneParamsR, pLandscape); +#if RSDEBUG + DEBUGLOG << "ReadGeneticsFile()" << endl; +#endif + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading genetics parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + }else{ + Rcpp::Rcout << "ReadGeneticsR() done." << endl; + } + + Rcpp::S4 TraitsParamsR("TraitsParams"); + TraitsParamsR = Rcpp::as(GeneParamsR.slot("Traits")); + read_error = ReadTraitsR(TraitsParamsR); +#if RSDEBUG + DEBUGLOG << "ReadTraitsFile()" << endl; +#endif + if(read_error) { + if(threadsafe){ + Rcpp::Rcout << "Error reading trait parameters - aborting" << endl; + } else{ + rsLog << msgsim << sim.simulation << msgerr << read_error << msgabt << endl; + } + params_ok = false; + }else{ + Rcpp::Rcout << "ReadTraitsR() done." << endl; + } + + } + + + if(params_ok) { + simParams sim = paramsSim->getSim(); + +#if RSDEBUG + DEBUGLOG << endl + << "RunBatchR(): i=" << i << " simulation=" << sim.simulation + //<< " landFile=" << landFile + << " outRange=" << sim.outRange << " outIntRange=" << sim.outIntRange << endl; +#endif + + Rcpp::Rcout << endl + << "Running simulation nr. " << to_string(sim.simulation) + //<< " on landscape no. " << Int2Str(land_nr) + << endl; + + + // for batch processing, include landscape number in parameter file name + if(!threadsafe) + OutParameters(pLandscape); + + // run the model + list_outPop = RunModel(pLandscape, i, ParMaster); + + +#if RSDEBUG + // DEBUGLOG << endl << "RunBatchR(): real landscape, i = " << i + // << " simulation = " << sim.simulation << " landFile = " << landFile + // << endl; +#endif + if(!threadsafe){ + t01 = time(0); + rsLog << msgsim << sim.simulation << "," << sim.reps << "," << sim.years << "," << t01 - t00 + << endl; + } + + } // end of if (params_ok) + else { + Rcpp::Rcout << endl << "Error in reading parameter file(s)... see RS log." << endl; + } + } // end of nSimuls for loop + + // close input files + +// if (landtype != 9) { + if (pLandscape != NULL) { + delete pLandscape; + pLandscape = NULL; + } + if(pManagement != NULL) { + delete pManagement; + pManagement = NULL; + } + } // end of landOK condition + + } // end of nLandscapes loop + +// Write performance data to log file + if(!threadsafe){ + t1 = time(0); + rsLog << endl << "Batch,,,," << t1 - t0 << endl; + if(rsLog.is_open()) { + rsLog.close(); + rsLog.clear(); + } + } + + return list_outPop; +} + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + +void setglobalvarsR(Rcpp::S4 control) +{ + + // nSimuls = 2; //read from parameterfile + // nLandscapes = 1; //read from landfile, but not yet used in R-class RSparams! + + batchnum = Rcpp::as(control.slot("batchnum")); + patchmodel = Rcpp::as(control.slot("patchmodel")); + resolution = Rcpp::as(control.slot("resolution")); + landtype = Rcpp::as(control.slot("landtype")); + maxNhab = Rcpp::as(control.slot("maxNhab")); + speciesdist = Rcpp::as(control.slot("speciesdist")); + distresolution = Rcpp::as(control.slot("distresolution")); + reproductn = Rcpp::as(control.slot("reproductn")); + repseasons = Rcpp::as(control.slot("repseasons")); + stagestruct = Rcpp::as(control.slot("stagestruct")); + stages = Rcpp::as(control.slot("stages")); + gTransferType = Rcpp::as(control.slot("transfer")); + translocation = Rcpp::as(control.slot("translocation")); + gHasNeutralGenetics = Rcpp::as(control.slot("neutralgenetics")); + gHasGeneticLoad = Rcpp::as(control.slot("geneticload")); + gHasGenetics = gHasNeutralGenetics || gHasGeneticLoad; + threadsafe = Rcpp::as(control.slot("threadsafe")); + spatial_demography = Rcpp::as(control.slot("spatial_demography")); + fixreplicateseed = Rcpp::as(control.slot("fixreplicateseed")); + +#if RSDEBUG + /* + Function slotNames("slotNames"); + CharacterVector snames = slotNames(obj); + for (int i = 0; i < snames.size(); i++) { + SEXP slot = obj.slot(Rcpp::as(snames[i])); + // do something with slot + } + */ +#endif +} + +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- +//--------------------------------------------------------------------------- + +#if !RSWIN64 +// check for UTF-16 encoding +string check_bom(string file) +{ + /* + const char *UTF_16_BE_BOM = "\xFE\xFF"; + const char *UTF_16_LE_BOM = "\xFF\xFE"; + const char *UTF_8_BOM = "\xEF\xBB\xBF"; + const char *UTF_32_BE_BOM = "\x00\x00\xFE\xFF"; + const char *UTF_32_LE_BOM = "\xFF\xFE\x00\x00"; + */ + string enc = "undef"; + + ifstream infile(file, ios::in | ios::binary); + if(!infile) { + enc = "error"; + infile.clear(); + } else { + char buffer[20]; + infile.read(buffer, 4); + if(buffer[0] == '\xFE' && buffer[1] == '\xFF') { // UTF-16 LE + enc = "utf16"; + } + if(buffer[0] == '\xFF' && buffer[1] == '\xFE') { // UTF-16 BE + enc = "utf16"; + } + if(buffer[0] == '\xEF' && buffer[1] == '\xBB' && buffer[2] == '\xBF') { // UTF-8 + enc = "utf8"; + } + if(buffer[0] == '\x00' && buffer[1] == '\x00' && buffer[2] == '\xFE' && buffer[3] == '\xFF') { // UTF-32 BE + enc = "utf32"; + } + if(buffer[0] == '\xFF' && buffer[1] == '\xFE' && buffer[2] == '\x00' && buffer[3] == '\x00') { // UTF-32 BE + enc = "utf32"; + } + /* + if (size >= 3) { + if (memcmp(data, UTF_8_BOM, 3) == 0) + return "UTF-8"; + } + if (size >= 4) { + if (memcmp(data, UTF_32_LE_BOM, 4) == 0) + return "UTF-32-LE"; + if (memcmp(data, UTF_32_BE_BOM, 4) == 0) + return "UTF-32-BE"; + } + if (size >= 2) { + if (memcmp(data, UTF_16_LE_BOM, 2) == 0) + return "UTF-16-LE"; + if (memcmp(data, UTF_16_BE_BOM, 2) == 0) + return "UTF-16-BE"; + }*/ + infile.close(); + } + return enc; +} +#endif + +//--------------------------------------------------------------------------- + +rasterdata ParseRasterHead(string file) +{ + wifstream infile; + rasterdata r; + wstring header; + int inint; + + r.ok = true; + r.errors = r.ncols = r.nrows = r.cellsize = 0; + r.xllcorner = r.yllcorner = 0.0; + r.utf = false; + + // open file +#if RSWIN64 + infile.open(file.c_str()); +#else + infile.open(file, std::ios::binary); +#endif + if (infile.is_open()) { +#if RSDEBUG + DEBUGLOG << "Parsing raster file " << file << std::endl; +#endif +#if !RSWIN64 + // check BOM for UTF-16 + if(check_bom(file) == "utf16") { + // apply BOM-sensitive UTF-16 facet + infile.imbue(std::locale(infile.getloc(), new std::codecvt_utf16)); + r.utf = true; + } else { + r.utf = false; + } +#endif + // parse ASCII header + infile >> header; + if (!infile.good()) { +#if RSDEBUG + DEBUGLOG << "ParseRasterHead(): failed to read " << file << std::endl; +#endif + r.ok = false; + r.errors = -211; + infile.close(); + infile.clear(); + return r; + } + if (header != L"ncols" && header != L"NCOLS") r.errors++; + infile >> r.ncols; + + infile >> header >> r.nrows; + if (header != L"nrows" && header != L"NROWS") r.errors++; + + infile >> header >> r.xllcorner; + if (header != L"xllcorner" && header != L"XLLCORNER") r.errors++; + + infile >> header >> r.yllcorner; + if (header != L"yllcorner" && header != L"YLLCORNER") r.errors++; + + double tmpcellsize; + infile >> header >> tmpcellsize; + if (header != L"cellsize" && header != L"CELLSIZE") r.errors++; + r.cellsize = (int) tmpcellsize; + + infile >> header >> inint; + if (header != L"NODATA_value" && header != L"NODATA_VALUE") r.errors++; + + + if (r.errors > 0) r.ok = false; + + } else { + r.ok = false; + r.errors = -111; + //OpenErrorR("Raster file ", file); +#if RSDEBUG + DEBUGLOG << "Raster file failed to open: " << file << std::endl; +#endif + } + infile.close(); + infile.clear(); + return r; +} + +//---------------------------------------------------------------------------------------------- + + +int ReadInitIndsFileR(int option, Landscape* pLandscape, Rcpp::DataFrame initindslist ) +{ + landParams paramsLand = pLandscape->getLandParams(); + demogrParams dem = pSpecies->getDemogrParams(); + //stageParams sstruct = pSpecies->getStage(); + initParams init = paramsInit->getInit(); + string filetype = "InitIndsList"; + Rcpp::CharacterVector colnames = initindslist.names(); + int lines = initindslist.nrows(); + int errors = 0, col_ix = 0; + + Rcpp::IntegerVector df_year; + Rcpp::IntegerVector df_species; + Rcpp::IntegerVector df_patch; + Rcpp::IntegerVector df_X; + Rcpp::IntegerVector df_Y; + Rcpp::IntegerVector df_Ninds; + Rcpp::IntegerVector df_Sex; + Rcpp::IntegerVector df_Age; + Rcpp::IntegerVector df_Stage; + + if(option == 0) { // parse and read header and lines + + // Check right headers format + if(colnames[col_ix++] == "Year") df_year = initindslist["Year"]; + else errors++; + if(colnames[col_ix++] == "Species") df_species = initindslist["Species"]; + else errors++; + if(patchmodel) { + if(colnames[col_ix++] == "PatchID") df_patch = initindslist["PatchID"]; + else errors++; + } else { + if(colnames[col_ix++] == "X") df_X = initindslist["X"]; + else errors++; + if(colnames[col_ix++] == "Y") df_Y = initindslist["Y"]; + else errors++; + } + if(colnames[col_ix++] == "Ninds") df_Ninds = initindslist["Ninds"]; + else errors++; + if(reproductn > 0) { + if(colnames[col_ix++] == "Sex") df_Sex = initindslist["Sex"]; + else errors++; + } + if(stagestruct) { + if(colnames[col_ix++] == "Age") df_Age = initindslist["Age"]; + else errors++; + if(colnames[col_ix++] == "Stage") df_Stage = initindslist["Stage"]; + else errors++; + } + // Report any errors in headers, and if so, terminate validation + if(errors > 0) { + FormatErrorR(filetype, errors); + return -111; + } + + paramsInit->resetInitInds(); + + // Read dataframe lines + initInd iind; + iind.year = -98765; + int ninds; + int totinds = 0; + int prevyear = -98765; + + for(int l = 0; l < lines; l++) { // loop over dataframe rows + + // Year + iind.year = df_year[l]; + if(iind.year < 0) { + BatchErrorR(filetype, l, 19, "Year"); + errors++; + } else { + if(iind.year < prevyear) { + BatchErrorR(filetype, l, 2, "Year", "previous Year"); + errors++; + } + } + prevyear = iind.year; + + // Species + iind.species = df_species[l]; + if(iind.species != 0) { + BatchErrorR(filetype, l, 0, " "); + errors++; + Rcpp::Rcout << "Species must be 0" << endl; + } + + // Patch | Coordinates + if(paramsLand.patchModel) { + iind.patchID = df_patch[l]; + if(iind.patchID < 1) { + BatchErrorR(filetype, l, 11, "PatchID"); + errors++; + iind.x = iind.y = 0; + } + } else { + iind.x = df_X[l]; + iind.y = df_Y[l]; + if(iind.x < 0 || iind.y < 0) { + BatchErrorR(filetype, l, 19, "X and Y"); + errors++; + iind.patchID = 0; + } + } + + // No of individuals + ninds = df_Ninds[l]; + if(ninds < 1) { + BatchErrorR(filetype, l, 11, "Ninds"); + errors++; + } + + // Sex + if(dem.repType > 0){ + iind.sex = df_Sex[l]; + if(iind.sex < 0 || iind.sex > 1) { + BatchErrorR(filetype, l, 1, "Sex"); + errors++; + } + } + else iind.sex = 0; + + // Stage + if(dem.stageStruct) { + iind.age = df_Age[l]; + iind.stage = df_Stage[l]; + if(iind.age < 1) { + BatchErrorR(filetype, l, 11, "Age"); + errors++; + } + if(iind.stage < 1) { + BatchErrorR(filetype, l, 11, "Stage"); + errors++; + } + if(iind.stage >= stages) { + BatchErrorR(filetype, l, 4, "Stage", "no. of stages"); + errors++; + } + } else { + iind.age = iind.stage = 0; + } + + for(int i = 0; i < ninds; i++) { + totinds++; + paramsInit->addInitInd(iind); + } + + iind.year = -98765; // finished current line + if(errors){ // check for format errors + return errors; + } + } // end of loop over rows + + Rcpp::Rcout << "Initial individuals list OK" << std::endl; + return 0; //totinds; + + } // end of option 0 + + if(option == 9) { // close file + return 0; + } + return -1; +} + + +int ReadInitIndsFileR(int option, Landscape* pLandscape) +{ + landParams paramsLand = pLandscape->getLandParams(); + demogrParams dem = pSpecies->getDemogrParams(); + //stageParams sstruct = pSpecies->getStage(); + initParams init = paramsInit->getInit(); + + string indsfile = paramsSim->getDir(1) + init.indsFile; + wifstream initIndsFile; + + wstring header; + string filetype = "InitIndsFile"; + string filename, ftype2, fname; + + int line, prevyear; + //int year, sex, species, patchID, x, y, ninds, age, stage; + + int errors = 0; + + if(option == 0) { // open file, parse and read header and lines + // open file +#if RSWIN64 + initIndsFile.open(indsfile.c_str()); +#else + initIndsFile.open(indsfile, std::ios::binary); +#endif + if(!initIndsFile.is_open()) { + OpenErrorR("Initial individuals file", indsfile); +#if RSDEBUG + DEBUGLOG << "Initial individuals file failed to open: " << indsfile << std::endl; +#endif + return -21; + } else { +#if RSDEBUG + DEBUGLOG << "Initial individuals file open to read" << std::endl; +#endif +#if !RSWIN64 + // check BOM for UTF-16 + if(check_bom(indsfile) == "utf16") + // apply BOM-sensitive UTF-16 facet + initIndsFile.imbue(std::locale(initIndsFile.getloc(), new std::codecvt_utf16)); +#endif + + // Check right headers format + initIndsFile >> header; + if(!initIndsFile.good()) { + Rcpp::Rcout << "Initial individuals failed to read" << std::endl; +#if RSDEBUG + DEBUGLOG << "Initial individuals failed to read" << std::endl; +#endif + return -211; + } + if(header != L"Year") + errors++; + initIndsFile >> header; + if(header != L"Species") + errors++; + if(patchmodel) { + initIndsFile >> header; + if(header != L"PatchID") + errors++; + } else { + initIndsFile >> header; + if(header != L"X") + errors++; + initIndsFile >> header; + if(header != L"Y") + errors++; + } + initIndsFile >> header; + if(header != L"Ninds") + errors++; + if(reproductn > 0) { + initIndsFile >> header; + if(header != L"Sex") + errors++; + } + if(stagestruct) { + initIndsFile >> header; + if(header != L"Age") + errors++; + initIndsFile >> header; + if(header != L"Stage") + errors++; + } + // Report any errors in headers, and if so, terminate validation + if(errors > 0) { + FormatErrorR(filetype, errors); + return -111; + } + + paramsInit->resetInitInds(); + + // Read data lines + initInd iind; + int ninds; + int totinds = 0; + + line = 1; + iind.year = prevyear = -98765; + initIndsFile >> iind.year; + + while(iind.year != -98765) { + // Year + if(iind.year < 0) { + BatchErrorR(filetype, line, 19, "Year"); + errors++; + } else { + if(iind.year < prevyear) { + BatchErrorR(filetype, line, 2, "Year", "previous Year"); + errors++; + } + } + prevyear = iind.year; + + // Species + initIndsFile >> iind.species; + if(iind.species != 0) { + BatchErrorR(filetype, line, 0, " "); + errors++; + Rcpp::Rcout << "Species must be 0" << endl; + } + + // Patch | Coordinates + if(paramsLand.patchModel) { + initIndsFile >> iind.patchID; + if(iind.patchID < 1) { + BatchErrorR(filetype, line, 11, "PatchID"); + errors++; + iind.x = iind.y = 0; + } + } else { + initIndsFile >> iind.x >> iind.y; + if(iind.x < 0 || iind.y < 0) { + BatchErrorR(filetype, line, 19, "X and Y"); + errors++; + iind.patchID = 0; + } + } + + // No of individuals + initIndsFile >> ninds; + if(ninds < 1) { + BatchErrorR(filetype, line, 11, "Ninds"); + errors++; + } + + // Sex + if(dem.repType > 0){ + initIndsFile >> iind.sex; + if(iind.sex < 0 || iind.sex > 1) { + BatchErrorR(filetype, line, 1, "Sex"); + errors++; + } + } + else iind.sex = 0; + + // Stage + if(dem.stageStruct) { + initIndsFile >> iind.age >> iind.stage; + if(iind.age < 1) { + BatchErrorR(filetype, line, 11, "Age"); + errors++; + } + if(iind.stage < 1) { + BatchErrorR(filetype, line, 11, "Stage"); + errors++; + } + if(iind.stage >= stages) { + BatchErrorR(filetype, line, 4, "Stage", "no. of stages"); + errors++; + } + } else { + iind.age = iind.stage = 0; + } + + for(int i = 0; i < ninds; i++) { + totinds++; + paramsInit->addInitInd(iind); + } + + line++; + iind.year = -98765; // finished current line + if(!errors){ // check for format errors + if(!initIndsFile.eof()) // check for EOF to end loop + initIndsFile >> iind.year; // read next year + } + } // end of while loop over lines + if(!initIndsFile.eof()) { + EOFerrorR(filetype); + errors++; + } + + } // end of "file is open" + + if(initIndsFile.is_open()) + initIndsFile.close(); + initIndsFile.clear(); + + Rcpp::Rcout << "Initial individuals file OK:" << indsfile << std::endl; + + return errors; //totinds; + + } // end of option 0 + + if(option == 9) { // close file + if(initIndsFile.is_open()) { + initIndsFile.close(); + } + initIndsFile.clear(); + return 0; + } + return -1; +} + +//--------------------------------------------------------------------------- + +void BatchErrorR(string filename, int line, int option, string fieldname) +{ + if(line == -999) { // message does not cite line number + Rcpp::Rcout << "*** Error in " << filename << ": "; + } else { + Rcpp::Rcout << "*** Error in " << filename << " at line " << line << ": "; + } + switch(option) { + case 0: + break; + case 1: + Rcpp::Rcout << fieldname << " must be 0 or 1"; + break; + case 2: + Rcpp::Rcout << fieldname << " must be 0, 1 or 2"; + break; + case 3: + Rcpp::Rcout << fieldname << " must be 0, 1, 2 or 3"; + break; + case 4: + Rcpp::Rcout << fieldname << " must be from 0 to 4"; + break; + case 5: + Rcpp::Rcout << fieldname << " must be from 0 to 5"; + break; + case 6: + Rcpp::Rcout << fieldname << " must be from 0 to 6"; + break; + case 7: + Rcpp::Rcout << fieldname << " must be from 0 to 7"; + break; + case 10: + Rcpp::Rcout << fieldname << " must be greater than zero"; + break; + case 11: + Rcpp::Rcout << fieldname << " must be 1 or more"; + break; + case 12: + Rcpp::Rcout << fieldname << " must be 2 or more"; + break; + case 13: + Rcpp::Rcout << fieldname << " must be 3 or more"; + break; + case 18: + Rcpp::Rcout << fieldname << " must be greater than 1.0"; + break; + case 19: + Rcpp::Rcout << fieldname << " must be 0 or more"; + break; + case 20: + Rcpp::Rcout << fieldname << " must be between 0 and 1"; + break; + case 21: + Rcpp::Rcout << fieldname << " must be greater than 1"; + break; + case 33: + Rcpp::Rcout << fieldname << " must be 1, 2 or 3"; + break; + case 44: + Rcpp::Rcout << fieldname << " must be from 1 to 4"; + break; + case 55: + Rcpp::Rcout << fieldname << " must be from 1 to 5"; + break; + case 66: + Rcpp::Rcout << fieldname << " must be from 1 to 6"; + break; + case 100: + Rcpp::Rcout << fieldname << " must be between 0 and 100"; + break; + case 111: + Rcpp::Rcout << fieldname << " must match the first Simulation in ParameterFile"; + break; + case 222: + Rcpp::Rcout << "Simulation numbers must be sequential integers"; + break; + case 333: + Rcpp::Rcout << "No. of " << fieldname << " columns must equal max. no. of habitats (" << maxNhab + << ") and be sequentially numbered starting from 1"; + break; + case 444: + Rcpp::Rcout << "No. of " << fieldname << " columns must be one fewer than no. of stages, i.e. " << stages - 1 + << ", and be sequentially numbered starting from 1"; + break; + case 555: + Rcpp::Rcout << "No. of " << fieldname << " columns must equal no. of stages, i.e. " << stages + << ", and be sequentially numbered starting from 0"; + break; + case 666: + Rcpp::Rcout << fieldname << " must be a unique positive integer"; + break; + default: + Rcpp::Rcout << "*** Unspecified error regarding parameter " << fieldname; + } + if(option != 0) + Rcpp::Rcout << endl; +} + +void BatchErrorR(string filename,int line,int option,string fieldname,string fieldname2) +{ + if (line == -999) { // message does not cite line number + Rcpp::Rcout << "*** Error in " << filename << ": "; + } else { + Rcpp::Rcout << "*** Error in " << filename << " at line " << line <<": "; + } + switch (option) { + case 0: + break; + case 1: + Rcpp::Rcout << fieldname << " must be greater than " << fieldname2; + break; + case 2: + Rcpp::Rcout << fieldname << " must be greater than or equal to " << fieldname2; + break; + case 3: + Rcpp::Rcout << fieldname << " must be less than or equal to " << fieldname2; + break; + case 4: + Rcpp::Rcout << fieldname << " must be less than " << fieldname2; + break; + default: + Rcpp::Rcout << "*** Unspecified error regarding parameters " << fieldname + << " and " << fieldname2; + ; + } + if (option != 0) Rcpp::Rcout << endl; +} + +void ArchFormatErrorR(void) +{ +//batchlog << "*** Format error in ArchFile: case-sensitive parameter names " +// << "must match the specification exactly" << endl; + Rcpp::Rcout << "*** Format error in ArchFile:" << msgcase << msgmatch << endl; +} + +void FormatErrorR(string filename, int errors) +{ + Rcpp::Rcout << "*** Format error in header line of "; + if(errors == 0) { + Rcpp::Rcout << filename << endl; + } else { + Rcpp::Rcout << filename << ": " << errors << " error"; + if(errors > 1) + Rcpp::Rcout << "s"; + Rcpp::Rcout << " detected" << endl; + } +} + +void OpenErrorR(string ftype, string fname) +{ + Rcpp::Rcout << "*** Unable to open " << ftype << " " << fname << std::endl; +} + +void EOFerrorR(string filename) +{ + Rcpp::Rcout << "*** Did not read to EOF in " << filename << std::endl; +} + +void StreamErrorR(string filename) +{ + Rcpp::Rcout << "*** Corrupted file stream in " << filename << std::endl << "Too few entries? Unsuppoerted file encoding? (You might try to use a different one, like UTF-8.)" << std::endl; +#if RSDEBUG + DEBUGLOG << "Corrupted file stream in " << filename << std::endl; +#endif +} + +//--------------------------------------------------------------------------- diff --git a/RangeShiftR/src/Rinterface.h b/RangeShiftR/src/Rinterface.h new file mode 100644 index 0000000..15cead4 --- /dev/null +++ b/RangeShiftR/src/Rinterface.h @@ -0,0 +1,183 @@ +/*---------------------------------------------------------------------------- + * + * Copyright (C) 2020 Anne-Kathleen Malchow, Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Damaris Zurell + * + * This file is part of RangeShiftR. + * + * RangeShiftR is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * RangeShifter is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with RangeShiftR. If not, see . + * + --------------------------------------------------------------------------*/ + + +/*------------------------------------------------------------------------------ + +RangeShifter v2.0 Rinterface + +Implements the interface to the R-package RangeshiftR. + +Author: Anne-Kathleen Malchow, Humboldt University Berlin + large parts modified from 'Main.cpp' and 'BatchMode.cpp' created by + Steve Palmer, University of Aberdeen + +------------------------------------------------------------------------------*/ + +#ifndef RinterfaceH +#define RinterfaceH + +//--------------------------------------------------------------------------- + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#if !RSWIN64 +#include +#endif + +using namespace std; + +#include + +#include "RScore/Parameters.h" +#include "RScore/Landscape.h" +#include "RScore/Species.h" +#include "RScore/SubCommunity.h" +#include "RScore/RSrandom.h" +#include "RScore/Model.h" +#include "RScore/Management.h" +#include "RScore/Cell.h" + + + +//--------------------------------------------------------------------------- + + +//Rcpp::List run_from_R(Rcpp::S4, Rcpp::String); // entry functions from R +//Rcpp::List BatchMainFile(string, Rcpp::S4); // missing dependend functions for file reading/parsing, from BatchMode.h/.cpp +Rcpp::List BatchMainR(std::string, Rcpp::S4); + +bool ReadLandParamsR(Landscape*, Rcpp::S4); +int ReadDynLandR(Landscape*, Rcpp::S4); +int ReadParametersR(Landscape*, Rcpp::S4); +int ReadStageStructureR(Rcpp::S4); +int ReadEmigrationR(Rcpp::S4); +int ReadTransferR(Landscape*, Rcpp::S4); +int ReadSettlementR(Rcpp::S4); +int ReadInitialisationR(Landscape*, Rcpp::S4); +int ReadGeneticsR(Rcpp::S4); +int ReadTraitsR(Rcpp::S4); +const sex_t intToSex(const int& i); +TraitType stringToTraitType(const std::string& str); +TraitType addSexDepToTrait(const TraitType& t, const sex_t& sex); +GenParamType strToGenParamType(const string& str); +ExpressionType stringToExpressionType(const std::string& str); +map NumericToParameterMap(string parameterString, Rcpp::NumericVector parameter); +set selectRandomLociPositions(int noLoci, const int& genomeSize); +DistributionType stringToDistributionType(const std::string& str); +void setUpSpeciesTrait(string TraitTypeR, + set positions, + string ExpressionTypeR, + set initialPositions, + string initDistR, + Rcpp::NumericVector initParamsR, + string initDominanceDistR, + Rcpp::NumericVector initDominanceParamsR, + string DominanceDistR, + Rcpp::NumericVector DominanceParamsR, + bool isInherited, + string MutationDistR, + Rcpp::NumericVector MutationParamsR, + float MutationRateR, + int sexdep, + bool isOutputR); +int ReadTranslocationR(Landscape*,Rcpp::S4); + +int ParseInitIndsFileR(wifstream&); + +int ReadInitIndsFileR(int,Landscape*,Rcpp::DataFrame); + +int ReadInitIndsFileR(int,Landscape*); + + +Rcpp::List RunBatchR(int, int, Rcpp::S4); +void setglobalvarsR(Rcpp::S4); + +struct DispersalTraitInputOptions { + bool isEmigIndVar = false; + bool isEmigDensDep = false; + bool isEmigSexDep = false; + + bool isSettIndVar = false; + bool isSettSexDep = false; + + bool isKernTransfIndVar = false; + bool isKernTransfSexDep = false; + bool usesTwoKernels = false; + + bool isSMSTransfIndVar = false; + bool usesSMSGoalBias = false; + + bool isCRWTransfIndVar = false; +}; + + + +//--------------------------------------------------------------------------- + +#if !RSWIN64 +string check_bom(string); // check BOM of a text file for UTF-16 encoding +#endif +rasterdata ParseRasterHead(string); //parse, read and return ASCII raster head data + +void BatchErrorR(string,int,int,string); +void BatchErrorR(string,int,int,string,string); + +//void CtrlFormatError(void); +//void ArchFormatError(void); +void FormatErrorR(string,int); +void OpenErrorR(string,string); +void EOFerrorR(string); +void StreamErrorR(string); +void ArchFormatErrorR(void); +//void FileOK(string,int,int); +//void FileHeadersOK(string); +//void SimulnCountError(string); + + +//--------------------------------------------------------------------------- + +// external pointers + +#if RSDEBUG +extern ofstream DEBUGLOG; +#endif + +extern paramGrad *paramsGrad; +extern paramStoch *paramsStoch; +extern paramInit *paramsInit; +extern paramSim *paramsSim; + +extern Species *pSpecies; +extern string costmapname; // see FormMove.cpp (VCL) OR Main.cpp (batch) +extern string genfilename; // see FormGenetics.cpp (VCL) OR Main.cpp (batch) +extern std::uint32_t RS_random_seed; // see RSrandom.cpp + +//--------------------------------------------------------------------------- +#endif diff --git a/Species.cpp b/Species.cpp deleted file mode 100644 index d91a3e4..0000000 --- a/Species.cpp +++ /dev/null @@ -1,1369 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - - //--------------------------------------------------------------------------- - -#include "Species.h" -//--------------------------------------------------------------------------- - -Species::Species(void) -{ - // initialise demographic parameters - repType = 0; nStages = 2; - stageStruct = false; - propMales = 0.5; harem = 1.0; bc = 1.0; lambda = 1.5; probRep = 1.0; - repSeasons = 1; - repInterval = 0; maxAge = 1000; survival = 1; - fecDens = false; fecStageDens = false; - devDens = false; devStageDens = false; - survDens = false; survStageDens = false; - disperseOnLoss = false; - for (int i = 0; i < NSTAGES; i++) { - for (int j = 0; j < NSEXES; j++) { - fec[i][j] = 0.0; dev[i][j] = 0.0; surv[i][j] = 0.0; - minAge[i][j] = 0; - } - } - devCoeff = survCoeff = 1.0; - ddwtFec = ddwtDev = ddwtSurv = 0; ddwtFecDim = ddwtDevDim = ddwtSurvDim = 0; - habK = 0; habDimK = 0; - minRK = 1.0; maxRK = 2.0; - - // initialise genome attributes - nChromosomes = nTraits = 0; - emigTrait[0] = 0; emigTrait[1] = 0; - movtTrait[0] = 0; movtTrait[1] = 0; - settTrait[0] = 0; settTrait[1] = 0; - diploid = true; - neutralMarkers = false; - pleiotropic = false; - trait1Chromosome = true; - probMutn = 0.0001f; - probCrossover = 0.0001f; - alleleSD = mutationSD = 0.1f; - nNLoci = 0; - nLoci = NULL; - traitdata = NULL; - traitnames = NULL; - nTraitNames = 0; - - // initialise emigration parameters - densDepEmig = false; stgDepEmig = false; sexDepEmig = false; indVarEmig = false; - emigStage = 0; - for (int i = 0; i < NSTAGES; i++) { - for (int j = 0; j < NSEXES; j++) { - d0[i][j] = 0.0; alphaEmig[i][j] = 0.0; betaEmig[i][j] = 1.0; - } - } - for (int j = 0; j < NSEXES; j++) { - d0Mean[0][j] = 0.0; alphaMean[0][j] = 0.0; betaMean[0][j] = 1.0; - d0SD[0][j] = 0.0; alphaSD[0][j] = 0.0; betaSD[0][j] = 1.0; - } - d0Scale = alphaScale = betaScale = 0.0; - - // initialise transfer parameters - moveModel = false; stgDepTrfr = false; sexDepTrfr = false; distMort = false; - indVarTrfr = false; - twinKern = false; - habMort = false; - costMap = false; - moveType = 1; - for (int i = 0; i < NSTAGES; i++) { - for (int j = 0; j < NSEXES; j++) { - meanDist1[i][j] = 100.0f; meanDist2[i][j] = 1000.0f; probKern1[i][j] = 0.99f; - } - } - for (int j = 0; j < NSEXES; j++) { - dist1Mean[0][j] = 100.0; dist1SD[0][j] = 10.0; - dist2Mean[0][j] = 1000.0; dist2SD[0][j] = 100.0; - PKern1Mean[0][j] = 0.9f; PKern1SD[0][j] = 0.01f; - stepLgthMean[0][j] = 10.0; stepLgthSD[0][j] = 1.0; - rhoMean[0][j] = 0.9f; rhoSD[0][j] = 0.01f; - dpMean[0][j] = 1.0; dpSD[0][j] = 0.1f; - gbMean[0][j] = 1.0; gbSD[0][j] = 0.1f; - alphaDBMean[0][j] = 1.0; alphaDBSD[0][j] = 0.1f; - betaDBMean[0][j] = 10.0; betaDBSD[0][j] = 1.0; - } - pr = 1; prMethod = 1; memSize = 1; goalType = 0; - dp = 1.0; gb = 1.0; alphaDB = 1.0; betaDB = 100000; - stepMort = 0.0; stepLength = 10.0; rho = 0.9f; - habStepMort = 0; habCost = 0; - fixedMort = 0.0; mortAlpha = 0.0; mortBeta = 1.0; - dist1Scale = dist2Scale = PKern1Scale = stepLScale = rhoScale = 0.0; - dpScale = 0.1f; gbScale = 0.1f; alphaDBScale = 0.1f; betaDBScale = 1.0; - habDimTrfr = 0; - straigtenPath = false; - fullKernel = false; - - // initialise settlement parameters - stgDepSett = false; sexDepSett = false; indVarSett = false; - - for (int i = 0; i < NSTAGES; i++) { - for (int j = 0; j < NSEXES; j++) { - densDepSett[i][j] = false; wait[i][j] = false; go2nbrLocn[i][j] = false; findMate[i][j] = false; - maxStepsYr[i][j] = 99999999; minSteps[i][j] = 0; maxSteps[i][j] = 99999999; - s0[i][j] = 1.0; alphaS[i][j] = 0.0; betaS[i][j] = 1.0; - } - } - for (int j = 0; j < NSEXES; j++) { - alphaSMean[0][j] = 0.0; alphaSSD[0][j] = 0.0; - betaSMean[0][j] = 0.0; betaSSD[0][j] = 0.0; - s0Mean[0][j] = 0.0; s0SD[0][j] = 0.0; - } - alphaSScale = 0.0; betaSScale = 0.0; s0Scale = 0.0; - - // initialise attributes - spNum = 0; - -} - -Species::~Species() { - // demographic parameters - if (habK != NULL) deleteHabK(); - if (ddwtFec != 0) deleteDDwtFec(); - if (ddwtDev != 0) deleteDDwtDev(); - if (ddwtSurv != 0) deleteDDwtSurv(); - // transfer parameters - if (habCost != 0 || habStepMort != 0) deleteHabCostMort(); - if (nLoci != NULL) deleteLoci(); - if (traitdata != NULL) deleteTraitData(); - if (traitnames != NULL) deleteTraitNames(); -} - -short Species::getSpNum(void) { return spNum; } - -//--------------------------------------------------------------------------- - -// Demographic functions - -void Species::setDemogr(const demogrParams d) { - if (d.repType >= 0 && d.repType <= 2) repType = d.repType; - if (d.repSeasons >= 1) repSeasons = d.repSeasons; - stageStruct = d.stageStruct; - if (d.propMales > 0.0 && d.propMales < 1.0) propMales = d.propMales; - if (d.harem > 0.0) harem = d.harem; - if (d.bc > 0.0) bc = d.bc; - if (d.lambda > 0.0) lambda = d.lambda; -} - -demogrParams Species::getDemogr(void) { - demogrParams d; - d.repType = repType; - d.repSeasons = repSeasons; - d.stageStruct = stageStruct; - d.propMales = propMales; - d.harem = harem; - d.bc = bc; - d.lambda = lambda; - return d; -} - -short Species::getRepType(void) { return repType; } - -bool Species::stageStructured(void) { return stageStruct; } - -void Species::createHabK(short nhab) { - if (nhab >= 0) { - habDimK = nhab; - if (habK != 0) deleteHabK(); - habK = new float[nhab]; - for (int i = 0; i < nhab; i++) habK[i] = 0.0; - } -} - -void Species::setHabK(short hx, float k) { - if (hx >= 0 && hx < habDimK) { - if (k >= 0.0) habK[hx] = k; - } -} - -float Species::getHabK(short hx) { - float k = 0.0; - if (hx >= 0 && hx < habDimK) k = habK[hx]; - return k; -} - -float Species::getMaxK(void) { - float k = 0.0; - for (int i = 0; i < habDimK; i++) { - if (habK[i] > k) k = habK[i]; - } - return k; -} - -void Species::deleteHabK(void) { - if (habK != 0) { - delete[] habK; habK = 0; - } -} - -void Species::setStage(const stageParams s) { - if (s.nStages > 1) nStages = s.nStages; - if (s.repInterval >= 0) repInterval = s.repInterval; - if (s.maxAge >= 1) maxAge = s.maxAge; - if (s.survival >= 0 && s.survival <= 2) survival = s.survival; - if (s.probRep > 0.0 && s.probRep <= 1.0) probRep = s.probRep; - fecDens = s.fecDens; fecStageDens = s.fecStageDens; - devDens = s.devDens; devStageDens = s.devStageDens; - survDens = s.survDens; survStageDens = s.survStageDens; - disperseOnLoss = s.disperseOnLoss; -} - -stageParams Species::getStage(void) { - stageParams s; - s.nStages = nStages; s.repInterval = repInterval; s.maxAge = maxAge; - s.survival = survival; s.probRep = probRep; - s.fecDens = fecDens; s.fecStageDens = fecStageDens; - s.devDens = devDens; s.devStageDens = devStageDens; - s.survDens = survDens; s.survStageDens = survStageDens; - s.disperseOnLoss = disperseOnLoss; - return s; -} - -void Species::setFec(short stg, short sex, float f) { - // NB fecundity for stage 0 must always be zero - if (stg > 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES && f >= 0) - fec[stg][sex] = f; -} - -float Species::getFec(short stg, short sex) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) - return fec[stg][sex]; - else return 0.0; -} - -float Species::getMaxFec(void) { - float maxfec = 0.0; - if (stageStruct) { - for (int stg = 1; stg < NSTAGES; stg++) { - if (fec[stg][0] > maxfec) maxfec = fec[stg][0]; - } - } - else maxfec = lambda; - return maxfec; -} - -void Species::setDev(short stg, short sex, float d) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES && d >= 0) - dev[stg][sex] = d; -} - -float Species::getDev(short stg, short sex) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) - return dev[stg][sex]; - else return 0.0; -} - -void Species::setSurv(short stg, short sex, float s) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES && s >= 0) - surv[stg][sex] = s; -} - -float Species::getSurv(short stg, short sex) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) - return surv[stg][sex]; - else return 0.0; -} - -void Species::setMinAge(short stg, short sex, int age) { - // NB min age for stages 0 & 1 must always be zero - if (stg > 1 && stg < NSTAGES && sex >= 0 && sex < NSEXES && age >= 0) - minAge[stg][sex] = age; -} - -short Species::getMinAge(short stg, short sex) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) - return minAge[stg][sex]; - else return 0; -} - -void Species::setDensDep(float d, float s) { - if (d > 0.0) devCoeff = d; - if (s > 0.0) survCoeff = s; -} - -densDepParams Species::getDensDep(void) { - densDepParams d; - d.devCoeff = devCoeff; d.survCoeff = survCoeff; - return d; -} - -void Species::createDDwtFec(short mSize) { - if (mSize >= 0 && mSize < (NSTAGES * NSEXES)) { - if (ddwtFec != 0) deleteDDwtFec(); - ddwtFecDim = mSize; - ddwtFec = new float* [mSize]; - for (int i = 0; i < mSize; i++) { - ddwtFec[i] = new float[mSize]; - for (int j = 0; j < mSize; j++) ddwtFec[i][j] = 1.0; - } - } -} - -void Species::setDDwtFec(short row, short col, float f) { - if (row >= 0 && row < ddwtFecDim && col >= 0 && col < ddwtFecDim) - ddwtFec[row][col] = f; -} - -float Species::getDDwtFec(short row, short col) { - if (row >= 0 && row < ddwtFecDim && col >= 0 && col < ddwtFecDim) - return ddwtFec[row][col]; - else return 0.0; -} - -void Species::deleteDDwtFec(void) { - if (ddwtFec != 0) { - for (int i = 0; i < ddwtFecDim; i++) if (ddwtFec[i] != 0) { - delete[] ddwtFec[i]; - } - delete[] ddwtFec; ddwtFec = 0; - } -} - -void Species::createDDwtDev(short mSize) { - if (mSize >= 0 && mSize < (NSTAGES * NSEXES)) { - if (ddwtDev != 0) deleteDDwtDev(); - ddwtDevDim = mSize; - ddwtDev = new float* [mSize]; - for (int i = 0; i < mSize; i++) { - ddwtDev[i] = new float[mSize]; - for (int j = 0; j < mSize; j++) ddwtDev[i][j] = 1.0; - } - } -} - -void Species::setDDwtDev(short row, short col, float f) { - if (row >= 0 && row < ddwtDevDim && col >= 0 && col < ddwtDevDim) - ddwtDev[row][col] = f; -} - -float Species::getDDwtDev(short row, short col) { - if (row >= 0 && row < ddwtDevDim && col >= 0 && col < ddwtDevDim) - return ddwtDev[row][col]; - else return 0.0; -} - -void Species::deleteDDwtDev(void) { - if (ddwtDev != 0) { - for (int i = 0; i < ddwtDevDim; i++) if (ddwtDev[i] != 0) { - delete[] ddwtDev[i]; - } - delete[] ddwtDev; ddwtDev = 0; - } -} - -void Species::createDDwtSurv(short mSize) { - if (mSize >= 0 && mSize < (NSTAGES * NSEXES)) { - if (ddwtSurv != 0) deleteDDwtSurv(); - ddwtSurvDim = mSize; - ddwtSurv = new float* [mSize]; - for (int i = 0; i < mSize; i++) { - ddwtSurv[i] = new float[mSize]; - for (int j = 0; j < mSize; j++) ddwtSurv[i][j] = 1.0; - } - } -} - -void Species::setDDwtSurv(short row, short col, float f) { - if (row >= 0 && row < ddwtSurvDim && col >= 0 && col < ddwtSurvDim) - ddwtSurv[row][col] = f; -} - -float Species::getDDwtSurv(short row, short col) { - if (row >= 0 && row < ddwtSurvDim && col >= 0 && col < ddwtSurvDim) - return ddwtSurv[row][col]; - else return 0.0; -} - -void Species::deleteDDwtSurv(void) { - if (ddwtSurv != 0) { - for (int i = 0; i < ddwtSurvDim; i++) if (ddwtSurv[i] != 0) { - delete[] ddwtSurv[i]; - } - delete[] ddwtSurv; ddwtSurv = 0; - } -} - -// Functions to handle min/max R or K (under environmental stochasticity) -void Species::setMinMax(float min, float max) { - if (min >= 0.0 && max > min) { - minRK = min; maxRK = max; - } -} -float Species::getMinMax(short opt) { - if (opt == 0) return minRK; - else return maxRK; -} - -//--------------------------------------------------------------------------- - -// Genome functions - -void Species::setGenomeData(genomeData d) { - diploid = d.diploid; - neutralMarkers = d.neutralMarkers; - trait1Chromosome = d.trait1Chromosome; - if (trait1Chromosome) { - if (d.nLoci > 0) nLoci[0] = d.nLoci; - } - if (d.probMutn >= 0.0 && d.probMutn <= 1.0) probMutn = d.probMutn; - if (d.probCrossover >= 0.0 && d.probCrossover <= 1.0) probCrossover = d.probCrossover; - if (d.alleleSD > 0.0) alleleSD = d.alleleSD; - if (d.mutationSD > 0.0) mutationSD = d.mutationSD; -} - -genomeData Species::getGenomeData(void) { - genomeData d; - d.diploid = diploid; - d.neutralMarkers = neutralMarkers; - d.pleiotropic = pleiotropic; - d.trait1Chromosome = trait1Chromosome; - if (nLoci != NULL) d.nLoci = nLoci[0]; - else d.nLoci = 0; - d.probMutn = probMutn; - d.probCrossover = probCrossover; - d.alleleSD = alleleSD; - d.mutationSD = mutationSD; - return d; -} - -bool Species::isDiploid(void) { return diploid; } - -// Chromosome functions - -void Species::setNChromosomes(int c) { - if (nLoci != NULL) deleteLoci(); - if (c > 0) { - nChromosomes = nNLoci = c; - nLoci = new short[c]; - for (int i = 0; i < nNLoci; i++) nLoci[i] = 0; - } - else nChromosomes = nNLoci = 0; -} - -int Species::getNChromosomes(void) { return nChromosomes; } - -void Species::setNLoci(const short chr, const short nloc) { - if (chr >= 0 && chr < nNLoci) { - if (nloc > 0) nLoci[chr] = nloc; - else nLoci[chr] = 0; - } -} - -int Species::getNLoci(const short chr) { - if (chr >= 0 && chr < nChromosomes) return nLoci[chr]; - else return 0; -} - -void Species::deleteLoci(void) { - if (nLoci != NULL) { delete[] nLoci; nLoci = NULL; } -} - -// Trait functions - -// Set 1:1 mapping of trait to chromosome -void Species::set1ChromPerTrait(const int nloc) { - nChromosomes = nTraits; - if (nLoci != NULL) deleteLoci(); - nLoci = new short[1]; - if (nloc > 0) nLoci[0] = nloc; - else nLoci[0] = 1; -} - -bool Species::has1ChromPerTrait(void) { return trait1Chromosome; } - -// Set trait attributes for the species -void Species::setTraits(void) { - - emigTrait[0] = 0; emigTrait[1] = 0; - movtTrait[0] = 0; movtTrait[1] = 0; - settTrait[0] = 0; settTrait[1] = 0; - nTraits = 0; -#if RSDEBUG - DebugGUI("Species::setTraits(): 0000 nChromosomes=" + Int2Str(nChromosomes) - + " nTraits=" + Int2Str(nTraits) - + " indVarEmig=" + Int2Str((int)indVarEmig) - + " indVarTrfr=" + Int2Str((int)indVarTrfr) - + " indVarSett=" + Int2Str((int)indVarSett) - ); -#endif - - if (indVarEmig) { - if (sexDepEmig) { - if (densDepEmig) nTraits += 6; else nTraits += 2; - } - else { - if (densDepEmig) nTraits += 3; else nTraits += 1; - } - emigTrait[0] = 0; emigTrait[1] = nTraits; - } - - int movttraits = 0; - if (indVarTrfr) { - if (moveModel) { - if (moveType == 1) { // SMS - movttraits = 1; // in contain batch 2 - if (goalType == 2) movttraits += 3; //in contain batch 2 - } - if (moveType == 2) movttraits = 2; - } - else { - if (sexDepTrfr) { - if (twinKern) movttraits = 6; else movttraits = 2; - } - else { - if (twinKern) movttraits = 3; else movttraits = 1; - } - } - movtTrait[0] = nTraits; movtTrait[1] = movttraits; - nTraits += movttraits; - } - - int setttraits = 0; - if (indVarSett) { - if (sexDepSett) setttraits = 6; else setttraits = 3; - settTrait[0] = nTraits; settTrait[1] = setttraits; - nTraits += setttraits; - } - - setTraitNames(); - -#if RSDEBUG - DebugGUI("Species::setTraits(): 9999 nChromosomes=" + Int2Str(nChromosomes) - + " nTraits=" + Int2Str(nTraits)); -#endif - -} - -void Species::setTraitNames(void) { - deleteTraitNames(); - nTraitNames = nTraits; - traitnames = new string[nTraitNames]; - int trait = 0; - if (indVarEmig) { - if (sexDepEmig) { - if (densDepEmig) { - traitnames[trait++] = "d0_F"; - traitnames[trait++] = "d0_M"; - traitnames[trait++] = "alpha_F"; - traitnames[trait++] = "alpha_M"; - traitnames[trait++] = "beta_F"; - traitnames[trait++] = "beta_M"; - } - else { - traitnames[trait++] = "d0_F"; - traitnames[trait++] = "d0_M"; - } - } - else { - traitnames[trait++] = "d0"; - if (densDepEmig) { - traitnames[trait++] = "alpha"; - traitnames[trait++] = "beta"; - } - } - } - - if (indVarTrfr) { - if (moveModel) { - if (moveType == 1) { // SMS - traitnames[trait++] = "DP"; - if (goalType == 2) { - traitnames[trait++] = "GB"; - traitnames[trait++] = "alphaDB"; - traitnames[trait++] = "betaDB"; - } - } - if (moveType == 2) { // CRW - traitnames[trait++] = "stepL"; - traitnames[trait++] = "rho"; - } - } - else { - if (sexDepTrfr) { - if (twinKern) - { - traitnames[trait++] = "meanDistI_F"; - traitnames[trait++] = "meanDistI_M"; - traitnames[trait++] = "meanDistII_F"; - traitnames[trait++] = "meanDistII_M"; - traitnames[trait++] = "probKernI_F"; - traitnames[trait++] = "probKernI_M"; - } - else { - traitnames[trait++] = "meanDistI_F"; - traitnames[trait++] = "meanDistI_M"; - } - } - else { - traitnames[trait++] = "meanDistI"; - if (twinKern) - { - traitnames[trait++] = "meanDistII"; - traitnames[trait++] = "probKernI"; - } - } - } - } - - if (indVarSett) { - if (sexDepSett) { - traitnames[trait++] = "s0_F"; - traitnames[trait++] = "s0_M"; - traitnames[trait++] = "alphaS_F"; - traitnames[trait++] = "alphaS_M"; - traitnames[trait++] = "betaS_F"; - traitnames[trait++] = "betaS_M"; - } - else { - traitnames[trait++] = "s0"; - traitnames[trait++] = "alphaS"; - traitnames[trait++] = "betaS"; - } - } -} - -void Species::deleteTraitNames(void) { - if (traitnames != NULL) { - delete[] traitnames; - traitnames = NULL; - } -} - -string Species::getTraitName(const int trait) { - string name = "not used"; - if (traitnames != NULL) { - if (trait >= 0 && trait < nTraits) { - name = traitnames[trait]; - } - } - return name; -} - -int Species::getNTraits(void) { return nTraits; } - -void Species::setTraitData(const int ntraits) { - deleteTraitData(); - traitdata = new traitData; - if (ntraits > 0) { - traitdata->nTraitMaps = ntraits; - traitdata->traitmaps = new traitMap * [ntraits]; - for (int i = 0; i < ntraits; i++) { - traitdata->traitmaps[i] = new traitMap; - } - } - else { // neutral markers only - traitdata->nTraitMaps = 0; - } - traitdata->neutralloci = new traitMap; - traitdata->neutralloci->nAlleles = 0; -} - -void Species::deleteTraitData(void) { - if (traitdata != NULL) { - for (int i = 0; i < traitdata->nTraitMaps; i++) { - if (traitdata->traitmaps[i]->traitalleles != 0) { - for (int j = 0; j < traitdata->traitmaps[i]->nAlleles; j++) { - delete traitdata->traitmaps[i]->traitalleles[j]; - } - } - delete[] traitdata->traitmaps[i]; - } - deleteNeutralLoci(); - delete traitdata; - traitdata = NULL; - } -} - -int Species::getNTraitMaps(void) { - if (traitdata == NULL) return 0; - else return traitdata->nTraitMaps; -} - -void Species::setTraitMap(const short trait, const short nalleles) { - traitdata->traitmaps[trait]->nAlleles = nalleles; - traitdata->traitmaps[trait]->traitalleles = new traitAllele * [nalleles]; - for (int i = 0; i < nalleles; i++) { - traitdata->traitmaps[trait]->traitalleles[i] = new traitAllele; - } -} - -int Species::getNTraitAlleles(const int trait) { - int nalleles = 0; - if (traitdata != NULL) { - if (trait >= 0 && trait < traitdata->nTraitMaps) { - nalleles = traitdata->traitmaps[trait]->nAlleles; - } - } - return nalleles; -} - -void Species::setTraitAllele(const short trait, const short allele, - const short chr, const short loc) -{ - traitdata->traitmaps[trait]->traitalleles[allele] = new traitAllele; - if (chr >= 0 && loc >= 0) { - traitdata->traitmaps[trait]->traitalleles[allele]->chromo = chr; - traitdata->traitmaps[trait]->traitalleles[allele]->locus = loc; - } - else { - traitdata->traitmaps[trait]->traitalleles[allele]->chromo = 0; - traitdata->traitmaps[trait]->traitalleles[allele]->locus = 0; - } -} - -traitAllele Species::getTraitAllele(const short trait, const short allele) { - traitAllele a; a.chromo = 0; a.locus = 0; - if (traitdata != NULL) { - if (trait >= 0 && trait < traitdata->nTraitMaps) { - if (allele >= 0 && allele < traitdata->traitmaps[trait]->nAlleles) { - a = *traitdata->traitmaps[trait]->traitalleles[allele]; - } - } - } - return a; -} - -// Neutral loci functions - -// Identify neutral loci and determine whether there is pleiotropy -void Species::setNeutralLoci(bool neutralMarkersOnly) { - bool neutral; - int nneutral = 0; - // find minimum of no. of defined / applied traits - int ntraits; - if (traitdata == 0) ntraits = 0; - else ntraits = traitdata->nTraitMaps; - if (ntraits > nTraits) ntraits = nTraits; - -// determine no. of neutral loci - deleteNeutralLoci(); - for (int i = 0; i < nNLoci; i++) { // each chromosome - for (int j = 0; j < nLoci[i]; j++) { // each locus - neutral = true; - for (int t = 0; t < ntraits; t++) { // each trait - for (int a = 0; a < traitdata->traitmaps[t]->nAlleles; a++) { - if (i == traitdata->traitmaps[t]->traitalleles[a]->chromo - && j == traitdata->traitmaps[t]->traitalleles[a]->locus) { - neutral = false; // as locus contributes to a trait - a = 999999; - } - } - if (!neutral) t = 999999; - } - if (neutral) nneutral++; - } - } - - traitdata->neutralloci = new traitMap; - traitdata->neutralloci->nAlleles = nneutral; - if (nneutral < 1) return; - - // record neutral markers - traitdata->neutralloci->traitalleles = new traitAllele * [nneutral]; - nneutral = 0; - for (int i = 0; i < nNLoci; i++) { // each chromosome - for (int j = 0; j < nLoci[i]; j++) { // each locus - neutral = true; - for (int t = 0; t < ntraits; t++) { // each trait - for (int a = 0; a < traitdata->traitmaps[t]->nAlleles; a++) { - if (i == traitdata->traitmaps[t]->traitalleles[a]->chromo - && j == traitdata->traitmaps[t]->traitalleles[a]->locus) { - neutral = false; // as locus contributes to a trait - a = 999999; - } - } - if (!neutral) t = 999999; - } - if (neutral) { - traitdata->neutralloci->traitalleles[nneutral] = new traitAllele; - traitdata->neutralloci->traitalleles[nneutral]->chromo = i; - traitdata->neutralloci->traitalleles[nneutral]->locus = j; - nneutral++; - } - } - } - - pleiotropic = false; - if (neutralMarkersOnly) return; // pleiotropy cannot apply - - // determine whether there is pleiotropy - int chr, loc; - int nloci = 0; // maximum no. of loci on any one chromosome - for (int i = 0; i < nNLoci; i++) { - if (nloci < nLoci[i]) nloci = nLoci[i]; - } - int*** locfreq; - locfreq = new int** [nNLoci]; - for (int i = 0; i < nNLoci; i++) { - locfreq[i] = new int* [nloci]; - for (int j = 0; j < nloci; j++) { - locfreq[i][j] = new int[ntraits]; - for (int t = 0; t < ntraits; t++) locfreq[i][j][t] = 0; - } - } - for (int t = 0; t < ntraits; t++) { // each trait - for (int a = 0; a < traitdata->traitmaps[t]->nAlleles; a++) { - chr = traitdata->traitmaps[t]->traitalleles[a]->chromo; - loc = traitdata->traitmaps[t]->traitalleles[a]->locus; - locfreq[chr][loc][t]++; - } - } - for (int i = 0; i < nNLoci; i++) { - for (int j = 0; j < nloci; j++) { - // remove multiple contributions of a locus to a particular trait - // (i.e. prevent recording of pseudo-pleiotropy) - for (int t = 0; t < ntraits; t++) { - if (locfreq[i][j][t] > 0) locfreq[i][j][t] = 1; - } - // sum at level of chromosome/locus - for (int t = 1; t < ntraits; t++) { - locfreq[i][j][0] += locfreq[i][j][t]; - } - if (locfreq[i][j][0] > 1) pleiotropic = true; - } - } - for (int i = 0; i < nNLoci; i++) { - for (int j = 0; j < nloci; j++) { - delete[] locfreq[i][j]; - } - delete[] locfreq[i]; - } - delete[] locfreq; - -} - -void Species::deleteNeutralLoci(void) { - if (traitdata->neutralloci != NULL) { - for (int i = 0; i < traitdata->neutralloci->nAlleles; i++) { - delete traitdata->neutralloci->traitalleles[i]; - } - delete[] traitdata->neutralloci; - } - traitdata->neutralloci = NULL; -} - -int Species::getNNeutralLoci(void) { - int nn = 0; - if (traitdata != NULL) { - if (traitdata->neutralloci != NULL) { - nn = traitdata->neutralloci->nAlleles; - } - } - return nn; -} - -traitAllele Species::getNeutralAllele(const short allele) { - traitAllele a; a.chromo = 0; a.locus = 0; - if (traitdata != NULL) { - if (allele >= 0 && allele < traitdata->neutralloci->nAlleles) { - a = *traitdata->neutralloci->traitalleles[allele]; - } - } - return a; -} - -//--------------------------------------------------------------------------- - -// Emigration functions - -void Species::setEmig(const emigRules e) { - densDepEmig = e.densDep; stgDepEmig = e.stgDep; sexDepEmig = e.sexDep; - indVarEmig = e.indVar; - if (e.emigStage >= 0) emigStage = e.emigStage; -} - -emigRules Species::getEmig(void) { - emigRules e; - e.densDep = densDepEmig; e.stgDep = stgDepEmig; e.sexDep = sexDepEmig; - e.indVar = indVarEmig; e.emigStage = emigStage; - e.emigTrait[0] = emigTrait[0]; e.emigTrait[1] = emigTrait[1]; - return e; -} - -void Species::setEmigTraits(const short stg, const short sex, const emigTraits e) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - if (e.d0 >= 0.0 && e.d0 <= 1.0) d0[stg][sex] = e.d0; - alphaEmig[stg][sex] = e.alpha; betaEmig[stg][sex] = e.beta; - } -} - -emigTraits Species::getEmigTraits(short stg, short sex) { - emigTraits e; - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - e.d0 = d0[stg][sex]; e.alpha = alphaEmig[stg][sex]; e.beta = betaEmig[stg][sex]; - } - else { - e.d0 = e.alpha = e.beta = 0.0; - } - return e; -} - -float Species::getEmigD0(short stg, short sex) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - return d0[stg][sex]; - } - else { - return 0.0; - } -} - -void Species::setEmigParams(const short stg, const short sex, const emigParams e) { - if (stg >= 0 && stg < 1 && sex >= 0 && sex < NSEXES) // implemented for stage 0 only - { - if (e.d0Mean >= 0.0 && e.d0Mean < 1.0) d0Mean[stg][sex] = e.d0Mean; - if (e.d0SD > 0.0 && e.d0SD < 1.0) d0SD[stg][sex] = e.d0SD; - alphaMean[stg][sex] = e.alphaMean; - if (e.alphaSD > 0.0) alphaSD[stg][sex] = e.alphaSD; - betaMean[stg][sex] = e.betaMean; - if (e.betaSD > 0.0) betaSD[stg][sex] = e.betaSD; - } -} - -emigParams Species::getEmigParams(short stg, short sex) { - emigParams e; - if (stg >= 0 && stg < 1 && sex >= 0 && sex < NSEXES) // implemented for stage 0 only - { - e.d0Mean = d0Mean[stg][sex]; e.d0SD = d0SD[stg][sex]; - e.d0Scale = d0Scale; - e.alphaMean = alphaMean[stg][sex]; e.alphaSD = alphaSD[stg][sex]; - e.alphaScale = alphaScale; - e.betaMean = betaMean[stg][sex]; e.betaSD = betaSD[stg][sex]; - e.betaScale = betaScale; - } - else { - e.d0Mean = e.alphaMean = e.betaMean = e.d0SD = e.alphaSD = e.betaSD = 0.0; - e.d0Scale = d0Scale; - e.alphaScale = alphaScale; - e.betaScale = betaScale; - } - return e; -} - -void Species::setEmigScales(const emigScales s) { - if (s.d0Scale >= 0.0 && s.d0Scale < 1.0) d0Scale = s.d0Scale; - if (s.alphaScale >= 0.0) alphaScale = s.alphaScale; - if (s.betaScale >= 0.0) betaScale = s.betaScale; -} - -emigScales Species::getEmigScales(void) { - emigScales s; - s.d0Scale = d0Scale; s.alphaScale = alphaScale; s.betaScale = betaScale; - return s; -} - -//--------------------------------------------------------------------------- - -// Transfer functions - -void Species::setTrfr(const trfrRules t) { - moveModel = t.moveModel; stgDepTrfr = t.stgDep; sexDepTrfr = t.sexDep; - distMort = t.distMort; indVarTrfr = t.indVar; - twinKern = t.twinKern; - habMort = t.habMort; - moveType = t.moveType; costMap = t.costMap; -} - -trfrRules Species::getTrfr(void) { - trfrRules t; - t.moveModel = moveModel; t.stgDep = stgDepTrfr; t.sexDep = sexDepTrfr; - t.distMort = distMort; t.indVar = indVarTrfr; - t.twinKern = twinKern; - t.habMort = habMort; - t.moveType = moveType; t.costMap = costMap; - t.movtTrait[0] = movtTrait[0]; t.movtTrait[1] = movtTrait[1]; - return t; -} - -void Species::setFullKernel(bool k) { - fullKernel = k; -} - -bool Species::useFullKernel(void) { return fullKernel; } - -void Species::setKernTraits(const short stg, const short sex, - const trfrKernTraits k, const int resol) -{ - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - if (k.meanDist1 > 0.0 && k.meanDist1 >= (float)resol) meanDist1[stg][sex] = k.meanDist1; - if (k.meanDist2 >= (float)resol) meanDist2[stg][sex] = k.meanDist2; - if (k.probKern1 > 0.0 && k.probKern1 < 1.0) probKern1[stg][sex] = k.probKern1; - } -} - -trfrKernTraits Species::getKernTraits(short stg, short sex) { - trfrKernTraits k; - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - k.meanDist1 = meanDist1[stg][sex]; - k.meanDist2 = meanDist2[stg][sex]; - k.probKern1 = probKern1[stg][sex]; - } - else { - k.meanDist1 = 0.0; k.meanDist2 = 0.0; k.probKern1 = 1.0; - } - return k; -} - -void Species::setMortParams(const trfrMortParams m) { - if (m.fixedMort >= 0.0 && m.fixedMort < 1.0) fixedMort = m.fixedMort; - mortAlpha = m.mortAlpha; - mortBeta = m.mortBeta; -} - -trfrMortParams Species::getMortParams(void) { - trfrMortParams m; - m.fixedMort = fixedMort; m.mortAlpha = mortAlpha; m.mortBeta = mortBeta; - return m; -} - -void Species::setMovtTraits(const trfrMovtTraits m) { - if (m.pr >= 1) pr = m.pr; - if (m.prMethod >= 1 && m.prMethod <= 3) prMethod = m.prMethod; - if (m.memSize >= 1 && m.memSize <= 14) memSize = m.memSize; - if (m.goalType >= 0 && m.goalType <= 2) goalType = m.goalType; - if (m.dp >= 1.0) dp = m.dp; - if (m.gb >= 1.0) gb = m.gb; - if (m.alphaDB > 0.0) alphaDB = m.alphaDB; - if (m.betaDB > 0) betaDB = m.betaDB; - if (m.stepMort >= 0.0 && m.stepMort < 1.0) stepMort = m.stepMort; - if (m.stepLength > 0.0) stepLength = m.stepLength; - if (m.rho > 0.0 && m.rho < 1.0) rho = m.rho; - straigtenPath = m.straigtenPath; -} - -trfrMovtTraits Species::getMovtTraits(void) { - trfrMovtTraits m; - m.pr = pr; m.prMethod = prMethod; m.memSize = memSize; m.goalType = goalType; - m.dp = dp; m.gb = gb; m.alphaDB = alphaDB; m.betaDB = betaDB; - m.stepMort = stepMort; m.stepLength = stepLength; m.rho = rho; - return m; -} - -trfrCRWTraits Species::getCRWTraits(void) { - trfrCRWTraits m; - m.stepMort = stepMort; m.stepLength = stepLength; m.rho = rho; - m.straigtenPath = straigtenPath; - return m; -} - -trfrSMSTraits Species::getSMSTraits(void) { - trfrSMSTraits m; - m.pr = pr; m.prMethod = prMethod; m.memSize = memSize; m.goalType = goalType; - m.dp = dp; m.gb = gb; m.alphaDB = alphaDB; m.betaDB = betaDB; m.stepMort = stepMort; - m.straigtenPath = straigtenPath; - return m; -} - -void Species::setKernParams(const short stg, const short sex, - const trfrKernParams k, const double resol) -{ - if (stg >= 0 && stg < 1 && sex >= 0 && sex < NSEXES) // implemented for stage 0 only - { - if (k.dist1Mean > 0.0 && k.dist1Mean >= resol && k.dist1SD > 0.0) { - dist1Mean[stg][sex] = k.dist1Mean; dist1SD[stg][sex] = k.dist1SD; - } - if (k.dist2Mean > 0.0 && k.dist2Mean >= resol && k.dist2SD > 0.0) { - dist2Mean[stg][sex] = k.dist2Mean; dist2SD[stg][sex] = k.dist2SD; - } - if (k.PKern1Mean > 0.0 && k.PKern1Mean < 1.0 && k.PKern1SD > 0.0 && k.PKern1SD < 1.0) { - PKern1Mean[stg][sex] = k.PKern1Mean; PKern1SD[stg][sex] = k.PKern1SD; - } - } -} - -trfrKernParams Species::getKernParams(short stg, short sex) { - trfrKernParams k; - if (stg >= 0 && stg < 1 && sex >= 0 && sex < NSEXES) // implemented for stage 0 only - { - k.dist1Mean = dist1Mean[stg][sex]; k.dist1SD = dist1SD[stg][sex]; - k.dist2Mean = dist2Mean[stg][sex]; k.dist2SD = dist2SD[stg][sex]; - k.PKern1Mean = PKern1Mean[stg][sex]; k.PKern1SD = PKern1SD[stg][sex]; - k.dist1Scale = dist1Scale; k.dist2Scale = dist2Scale; k.PKern1Scale = PKern1Scale; - } - else { - k.dist1Mean = 100000.0; k.dist1SD = 0.001f; k.dist1Scale = 1.0; - k.dist2Mean = 100000.0; k.dist2SD = 0.001f; k.dist2Scale = 1.0; - k.PKern1Mean = 0.5; k.PKern1SD = 0.1f; k.PKern1Scale = 0.1f; - } - return k; -} - -void Species::setSMSParams(const short stg, const short sex, const trfrSMSParams s) { - if (stg >= 0 && stg < 1 && sex >= 0 && sex < 1) // implemented for stage 0 & sex 0 only - { - if (s.dpMean >= 1.0 && s.dpSD > 0.0) { - dpMean[stg][sex] = s.dpMean; dpSD[stg][sex] = s.dpSD; - } - if (s.gbMean >= 1.0 && s.gbSD > 0.0) { - gbMean[stg][sex] = s.gbMean; gbSD[stg][sex] = s.gbSD; - } - if (s.alphaDBMean > 0.0 && s.alphaDBSD > 0.0) { - alphaDBMean[stg][sex] = s.alphaDBMean; alphaDBSD[stg][sex] = s.alphaDBSD; - } - if (s.betaDBMean >= 1.0 && s.betaDBSD > 0.0) { - betaDBMean[stg][sex] = s.betaDBMean; betaDBSD[stg][sex] = s.betaDBSD; - } - } -} - -trfrSMSParams Species::getSMSParams(short stg, short sex) { - trfrSMSParams s; - if (stg >= 0 && stg < 1 && sex >= 0 && sex < 1) // implemented for stage 0 & sex 0 only - { - s.dpMean = dpMean[stg][sex]; s.dpSD = dpSD[stg][sex]; - s.gbMean = gbMean[stg][sex]; s.gbSD = gbSD[stg][sex]; - s.alphaDBMean = alphaDBMean[stg][sex]; s.alphaDBSD = alphaDBSD[stg][sex]; - s.betaDBMean = betaDBMean[stg][sex]; s.betaDBSD = betaDBSD[stg][sex]; - s.dpScale = dpScale; s.gbScale = gbScale; - s.alphaDBScale = alphaDBScale; s.betaDBScale = betaDBScale; - } - else { - s.dpMean = 1.0; s.dpSD = 0.1f; s.dpScale = 0.1f; - s.gbMean = 1.0; s.gbSD = 0.1f; s.gbScale = 0.1f; - s.alphaDBMean = 1.0; s.alphaDBSD = 0.1f; s.alphaDBScale = 0.1f; - s.betaDBMean = 10.0; s.betaDBSD = 1.0; s.betaDBScale = 1.0; - } - return s; -} - -void Species::setCRWParams(const short stg, const short sex, const trfrCRWParams m) { - if (stg >= 0 && stg < 1 && sex >= 0 && sex < 1) // implemented for stage 0 & sex 0 only - { - if (m.stepLgthMean > 0.0 && m.stepLgthSD > 0.0) { - stepLgthMean[stg][sex] = m.stepLgthMean; stepLgthSD[stg][sex] = m.stepLgthSD; - } - if (m.rhoMean > 0.0 && m.rhoMean < 1.0 && m.rhoSD > 0.0 && m.rhoSD < 1.0) { - rhoMean[stg][sex] = m.rhoMean; rhoSD[stg][sex] = m.rhoSD; - } - } -} - -trfrCRWParams Species::getCRWParams(short stg, short sex) { - trfrCRWParams m; - if (stg >= 0 && stg < 1 && sex >= 0 && sex < 1) // implemented for stage 0 & sex 0 only - { - m.stepLgthMean = stepLgthMean[stg][sex]; m.stepLgthSD = stepLgthSD[stg][sex]; - m.rhoMean = rhoMean[stg][sex]; m.rhoSD = rhoSD[stg][sex]; - m.stepLScale = stepLScale; m.rhoScale = rhoScale; - } - else { - m.stepLgthMean = 1.0; m.stepLgthSD = 0.1f; m.stepLScale = 0.1f; - m.rhoMean = 0.5; m.rhoSD = 0.1f; m.rhoScale = 0.1f; - } - return m; -} - -void Species::setTrfrScales(const trfrScales s) { - if (s.dist1Scale >= 0.0) dist1Scale = s.dist1Scale; - if (s.dist2Scale >= 0.0) dist2Scale = s.dist2Scale; - if (s.PKern1Scale > 0.0 && s.PKern1Scale < 1.0) PKern1Scale = s.PKern1Scale; - if (s.dpScale > 0.0) dpScale = s.dpScale; - if (s.gbScale > 0.0) gbScale = s.gbScale; - if (s.alphaDBScale > 0.0) alphaDBScale = s.alphaDBScale; - if (s.betaDBScale > 0.0) betaDBScale = s.betaDBScale; - if (s.stepLScale > 0.0) stepLScale = s.stepLScale; - if (s.rhoScale > 0.0 && s.rhoScale < 1.0) rhoScale = s.rhoScale; -} - -trfrScales Species::getTrfrScales(void) { - trfrScales s; - s.dist1Scale = dist1Scale; s.dist2Scale = dist2Scale; s.PKern1Scale = PKern1Scale; - s.dpScale = dpScale; s.gbScale = gbScale; - s.alphaDBScale = alphaDBScale; s.betaDBScale = betaDBScale; - s.stepLScale = stepLScale; s.rhoScale = rhoScale; - return s; -} - -short Species::getMovtHabDim() { return habDimTrfr; } - -void Species::createHabCostMort(short nhab) { - if (nhab >= 0) { - habDimTrfr = nhab; - if (habCost != 0 || habStepMort != 0) deleteHabCostMort(); - habCost = new int[nhab]; - habStepMort = new double[nhab]; - for (int i = 0; i < nhab; i++) { - habCost[i] = 1; habStepMort[i] = 0.0; - } - } -} - -void Species::setHabCost(short hab, int cost) { - if (hab >= 0 && hab < habDimTrfr) { - if (cost >= 1) habCost[hab] = cost; - } -} - -void Species::setHabMort(short hab, double mort) { - if (hab >= 0 && hab < habDimTrfr) { - if (mort >= 0.0 && mort < 1.0) habStepMort[hab] = mort; - } -} - -int Species::getHabCost(short hab) { - int cost = 0; - if (hab >= 0 && hab < habDimTrfr) cost = habCost[hab]; - return cost; -} - -double Species::getHabMort(short hab) { - double pmort = 0.0; - if (hab >= 0 && hab < habDimTrfr) pmort = habStepMort[hab]; - return pmort; -} - -void Species::deleteHabCostMort(void) { - if (habCost != 0) { - delete[] habCost; habCost = 0; - } - if (habStepMort != 0) { - delete[] habStepMort; habStepMort = 0; - } -} - -//--------------------------------------------------------------------------- - -// Settlement functions - -void Species::setSettle(const settleType s) { - stgDepSett = s.stgDep; sexDepSett = s.sexDep; indVarSett = s.indVar; -} - -settleType Species::getSettle(void) { - settleType s; - s.stgDep = stgDepSett; s.sexDep = sexDepSett; s.indVar = indVarSett; - s.settTrait[0] = settTrait[0]; s.settTrait[1] = settTrait[1]; - return s; -} - -void Species::setSettRules(const short stg, const short sex, const settleRules s) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - densDepSett[stg][sex] = s.densDep; wait[stg][sex] = s.wait; - go2nbrLocn[stg][sex] = s.go2nbrLocn; findMate[stg][sex] = s.findMate; - } -} - -settleRules Species::getSettRules(short stg, short sex) { - settleRules s; - s.densDep = false; - s.findMate = false; - s.go2nbrLocn = false; - s.wait = false; - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - s.densDep = densDepSett[stg][sex]; s.wait = wait[stg][sex]; - s.go2nbrLocn = go2nbrLocn[stg][sex]; s.findMate = findMate[stg][sex]; - } - return s; -} - -void Species::setSteps(const short stg, const short sex, const settleSteps s) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - if (s.maxStepsYr >= 1) maxStepsYr[stg][sex] = s.maxStepsYr; - else maxStepsYr[stg][sex] = 99999999; - if (s.minSteps >= 0) minSteps[stg][sex] = s.minSteps; - else minSteps[stg][sex] = 0; - if (s.maxSteps >= 1) maxSteps[stg][sex] = s.maxSteps; - else maxSteps[stg][sex] = 99999999; - } -} - -settleSteps Species::getSteps(short stg, short sex) { - settleSteps s; - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - s.maxStepsYr = maxStepsYr[stg][sex]; - s.minSteps = minSteps[stg][sex]; - s.maxSteps = maxSteps[stg][sex]; - } - else { - s.maxStepsYr = 99999999; - s.minSteps = 0; - s.maxSteps = 99999999; - } - return s; -} - -void Species::setSettTraits(const short stg, const short sex, const settleTraits dd) { - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - if (dd.s0 > 0.0 && dd.s0 <= 1.0) s0[stg][sex] = dd.s0; - alphaS[stg][sex] = dd.alpha; betaS[stg][sex] = dd.beta; - } -} - -settleTraits Species::getSettTraits(short stg, short sex) { - settleTraits dd; - if (stg >= 0 && stg < NSTAGES && sex >= 0 && sex < NSEXES) { - dd.s0 = s0[stg][sex]; dd.alpha = alphaS[stg][sex]; dd.beta = betaS[stg][sex]; - } - else { dd.s0 = 1.0; dd.alpha = dd.beta = 0.0; } - return dd; -} - -void Species::setSettParams(const short stg, const short sex, const settParams s) { - if (stg >= 0 && stg < 1 && sex >= 0 && sex < NSEXES) // implemented for stage 0 only - { - if (s.s0Mean >= 0.0 && s.s0Mean < 1.0) s0Mean[stg][sex] = s.s0Mean; - if (s.s0SD > 0.0 && s.s0SD < 1.0) s0SD[stg][sex] = s.s0SD; - alphaSMean[stg][sex] = s.alphaSMean; - if (s.alphaSSD > 0.0) alphaSSD[stg][sex] = s.alphaSSD; - betaSMean[stg][sex] = s.betaSMean; - if (s.betaSSD > 0.0) betaSSD[stg][sex] = s.betaSSD; - if (sex == 0) { - if (s.s0Scale > 0.0 && s.s0Scale < 1.0) s0Scale = s.s0Scale; - if (s.alphaSScale > 0.0) alphaSScale = s.alphaSScale; - if (s.betaSScale > 0.0) betaSScale = s.betaSScale; - } - } -} - -settParams Species::getSettParams(short stg, short sex) { - settParams s; - if (stg >= 0 && stg < 1 && sex >= 0 && sex < NSEXES) // implemented for stage 0 only - { - s.s0Mean = s0Mean[stg][sex]; s.s0SD = s0SD[stg][sex]; - s.alphaSMean = alphaSMean[stg][sex]; s.alphaSSD = alphaSSD[stg][sex]; - s.betaSMean = betaSMean[stg][sex]; s.betaSSD = betaSSD[stg][sex]; - } - else { - s.s0Mean = s.alphaSMean = s.betaSMean = s.s0SD = s.alphaSSD = s.betaSSD = 0.0; - } - s.s0Scale = s0Scale; - s.alphaSScale = alphaSScale; - s.betaSScale = betaSScale; - return s; -} - -void Species::setSettScales(const settScales s) { - if (s.s0Scale >= 0.0 && s.s0Scale < 1.0) s0Scale = s.s0Scale; - if (s.alphaSScale >= 0.0) alphaSScale = s.alphaSScale; - if (s.betaSScale >= 0.0) betaSScale = s.betaSScale; -} - -settScales Species::getSettScales(void) { - settScales s; - s.s0Scale = s0Scale; s.alphaSScale = alphaSScale; s.betaSScale = betaSScale; - return s; -} - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - diff --git a/Species.h b/Species.h deleted file mode 100644 index 8b6c07f..0000000 --- a/Species.h +++ /dev/null @@ -1,748 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - - /*------------------------------------------------------------------------------ - - RangeShifter v2.0 Species - - Implements the Species class - - There is ONE instance of a Species for each species within the Community - AND THIS IS CURRENTLY LIMITED TO A SINGLE SPECIES. - The class holds all the demographic and dispersal parameters of the species. - - For full details of RangeShifter, please see: - Bocedi G., Palmer S.C.F., Pe’er G., Heikkinen R.K., Matsinos Y.G., Watts K. - and Travis J.M.J. (2014). RangeShifter: a platform for modelling spatial - eco-evolutionary dynamics and species’ responses to environmental changes. - Methods in Ecology and Evolution, 5, 388-396. doi: 10.1111/2041-210X.12162 - - Authors: Greta Bocedi & Steve Palmer, University of Aberdeen - - Last updated: 28 July 2021 by Greta Bocedi - - ------------------------------------------------------------------------------*/ - -#ifndef SpeciesH -#define SpeciesH - -#include "Parameters.h" - -// structures for demographic parameters - -struct demogrParams { - short repType; - short repSeasons; - float propMales; float harem; float bc; float lambda; - bool stageStruct; -}; -struct stageParams { - short nStages; short repInterval; short maxAge; short survival; - float probRep; - bool fecDens; bool fecStageDens; bool devDens; bool devStageDens; - bool survDens; bool survStageDens; bool disperseOnLoss; -}; -struct densDepParams { - float devCoeff; float survCoeff; -}; - -// structures for genetics - -struct genomeData { - int nLoci; - bool diploid; bool neutralMarkers; bool pleiotropic; bool trait1Chromosome; - double probMutn, probCrossover, alleleSD, mutationSD; -}; - -struct traitAllele { - short chromo; short locus; -}; - -struct traitMap { - short nAlleles; - traitAllele** traitalleles; -}; - -struct traitData { - short nTraitMaps; - traitMap** traitmaps; - traitMap* neutralloci; -}; - -// structures for emigration parameters - -struct emigRules { - bool densDep; bool stgDep; bool sexDep; bool indVar; - short emigStage; - short emigTrait[2]; -}; -struct emigTraits { - float d0; float alpha; float beta; -}; -struct emigParams { - double d0Mean; double d0SD; double d0Scale; - double alphaMean; double alphaSD; double alphaScale; - double betaMean; double betaSD; double betaScale; -}; -struct emigScales { - double d0Scale; double alphaScale; double betaScale; -}; - -// structures for transfer parameters - -struct trfrRules { - bool moveModel; bool stgDep; bool sexDep; - bool distMort; bool indVar; - bool twinKern; - bool habMort; - short moveType; bool costMap; - short movtTrait[2]; -}; -struct trfrKernTraits { - float meanDist1; float meanDist2; float probKern1; -}; -struct trfrMortParams { - float fixedMort; float mortAlpha; float mortBeta; -}; -struct trfrMovtTraits { - short pr; short prMethod; short memSize; short goalType; - float dp; float gb; float alphaDB; int betaDB; - float stepMort; float stepLength; float rho; - bool straigtenPath; -}; -struct trfrCRWTraits { - float stepMort; float stepLength; float rho; bool straigtenPath; -}; -struct trfrSMSTraits { - short pr; short prMethod; short memSize; short goalType; - float dp; float gb; float alphaDB; int betaDB; float stepMort; - bool straigtenPath; -}; -struct trfrKernParams { - double dist1Mean; double dist1SD; double dist1Scale; - double dist2Mean; double dist2SD; double dist2Scale; - double PKern1Mean; double PKern1SD; double PKern1Scale; -}; -struct trfrSMSParams { - double dpMean; double dpSD; double gbMean; double gbSD; - double alphaDBMean; double alphaDBSD; double betaDBMean; double betaDBSD; - double dpScale; double gbScale; double alphaDBScale; double betaDBScale; -}; -struct trfrCRWParams { - double stepLgthMean; double stepLgthSD; double stepLScale; - double rhoMean; double rhoSD; double rhoScale; -}; -struct trfrScales { - float dist1Scale; float dist2Scale; float PKern1Scale; - float dpScale; float gbScale; float alphaDBScale; float betaDBScale; - float stepLScale; float rhoScale; -}; - -// structures for settlement parameters - -struct settleType { - bool stgDep; bool sexDep; bool indVar; - short settTrait[2]; -}; -struct settleRules { - bool densDep; bool wait; bool go2nbrLocn; bool findMate; -}; -struct settleSteps { - int minSteps; int maxSteps; int maxStepsYr; -}; -struct settleTraits { - float s0; float alpha; float beta; -}; -struct settParams { - double s0Mean; double s0SD; double s0Scale; - double alphaSMean; double alphaSSD; double alphaSScale; - double betaSMean; double betaSSD; double betaSScale; -}; -struct settScales { - double s0Scale; double alphaSScale; double betaSScale; -}; - - -//--------------------------------------------------------------------------- - -class Species { - -public: - Species(void); - ~Species(void); - short getSpNum(void); - - // demographic parameter functions - - void createHabK( // Create habitat carrying capacity table - short // no. of habitats - ); - void setHabK( - short, // habitat index no. (NB may differ from habitat no. supplied by user) - float // carrying capacity (inds/cell) - ); - float getHabK( - short // habitat index no. (NB may differ from habitat no. supplied by user) - ); - float getMaxK(void); // return highest carrying capacity over all habitats - void deleteHabK(void); // Delete habitat carrying capacity table - void setStage( // Set stage structure parameters - const stageParams // structure holding stage structure parameters - ); - stageParams getStage(void); // Get stage structure parameters - void setDemogr( // Set general demographic parameters - const demogrParams // structure holding general demographic parameters - ); - demogrParams getDemogr(void); // Get general demographic parameters - short getRepType(void); - bool stageStructured(void); - void setDensDep( // Set demographic density dependence coefficients - float, // development coefficient - float // survival coefficient - ); - densDepParams getDensDep(void); // Get development and survival coefficients - - void setFec( // Set fecundity - short, // stage (must be > 0) - short, // sex - float // fecundity - ); - float getFec( // Get fecundity - short, // stage - short // sex - ); - void setDev( // Set development probability - short, // stage - short, // sex - float // development probability - ); - float getDev( // Get development probability - short, // stage - short // sex - ); - void setSurv( // Set survival probability - short, // stage - short, // sex - float // survival probability - ); - float getSurv( // Get survival probability - short, // stage - short // sex - ); - - float getMaxFec(void); // Get highest fecundity of any stage - void setMinAge( // Set minimum age - short, // stage - short, // sex - int // minimum age (years) (must be zero for stages 0 and 1) - ); - short getMinAge( // Get minimum age - short, // stage - short // sex - ); - void createDDwtFec( // Create fecundity weights matrix - short // matrix dimension - no. of stages * no. of sexes - ); - void setDDwtFec( // Set fecundity weights matrix element - short, // row - short, // column - float // weight - ); - float getDDwtFec( // Get fecundity weights matrix element - short, // row - short // column - ); - void deleteDDwtFec(void); // Delete fecundity weights matrix - void createDDwtDev( // Create development weights matrix - short // matrix dimension - no. of stages * no. of sexes - ); - void setDDwtDev( // Set development weights matrix element - short, // row - short, // column - float // weight - ); - float getDDwtDev( // Get development weights matrix element - short, // row - short // column - ); - void deleteDDwtDev(void); // Delete development weights matrix - void createDDwtSurv( // Create survival weights matrix - short // matrix dimension - no. of stages * no. of sexes - ); - void setDDwtSurv( // Set survival weights matrix element - short, // row - short, // column - float // weight - ); - float getDDwtSurv( // Get survival weights matrix element - short, // row - short // column - ); - void deleteDDwtSurv(void); // Delete survival weights matrix - // Functions to handle min/max R or K (under environmental stochasticity) - void setMinMax( // Set min and max values - float, // min - float // max - ); - float getMinMax( // Get min/max value - short // option: 0 = return minimum, otherwise = return maximum - ); - - - // genome functions - - void setGenomeData(genomeData); - genomeData getGenomeData(void); - bool isDiploid(void); - void setNChromosomes( // Set no. of chromosomes - int // no. of chromosomes - ); - int getNChromosomes(void); - void setNLoci( - const short, // chromosome no. - const short // locus no. - ); - int getNLoci( - const short // chromosome no. - ); - void deleteLoci(void); - void set1ChromPerTrait( // Set 1:1 mapping of trait to chromosome - const int // no. of loci on each chromosome - ); - bool has1ChromPerTrait(void); - void setTraits(void); // Set trait attributes for the species - void setTraitNames(void); - void deleteTraitNames(void); - string getTraitName( - const int // trait no. - ); - int getNTraits(void); - void setTraitData( - const int // no. of traits - ); - void deleteTraitData(void); - int getNTraitMaps(void); - void setTraitMap( - const short, // trait no. - const short // no. of alleles - ); - int getNTraitAlleles( - const int // trait no. - ); - void setTraitAllele( - const short, // trait no. - const short, // trait allele no. - const short, // chromosome no. - const short // chromosome locus no. - ); - traitAllele getTraitAllele( - const short, // trait no. - const short // trait allele no. - ); - void setNeutralLoci(bool); - void deleteNeutralLoci(void); - int getNNeutralLoci(void); - traitAllele getNeutralAllele( - const short // allele no. - ); - - // emigration parameter functions - - void setEmig( // Set emigration rules - const emigRules // structure holding emigration rules - ); - emigRules getEmig(void); // Get emigration rules - void setEmigTraits( // Set emigration trait parameters - const short, // stage - const short, // sex - const emigTraits // structure holding emigration trait parameters - ); - emigTraits getEmigTraits( // Get emigration trait parameters - short, // stage - short // sex - ); - float getEmigD0( // Get (maximum) emigration probability - short, // stage - short // sex - ); - void setEmigParams( // Set emigration initialisation parameters - const short, // stage (NB implemented for stage 0 only) - const short, // sex - const emigParams // structure holding parameters - ); - emigParams getEmigParams( // Get emigration initialisation parameters - short, // stage (NB implemented for stage 0 only) - short // sex - ); - void setEmigScales( // Set emigration mutation parameters - const emigScales // structure holding emigration mutation parameters - ); - emigScales getEmigScales(void); // Get emigration mutation parameters - - // transfer parameter functions - - void setTrfr( // Set transfer rules - const trfrRules // structure holding transfer rules - ); - trfrRules getTrfr(void); // Get transfer rules - void setFullKernel( // Set fullKernel condition - bool // fullKernel value - ); - bool useFullKernel(void); - void setKernTraits( // Set transfer by kernel parameters - const short, // stage - const short, // sex - const trfrKernTraits, // structure holding transfer by kernel parameters - const int // Landscape resolution - ); - trfrKernTraits getKernTraits( // Get transfer by kernel parameters - short, // stage - short // sex - ); - void setMortParams( // Set transfer mortality parameters - const trfrMortParams // structure holding transfer mortality parameters - ); - trfrMortParams getMortParams(void); // Get transfer mortality parameters - void setMovtTraits( // Set transfer movement model parameters - const trfrMovtTraits // structure holding transfer movement model parameters - ); - trfrMovtTraits getMovtTraits(void); // Get transfer movement model traits - trfrCRWTraits getCRWTraits(void); // Get CRW traits - trfrSMSTraits getSMSTraits(void); // Get SMS traits - void setKernParams( // Set initial transfer by kernel parameter limits - const short, // stage (NB implemented for stage 0 only) - const short, // sex - const trfrKernParams, // structure holding min and max values - const double // Landscape resolution - ); - trfrKernParams getKernParams( // Get initial transfer by kernel parameter limits - short, // stage (NB implemented for stage 0 only) - short // sex - ); - void setSMSParams( // Set initial transfer by SMS parameter limits - const short, // stage (NB implemented for stage 0 only) - const short, // sex (NB implemented for sex 0 only) - const trfrSMSParams // structure holding min and max values - ); - trfrSMSParams getSMSParams( // Get initial transfer by SMS parameter limits - short, // stage (NB implemented for stage 0 only) - short // sex (NB implemented for sex 0 only) - ); - void setCRWParams( // Set initial transfer by CRW parameter limits - const short, // stage (NB implemented for stage 0 only) - const short, // sex (NB implemented for sex 0 only) - const trfrCRWParams // structure holding min and max values - ); - trfrCRWParams getCRWParams( // Get initial transfer by CRW parameter limits - short, // stage (NB implemented for stage 0 only) - short // sex (NB implemented for sex 0 only) - ); - void setTrfrScales( // Set transfer mutation parameters - const trfrScales // structure holding transfer mutation parameters - ); - trfrScales getTrfrScales(void); // Get transfer mutation parameters - // Return dimension of habitat-dependent step mortality and costs matrices - short getMovtHabDim(void); - void createHabCostMort( // Create habitat-dependent costs and mortality matrices - short // no. of habitats - ); - void setHabCost( // Set habitat-dependent cost - short, // habitat index no. - int // cost value - ); - void setHabMort( // Set habitat-dependent per-step mortality - short, // habitat index no. - double // mortality rate - ); - int getHabCost( // Get habitat-dependent cost - short // habitat index no. - ); - double getHabMort( // Get habitat-dependent per-step mortality - short // habitat index no. - ); - void deleteHabCostMort(void); // Delete habitat-dependent costs and mortality matrices - - // settlement parameter functions - - void setSettle( // Set settlement type - const settleType // structure holding settlement type (stage- and/or sex-dependent) - ); - settleType getSettle(void); // Get settlement type - void setSettRules( // Set settlement rules - const short, // stage - const short, // sex - const settleRules // structure holding settlement rules - ); - settleRules getSettRules( // Get settlement rules - short, // stage - short // sex - ); - void setSteps( // Set path step limit parameters - const short, // stage - const short, // sex - const settleSteps // structure holding path step limit parameters - ); - settleSteps getSteps( // Set path step limit parameters - short, // stage - short // sex - ); - void setSettTraits( // Set settlement density dependence traits - const short, // stage - const short, // sex - const settleTraits // structure holding density dependence traits - ); - settleTraits getSettTraits( // Get settlement density dependence traits - short, // stage - short // sex - ); - void setSettParams( // Set settlement initialisation parameters - const short, // stage (NB implemented for stage 0 only) - const short, // sex - const settParams // structure holding parameters - ); - settParams getSettParams( // Get settlement initialisation parameters - short, // stage (NB implemented for stage 0 only) - short // sex - ); - void setSettScales( // Set settlement mutation parameters - const settScales // structure holding settlement mutation parameters - ); - settScales getSettScales(void); // Get settlement mutation parameters - -private: - - // NOTE: SEQUENCE OF PARAMETER VARIABLES MAY NEED TO BE ALTERED FOR EFFICIENTCY ... - // ... but that is of low importance, as there will only be one (or a few) instance(s) - - // demographic parameters - - short repType; // 0 = asexual, 1 = simple two sex, 2 = complex two sex - short nStages; // no. of stages (incl. juveniles) in structured population - float propMales; // proportion of males at birth in sexual model - float harem; // max harem size in complex sexual model - float bc; // competition coefficient for non-structured population - float lambda; // max intrinsic growth rate for non-structured population - float probRep; // probability of reproducing in subsequent seasons - short repSeasons; // no. of reproductive seasons per year - short repInterval; // no. of reproductive seasons between subsequent reproductions - short maxAge; // max age in structured population - short survival; // survival timing: 0 = at reprodn, 1 = between reprodns, 2 = anually - bool stageStruct; - bool fecDens; - bool fecStageDens; - bool devDens; - bool devStageDens; - bool survDens; - bool survStageDens; - bool disperseOnLoss; // individuals disperse on complete loss of patch - // (otherwise they die) - short habDimK; // dimension of carrying capacities matrix - float* habK; // habitat-specific carrying capacities (inds/cell) - float devCoeff; // density-dependent development coefficient - float survCoeff; // density-dependent survival coefficient - float** ddwtFec; // density-dependent weights matrix for fecundity - float** ddwtDev; // density-dependent weights matrix for development - float** ddwtSurv; // density-dependent weights matrix for survival - // NB for the following arrays, sex 0 is females, sex 1 is males - float fec[NSTAGES][NSEXES]; // fecundities - float dev[NSTAGES][NSEXES]; // development probabilities - float surv[NSTAGES][NSEXES]; // survival probabilities - short minAge[NSTAGES][NSEXES]; // minimum age to enter stage - // NOTE - IN THEORY, NEXT 3 VARIABLES COULD BE COMMON, BUT WE WOULD NEED TO ENSURE THAT - // ALL MATRICES ARE DELETED IF THERE IS A CHANGE IN NO. OF STAGES OR REPRODUCTION TYPE - // ***** TO BE RECONSIDERED LATER ***** - short ddwtFecDim; // dimension of density-dependent weights matrix for fecundity - short ddwtDevDim; // dimension of density-dependent weights matrix for fecundity - short ddwtSurvDim; // dimension of density-dependent weights matrix for fecundity - float minRK; // minimum ) growth rate OR carrying capacity - float maxRK; // maximum ) (under environmental stochasticity) - - // genome parameters - - short nTraits; // no. of inheritable traits - short emigTrait[2]; // to record first and no. of emigration traits - short movtTrait[2]; // to record first and no. of transfer traits - short settTrait[2]; // to record first and no. of settlement traits - bool diploid; - bool neutralMarkers; // neutral markers in absence of any adaptive traits - bool pleiotropic; - bool trait1Chromosome; // 1:1 mapping of chromosome to trait - short nChromosomes; // no. of chromosomes - double probMutn; // allelic mutation probability - double probCrossover; // crossover probability at meiosis - double alleleSD; // s.d. of initial allelic values around phenotypic value - double mutationSD; // s.d. of mutation magnitude - short nNLoci; // no. of nLoci set - short* nLoci; // no. of loci per chromosome - short nTraitNames; // no. of trait names set - traitData* traitdata; // for mapping of chromosome loci to traits - string* traitnames; // trait names for parameter output - - // emigration parameters - - bool densDepEmig; // density-dependent emigration - bool stgDepEmig; // stage-dependent emigration - bool sexDepEmig; // sex-dependent emigration - bool indVarEmig; // individual variation in emigration - short emigStage; // stage which emigrates (used for stage-strucutred population - // having individual variability in emigration probability) -// NB for the following arrays, sex 0 is females, sex 1 is males - float d0[NSTAGES][NSEXES]; // maximum emigration probability - float alphaEmig[NSTAGES][NSEXES]; // slope of density-dependent reaction norm - float betaEmig[NSTAGES][NSEXES]; // inflection point of reaction norm (in terms of N/K) - // NB Initialisation parameters are made double to avoid conversion errors (reason unclear) - // on traits maps using FloatToStr() - // As evolving traits are not stage-dependent, no. of rows can be 1 - // Indeed, they could be 1-D arrays - double d0Mean[1][NSEXES]; - double d0SD[1][NSEXES]; - double alphaMean[1][NSEXES]; - double alphaSD[1][NSEXES]; - double betaMean[1][NSEXES]; - double betaSD[1][NSEXES]; - double d0Scale; // scaling factor for d0 - double alphaScale; // scaling factor for alpha - double betaScale; // scaling factor for beta - - // transfer parameters - - bool moveModel; - bool stgDepTrfr; - bool sexDepTrfr; - bool distMort; - bool indVarTrfr; - bool twinKern; - bool habMort; // habitat-dependent mortality - float meanDist1[NSTAGES][NSEXES]; // mean of 1st dispersal kernel (m) - float meanDist2[NSTAGES][NSEXES]; // mean of 2nd dispersal kernel (m) - float probKern1[NSTAGES][NSEXES]; // probability of dispersing with the 1st kernel - // NB INITIAL limits are made double to avoid conversion errors (reason unclear) - // on traits maps using FloatToStr() - // As evolving traits are are not stage-dependent, no. of rows can be 1 - // Indeed, as they are INITIAL limits, which may subsequently be exceeded, they could be - // 1-D arrays - double dist1Mean[1][NSEXES]; // mean of initial mean of the 1st dispersal kernel (m) - double dist1SD[1][NSEXES]; // s.d. of initial mean of the 1st dispersal kernel (m) - double dist2Mean[1][NSEXES]; // mean of initial mean of the 2nd dispersal kernel (m) - double dist2SD[1][NSEXES]; // s.d. of initial mean of the 2nd dispersal kernel (m) - double PKern1Mean[1][NSEXES]; // mean of initial prob. of dispersing with 1st kernel - double PKern1SD[1][NSEXES]; // s.d. of initial prob. of dispersing with 1st kernel - float dist1Scale; // scaling factor for mean of 1st dispersal kernel (m) - float dist2Scale; // scaling factor for mean of 2nd dispersal kernel (m) - float PKern1Scale; // scaling factor for prob. of dispersing with 1st kernel - float fixedMort; // constant mortality probability - float mortAlpha; // slope for mortality distance dependence function - float mortBeta; // inflection point for mortality distance dependence function - short moveType; // 1 = SMS, 2 = CRW - short pr; // SMS perceptual range (cells) - short prMethod; // SMS perceptual range evaluation method: - // 1 = arith. mean, 2 = harmonic mean, 3 = inverse weighted arith. mean - short memSize; // SMS memory size (1-14 steps) - short goalType; // SMS goal bias type: 0 = none, 1 = towards goal, 2 = dispersal bias - float dp; // SMS directional persistence - float gb; // SMS goal bias - float alphaDB; // SMS dispersal bias decay rate - int betaDB; // SMS dispersal bias decay inflection point (no. of steps) - float stepMort; // constant per-step mortality probability for movement models - double* habStepMort; // habitat-dependent per-step mortality probability - float stepLength; // CRW step length (m) - float rho; // CRW correlation coefficient - double dpMean[1][NSEXES]; // mean of initial SMS directional persistence - double dpSD[1][NSEXES]; // s.d. of initial SMS directional persistence - double gbMean[1][NSEXES]; // mean of initial SMS goal bias - double gbSD[1][NSEXES]; // s.d. of initial SMS goal bias - double alphaDBMean[1][NSEXES]; // mean of initial SMS dispersal bias decay rate - double alphaDBSD[1][NSEXES]; // s.d. of initial SMS dispersal bias decay rate - double betaDBMean[1][NSEXES]; // mean of initial SMS dispersal bias decay infl. pt. - double betaDBSD[1][NSEXES]; // s.d. of initial SMS dispersal bias decay infl. pt. - float dpScale; // scaling factor for SMS directional persistence - float gbScale; // scaling factor for SMS goal bias - float alphaDBScale; // scaling factor for SMS dispersal bias decay rate - float betaDBScale; // scaling factor for SMS dispersal bias decay infl. pt. - double stepLgthMean[1][NSEXES]; // mean of initial step length (m) - double stepLgthSD[1][NSEXES]; // s.d. of initial step length (m) - double rhoMean[1][NSEXES]; // mean of initial correlation coefficient - double rhoSD[1][NSEXES]; // s.d. of initial correlation coefficient - float stepLScale; // scaling factor for step length (m) - float rhoScale; // scaling factor for correlation coefficient - short habDimTrfr; // dimension of habitat-dependent step mortality and costs matrices - int* habCost; // habitat costs - bool costMap; // import cost map from file? - bool straigtenPath; // straighten path after decision not to settle - bool fullKernel; // used to indicate special case when density-independent emigration - // is 1.0, and kernel-based movement within the natal cell is used - // to determine philopatry - -// settlement parameters - - bool stgDepSett; - bool sexDepSett; - bool indVarSett; // individual variation in settlement - bool densDepSett[NSTAGES][NSEXES]; - bool wait[NSTAGES][NSEXES]; // wait to continue moving next season (stage-structured model only) - bool go2nbrLocn[NSTAGES][NSEXES]; // settle in neighbouring cell/patch if available (ditto) - bool findMate[NSTAGES][NSEXES]; - int minSteps[NSTAGES][NSEXES]; // minimum no. of steps - int maxSteps[NSTAGES][NSEXES]; // maximum total no. of steps - int maxStepsYr[NSTAGES][NSEXES]; // maximum no. of steps in any one dispersal period - float s0[NSTAGES][NSEXES]; // maximum settlement probability - float alphaS[NSTAGES][NSEXES]; // slope of the settlement reaction norm to density - float betaS[NSTAGES][NSEXES]; // inflection point of the settlement reaction norm to density - double s0Mean[1][NSEXES]; // mean of initial maximum settlement probability - double s0SD[1][NSEXES]; // s.d. of initial maximum settlement probability - double alphaSMean[1][NSEXES]; // mean of initial settlement reaction norm slope - double alphaSSD[1][NSEXES]; // s.d. of initial settlement reaction norm slope - double betaSMean[1][NSEXES]; // mean of initial settlement reaction norm inflection point - double betaSSD[1][NSEXES]; // s.d. of initial settlement reaction norm inflection point - float s0Scale; // scaling factor for maximum settlement probability - float alphaSScale; // scaling factor for settlement reaction norm slope - float betaSScale; // scaling factor for settlement reaction norm inflection point - - // other attributes - - int spNum; - -}; - -/* IMPORTANT NOTE: -At the time of writing (24/4/14) the stage- and sex-dependent parameters for emigration -and dispersal (e.g. d0[NSTAGES][NSEXES]) are set according to the appropriate stage- and -sex-dependent settings; thus a species could be structured and sexual, but parameter values -are set for elements [0][0] only if emigration/transfer is stage- and sex-independent. -However, the parameters for settlement are set for ALL stages and sexes appropriate to the -species, regardless of settlement dependency. The rationale for this is that settlement -parameters need to be accessed many more times for a movement model (at each step) than -emigration or transfer parameters, and therefore there will be a performance gain in -avoiding nested if statements in Individual::moveStep() which would otherwise be required -to get the correct parameter values from the settlement arrays. Whether that particular -rationale is justified remains to be tested! -*/ - -//--------------------------------------------------------------------------- - -#if RSDEBUG -//extern ofstream DEBUGLOG; -extern void DebugGUI(string); -#endif - -//--------------------------------------------------------------------------- -#endif diff --git a/SubCommunity.cpp b/SubCommunity.cpp deleted file mode 100644 index d908892..0000000 --- a/SubCommunity.cpp +++ /dev/null @@ -1,1008 +0,0 @@ -/*---------------------------------------------------------------------------- - * - * Copyright (C) 2020 Greta Bocedi, Stephen C.F. Palmer, Justin M.J. Travis, Anne-Kathleen Malchow, Damaris Zurell - * - * This file is part of RangeShifter. - * - * RangeShifter is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * RangeShifter is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with RangeShifter. If not, see . - * - --------------------------------------------------------------------------*/ - - - //--------------------------------------------------------------------------- - -#include "SubCommunity.h" -//--------------------------------------------------------------------------- - -ofstream outtraits; - -//--------------------------------------------------------------------------- - -SubCommunity::SubCommunity(Patch* pPch, int num) { - subCommNum = num; - pPatch = pPch; - // record the new sub-community no. in the patch - pPatch->setSubComm((intptr)this); - initial = false; - occupancy = 0; -} - -SubCommunity::~SubCommunity() { - pPatch->setSubComm(0); - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - delete popns[i]; - } - popns.clear(); - if (occupancy != 0) delete[] occupancy; -} - -intptr SubCommunity::getNum(void) { return subCommNum; } - -Patch* SubCommunity::getPatch(void) { return pPatch; } - -locn SubCommunity::getLocn(void) { - locn loc = pPatch->getCellLocn(0); - return loc; -} - -void SubCommunity::setInitial(bool b) { initial = b; } - -void SubCommunity::initialise(Landscape* pLandscape, Species* pSpecies) -{ - int ncells; - landParams ppLand = pLandscape->getLandParams(); - initParams init = paramsInit->getInit(); - // determine size of initial population - int nInds = 0; - if (subCommNum == 0 // matrix patch - || !initial) // not in initial region or distribution - nInds = 0; - else { - float k = pPatch->getK(); - if (k > 0.0) { // patch is currently suitable for this species - switch (init.initDens) { - case 0: // at carrying capacity - nInds = (int)k; - break; - case 1: // at half carrying capacity - nInds = (int)(k / 2.0); - break; - case 2: // specified no. per cell or density - ncells = pPatch->getNCells(); - if (ppLand.patchModel) { - nInds = (int)(init.indsHa * (float)(ncells * ppLand.resol * ppLand.resol) / 10000.0); - } - else { - nInds = init.indsCell * ncells; - } - break; - } - } - else nInds = 0; - } - // create new population only if it is non-zero or the matrix popn - if (subCommNum == 0 || nInds > 0) { - newPopn(pLandscape, pSpecies, pPatch, nInds); - } -} - -// initialise a specified individual -void SubCommunity::initialInd(Landscape* pLandscape, Species* pSpecies, - Patch* pPatch, Cell* pCell, int ix) -{ - - demogrParams dem = pSpecies->getDemogr(); - stageParams sstruct = pSpecies->getStage(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); - settleType sett = pSpecies->getSettle(); - genomeData gen = pSpecies->getGenomeData(); - short stg, age, repInt; - Individual* pInd; - float probmale; - - // create new population if not already in existence - int npopns = (int)popns.size(); - if (npopns < 1) { - newPopn(pLandscape, pSpecies, pPatch, 0); - } - - // create new individual - initInd iind = paramsInit->getInitInd(ix); - if (dem.stageStruct) { - stg = iind.stage; age = iind.age; repInt = sstruct.repInterval; - } - else { - age = stg = 1; repInt = 0; - } - if (dem.repType == 0) { - probmale = 0.0; - } - else { - if (iind.sex == 1) probmale = 1.0; else probmale = 0.0; - } - pInd = new Individual(pCell, pPatch, stg, age, repInt, probmale, trfr.moveModel, trfr.moveType); - - // add new individual to the population - // NB THIS WILL NEED TO BE CHANGED FOR MULTIPLE SPECIES... - popns[0]->recruit(pInd); - - if (emig.indVar || trfr.indVar || sett.indVar || gen.neutralMarkers) - { - // individual variation - set up genetics - landData land = pLandscape->getLandData(); - pInd->setGenes(pSpecies, land.resol); - } - -} - -// Create a new population, and return its address -Population* SubCommunity::newPopn(Landscape* pLandscape, Species* pSpecies, - Patch* pPatch, int nInds) -{ - landParams land = pLandscape->getLandParams(); - int npopns = (int)popns.size(); - popns.push_back(new Population(pSpecies, pPatch, nInds, land.resol)); - return popns[npopns]; -} - -popStats SubCommunity::getPopStats(void) { - popStats p, pop; - p.pSpecies = 0; p.spNum = 0; p.nInds = p.nAdults = p.nNonJuvs = 0; p.breeding = false; - p.pPatch = pPatch; - // FOR SINGLE SPECIES IMPLEMENTATION, THERE IS ONLY ONE POPULATION IN THE PATCH - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - pop = popns[i]->getStats(); - p.pSpecies = pop.pSpecies; - p.spNum = pop.spNum; - p.nInds += pop.nInds; - p.nNonJuvs += pop.nNonJuvs; - p.nAdults += pop.nAdults; - p.breeding = pop.breeding; - } - return p; -} - -void SubCommunity::resetPopns(void) { - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - delete popns[i]; - } - popns.clear(); - // clear the list of populations in the corresponding patch - pPatch->resetPopn(); -} - -void SubCommunity::resetPossSettlers(void) { - if (subCommNum == 0) return; // not applicable in the matrix - pPatch->resetPossSettlers(); -} - -// Extirpate all populations according to -// option 0 - random local extinction probability -// option 1 - local extinction probability gradient -// NB only applied for cell-based model -void SubCommunity::localExtinction(int option) { - double pExtinct = 0.0; - if (option == 0) { - envStochParams env = paramsStoch->getStoch(); - if (env.localExt) pExtinct = env.locExtProb; - } - else { - envGradParams grad = paramsGrad->getGradient(); - Cell* pCell = pPatch->getRandomCell(); // get only cell in the patch - // extinction prob is complement of cell gradient value plus any non-zero prob at the optimum - pExtinct = 1.0 - pCell->getEnvVal() + grad.extProbOpt; - if (pExtinct > 1.0) pExtinct = 1.0; - } - if (pRandom->Bernoulli(pExtinct)) { - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - popns[i]->extirpate(); - } - } -} - -// Action in event of patch becoming unsuitable owing to landscape change -void SubCommunity::patchChange(void) { - if (subCommNum == 0) return; // no reproduction in the matrix - Species* pSpecies; - float localK = 0.0; - int npops = (int)popns.size(); - // THE FOLLOWING MAY BE MORE EFFICIENT WHILST THERE IS ONLY ONE SPECIES ... - if (npops < 1) return; - localK = pPatch->getK(); - if (localK <= 0.0) { // patch in dynamic landscape has become unsuitable - for (int i = 0; i < npops; i++) { // all populations - pSpecies = popns[i]->getSpecies(); - demogrParams dem = pSpecies->getDemogr(); - if (dem.stageStruct) { - stageParams sstruct = pSpecies->getStage(); - if (sstruct.disperseOnLoss) popns[i]->allEmigrate(); - else popns[i]->extirpate(); - } - else { // non-stage-structured species is destroyed - popns[i]->extirpate(); - } - } - } -} - -void SubCommunity::reproduction(int resol, float epsGlobal, short rasterType, bool patchModel) -{ - if (subCommNum == 0) return; // no reproduction in the matrix - float localK, envval; - Cell* pCell; - envGradParams grad = paramsGrad->getGradient(); - envStochParams env = paramsStoch->getStoch(); - - int npops = (int)popns.size(); - // THE FOLLOWING MAY BE MORE EFFICIENT WHILST THERE IS ONLY ONE SPECIES ... - if (npops < 1) return; - - localK = pPatch->getK(); - if (localK > 0.0) { - if (patchModel) { - envval = 1.0; // environmental gradient is currently not applied for patch-based model - } - else { // cell-based model - if (grad.gradient && grad.gradType == 2) - { // gradient in fecundity - Cell* pCell = pPatch->getRandomCell(); // locate the only cell in the patch - envval = pCell->getEnvVal(); - } - else envval = 1.0; - } - if (env.stoch && !env.inK) { // stochasticity in fecundity - if (env.local) { - if (!patchModel) { // only permitted for cell-based model - pCell = pPatch->getRandomCell(); - if (pCell != 0) envval += pCell->getEps(); - } - } - else { // global stochasticity - envval += epsGlobal; - } - } - for (int i = 0; i < npops; i++) { // all populations - popns[i]->reproduction(localK, envval, resol); - popns[i]->fledge(); - } - } -} - -void SubCommunity::emigration(void) -{ - if (subCommNum == 0) return; // no emigration from the matrix - float localK; - int npops = (int)popns.size(); - // THE FOLLOWING MAY BE MORE EFFICIENT WHILST THERE IS ONLY ONE SPECIES ... - if (npops < 1) return; - localK = pPatch->getK(); - // NOTE that even if K is zero, it could have been >0 in previous time-step, and there - // might be emigrants if there is non-juvenile emigration - for (int i = 0; i < npops; i++) { // all populations - popns[i]->emigration(localK); - } -} - -// Remove emigrants from their natal patch and add to patch 0 (matrix) -void SubCommunity::initiateDispersal(SubCommunity* matrix) { - if (subCommNum == 0) return; // no dispersal initiation in the matrix - popStats pop; - disperser disp; - - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - pop = popns[i]->getStats(); - for (int j = 0; j < pop.nInds; j++) { - disp = popns[i]->extractDisperser(j); - if (disp.yes) { // disperser - has already been removed from natal population - // add to matrix population - matrix->recruit(disp.pInd, pop.pSpecies); - } - } - // remove pointers to emigrants - popns[i]->clean(); - } - -} - -// Add an individual into the local population of its species in the patch -void SubCommunity::recruit(Individual* pInd, Species* pSpecies) { - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - if (pSpecies == popns[i]->getSpecies()) { - popns[i]->recruit(pInd); - } - } -} - -// Transfer through the matrix - run for the matrix sub-community only -#if RS_RCPP -int SubCommunity::transfer(Landscape* pLandscape, short landIx, short nextseason) -#else -int SubCommunity::transfer(Landscape* pLandscape, short landIx) -#endif // RS_RCPP -{ - int ndispersers = 0; - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations -#if RS_RCPP - ndispersers += popns[i]->transfer(pLandscape, landIx, nextseason); -#else - ndispersers += popns[i]->transfer(pLandscape, landIx); -#endif // RS_RCPP - - } - return ndispersers; -} - -//--------------------------------------------------------------------------- - -// Remove emigrants from patch 0 (matrix) and transfer to sub-community -// in which their destination co-ordinates fall -// This function is executed for the matrix patch only - -void SubCommunity::completeDispersal(Landscape* pLandscape, bool connect) -{ - int popsize; - disperser settler; - Species* pSpecies; - Population* pPop; - Patch* pPrevPatch; - Patch* pNewPatch; - Cell* pPrevCell; - SubCommunity* pSubComm; - - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - pSpecies = popns[i]->getSpecies(); - popsize = popns[i]->getNInds(); - for (int j = 0; j < popsize; j++) { - bool settled; - settler = popns[i]->extractSettler(j); - settled = settler.yes; - if (settled) { - // settler - has already been removed from matrix population - // find new patch - pNewPatch = (Patch*)settler.pCell->getPatch(); - // find population within the patch (if there is one) - pPop = (Population*)pNewPatch->getPopn((intptr)pSpecies); - if (pPop == 0) { // settler is the first in a previously uninhabited patch - // create a new population in the corresponding sub-community - pSubComm = (SubCommunity*)pNewPatch->getSubComm(); - pPop = pSubComm->newPopn(pLandscape, pSpecies, pNewPatch, 0); - } - pPop->recruit(settler.pInd); - if (connect) { // increment connectivity totals - int newpatch = pNewPatch->getSeqNum(); - pPrevCell = settler.pInd->getLocn(0); // previous cell - intptr patch = pPrevCell->getPatch(); - if (patch != 0) { - pPrevPatch = (Patch*)patch; - int prevpatch = pPrevPatch->getSeqNum(); - pLandscape->incrConnectMatrix(prevpatch, newpatch); - } - } - } - else { // for group dispersal only - } - } - // remove pointers in the matrix popn to settlers - popns[i]->clean(); - } - -} - -//--------------------------------------------------------------------------- - -void SubCommunity::survival(short part, short option0, short option1) -{ - int npops = (int)popns.size(); - if (npops < 1) return; - if (part == 0) { - float localK = pPatch->getK(); - for (int i = 0; i < npops; i++) { // all populations - popns[i]->survival0(localK, option0, option1); - } - } - else { - for (int i = 0; i < npops; i++) { // all populations - popns[i]->survival1(); - } - } -} - -void SubCommunity::ageIncrement(void) { - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - popns[i]->ageIncrement(); - } -} - -// Find the population of a given species in a given patch -Population* SubCommunity::findPop(Species* pSp, Patch* pPch) { -#if RSDEBUG - DEBUGLOG << "SubCommunity::findPop(): this=" << this - << endl; -#endif - - Population* pPop = 0; - popStats pop; - int npops = (int)popns.size(); - - for (int i = 0; i < npops; i++) { // all populations - pop = popns[i]->getStats(); - if (pop.pSpecies == pSp && pop.pPatch == pPch) { // population located - pPop = popns[i]; - break; - } - else pPop = 0; - } - return pPop; -} - -//--------------------------------------------------------------------------- - -void SubCommunity::createOccupancy(int nrows) { - if (occupancy != 0) deleteOccupancy(); - if (nrows > 0) { - occupancy = new int[nrows]; - for (int i = 0; i < nrows; i++) occupancy[i] = 0; - } -} - -void SubCommunity::updateOccupancy(int row) { - popStats pop; - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { - pop = popns[i]->getStats(); - if (pop.nInds > 0 && pop.breeding) { - occupancy[row]++; - i = npops; - } - } -} - -int SubCommunity::getOccupancy(int row) { - if (row >= 0) return occupancy[row]; - else return 0; -} - -void SubCommunity::deleteOccupancy(void) { - delete[] occupancy; - occupancy = 0; -} - -//--------------------------------------------------------------------------- -// Open population file and write header record -bool SubCommunity::outPopHeaders(Landscape* pLandscape, Species* pSpecies, int option) -{ - bool fileOK; - Population* pPop; - landParams land = pLandscape->getLandParams(); - - if (option == -999) { // close the file - // as all populations may have been deleted, set up a dummy one - // species is not necessary - pPop = new Population(); - fileOK = pPop->outPopHeaders(-999, land.patchModel); - delete pPop; - } - else { // open the file - // as no population has yet been created, set up a dummy one - // species is necessary, as columns depend on stage and sex structure - pPop = new Population(pSpecies, pPatch, 0, land.resol); - fileOK = pPop->outPopHeaders(land.landNum, land.patchModel); - delete pPop; - } - return fileOK; -} - -// Write records to population file -void SubCommunity::outPop(Landscape* pLandscape, int rep, int yr, int gen) -{ - landParams land = pLandscape->getLandParams(); - envGradParams grad = paramsGrad->getGradient(); - envStochParams env = paramsStoch->getStoch(); - bool writeEnv = false; - bool gradK = false; - if (grad.gradient) { - writeEnv = true; - if (grad.gradType == 1) gradK = true; // ... carrying capacity - } - if (env.stoch) writeEnv = true; - - // generate output for each population within the sub-community (patch) - // provided that the patch is suitable (i.e. non-zero carrying capacity) - // or the population is above zero (possible if there is stochasticity or a moving gradient) - // or it is the matrix patch in a patch-based model - int npops = (int)popns.size(); - int patchnum; - Cell* pCell; - float localK; - float eps = 0.0; - if (env.stoch) { - if (env.local) { - pCell = pPatch->getRandomCell(); - if (pCell != 0) eps = pCell->getEps(); - } - else { - eps = pLandscape->getGlobalStoch(yr); - } - } - - patchnum = pPatch->getPatchNum(); - for (int i = 0; i < npops; i++) { // all populations - localK = pPatch->getK(); - if (localK > 0.0 || (land.patchModel && patchnum == 0)) { - popns[i]->outPopulation(rep, yr, gen, eps, land.patchModel, writeEnv, gradK); - } - else { - if (popns[i]->totalPop() > 0) { - popns[i]->outPopulation(rep, yr, gen, eps, land.patchModel, writeEnv, gradK); - } - } - } -} - -// Write records to individuals file -void SubCommunity::outInds(Landscape* pLandscape, int rep, int yr, int gen, int landNr) { - landParams ppLand = pLandscape->getLandParams(); - if (landNr >= 0) { // open the file - popns[0]->outIndsHeaders(rep, landNr, ppLand.patchModel); - return; - } - if (landNr == -999) { // close the file - popns[0]->outIndsHeaders(rep, -999, ppLand.patchModel); - return; - } - // generate output for each population within the sub-community (patch) - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - popns[i]->outIndividual(pLandscape, rep, yr, gen, pPatch->getPatchNum()); - } -} - -// Write records to individuals file -void SubCommunity::outGenetics(int rep, int yr, int gen, int landNr) -{ - if (landNr >= 0) { // open the file - popns[0]->outGenetics(rep, yr, landNr); - return; - } - if (landNr == -999) { // close the file - popns[0]->outGenetics(rep, yr, landNr); - return; - } - // generate output for each population within the sub-community (patch) - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - popns[i]->outGenetics(rep, yr, landNr); - } -} - -// Population size of a specified stage -int SubCommunity::stagePop(int stage) { - int popsize = 0; - int npops = (int)popns.size(); - for (int i = 0; i < npops; i++) { // all populations - popsize += popns[i]->stagePop(stage); - } - return popsize; -} - -// Open traits file and write header record -bool SubCommunity::outTraitsHeaders(Landscape* pLandscape, Species* pSpecies, int landNr) -{ - landParams land = pLandscape->getLandParams(); - if (landNr == -999) { // close file - if (outtraits.is_open()) outtraits.close(); - outtraits.clear(); - return true; - } - - string name; - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); - settleType sett = pSpecies->getSettle(); - simParams sim = paramsSim->getSim(); - - string DirOut = paramsSim->getDir(2); - if (sim.batchMode) { - if (land.patchModel) { - name = DirOut - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(landNr) - + "_TraitsXpatch.txt"; - } - else { - name = DirOut - + "Batch" + Int2Str(sim.batchNum) + "_" - + "Sim" + Int2Str(sim.simulation) + "_Land" + Int2Str(landNr) - + "_TraitsXcell.txt"; - } - } - else { - if (land.patchModel) { - name = DirOut + "Sim" + Int2Str(sim.simulation) + "_TraitsXpatch.txt"; - } - else { - name = DirOut + "Sim" + Int2Str(sim.simulation) + "_TraitsXcell.txt"; - } - } - outtraits.open(name.c_str()); - - outtraits << "Rep\tYear\tRepSeason"; - if (land.patchModel) outtraits << "\tPatchID"; - else - outtraits << "\tx\ty"; - - if (emig.indVar) { - if (emig.sexDep) { - if (emig.densDep) { - outtraits << "\tF_meanD0\tF_stdD0\tM_meanD0\tM_stdD0"; - outtraits << "\tF_meanAlpha\tF_stdAlpha\tM_meanAlpha\tM_stdAlpha"; - outtraits << "\tF_meanBeta\tF_stdBeta\tM_meanBeta\tM_stdBeta"; - } - else { - outtraits << "\tF_meanEP\tF_stdEP\tM_meanEP\tM_stdEP"; - } - } - else { - if (emig.densDep) { - outtraits << "\tmeanD0\tstdD0\tmeanAlpha\tstdAlpha"; - outtraits << "\tmeanBeta\tstdBeta"; - } - else { - outtraits << "\tmeanEP\tstdEP"; - } - } - } - if (trfr.indVar) { - if (trfr.moveModel) { - if (trfr.moveType == 1) { - outtraits << "\tmeanDP\tstdDP\tmeanGB\tstdGB"; - outtraits << "\tmeanAlphaDB\tstdAlphaDB\tmeanBetaDB\tstdBetaDB"; - } - if (trfr.moveType == 2) { - outtraits << "\tmeanStepLength\tstdStepLength\tmeanRho\tstdRho"; - } - } - else { - if (trfr.sexDep) { - outtraits << "\tF_mean_distI\tF_std_distI\tM_mean_distI\tM_std_distI"; - if (trfr.twinKern) - outtraits << "\tF_mean_distII\tF_std_distII\tM_mean_distII\tM_std_distII" - << "\tF_meanPfirstKernel\tF_stdPfirstKernel" - << "\tM_meanPfirstKernel\tM_stdPfirstKernel"; - } - else { - outtraits << "\tmean_distI\tstd_distI"; - if (trfr.twinKern) - outtraits << "\tmean_distII\tstd_distII\tmeanPfirstKernel\tstdPfirstKernel"; - } - } - } - if (sett.indVar) { - if (sett.sexDep) { - outtraits << "\tF_meanS0\tF_stdS0\tM_meanS0\tM_stdS0"; - outtraits << "\tF_meanAlphaS\tF_stdAlphaS\tM_meanAlphaS\tM_stdAlphaS"; - outtraits << "\tF_meanBetaS\tF_stdBetaS\tM_meanBetaS\tM_stdBetaS"; - } - else { - outtraits << "\tmeanS0\tstdS0"; - outtraits << "\tmeanAlphaS\tstdAlphaS"; - outtraits << "\tmeanBetaS\tstdBetaS"; - } - } - outtraits << endl; - - return outtraits.is_open(); -} - -// Write records to traits file and return aggregated sums -traitsums SubCommunity::outTraits(traitCanvas tcanv, - Landscape* pLandscape, int rep, int yr, int gen, bool commlevel) -{ - int popsize, ngenes; - landParams land = pLandscape->getLandParams(); - simParams sim = paramsSim->getSim(); - bool writefile = false; - if (sim.outTraitsCells && yr % sim.outIntTraitCell == 0 && !commlevel) - writefile = true; - traitsums ts, poptraits; - for (int i = 0; i < NSEXES; i++) { - ts.ninds[i] = 0; - ts.sumD0[i] = ts.ssqD0[i] = 0.0; - ts.sumAlpha[i] = ts.ssqAlpha[i] = 0.0; ts.sumBeta[i] = ts.ssqBeta[i] = 0.0; - ts.sumDist1[i] = ts.ssqDist1[i] = 0.0; ts.sumDist2[i] = ts.ssqDist2[i] = 0.0; - ts.sumProp1[i] = ts.ssqProp1[i] = 0.0; - ts.sumDP[i] = ts.ssqDP[i] = 0.0; - ts.sumGB[i] = ts.ssqGB[i] = 0.0; - ts.sumAlphaDB[i] = ts.ssqAlphaDB[i] = 0.0; - ts.sumBetaDB[i] = ts.ssqBetaDB[i] = 0.0; - ts.sumStepL[i] = ts.ssqStepL[i] = 0.0; ts.sumRho[i] = ts.ssqRho[i] = 0.0; - ts.sumS0[i] = ts.ssqS0[i] = 0.0; - ts.sumAlphaS[i] = ts.ssqAlphaS[i] = 0.0; ts.sumBetaS[i] = ts.ssqBetaS[i] = 0.0; - } - - // generate output for each population within the sub-community (patch) - // provided that the patch is suitable (i.e. non-zero carrying capacity) - int npops = (int)popns.size(); - Species* pSpecies; - float localK; - - for (int i = 0; i < npops; i++) { // all populations - localK = pPatch->getK(); - if (localK > 0.0 && popns[i]->getNInds() > 0) { - pSpecies = popns[i]->getSpecies(); - demogrParams dem = pSpecies->getDemogr(); - emigRules emig = pSpecies->getEmig(); - trfrRules trfr = pSpecies->getTrfr(); - settleType sett = pSpecies->getSettle(); - poptraits = popns[i]->getTraits(pSpecies); - - if (writefile) { - outtraits << rep << "\t" << yr << "\t" << gen; - if (land.patchModel) { - outtraits << "\t" << pPatch->getPatchNum(); - } - else { - locn loc = pPatch->getCellLocn(0); - outtraits << "\t" << loc.x << "\t" << loc.y; - } - } - - if (emig.indVar) { - if (emig.sexDep) { // must be a sexual species - ngenes = 2; - } - else { - if (dem.repType == 0) { // asexual reproduction - ngenes = 1; - } - else { // sexual reproduction - ngenes = 1; - } - } - double mnD0[2], mnAlpha[2], mnBeta[2], sdD0[2], sdAlpha[2], sdBeta[2]; - for (int g = 0; g < ngenes; g++) { - mnD0[g] = mnAlpha[g] = mnBeta[g] = sdD0[g] = sdAlpha[g] = sdBeta[g] = 0.0; - // individuals may have been counted by sex if there was - // sex dependency in another dispersal phase - if (ngenes == 2) popsize = poptraits.ninds[g]; - else popsize = poptraits.ninds[0] + poptraits.ninds[1]; - if (popsize > 0) { - mnD0[g] = poptraits.sumD0[g] / (double)popsize; - mnAlpha[g] = poptraits.sumAlpha[g] / (double)popsize; - mnBeta[g] = poptraits.sumBeta[g] / (double)popsize; - if (popsize > 1) { - sdD0[g] = poptraits.ssqD0[g] / (double)popsize - mnD0[g] * mnD0[g]; - if (sdD0[g] > 0.0) sdD0[g] = sqrt(sdD0[g]); else sdD0[g] = 0.0; - sdAlpha[g] = poptraits.ssqAlpha[g] / (double)popsize - mnAlpha[g] * mnAlpha[g]; - if (sdAlpha[g] > 0.0) sdAlpha[g] = sqrt(sdAlpha[g]); else sdAlpha[g] = 0.0; - sdBeta[g] = poptraits.ssqBeta[g] / (double)popsize - mnBeta[g] * mnBeta[g]; - if (sdBeta[g] > 0.0) sdBeta[g] = sqrt(sdBeta[g]); else sdBeta[g] = 0.0; - } - else { - sdD0[g] = sdAlpha[g] = sdBeta[g] = 0.0; - } - } - } - if (writefile) { - if (emig.sexDep) { - outtraits << "\t" << mnD0[0] << "\t" << sdD0[0]; - outtraits << "\t" << mnD0[1] << "\t" << sdD0[1]; - if (emig.densDep) { - outtraits << "\t" << mnAlpha[0] << "\t" << sdAlpha[0]; - outtraits << "\t" << mnAlpha[1] << "\t" << sdAlpha[1]; - outtraits << "\t" << mnBeta[0] << "\t" << sdBeta[0]; - outtraits << "\t" << mnBeta[1] << "\t" << sdBeta[1]; - } - } - else { // sex-independent - outtraits << "\t" << mnD0[0] << "\t" << sdD0[0]; - if (emig.densDep) { - outtraits << "\t" << mnAlpha[0] << "\t" << sdAlpha[0]; - outtraits << "\t" << mnBeta[0] << "\t" << sdBeta[0]; - } - } - } - } - - if (trfr.indVar) { - if (trfr.moveModel) { - // CURRENTLY INDIVIDUAL VARIATION CANNOT BE SEX-DEPENDENT - ngenes = 1; - } - else { - if (trfr.sexDep) { // must be a sexual species - ngenes = 2; - } - else { - ngenes = 1; - } - } - double mnDist1[2], mnDist2[2], mnProp1[2], mnStepL[2], mnRho[2]; - double sdDist1[2], sdDist2[2], sdProp1[2], sdStepL[2], sdRho[2]; - double mnDP[2], mnGB[2], mnAlphaDB[2], mnBetaDB[2]; - double sdDP[2], sdGB[2], sdAlphaDB[2], sdBetaDB[2]; - for (int g = 0; g < ngenes; g++) { - mnDist1[g] = mnDist2[g] = mnProp1[g] = mnStepL[g] = mnRho[g] = 0.0; - sdDist1[g] = sdDist2[g] = sdProp1[g] = sdStepL[g] = sdRho[g] = 0.0; - mnDP[g] = mnGB[g] = mnAlphaDB[g] = mnBetaDB[g] = 0.0; - sdDP[g] = sdGB[g] = sdAlphaDB[g] = sdBetaDB[g] = 0.0; - // individuals may have been counted by sex if there was - // sex dependency in another dispersal phase - if (ngenes == 2) popsize = poptraits.ninds[g]; - else popsize = poptraits.ninds[0] + poptraits.ninds[1]; - if (popsize > 0) { - mnDist1[g] = poptraits.sumDist1[g] / (double)popsize; - mnDist2[g] = poptraits.sumDist2[g] / (double)popsize; - mnProp1[g] = poptraits.sumProp1[g] / (double)popsize; - mnStepL[g] = poptraits.sumStepL[g] / (double)popsize; - mnRho[g] = poptraits.sumRho[g] / (double)popsize; - mnDP[g] = poptraits.sumDP[g] / (double)popsize; - mnGB[g] = poptraits.sumGB[g] / (double)popsize; - mnAlphaDB[g] = poptraits.sumAlphaDB[g] / (double)popsize; - mnBetaDB[g] = poptraits.sumBetaDB[g] / (double)popsize; - if (popsize > 1) { - sdDist1[g] = poptraits.ssqDist1[g] / (double)popsize - mnDist1[g] * mnDist1[g]; - if (sdDist1[g] > 0.0) sdDist1[g] = sqrt(sdDist1[g]); else sdDist1[g] = 0.0; - sdDist2[g] = poptraits.ssqDist2[g] / (double)popsize - mnDist2[g] * mnDist2[g]; - if (sdDist2[g] > 0.0) sdDist2[g] = sqrt(sdDist2[g]); else sdDist2[g] = 0.0; - sdProp1[g] = poptraits.ssqProp1[g] / (double)popsize - mnProp1[g] * mnProp1[g]; - if (sdProp1[g] > 0.0) sdProp1[g] = sqrt(sdProp1[g]); else sdProp1[g] = 0.0; - sdStepL[g] = poptraits.ssqStepL[g] / (double)popsize - mnStepL[g] * mnStepL[g]; - if (sdStepL[g] > 0.0) sdStepL[g] = sqrt(sdStepL[g]); else sdStepL[g] = 0.0; - sdRho[g] = poptraits.ssqRho[g] / (double)popsize - mnRho[g] * mnRho[g]; - if (sdRho[g] > 0.0) sdRho[g] = sqrt(sdRho[g]); else sdRho[g] = 0.0; - sdDP[g] = poptraits.ssqDP[g] / (double)popsize - mnDP[g] * mnDP[g]; - if (sdDP[g] > 0.0) sdDP[g] = sqrt(sdDP[g]); else sdDP[g] = 0.0; - sdGB[g] = poptraits.ssqGB[g] / (double)popsize - mnGB[g] * mnGB[g]; - if (sdGB[g] > 0.0) sdGB[g] = sqrt(sdGB[g]); else sdGB[g] = 0.0; - sdAlphaDB[g] = poptraits.ssqAlphaDB[g] / (double)popsize - mnAlphaDB[g] * mnAlphaDB[g]; - if (sdAlphaDB[g] > 0.0) sdAlphaDB[g] = sqrt(sdAlphaDB[g]); else sdAlphaDB[g] = 0.0; - sdBetaDB[g] = poptraits.ssqBetaDB[g] / (double)popsize - mnBetaDB[g] * mnBetaDB[g]; - if (sdBetaDB[g] > 0.0) sdBetaDB[g] = sqrt(sdBetaDB[g]); else sdBetaDB[g] = 0.0; - } - } - } - if (writefile) { - if (trfr.moveModel) { - if (trfr.moveType == 1) { - outtraits << "\t" << mnDP[0] << "\t" << sdDP[0]; - outtraits << "\t" << mnGB[0] << "\t" << sdGB[0]; - outtraits << "\t" << mnAlphaDB[0] << "\t" << sdAlphaDB[0]; - outtraits << "\t" << mnBetaDB[0] << "\t" << sdBetaDB[0]; - } - if (trfr.moveType == 2) { - outtraits << "\t" << mnStepL[0] << "\t" << sdStepL[0]; - outtraits << "\t" << mnRho[0] << "\t" << sdRho[0]; - } - } - else { - if (trfr.sexDep) { - outtraits << "\t" << mnDist1[0] << "\t" << sdDist1[0]; - outtraits << "\t" << mnDist1[1] << "\t" << sdDist1[1]; - if (trfr.twinKern) - { - outtraits << "\t" << mnDist2[0] << "\t" << sdDist2[0]; - outtraits << "\t" << mnDist2[1] << "\t" << sdDist2[1]; - outtraits << "\t" << mnProp1[0] << "\t" << sdProp1[0]; - outtraits << "\t" << mnProp1[1] << "\t" << sdProp1[1]; - } - } - else { // sex-independent - outtraits << "\t" << mnDist1[0] << "\t" << sdDist1[0]; - if (trfr.twinKern) - { - outtraits << "\t" << mnDist2[0] << "\t" << sdDist2[0]; - outtraits << "\t" << mnProp1[0] << "\t" << sdProp1[0]; - } - } - } - } - } - - if (sett.indVar) { - if (sett.sexDep) { // must be a sexual species - ngenes = 2; - } - else { - if (dem.repType == 0) { // asexual reproduction - ngenes = 1; - } - else { // sexual reproduction - ngenes = 1; - } - } - // CURRENTLY INDIVIDUAL VARIATION CANNOT BE SEX-DEPENDENT - double mnS0[2], mnAlpha[2], mnBeta[2], sdS0[2], sdAlpha[2], sdBeta[2]; - for (int g = 0; g < ngenes; g++) { - mnS0[g] = mnAlpha[g] = mnBeta[g] = sdS0[g] = sdAlpha[g] = sdBeta[g] = 0.0; - // individuals may have been counted by sex if there was - // sex dependency in another dispersal phase - if (ngenes == 2) popsize = poptraits.ninds[g]; - else popsize = poptraits.ninds[0] + poptraits.ninds[1]; - if (popsize > 0) { - mnS0[g] = poptraits.sumS0[g] / (double)popsize; - mnAlpha[g] = poptraits.sumAlphaS[g] / (double)popsize; - mnBeta[g] = poptraits.sumBetaS[g] / (double)popsize; - if (popsize > 1) { - sdS0[g] = poptraits.ssqS0[g] / (double)popsize - mnS0[g] * mnS0[g]; - if (sdS0[g] > 0.0) sdS0[g] = sqrt(sdS0[g]); else sdS0[g] = 0.0; - sdAlpha[g] = poptraits.ssqAlphaS[g] / (double)popsize - mnAlpha[g] * mnAlpha[g]; - if (sdAlpha[g] > 0.0) sdAlpha[g] = sqrt(sdAlpha[g]); else sdAlpha[g] = 0.0; - sdBeta[g] = poptraits.ssqBetaS[g] / (double)popsize - mnBeta[g] * mnBeta[g]; - if (sdBeta[g] > 0.0) sdBeta[g] = sqrt(sdBeta[g]); else sdBeta[g] = 0.0; - } - else { - sdS0[g] = sdAlpha[g] = sdBeta[g] = 0.0; - } - } - } - if (writefile) { - if (sett.sexDep) { - outtraits << "\t" << mnS0[0] << "\t" << sdS0[0]; - outtraits << "\t" << mnS0[1] << "\t" << sdS0[1]; - outtraits << "\t" << mnAlpha[0] << "\t" << sdAlpha[0]; - outtraits << "\t" << mnAlpha[1] << "\t" << sdAlpha[1]; - outtraits << "\t" << mnBeta[0] << "\t" << sdBeta[0]; - outtraits << "\t" << mnBeta[1] << "\t" << sdBeta[1]; - } - else { // sex-independent - outtraits << "\t" << mnS0[0] << "\t" << sdS0[0]; - outtraits << "\t" << mnAlpha[0] << "\t" << sdAlpha[0]; - outtraits << "\t" << mnBeta[0] << "\t" << sdBeta[0]; - } - } - } - - if (writefile) outtraits << endl; - - for (int s = 0; s < NSEXES; s++) { - ts.ninds[s] += poptraits.ninds[s]; - ts.sumD0[s] += poptraits.sumD0[s]; ts.ssqD0[s] += poptraits.ssqD0[s]; - ts.sumAlpha[s] += poptraits.sumAlpha[s]; ts.ssqAlpha[s] += poptraits.ssqAlpha[s]; - ts.sumBeta[s] += poptraits.sumBeta[s]; ts.ssqBeta[s] += poptraits.ssqBeta[s]; - ts.sumDist1[s] += poptraits.sumDist1[s]; ts.ssqDist1[s] += poptraits.ssqDist1[s]; - ts.sumDist2[s] += poptraits.sumDist2[s]; ts.ssqDist2[s] += poptraits.ssqDist2[s]; - ts.sumProp1[s] += poptraits.sumProp1[s]; ts.ssqProp1[s] += poptraits.ssqProp1[s]; - ts.sumDP[s] += poptraits.sumDP[s]; ts.ssqDP[s] += poptraits.ssqDP[s]; - ts.sumGB[s] += poptraits.sumGB[s]; ts.ssqGB[s] += poptraits.ssqGB[s]; - ts.sumAlphaDB[s] += poptraits.sumAlphaDB[s]; ts.ssqAlphaDB[s] += poptraits.ssqAlphaDB[s]; - ts.sumBetaDB[s] += poptraits.sumBetaDB[s]; ts.ssqBetaDB[s] += poptraits.ssqBetaDB[s]; - ts.sumStepL[s] += poptraits.sumStepL[s]; ts.ssqStepL[s] += poptraits.ssqStepL[s]; - ts.sumRho[s] += poptraits.sumRho[s]; ts.ssqRho[s] += poptraits.ssqRho[s]; - ts.sumS0[s] += poptraits.sumS0[s]; ts.ssqS0[s] += poptraits.ssqS0[s]; - ts.sumAlphaS[s] += poptraits.sumAlphaS[s]; ts.ssqAlphaS[s] += poptraits.ssqAlphaS[s]; - ts.sumBetaS[s] += poptraits.sumBetaS[s]; ts.ssqBetaS[s] += poptraits.ssqBetaS[s]; - } - } - } - return ts; -} - -//--------------------------------------------------------------------------- - -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- -//--------------------------------------------------------------------------- - - diff --git a/Utils.cpp b/Utils.cpp deleted file mode 100644 index 9d36b92..0000000 --- a/Utils.cpp +++ /dev/null @@ -1,26 +0,0 @@ -#include "Utils.h" - -const string Int2Str(const int x) -{ - ostringstream o; - if (!(o << x)) return "ERROR"; - return o.str(); -} -const string Float2Str(const float x) { - ostringstream o; - if (!(o << x)) return "ERROR"; - return o.str(); -} -const string Double2Str(const double x) { - ostringstream o; - if (!(o << x)) return "ERROR"; - return o.str(); -} - -// Evaluate a lambda and assert we get the correct error -void assert_error(const string& exptd_err_msg, void (*lambda)(void)) { - string err_msg{ "No error.\n" }; - try { lambda(); } // evaluate - catch (exception& e) { err_msg = e.what(); } - assert(err_msg == exptd_err_msg); -} \ No newline at end of file diff --git a/Utils.h b/Utils.h deleted file mode 100644 index 34854a7..0000000 --- a/Utils.h +++ /dev/null @@ -1,18 +0,0 @@ -#ifndef UtilsH -#define UtilsH - -#include -#include -#include - -#include -using namespace std; - -const string Int2Str(const int x); -const string Float2Str(const float x); -const string Double2Str(const double x); - -// Evaluate a lambda and assert we get the correct error -void assert_error(const string& exptd_err_msg, void (*x)(void)); - -#endif // UtilsH