[REVIEW]: Omniscape.jl: Software to predict omni-directional landscape connectivity

[whedon]

Submitting author: @vlandau (Vincent Landau)
Repository: https://github.com/Circuitscape/Omniscape.jl
Version: v0.4.4
Editor: @melissawm
Reviewer: @juliohm, @tpoisot
Archive: 10.5281/zenodo.4466323

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/735ea484dee8a0ab28f10183aa420d77"><img src="https://joss.theoj.org/papers/735ea484dee8a0ab28f10183aa420d77/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/735ea484dee8a0ab28f10183aa420d77/status.svg)](https://joss.theoj.org/papers/735ea484dee8a0ab28f10183aa420d77)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@juliohm & @tpoisot, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @melissawm know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @juliohm

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@vlandau) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @tpoisot

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@vlandau) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @juliohm, @tpoisot it looks like you're currently assigned to review this paper 🎉.

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1111/j.0014-3820.2006.tb00500.x is OK
- 10.1137/141000671 is OK
- 10.1890/07-1861.1 is OK
- 10.1111/cobi.13230 is OK
- 10.21105/jcon.00058 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[melissawm]

👋🏼 @vlandau @juliohm @tpoisot this is the review thread for the paper. All of our communications will happen here from now on.

Both reviewers have checklists at the top of this thread with the JOSS requirements. As you go over the submission, please check any items that you feel have been satisfied. There are also links to the JOSS reviewer guidelines.

The JOSS review is different from most other journals. Our goal is to work with the authors to help them meet our criteria instead of merely passing judgment on the submission. As such, the reviewers are encouraged to submit issues and pull requests on the software repository. When doing so, please mention openjournals/joss-reviews#2829 so that a link is created to this thread (and I can keep an eye on what is happening). Please also feel free to comment and ask questions on this thread. In my experience, it is better to post comments/questions/suggestions as you come across them instead of waiting until you've reviewed the entire package.

We aim for reviews to be completed within about 2-4 weeks. Please let me know if any of you require some more time. We can also use Whedon (our bot) to set automatic reminders if you know you'll be away for a known period of time.

Please feel free to ping me (@melissawm) if you have any questions/concerns.

[vlandau]

@melissawm I slightly adjusted the title immediately after submitting a while back -- will that be reflected if/when the submission is accepted and published? Just wanted to double check. Thanks!

[melissawm]

Yes, the paper should be published under the new title, but I might need to check this upon acceptance. Can you please remind me to do that, just in case? :) Thanks!

[vlandau]

Yes, will do. Thanks! 🙂

[juliohm]

@vlandau can you please provide an example in the documentation that can be run easily? The example provided depends on a file that is not available. Also, can you plot the output of this example in the documentation? Ideally this example should come as one of the first things in your docs before you even start explaining the algorithm.

Also, can you please add a statement of need explaining why this functionality is important, and how other packages from other languages may provide similar functionality?

[tpoisot]

I concur with @juliohm - it would be good to have a fully runnable example, and the results shown in the paper.

[tpoisot]

@melissawm I can't edit the comment at the top (probably because I am not assigned)

[vlandau]

@juliohm yes definitely! I tried to get at the importance of the functionality of the package in the second paragraph in the motivation section -- I explain the value of the Omniscape algorithm, how it differs from the similar package "Circuitscape.jl", and that until now there was not a software package implementing it. Should I just shift that to its own "Statement of Need" section?

[juliohm]

I think I'm missing the context here. Someone coming for the first time in the subject will wonder why ominiscape ? What problems it addresses? You need to show the potential users what it is about and how the features are used in practical applications.

…

On Wed, Nov 18, 2020, 13:39 Vincent Landau ***@***.***> wrote: @juliohm <https://github.com/juliohm> yes definitely! I tried to get at the importance of the functionality of the package in the second paragraph in the motivation section -- I explain the value of the Omniscape algorithm, how it differs from the similar package "Circuitscape.jl", and that until now there was not a software package implementing it. Should I just shift that to its own "Statement of Need" section? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2829 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZQW3J3XOUJL34KV4QO5WTSQP2DVANCNFSM4TP2XSFQ> .

[vlandau]

@juliohm okay thanks, I'll elaborate on that a bit.

[vlandau]

@juliohm I gave it a shot in the latest commit, thanks!

[vlandau]

@whedon generate pdf

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[vlandau]

Working on adding a working example next.

[vlandau]

@juliohm @tpoisot please see the new Examples section in the docs. Following the example set by other Julia packages' documentation, I created a dedicated section for examples and linked to it in both the table of contents and the User Guide.

[melissawm]

@whedon re-invite @tpoisot as reviewer

[whedon]

The reviewer already has a pending invite.

@tpoisot please accept the invite by clicking this link: https://github.com/openjournals/joss-reviews/invitations

[melissawm]

@tpoisot please accept the invitation and let me know if that solves the issue. Thanks!

[juliohm]

@vlandau the example section you linked could be improved. Imagine that you are explaining this subject to someone that never heard of connectivity maps before. You need to plot the input images, display the entries of the resistance table, and how they can be interpreted, and finally display the result of the run_omniscape function, ideally without using a file, but instead the method with arguments. The easier you make the life of the reader, the more they will appreciate your work. Can you refactor the example like that?

[melissawm]

@whedon check references

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1111/j.0014-3820.2006.tb00500.x is OK
- 10.1137/141000671 is OK
- 10.1890/07-1861.1 is OK
- 10.1111/cobi.13230 is OK
- 10.21105/jcon.00058 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[melissawm]

@vlandau, A few final comments:

• In the reference Anantharaman et al, 2020, the publication venue listed in the paper is "Proceedings of the JuliaCon Conferences", which is different from the DOI (JuliaCon Proceedings). Can you check which is the correct one?
• For the reference Bunn et al, 2000, can you confirm that this is the right DOI? In that case, can you add it to the reference?
• For the McRae et al, 2016 reference, it seems to me that this is the right DOI - can you confirm and add it to the reference if that's the case?

After this, I ask that you re-read the paper and make sure all is good so we can proceed with publishing. Thanks!

[vlandau]

@melissawm I've added those DOIs, thanks! I have reviewed the paper and all looks good to me!

For Anantharaman et al, I am checking with the folks from Julia. It looks like the citation shown on that page has "JuliaCon Proceedings" but the bibtex snippet that they provide on the same page uses "Proceedings of the JuliaCon Conferences." I will post back here once I find out which to use.

[vlandau]

@melissawm Okay, they said to go with JuliaCon Proceedings. Thanks for flagging that! I just fixed the reference in the paper.bib file.

[vlandau]

@whedon generate pdf

[whedon]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[melissawm]

At this point could you:

• Archive the reviewed software in Zenodo or a similar service (e.g., figshare, an institutional repository) with the correct version
• Check the archival deposit (e.g., in Zenodo) has the correct metadata. This includes the title (should match the paper title) and author list (make sure the list is correct and people who only made a small fix are not on it). You may also add the authors' ORCID.
• Please list the DOI of the archived version here.

I can then move forward with accepting the submission. Thanks!

[vlandau]

Alright, it should all be here. The DOI is 10.5281/zenodo.4466323

Thank you!

[vlandau]

@melissawm just checking in (realized I forgot to tag you in the last comment). Thanks!

[melissawm]

Thank you, @vlandau ! Just checking - there is a small typo on the summary for Zenodo:

Omniscape.jl implements to Omniscape omnidirectional habitat connectivity modeling algorithm (McRae et al. 2016) in the Julia programming language.

Also you mention References but there is only one paper listed - is this intentional?

[vlandau]

@melissawm thanks I'll fix that typo! That was the only paper I cited so it was the only one listed in references.

[melissawm]

@whedon set 10.5281/zenodo.4466323 as archive

[whedon]

OK. 10.5281/zenodo.4466323 is the archive.

[melissawm]

Hello @openjournals/joss-eics , I believe this is ready for publishing.

Thanks again @vlandau, @juliohm and @tpoisot !

[danielskatz]

@melissawm - the final step from you should be @whedon accept, which will generate a final proof that you could check, and notifies the AEiCs

[melissawm]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1111/j.0014-3820.2006.tb00500.x is OK
- 10.1006/jema.2000.0373 is OK
- 10.1137/141000671 is OK
- 10.1890/07-1861.1 is OK
- 10.1111/cobi.13230 is OK
- 10.21105/jcon.00058 is OK
- 10.13140/RG.2.1.4158.6166 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👋 @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/joss-papers#2062

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#2062, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[danielskatz]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.02829 joss-papers#2063
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02829
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[danielskatz]

Congratulations to @vlandau (Vincent Landau) and co-authors!!

And thanks to @juliohm @tpoisot for reviewing, and @melissawm for editing!

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.02829/status.svg)](https://doi.org/10.21105/joss.02829)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.02829">
  <img src="https://joss.theoj.org/papers/10.21105/joss.02829/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.02829/status.svg
   :target: https://doi.org/10.21105/joss.02829

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss