search

steps-dev / steps

steps: Spatially- and Temporally- Explicit Population Simulator
19 stars 7 forks source link

Mortality description is so confusion #27

Closed geryan closed 5 years ago

geryan commented 5 years ago

This function modifies a population by multiplying a spatial layer with populations in each timestep. The values of the input layers range between 0 and 1 and represent the proportion reductions in populations (e.g. 0 reduces the population to zero, whilst 0.5 reduces the population by 50

Consider a little rewrite as I find this behaviour counterintuitive, and suspect I'm not alone (sample size of 2). If I reduce a population by a proportion of 0.8 I would expect 80% mortality, and would expect a mortality value of 1 mean 100% mortality, but this function does the exact opposite. I suspect that many people might make this error. Irregardless of the deficiencies in my understandingness, I think it could be helpful if the description were a little clearer.

May I suggest something along the lines of the following:

This function modifies a population by a mortality layer included in a steps landscape object. The mortality layer consists of values from 0–1 and modifies the population by multiplying the population of a cell by the value of the corresponding cell in a mortality layer,

Thus a cell with e.g. 10 individuals before mortality and corresponding mortality layer cell with a value of 0.2 would have 2 individuals after modification, a mortality value of 1 would result in no mortality and a population of 10, and a mortality value of 0 would result in complete mortality and a population of 0.

Also, may be helpful to explain what happens with rounding.

plsxpln

cvisintin commented 5 years ago

Thanks Gerry. We have changed the documentation to read: "This function modifies a population by a mortality spatial layer included in a steps landscape object. The mortality layer consists of values from 0–1 and modifies the population by multiplying the population of a cell by the value of the corresponding cell in a mortality layer. For example, a cell with ten individuals before the mortality function is applied, and corresponding mortality layer cell with a value of 0.2, would have two individuals remaining after modification. Note, rounding also occurs after modification using a ceiling method (i.e the largest whole integer is retained)."