Proposal for new "Colonization" module

[chaukap]

Update: The name of the module has been changed from "invasion" to "colonization". Any references to "invasion" below should be treated as if they read "colonization".

After considering what we would like to use seed dispersal for, I have come up with a different way of thinking about seed dispersal "initialization" that would allow us to decouple it from spinup altogether. My goal is to allow the specificity that we discussed in the meeting on 1/17/2020 but also keep the inputs simple to understand.

Background

In the meeting we discussed how to initialize seed dispersal. As discussed in issue #326, seed dispersal necessitates a way to establish individuals before we can let them spread using seed dispersal. Our initial thought was a new form of initialization, seed dispersal initialization, which would create a seed bank for each species to establish for N years where n is specified in inputs. My understanding is that the group would also like the ability to initialize seed dispersal later in the simulation, for example year 50.

Problem

There are a few reasons that having two initialization options, specifically two options that are so different, would be a problem:

• Seed dispersal initialization and spinup would be run side by side and would not be mutually exclusive. This might be confusing to the user. For example:
  • What if the user requests both types of initialization for a single species? Would this throw off the balance of the ecosystem?
  • What if the user forgets to turn on an initialization method for a species that is using seed dispersal? Should we fix it, warn them, or let them find their mistake in the output files?
• If we want to begin seed dispersal initialization later in the simulation, say at year 50, the initialization module is poorly equipped to handle this.
  • Initialization was intended to be run before any statistics were collected, i.e. before the actual simulation ever began. All of the logic that I put in place for initialization (specifically for spinup) would be useless if we want to run something in the middle of the simulation.

Introduction

It is therefore my opinion that we should avoid putting seed dispersal initialization into the initialization module. In fact, I believe we should scrap the idea of seed dispersal "initialization" entirely, and look at the whole process from a new point of view. What we are really looking for is a way for species to invade an ecosystem in a specific year, and see how the ecosystem responds. With seed dispersal all we need is a way to seed the invasive species, then let the plants begin dispersing seeds as described in the paper.

Proposal

I think we should add an entirely new module to the code called invasion. This module would be responsible for establishing all invasive species using seed dispersal. The user would be able to control the year the invasion event begins, which cells it affects, and how long it lasts. During the "invasion" the invasive species would always have a seed bank available meaning it would always be able to establish.

Implementation

The invasion module would require its own input CSV with four input parameters as shown here.

Each row in this file would be called an "invasion event". For each invasion event the user must specify the cell it affects, the species that is invading, the year to begin, and the amount of time to keep the seed bank full before the species must begin establishing on it's own.

In the example above there are two invasion events:

1. Cheatgrass invades cell 1 starting at year 50 with a seed bank that will last until year 56, after which establishment according to the paper will begin to occur.
2. Sagebrush invades cell 4 in year 1 with a seed bank that lasts 10 years. After which time establishment according to the paper will begin to occur.

Note that in event 2 we are invading in year 1, which would have the same effect as running the seed dispersal "initialization" option I would like to avoid implementing.

From a programming perspective this new module would be simple to write. It would be run every year before establishment and look something like this:

If the user requested at least one invasion event this year
    Determine the species they would like to invade with
    Determine the cell(s) they would like to invade
    For those species
        For those cells
            theCell->mySpecies[sp]->seedsPresent = TRUE;

And then, when the establishment module is run, the invading species would have a chance to establish.

Advantages

I believe this implementation provides some distinct advantages:

• Establishment of species would become both species-specific and cell-specific. Currently it is only species-specific.
• The number of invasion events is arbitrary. A species could invade multiple times during a simulation.
• All of the functionality planned for seed dispersal initialization would still be possible by setting Start Year to 1.
• Invasion and Initialization would be completely decoupled. No need to worry about choosing one or the other or neither.

Of course this is ultimately an ecological decision and if we want to implement it some other way please let me know. @kpalmqui, @dschlaep, @ScottCJr if you have time I would like to get all of your opinions on this.

[kpalmqui]

@chaukap just a few nuanced comments:

1. species that are "invading" (really colonizing) a landscape do not need to be "invasive" species per se. Let's avoid using the language invasive species anywhere in the documentation. Specifically, I am referring to your comment:

This module would be responsible for establishing all invasive species using seed dispersal.

BRTE is an invasive species and the user would not always have to use the invasion module for it to establish in STEPWAT2. Instead, this is a way for a species to begin colonizing the grid via seed dispersal at some time that is specified by the user. That could be Year 1 or Year 50.

2. I am confused by your comment:

Cheatgrass invades cell 1 starting at year 50 with a seed bank that will last until year 56, after which establishment according to the paper will begin to occur.

While seeds would be present in cell 1 at year 50 to year 56 under this specification, normal establishment would still have to occur (i.e. a random number draw compared to pestab). Therefore, I am confused by when you mean by

establishment according to the paper will begin to occur

[chaukap]

@kpalmqui Addressing your comments:

1. "Colonization" seems like a better name for this module, to make it more generalized.
2. When I say establishment according to the paper I mean seed dispersal establishment. Basically, for 5 years Species[sp]->seedsPresent will be TRUE. Therefore the species will still have to perform the random number draw compared to pestab to establish.

[kpalmqui]

@chaukap "Colonization" sounds good.

I think were are on the same page about 2. It was just a little confusing to me as worded.

[chaukap]

@kpalmqui sorry for the confusion, I'm still trying to nail down the specifics but I believe we are on the same page. It seems to me that this module would have to do two things for a colonization event:

1) set Species[sp]->seedsPresent = TRUE
2) if Species[sp]->use_me is FALSE, set it to TRUE.

That way, regardless of whether or not seed dispersal is turned on, this module will undoubtedly allow the species the chance to establish in the given cell.

[kpalmqui]

@chaukap this is great. Definitely on the same page.

[chaukap]

@kpalmqui With your permission I'll implement this module and commit it as soon as possible. That way we can discuss the actual code, and if we decide we don't like it I can always roll back the commit.

[kpalmqui]

@chaukap given that we think this is how we want to move forward, despite awaiting feedback from the group, you can move forward with implementing this module

[dschlaep]

I was tagged initially here. I skimmed the proposal and discussion here and quite like it, particularly after renaming it to colonization.

One point that came to mind was the application of this module to simulate restoration action, e.g., seeding of a large area at a specific point in time. I know that we have "startyr" in rgroup.in; however, this "startyr" approach seems simplistic to what is proposed here.

To facilitate inputs for a simulation where a restoration activity seeds across many/all cells, it may be convenient to have a way to provide inputs other than list each cell separately. Would we want a symbol, e.g., -1, as input to mean all cells, and allow ranges of cells, e.g., 51-100, to mean cells between cell IDs 51 and 100? I know this is only about user convenience not functionality.

[kpalmqui]

@dschlaep thanks for your review and comment. Were you thinking these additional parameters would be provided in the .in file where we also turn on the "colonization" module?

[dschlaep]

Sorry for not making my idea clear: I meant that this would be additional ways to provide inputs to the table described above "The invasion module would require its own input CSV with four input parameters as shown here.", e.g.,

Cell	Species	Start Year	Duration
1	brte	50	5
-1	artr	1	10
51-100	phho	10	1

[kpalmqui]

@dschlaep thanks for the clarification - this is a great idea and both Chandler and I agree that this is how we should move forward. Thanks again!

[chaukap]

@dschlaep Thank you for weighing in! I agree with your suggestion and I'll create an issue to specify multiple/all cells in one line.

[chaukap]

@kpalmqui @dschlaep I have the basic implementation ready to use. Issue #443 is next on my list but if either of you want to test out the module feel free!.

[chaukap]

After some testing I am pleased to say that the colonization module works as expected. I used a 9 x 9 grid, no initialization, seed dispersal turned on for sagebrush, and colonized cells 0 - 3 at year 50 for 10 years. Sure enough, sagebrush appeared in cells 0 - 3 between years 50 - 54 (remember it still has to pass the pestab test) and once individuals reached maturity Sagebrush began appearing in the other cells that had not been marked for colonization. There were even some instances where sagebrush disappeared from cell 0 only to reestablish via seeds from the other cells.

[dschlaep]

Sounds awesome!

[kpalmqui]

@chaukap is there a flag to tell the program that the colonization module will be used?

Is the "seeds" initilization method now obsolete in grid_setup.in?

Thanks for the clarification here. I also believe we need to add some documentation of this colonization module somewhere in the inputs. Any thoughts on that?

[chaukap]

@kpalmqui The colonization module is turned off by removing all colonization events from grid_colonization.csv. If you would like a binary flag that would allow colonization to be turned off while leaving grid_colonization.csv populated I could easily add it.

You are correct that "seeds" is completely obsolete. It should most definitely be removed from the code and documentation, but that also raises another point:

It looks like "spinup" will remain the only initialization option for the foreseeable future. Therefore, "initialization" and "spinup" are synonymous and using both words seems confusing for people trying to use the program (as we witnessed during the group call). My proposal is to simplify the initialization module by merging "spinup" and "initialization". Basically, in grid_setup.in, instead of specifying "spinup" or "none" for initialization the user could just specify "on" or "off". I could also simplify the code to make it a little faster.

I think we should discuss initialization during our call this week before we change anything.

And finally, we definitely need to document the input file. I'm thinking this would be a good opportunity to create a wiki page entry that thoroughly explains the file. While we're at it I could also document all of the grid input files in the wiki, then we can reference the entries in README.md to make them easier to find.

[chaukap]

@kpalmqui I just created a wiki entry for grid_colonization.csv here.

[kpalmqui]

@chaukap great idea! This is wonderful. Sounds good regarding discussing "initialization" during our call on Wednesday

[chaukap]

The colonization module has been completed. You can find high-level documentation of the module in the wiki.