response_to_referees.Rmd

---
title: "Response to referees"
date: \today
output:
    pdf_document:
        includes:
            in_header: mystyles_ED.sty
---

>We thank the reviewers and the editor for their positive comments and their
insightful feedback on the manuscript and the code. We found these comments
helpful for improving both. We re-submit an improved manuscript incorporating
the reviewers' suggestions. Mainly, we have changed the package name and
have extended our argumentation about why we think the field would benefit
from this implementation of the bio-energetic model of Yodzis and Ines (1992).

## Associate Editor's comments to the Author:

I have received two reviews for this manuscript; both broadly positive but
with constructive suggestions that will improve the manuscript. Reviewer
1 in particular questions how widely this will be used - some expansion of
section IV would be useful here.

> We agree that a better contextualization will allow to see how widely this
model has been used and still is. We have included a table as Supplementary
Material, presenting the past uses of Yodzis & Ines (1992) bio-energetic model
from 2007 until today. We believe that this table illustrate how broadly this
model can be used, and especially the variety of questions it allows answering.

Much is made of the high performance nature of the code here, but no benchmarks
are provided and no comparisons with competing approaches are provided. Is
this modelling work routinely limited by speed?  And is the step change
in speed here enough to help this? Given that most ODE solvers find their
way into heavily optimised compiled code, it's not immediately clear there
will be a significant difference. Some clarification here may help justify
the statements.

>We agree with this statement -- this being said, `ODE.jl` is a native
implementation of some common numerical solvers, so no time is spent exchanging
information between the Julia code and the wrapped library. At a higher level,
Julia is natively designed for parallel / distributed computing, so very
naive approach should see almost linear speed-ups on multicore machines. In
addition, a benchmark would make sense only if the other solutions were (i)
widely used and (ii) feature equivalent.

Also I note that on ODE.jl the README says: *"Need something long-term reliable
right now? See the Sundials.jl package, which provides wrappers for the
excellent Sundials ODE solver library."* (among other statements of
instability). Is this overstated?

>In part, yes. The instability refers not to the behavior of the code, but
to the API itself, meaning that it may change in future releases. However,
because we have organized the code so that all calls to ODE.jl go through
a single function, and it will be easy for us to track API changes. In
over a year of working with ODE.jl, we have noted no change in API (and no
difference in performance when using this or Sundials.jl). We will also revert
to Sundials.jl once a very specific memory management in the library they
wrap will be solved; this currently means that there is a memory leak under
some situations, which result in multiple successive simulations aborting.

## Reviewer 1

This is a clearly written Application note, introducing a julia package for
simulating biomass dynamics in community food webs. I don't know a lot
about foodwebs and biomass dynamics (I assume I was chosen as a reviewer
because I am familiar with julia), so I will just remark on the
presentation and application here. The application appears to do what it
promises with a reasonably intuitive interface. The documentation looks
thorough and accessible and the code is clean and appears efficient. There
isn’t a lot of code as the package draws extensively on existing
functionality in other julia packages, but that is in accordance with good
coding practice.

>We thank the reviewer for his positive comments; as is the case for most
languages with thriving package ecosystems, we indeed draw on the work of
the community to avoid re-implementation of existing features. We have taken
care to write most wrapper code as single, short, well-tested functions,
so that we will be able to track API changes should they arise.

At present, though, I don’t think the authors make a compelling case that
 this software will be taken up and used widely in the field. One of the
 motivations for publishing software papers is to make tools that may be
 used broadly and generally available to the wider ecological community, to
 enhance reproducibility and efficiency among ecologists. I think it would
 be nice if the authors could provide, e.g. a list of published papers since
 2008 that have used the underlying mathematical model and could have
 benefitted from having this package available, and perhaps include as an
 example a reanalysis of one of these papers that directly demonstrates how
 easy it is with this package. If that is not feasible, then at the very
 least look ahead and highlight how this package has broader general
 applicability.

 >As shown in the table now added as Supplementary Material, the Yodzis & Ines
 (1990) bio-energetic model has been widely used to this days in community
 ecology, and helped produce some influential results.  Each of the study
 presented in the table used their own implementation, and none (except
 the most recent) were released to date, making it difficult to reproduce
 their results. The fact that the bio-energetic model can be applied to any
 type of community, and that it can be used in combination with other model
 (such as the nutrient-intake model, Brose et al., 2005a,b; Brose et al.,
 2008) make it a broadly used model in community ecology. In addition, some
 of the authors have used this model extensively for teaching. Although this
 did not result in publications, we believe that this type of packages is
 valuable as a teaching tool too.

 >However, we have not included a re-analysis of one of these papers because
 we do not know what choices were made regarding the simulation or some of the
 parameters -- although use case IV.ii (Effect of consumer-resource body-mass
 ratio on stability) is close to Brose et al. (2006) analysis. Adding explicit
 reproduction of previous studies would require to dig into why and how the
 results differ, and this is a rabbit hole we do not intend to dig ourselves
 in: even minute changes in simulations parameters or implementation choices
 can have quantitative consequences on the results. We think that the simple
 use cases and the table now presented in the manuscript are sufficient to
 illustrate how broadly this model has been (and still is) used.

It did strike me as strange that the paper has 5 authors from different
institutions, but the julia code seems to be written exclusively by the
last author. At least the local git (non-github) repository has 100% of
commits from the last author, so e.g. the first author appears to never have
contributed to the application code. I am sure there is a good explanation
for this, it just appears odd at first glance, so perhaps a clear author
contributions statement would be useful.

>Authors ED and TP contributed most of the code, which is based on a
preliminary C version by DG, and was modified during discussions with UB
and DBS. The github version is a mirror of our in-house git server (as of
this revision, the GitHub version is the one used for active development).
Due to the way we handled merging branches and pushing to the mirror, changes
were attributed to TP regardless of who committed them. We will now move the
package entirely to github to ensure proper attribution tracking. Should the
associate editor need it, here is the list of contributions: TP and ED wrote
the package, based on original code by DG reproducing the model as described
by UG. DBS and TP and ED came up with the strategy for tests. ED and DBS
and TP decided on the use cases. ED wrote the manuscript with feedback from
all authors.

I have a number of minor suggestions for impovement, in no particular order:

 1. The package is called ’befmw’, perhaps following a common R
 convention of having short abbreviations for package names. The julia
 metadata maintainers prefer long readable package names, such as
 ”BioEnergeticFoodwebs.jl” (so do I). It would be useful to make sure that
 the package is tagged in METADATA before publication, so that any name
 change suggestions from the julia package maintainers can be reflected in
 the application note.

>We do agree with this suggestion -- during the revisions, we tagged the
package into METADATA and changed its name to `BioEnergeticFoodwebs`. The
current version is `0.1.0`, and version `0.1.1` has been submitted and will
be available in METADATA soon.

2. The author response now highlights an online wiki documentation,
 but that isn’t mentioned in the MS as far as I can see -- I think it should
 be highlighted clearly.

>The online documentation is mentioned in part III (Implementation and
availability), with the corresponding link. We moved the documentation to the
package source code itself, and the new URL is given in the paper. We also
added a link to a discussion room for instant help / feedback on package use.

3. The documentation mentions that many linux distros have a julia
 package, but that is not the recommended way to install julia on linux –
 installation should be via tarball from julialang.org.

>We agree that the recommended way to install anything is indeed to use the
sources from the website -- though an overwhelming majority of users, ourselves
included, tend to use the packages from their distributions. Because we test on
the current, past, and future version of Julia, we are confident that all
versions that are 'out there' will be able to work with our package. However,
we now precise in the documentation that the recommended way to install Julia
on Linux is via tarball from julialang.org.

4. I don’t think the function name ’nichemodel’ is ideal, as that term
 is used for many different things in ecology.

> We agree that the term *niche* is widely used in ecology but we also
argue that the particular term *niche model* is well accepted in food web
ecology and, as it can be seen in the SUpp. Mat. table, is widely used in the
literature to describe the model we implemented under the name `nichemodel`. We
think that it is a clear reference to Williams and Martinez (2000) niche model
and that choosing another name for this function might be confusing for users.

5. Line 71: ”is an important effort” - ”is important”.

>We thank the reviewer for this suggestion, we corrected the manuscript
accordingly.

6. The sentence line 61-63 is unclear.

*Simulation-based studies are more at risk than analytical-based ones, since
the computational aspect is an additional layer of complexity on the
mathematical one.*

>We have chosen to remove this sentence from the manuscript, as it was not
necessary to the understanding of this paragraph.

7. Line 89: ”independant” - ”independent”

>Corrected.

8. Line 127 mentions ’vertebrates’ and Fig 1. mentions ’ectotherms’,
 but it is not clear from the preceding presentation of the model what the
 effect of incorporating these factors is.

>We thank the reviewer for pointing out to this inconsistency (here,
*vertebrate* refers to *ectotherm vertebrates* only, which is now the term used
throughout the manuscript), we also have clarified the effect of changing this
parameter in a new paragraph (lines 117-122).

9. It is not clear why the code snippet in line 214 needs to include
 trophic rank.

 `vert = round(Bool,trophic_rank(A).>1.0)`

>This line of code create a vector determining whether the organism $i$ is an
ectotherm vertebrate (`vert[i] = 1`) or not (`vert[i] = 0`). The inclusion of
the trophic rank is not necessary for the computation of the biomass dynamics,
as this parameter is not used for producers (because for producers `trophic_rank =
1`), but it would be ecologically incorrect to have primary producers being
vertebrate, that is why we have chosen to precise this argument.

10. Fig. 2 caption: ”sahded” - ”shaded”

>Corrected.

## Reviewer 2

This Application Note presents a new implementation of a popular
bioenergetic model of food web dynamics, aiming to replace the
idiosyncratic models implemented by numerous authors with an easy-to-use
standard.

I have downloaded Julia and the befwm package, and tried some of the
functionality presented in the manuscript and on the authors' website.
There were a few minor inconsistencies (the arguments do not always seem to
match between the code in the manuscript and in the tutorial), though some
of this may be my lack of familiarity with the language, and the natural
process of working through the development of a package in a rapidly evolving
language. Otherwise I found the functions intuitive and the structure of
the objects well-suited to the goals.

>We thank the reviewer for his/her positive comments and his insightful
remarks, which we found useful in improving our work.

>We also thank the reviewer for pointing at the inconsistencies between the
code presented in the manuscript and the tutorials, we have been through
both and corrected the mistakes we could find.

While there is little new in this manuscript in terms of methods
development, I expect that the availability of a standard and reliable
implementation of the Yodzis & Innes model and its descendants will be of
interest to a good number of food web ecologists. The model itself is
well-documented in the manuscript, and the functions are outlined well in
the tutorials. This will be especially important given that Julia is likely
to be new to the majority of end-users, though its performance and
simplicity seem likely to grow its popularity over time, and some of the
R-Julia interfaces may help people wanting to continue to work in the R
environment (though I have not tried these yet). I could also see this
turning into a useful teaching tool at multiple levels.

>We agree that the package presented here do not present a methodological
novelty, which in our opinion should be the case for software papers:
to present an implementation of existing methods or models. As emphasized
by the reviewer, we think that having a reliable implementation of this
influential model will be useful for many food-web ecologists by improving
both the reliability and reproducibility of their analysis. We are aware of
the R-Julia interfaces, but have not tested them extensively. The way they
work at the moment require to write the exact same amount of Julia code,
and then some R code on top -- instead, we have offered the opportunity to
export simulation output as JSON (which the many R JSON libraries can read).

I have only a few relatively minor comments:

The measure referred to as `foodweb_diversity` (P8 L159) is identical to the
evenness component (J') of the Shannon H' index, is it not? The explanation
is a bit convoluted for something that should be familiar to ecologists, and
ideally the function would have been called `foodweb_evenness` or something,
as the diversity index itself may also be of interest to users.

>The measure referred to as `foodweb_diversity` is indeed identical to the
evenness component of the Shannon index (a.k.a. Pielou's evenness), as noted
by the reviewer, which is a diversity index. We understand the view of the
reviewer, although we prefer that the name of the function actually refers
to what it is measuring instead of the name of the index itself.

In IV.i and figure 1, I suggest using outcome-neutral terminology in place of
"conditions of coexistence[or competitive exclusion]", because coexistence [or
not] is an outcome that may depend on the food web context.  Perhaps phrase
in terms of interspecific competition being greater than, equal to, or less
than intraspecific competition?

>We agree that the use of the terms *coexistence* and *competitive exclusion*
is not really adapted as it indeed refer to potential outcomes of the
chosen values of relative inter-specific competition. We have replaced
it in the text following the suggestions of the reviewer. We now refer
to inter-specific competition greater, equal or lower than intra-specific
competition. Although we kept the terms *coexistence*, *neutrally stable*
and *exclusion* in the figure, which represent the outcomes.

In the code for section IV.ii (p11-12) it appears that there is a missing
loop - scaling and the counter 'i' are not defined anywhere.

>We are thankful for the reviewer for pointing out this error, some
information were indeed missing, we thus corrected the code on pages 11-12.

The `species_persistence` function is not documented as far as I can see,
and it's not working on the output of a simulation for me. I would suggest
using the function instead of manually dividing by the initial richness in
the code in IV.iii, as it will be less likely to lead to errors if adapted
to other simulations (e.g. that vary starting richness).

>The `species_persistence` function is now documented, and a bug in it has
been fixed (in release `0.1.1`). The documentation can be accessed by typing
`?species_persistence` in Julia. In addition, we have added `species_richness`
as an output function (which avoids the problems identified by the reviewer).

There are a handful of typos throughout the manuscript, and some of the
references are formatted inconsistently.

>Corrected.