[REVIEW]: NERD: Numerical Estimation of Rodenticide Density

Submitting author: !--author-handle-->@devarops@marcosvital<!--end-editor-- Reviewers: @ashleefv, @jhabriel, @david-yannick Archive: Pending

Status

Status badge code:

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

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

@ashleefv & @jhabriel & @david-yannick, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @marcosvital 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 ✨

Checklists

📝 Checklist for @ashleefv

📝 Checklist for @david-yannick

📝 Checklist for @jhabriel

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

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

@editorialbot commands

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

@editorialbot generate pdf

Software report:

github.com/AlDanial/cloc v 1.90  T=0.03 s (1795.8 files/s, 138885.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          26            226             81           1167
Markdown                         4            170              0            517
CSV                              6              0              0            299
YAML                             3              6              0            204
TeX                              1             13              0            160
JSON                             3              0              0            150
Jupyter Notebook                 3              0            598            139
make                             1             15              0             67
Dockerfile                       2              0              0             35
Bourne Shell                     1              3              5             12
-------------------------------------------------------------------------------
SUM:                            50            433            684           2750
-------------------------------------------------------------------------------

Commit count by author:

   125  Fernando
   111  Simon Duarte
    91  Evaristo Rojas
    60  siduartep
    19  Xavier Paredes
    16  Guillermo Olvera
    12  Evaristo Rojas • GECI
    10  Mario Villasante
     9  Nepo Rojas
     7  Nepo Rojas • GECI
     3  Guillermo Olvera • GECI
     3  MemoOlv
     2  devarops
     2  mvillasante
     1  nepito

Paper file info:

📄 Wordcount for paper.md is 1574

✅ The paper includes a Statement of need section

License info:

🟡 License found: GNU Affero General Public License v3.0 (Check here for OSI approval)

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

OK DOIs

- 10.1007/s10530-008-9402-3 is OK
- 10.1098/rsbl.2003.0153 is OK
- 10.1016/0272-7714(86)90028-4 is OK
- 10.1016/j.gecco.2015.02.010 is OK
- 10.1111/j.1523-1739.2007.00859.x is OK
- 10.3354/meps06860 is OK
- 10.1016/j.biocon.2014.10.014 is OK
- 10.1111/j.1365-2486.2011.02464.x is OK
- 10.1038/35002501 is OK
- 10.5281/zenodo.10214344 is OK
- 10.1007/s10530-005-0421-z is OK

MISSING DOIs

- No DOI given, and none found for title: The spread of commensal species of Rattus to ocean...
- No DOI given, and none found for title: Habitat use by three rat species (Rattus spp.) on ...
- No DOI given, and none found for title: Linking marine and terrestrial food webs: Allochth...

INVALID DOIs

- None

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

Dear @ashleefv, @jhabriel and @david-yannick, thank you again for accepting review this submission for JOSS.

The reviewing process is checklist based, and instructions were already posted above by the editorial bot - but let me know if you need any assistance, ok? Also, you can tag @devarops if you have specific questions about the manuscript.

@devarops, you can tag your co-authors GitHub accounts if you want, so they will be able to follow this issue and answer to questions as well.

Review checklist for @ashleefv

Conflict of interest

[x] 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

[x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

[x] Repository: Is the source code for this software available at the https://github.com/IslasGECI/nerd?
[x] License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
[ ] Contribution and authorship: Has the submitting author (@devarops) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[ ] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] 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

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] 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

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[ ] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] 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?

Regarding contribution and authorship: @devarops is the only of the three listed authors that appears to have contributed to the repository. There are 7 other repository contributors who are not listed as JOSS paper authors.

I have several additional comments.

Paper.md

paper.md is inside the examples subfolder. It seems weird to include the code in the paper.md file.
typo: "resorting" should be "restoring" in Introduction.
typo: Figure 1 caption "even" should be "event" and "line" should be "curve"
typo: Figure 2 caption density units should be kg/m^2 instead of kg/ha to match the y-axis units
Figure 3 caption also lists density as kg/ha. Is it more useful to stay in density kg/ha or kg/m^2 throughout the paper.md and the code? Consistency is desireable.

readme.md

the link to where to explore the Jupyter notebooks does not work. The local host typically needs to be deployed by Jupyter on one's local machine.

examples/calibration-demo.ipynb

The text in the first section includes TeX commands for \eqref and Figure \ref cross-referencing that are not understood in the Jupyter notebook. They both render as ??? in the notebook.
/workdir is not automatically set.
In [3]: I needed to change the file location to "../tests/data/flow.csv" for the csv file to be read.
In [5]: "figures/calibration.png" works as the path. The paper.md file shows the following for this line: plt.savefig("examples/figures/calibration.png", dpi=300, transparent=True) but that disagrees with the calibration.demo.ipynb code and doesn't run on my computer either.
In [6]: "../tests/data/profile.csv"
In [8]: "figures/plots.png"
In [12]: "figures/density_profile.png"
In [15]: "figures/contour_plot.png"
The text after the figure saved as calibration.png is the caption for Figure 1 in the paper.md file. That Markdown text does not render correctly in the .ipynb file.
The text after the figure saved as plots.png is in Spanish "Aca va el pie de figura" or "Here goes the figure caption" and does not render correctly in the .ipynb file.
The text after the figure saved as density_profile.png is in Spanish "Aca va el pie de figura" or "Here goes the figure caption" and does not render correctly in the .ipynb file.
The text after the figure saved as contour_plot.png is the caption for Figure 3 in the paper.md file. That Markdown text does not render correctly in the .ipynb file.
The text in the last section includes TeX commands Figure \ref cross-referencing that is not understood in the Jupyter notebook and renders as ??? in the notebook. Recommended to move this text to the top of the notebook.

examples/proceedings.ipynb

This seems like a draft of paper.md and may not need to be in the repository anymore. I did not review this file or the preprint.md file as they are neither the paper.md or the main code or examples.

examples/tiling_demo.ipynb

This file does not run for me because there are many nested instances of /workdir/ in the .ipynb file as well as the .json file. workdir needs to be specified or automated for this to run. I replaced /workdir/ with ../ everywhere in the .ipynb and .json files to get this to run.
The text before the Discussion section is in Spanish "Aca va el pie de figura" or "Here goes the figure caption" and does not render correctly in the .ipynb file.
The Discussion at the end of this notebook could be easily included as part of the introduction. Then Discussion and References sections would not be included. Currently References section is empty in this .ipynb file and is not needed.

Throughout the nerd repository

I recommend replacing relative paths (dot notation) of imports
```
from . import 
from .. import
```
with the specific absolute paths, e.g., in nerd\calibration\best_density_function.py
```
from nerd.calibration import get_rmse_from_function_array
from nerd import density_functions as df
```
PEP 8 standard explicitly recommends absolute imports: https://realpython.com/absolute-vs-relative-python-imports/ This recommendation applies to the following scripts:

nerd/calibration/init.py nerd/calibration/best_density_function.py nerd/calibration/model.py nerd/calibration/rmse.py nerd/density_functions/init.py nerd/io/init.py nerd/mapping/init.py nerd/init.py

Your files nerd/io/import_data.py and nerd/mapping/tiling.py already use the recommended absolute paths for imports.

Review checklist for @david-yannick

Conflict of interest

[x] 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

[x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

[x] Repository: Is the source code for this software available at the https://github.com/IslasGECI/nerd?
[x] License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
[x] Contribution and authorship: Has the submitting author (@devarops) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[ ] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[ ] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[ ] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] 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

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] 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

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[ ] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] 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?

Thank you, @ashleefv, for your thoughtful review and valuable feedback. We are currently addressing your comments and suggestions, and we are confident that your insights will significantly enhance the quality of our paper.

https://github.com/IslasGECI/nerd/issues/53

Review checklist for @jhabriel

Conflict of interest

[x] 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

[x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

[x] Repository: Is the source code for this software available at the https://github.com/IslasGECI/nerd?
[x] License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
[ ] Contribution and authorship: Has the submitting author (@devarops) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] 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

[x] 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.
[x] 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)?
[x] 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

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[ ] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] 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?

I have finished my review of the NERD package. I also have some additional comments/suggestions, which are given below.

Installation

Installation through pip works fine. I also tested the docker version and it works as stated. However, I would recommend including the option of installing NERD from source (this will be interesting for someone who wants to work with the development version rather than the stable version). To allow for this, you will need to include a requirements.txt file with the package dependencies and the instructions on how to install from source.
Please state in the README the Python versions that NERD supports.

Citation

I would strongly recommend adding a CITATION.cff file. See https://citation-file-format.github.io/

Community Guidelines

I strongly recommend adding a CODE_OF_CONDUCT.md file. See https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project
I strongly recommend adding a CONTRIBUTING.md file, where there are clear guidelines on how one can contribute to the project. Specifically, are the formatting (flake8, isort, black), typing (mypy) , testing (pytest) requirements before opening a pull request.
Please, add in the README.md how an user can establish contact in case of finding bugs / questions / feature requests etc.
Please, give some hint about the purpose of the last link in the README.

Examples

I have encountered difficulty running the examples. There are a lot of errors and hyperlinks broken. I believe @ashleefv did a wonderful job at reviewing those, so I won’t go through those.

Source code documentation and typing

Several classes, functions and methods are lacking docstrings and type hints. They have to be fixed.

Classes/Functions/Methods that are lacking docstrings:

nerd/calibration/best_density_function/get_density_function_array
nerd/calibration/best_density_function/select_best_density_function_from_array
nerd/calibration/rmse/get_rmse_from_function_array
nerd/calibration/rmse/get_rmse
nerd/io/Nerd
nerd/io/Nerd.calculate_total_density
nerd/io/geo2utm/geo2utm
nerd/io/import_data/tracmap2csv
nerd/io/import_data/import_tracmap
nerd/io/import_data/import_calibration_data
nerd/io/import_data/check_output_directory
nerd/io/import_data/import_multifile_tracmap
nerd/io/import_data/create_df_list
nerd/io/import_data/select_parameters_by_index
nerd/io/import_data/select_density_function
nerd/mapping/tiling/slope_between_two_points
nerd/mapping/tiling/orthogonal_slope
nerd/mapping/tiling/safe_divition
nerd/mapping/tiling/cell_edges_slopes
nerd/mapping/tiling/calculate_cell_y_limits
nerd/mapping/tiling/cell_y_coordinates
nerd/mapping/tiling/calculate_cell_x_limits
nerd/mapping/tiling/cell_x_coordinates
nerd/mapping/tiling/generate_cell_from_coordinates
nerd/mapping/tiling/calculate_cell_density_in_border
nerd/mapping/tiling/density_in_tile
nerd/mapping/tiling/is_inside_tile
nerd/mapping/tiling/calculate_directions
nerd/mapping/tiling/generate_tile_direction_arrays
nerd/mapping/tiling/sign_of_direction
nerd/mapping/tiling/reorder_end_tile
nerd/mapping/tiling/check_directions
nerd/mapping/tiling/generate_contours
nerd/mapping/tiling/create_contour_polygon_list
nerd/mapping/tiling/export_contour_list_as_shapefile
nerd/mapping/tiling/generate_grid_density
nerd/mapping/tiling/Tracks
nerd/mapping/tiling/Tracks.y_coordinates
nerd/mapping/tiling/Tracks.x_coordinates
nerd/mapping/tiling/Tracks.bucket_logger
nerd/mapping/tiling/Tracks.helicopter_speed
nerd/mapping/tiling/Tracks.n_data
nerd/mapping/tiling/calculate_total_density
nerd/mapping/tiling/generate_uniform_density_array
nerd/mapping/tiling/density_contours_intervals

Classes/Functions/Methods that are lacking type hints:

nerd/calibration/best_density_function/get_density_function_array nerd/calibration/best_density_function/select_best_density_function_from_array
nerd/calibration/rmse/get_rmse_from_function_array
nerd/calibration/rmse/get_rmse
nerd/io/Nerd.calculate_total_density
nerd/io/geo2utm/geo2utm
nerd/io/import_data/import_tracmap
nerd/io/import_data/import_calibration_data
nerd/io/import_data/check_output_directory
nerd/io/import_data/import_multifile_tracmap
nerd/io/import_data/create_df_list
nerd/io/import_data/select_parameters_by_index
nerd/io/import_data/select_density_function
nerd/mapping/tiling/slope_between_two_points
nerd/mapping/tiling/orthogonal_slope
nerd/mapping/tiling/safe_divition
nerd/mapping/tiling/cell_edges_slopes
nerd/mapping/tiling/calculate_cell_y_limits
nerd/mapping/tiling/cell_y_coordinates
nerd/mapping/tiling/calculate_cell_x_limits
nerd/mapping/tiling/cell_x_coordinates
nerd/mapping/tiling/generate_cell_from_coordinates
nerd/mapping/tiling/calculate_cell_density_in_border
nerd/mapping/tiling/density_in_tile
nerd/mapping/tiling/is_inside_tile
nerd/mapping/tiling/calculate_directions
nerd/mapping/tiling/generate_tile_direction_arrays
nerd/mapping/tiling/sign_of_direction
nerd/mapping/tiling/reorder_end_tile
nerd/mapping/tiling/check_directions
nerd/mapping/tiling/generate_contours
nerd/mapping/tiling/create_contour_polygon_list
nerd/mapping/tiling/export_contour_list_as_shapefile
nerd/mapping/tiling/generate_grid_density
nerd/mapping/tiling/Tracks.y_coordinates
nerd/mapping/tiling/Tracks.x_coordinates
nerd/mapping/tiling/Tracks.bucket_logger
nerd/mapping/tiling/Tracks.helicopter_speed
nerd/mapping/tiling/Tracks.n_data
nerd/mapping/tiling/calculate_total_density
nerd/mapping/tiling/generate_uniform_density_array
nerd/mapping/tiling/density_contours_intervals

Testing

The package is well tested. Good job.

Paper

The paper is lacking the State of Field. Basically, a paragraph where NERD is compared to alternative software (if any).
I recommend avoiding the plt.savefig commands, and simply go for plt.show().
Could you add the city and country of Grupo de Ecología y Conservación de Islas?
Figure 1: Possibly typo. Did you mean event instead of even?
Figure 4: Please add label axes.
Figure 4: Please add the colorbar with proper units.
L81. I suggest removing extremely.
L86. I suggest removing incredibly. 
L86. The word notably is used twice in the paragraph. Consider using a synonym.

My review is complete, below are a few comments and questions:

Authors created NERD to address lack of means to produce bait density maps and identify gaps [48-49]. There is not a State of Field section, however, it mentioned that there is a lack in this area. o Are these exclusive to helicopter based releases and/or also be applicable to drones?
Perhaps included parameters to account for expected mean ground wind speed and direction? This would potentially impact how rodenticide is dispersed [68-69] ?
Add guidelines for 3rd party contribution

openjournals / joss-reviews