Preparing animal input data for model run

[nickwctan]

This goal of this issue is to document and streamline the animal data files for model run, especially for functional groups data.

We want to ensure that:

• input data files, such as functional groups are in the correct format
• spatial resolution is coherent with model grid (9x9 grid cells?)
• temporal resolution is appropriate. Some model constants are currently defined in daily or monthly interval.
• ensure the model can access required data stored in NetCDF

We expect the following steps to be needed:

• Determine extent specified by the user for a new model run
• Determine standard formats used by model for animal input
• Create a new generation script in Python (and in R eventually as well) called (let’s name it for now) “animal_example_data.py” script to load the data from CSV files (primarily derived data files in the VE data science repo.

Eventually we should discuss with other data team and standardising the data pipeline.

[nickwctan]

At present, the only file related to animal module is virtual ecosystem/example_data/config/animal_functional_groups.toml which specifies the (obviously) functional groups and the associated life history traits (diet, reproductive strategy etc.) of the animals we would like to place in our grids. Am I correct?

Now should there be any other files needed for a model run with the animal module? I assume there would be a generation script to “create” our data input files.

Would be great to hear your thoughts on this. @TaranRallings

Thanks!

[annarallings]

It would be good to identify any parameters that may be commonly modified for different types of scenarios and see how they are coded into the model right now. Might be good to flag for configuring the model or for changing up the formats if need be in the future (e.g. there are many rates that we're collected for different aspects of the model that aren't related to the functional groups).

[Baizurah]

Adding to Nick's comment on animal module input files:

• Currently the functional groups file are classified in TOML format.
• Each group requires certain information ie: which animals it covers (taxa), what it eats (diet), whether it’s warm or cold blooded, adult weight and etc.
• Densities/allometric rule can be set by using “damuth” or “madingley” values.
• Movement/status can be set through static, migrate/active etc.
• Grid size- default using 9x9 grid, though I expect eventually this might be something that can tweaked, considering that we want to include movement of cohort?
• Time steps- Most daily actions run on daily basis (ie: feeding, metabolism). Major events can be customized.

File types to use:
NetCDF= environmental variables
TOML/CSV for functional groups and classifications.

Expectations:

• values in certain classifications are finalized esp those relate to range/toy values, ie: pop densities of certain group, missing values for stoichiometry info, basically sync with new data acquired.
  -steps that checks each functional group entry has the required files like what we have currently in animal.config.toml
  -Identify if there are any possibilites/relevance to swap between dammuth/madingley as choice of allometric rule for initial densities. Dammuth mainly focus on mammals, while madingley provide global data on other functional group.

This is more to self note or anyone feel free to clarify..

1. Is there any info on how many cohorts are needed per funtional group and is this configureable?
2. Is there any information on adult mass needed before a cohort can be reproduce?

[TaranRallings]

To initialize the animal model, the core need is the list of functional groups and their traits as is found in example_functional_group_import.csv. To support this, a few other things will need to be set for any given run of the model:

1. density_scaling_method can be set to Damuth if needed but defaults to Madingley
2. target_cohorts_per_fg - the number of desired cohorts per functional group to initialize the model
3. minimum_cohort_size - the minimum number of individuals in a cohort to initialize the model

2 and 3 are computational issues that we will have to experiment with to find what works well. This is an artefact from dropping from Madingly's spatial resolution of one degree grid cells down to a single hectare. Density scaling method is just a framework for letting people experiment with allometric density assumptions. Currently, nothing else that is specific to the animal model needs to be set.

Issues like grid number are set at the level of the whole simulation. The 9x9 grid is purely for construction purposes and we expect the working grids to be both much larger and to vary in size significantly.

1. Is there any info on how many cohorts are needed per funtional group and is this configureable?

As above, this is something we will have to determine for ourselves but will be configurable.

2. Is there any information on adult mass needed before a cohort can be reproduce?

adult mass is the mass at which a cohort can begin to turn excess mass into reproductive mass. When reproductive mass hits 0.5 adult mass, a reproductive event occurs.

[davidorme]

I think the critical thing here is that the system for animals is different from the plants in a many ways.

Plants:

• Has a library of PFTs that provide a flora for the simulation but these don't have to be used
• Has a separate file that defines cohorts per cell: this cell ID, this PFT, this size.

Animals (if I understand correctly @TaranRallings!):

• Has the functional group definition - if a group is in this input file, then it is in the model. The FG either defines a target density within the simulation or that density is determined internally from the AnimalModel constants, which provides population density terms by diet type.
• The cohort structure of the individuals within the FG is determined within the model using scaling laws.
• The initial locations of the cohorts across cells is determined randomly.

[TaranRallings]

@davidorme I think that is more or less correct. Cohort structure is now partially determined by model configuration through target_cohorts_per_fg and minimum_cohort_size, and the functional group's density trait but the internal scaling otherwise sets the density.

I think it will be a good idea to bring the two systems into alignment. What you are describing in the plant model's configuration are desirable for the animal model as they give more precise control for people who want it, they just haven't been pressing so far.

The list of functional groups that @annarallings is defining will be turned into an internal optional library. The second file is desirable but not currently in the works.

[annarallings]

The list of functional groups that @annarallings is defining will be turned into an internal optional library. The second file is desirable but not currently in the works.

Please see Functional Group model levels (contact me for access if you can't get in)

[Baizurah]

@TaranRallings Thanks for your helpful comments. @annarallings I could not get access to the link. I've got the 404 ERROR.

[nickwctan]

Thanks guys. This has definitely brought more light into the animal module. Discussing this will also help us to plan our study design in the resilience paper.

So if I understand correctly, for model initialisation in the future, the number of individuals in a cohort will be determined by minimum_cohort_size, in which the number of cohorts per functional group will be determined by target_cohorts_per_fg.

density_scaling_method (I assume similar to the first part of code in scaling_functions.py) determines the population density of that Animal Cohort [individuals/m2]. How does that differ from minimum_cohort_size? Are these going to be two different configurations to determine no. of individuals in a cohort to initiate the model?

Adding to the discussion to determining cohort structure, I agree that perhaps having a similar structure as the plant model with a PFTs file and example_plant_cohorts.csv would be beneficial to be able configure individual cohort size in each different grid cell as required by the user (although as I understand from Taran, that is not a priority yet).

The list of functional groups that @annarallings is defining will be turned into an internal optional library. The second file is desirable but not currently in the works.

Please see Functional Group model levels (contact me for access if you can't get in)

It's on sharepoint and I do not have access to it yet unfortunately :(

[annarallings]

I've put a copy on Google Drive: https://docs.google.com/spreadsheets/d/1VqsGKD4WWffq9liD1jrZPwMmoYI9c7OW/edit?usp=sharing&ouid=114698470455787851518&rtpof=true&sd=true
(this has limited access just for data privacy, but Bai and Nick I've added you to the access list)

[Baizurah]

Thank you Anna, I will have a look.

[Baizurah]

@TaranRallings Thank you for your clarification. It does helps a lot! Does the animal module currently operates automatically at the start and mostly for pop density, will still use the density scaling law (mainly the diet type, ie: herbivorous mammals etc)?

[TaranRallings]

Does the animal module currently operates automatically at the start and mostly for pop density, will still use the density scaling law (mainly the diet type, ie: herbivorous mammals etc)?

I don't quite understand the question, can you elaborate?

[nickwctan]

So if I understand correctly, for model initialisation in the future, the number of individuals in a cohort will be determined by minimum_cohort_size, in which the number of cohorts per functional group will be determined by target_cohorts_per_fg.

density_scaling_method (I assume similar to the first part of code in scaling_functions.py) determines the population density of that Animal Cohort [individuals/m2]. How does that differ from minimum_cohort_size? Are these going to be two different configurations to determine no. of individuals in a cohort to initiate the model?

Just went through Taran's code in animal_model.py and found the answer to my question above.

The total number of individuals for the whole area is estimated through density_scaling_method. These individuals are then distributed into cohorts following minimum_cohort_size (min. number of indiv. in a cohort) and target_cohorts_per_fg (ideal number of cohorts).

This comment is more of a note-to-self.