JOSS: Textual edits to paper

[kellykochanski]

This is a well-written paper overall, and backed up by even better documentation in the main repository.

I'm collecting proposed edits to the text here, organized according to the JOSS review criteria. (This issue will be edited and extended as I work through the paper and repository.) Most of these comments are answered in the documentation, and I won't penalize you for copying text over where relevant - these comments are intended to make the paper into a good standalone summary.

Summary

The summary clearly explains the mathematical and ecological interest in ecological networks, and discusses the suitability of Julia for analyzing them. However, it's not as compelling as it might be.

• Describe the uses of the package more specifically in the summary, perhaps with example use cases
• Either explain more specifically why Julia's typing system is particularly good for ecological network analysis, or remove the sentence claiming that it is good.

Statement of need

Again, this is a well-written statement that would be strengthened by specifics.

• Explain the problem you solve in terms of downstream/ultimate impact (e.g. better ability to predict animal population declines?) instead of process (ecological network analysis). This should probably go in the first couple sentences.

State of the field

I don't actually see a section on the state of the field. Please add one that answers the questions below:

• What other software packages are available for modeling ecological networks?
• How did that software limit/enable ecology research? What does your package change?
• In what situations is your package more useful than existing packages?

Quality of writing

The writing quality is good overall :)

My main critique is, as above, that the paper doesn't give me a very clear idea of what the software does. It explains the inputs (mangal.io) clearly; the backend analysis method (ecological networks, graph theory) vaguely; the usage clearly (use cases); and the outputs vaguely. I believe it is important to explain the method and the outputs more clearly, as this will help users decide whether or not your software is appropriate for their usage. I think this could be done best by creating clear subtitles in the paper such as, "input", "method", "output products", "example use/use cases".

• Explain analysis methods clearly, either in the text or by appropriate references to papers or docs.
• List/explain the outputs that this software can produce.

I've put a few line-by-line suggestions below. Since I'm mainly evaluating the software, I won't delay acceptance of your paper based on these points.

• Capitalize department names ('Biology') in institutional affiliations
• Should use cases be past tense (your work), or present tense (examples for users)?
• (Nitpicking) "Diverse measures" is much clearer than "A diversity of measures" (statement of need)

References

Good work including all the dois!

[FrancisBanville]

Thank you so much for your valuable feedbacks @kellykochanski.

The modified manuscript is in the branch joss-article-review1. We hope that we have adequately addressed your comments.

Summary

We added a sentence in the summary describing in greater detail the uses of the software.

We chose to keep the statement that Julia's typing system is good for ecological research, and we explained more specifically why.

Statement of need

We added a brief explanation at the beginning of this section about the ultimate impacts of analyzing ecological networks.

State of the field

We added a section on the state of the field, in which we listed the main packages available for modeling ecological networks, in Julia and in other programming languages. We explained how our software is different and what are its added values.

Quality of writing

We added a figure on our proposed workflow, in which we explained the inputs, outputs, and analysis methods more clearly.

We also wrote our use cases in the present tense.