whedon commented 4 years ago

Submitting author: @CourtneySmith32 (Courtney Smith) Repository: https://github.com/pyReef-model/RADWave Version: v1.0.0 Editor: @sjpfenninger Reviewer: @bradyrx, @scivision Archive: 10.5281/zenodo.3733848

Status

Status badge code:

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

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

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

Make sure you're logged in to your GitHub account
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 @sjpfenninger know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @bradyrx

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 repository url?
[x] 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 (@CourtneySmith32) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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)?
[ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
[x] 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: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] 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?

Review checklist for @scivision

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 repository url?
[x] 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 (@CourtneySmith32) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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?
[x] 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: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] 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?

whedon commented 4 years ago

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

:star: Important :star:

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:

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

watching

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

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 commented 4 years ago

Reference check summary:

OK DOIs

- 10.1016/J.RSE.2018.06.006 is OK
- 10.1038/s41597-019-0083-9 is OK

MISSING DOIs

- None

INVALID DOIs

- None

whedon commented 4 years ago

:point_right: Check article proof :page_facing_up: :point_left:

labarba commented 4 years ago

👋 @sjpfenninger — It looks like you will need to reach out to your reviewers by email to request an update, and propel this along...

sjpfenninger commented 4 years ago

@labarba Thanks, yes, I'm on it!

bradyrx commented 4 years ago

Review of `RADWave`

Thank you to @CourtneySmith32 and colleagues for submitting this software and manuscript. The documentation is extensive and I found the binder examples impressive and quite useful. I appreciate that all of the binder analysis was done with THREDDS to show that data can be pulled from remote servers and need not be stored locally for this package to work. It's clear that RADWave serves a need in the community and will make analyzing altimetry data a lot smoother. Nice work!

I have comments below on the software, documentation, and summary paper that should be addressed prior to publication with JOSS. Generally, some more care needs to be taken with package management (testing, CI, etc.) and the code base needs to be cleaned up a bit (consistent naming and returns, linting, etc.). However, once these are addressed I think it's a great fit for the journal.

General Comments/Questions

I would consider renaming the package to radwave. PEP guidelines suggest that python packages should be named in all lowercase, and only use underscores to improve readability (https://www.python.org/dev/peps/pep-0008/#package-and-module-names).
Does this only work with the setup from AODN, or will it work with any THREDDS altimetry data? From the summary paper, it seems like AODN hosts all altimetry mission output, so this might not be relevant. If that's the case, I would suggest making this clear in the docs. Currently the docs/manuscript say AODN is used to illustrate the package capabilities, but has any testing been done on other servers?
Why are the notebooks/tutorial replicated in both /Notebooks/ and /src/RADWave/Notebooks/? I imagine these can be consolidated into one location. Typically for python, everything from src can be moved to the main folder.
I would encourage the use of a CI service like Travis for this package. This ensures that the package can be built/installed for a given PR's updates, and will run a testing suite as well (which I suggest in the next section).
Is 30 days the common moving average window in the field for wave time series? Currently, the 30-day average is hard-coded into the class methods for plotting time series. It might be useful for the user to be able to designate the moving average window length.

Code Comments

I don't think the empty return statements are necessary throughout the class methods.
I would strongly recommend running flake8 or a similar linter on the code. There's currently 100 errors that come through from flake8 on the code base. It might also help to have a column-width limitation for user and developer readability. E.g. black, or just enforce an 80 or 88 line limit.
I think functions can generally be renamed for clarity. E.g. processingAltimeterData can become processAltimeterData and readingAltimeterData to readAltimeterData. seriesSeasonMonth can be renamed something more clear like computeSeasonalCharacteristics (or something less verbose). timeSeries should be something more descriptive like generate_time_series or something in camelCase. It currently reads like a class attribute.
Time series options ('H', 'T', 'P', 'E' and 'Cg') should be clearly defined in the docs and/or in the docstring for plotTimeSeries.
I would consider returning the derived df's from functions instead of just adding them as object attributes. E.g. from timeSeries and close2Track. Generally it's intuitive for the user to be returned the computation result from a method like these. Since there's no __repr__ on the main class, the user has no interaction with their object and can't see when timeSeries has already been computed. Further, there's inconsistencies with seriesSeasonMonth which returns the df, but the former two mentioned methods which don't.
cycloneAltiPoint should probably be renamed to plotCycloneAltiPoint for consistency and clarity.

Review Checklist

General checks

[ ] Contribution and authorship: Has the submitting author (@CourtneySmith32) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Could the lead author please outline their contribution and Dr. Vila-Concejo's contribution to the software? The repository suggests that all of the code was written by @tristan-salles, and the Sphinx copyright and contact email on the documentation goes to @tristan-salles as well.

Documentation

[X] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.

I think the installation page is comprehensive and I appreciate the multiple methods to install. However, I would also suggest registering RADWave with conda-forge, since this is probably the best package management solution out there right now.
[ ] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?

The only testing available is testInstall.py, which seems to just test that RADWave can be imported and the main THREDDS method run. First, it's currently breaking for me (see https://github.com/pyReef-model/RADWave/issues/1).

Secondly, RADWave should have unit testing well beyond this. I would suggest having, e.g. a pytest suite that is run with continuous integration, such as Travis, on all PRs. You can use coveralls or a similar service to check how much of the code base is covered by testing. At the minimum, I would test all of the methods in the waveAnalysis object and ensure that they run without breaking. You should probably use pytest.parametrize to loop through different keyword options as well.

If the authors don't have too much experience with this level of unit testing, I suggest checking out our testing suite at climpred: https://github.com/bradyrx/climpred/tree/master/climpred/tests. I think we have generally minimal examples there, which are easier to base testing off of than a bigger package like numpy or xarray.

Software paper

[ ] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?

Please see comments below. I suggest that the paper be carefully revised in a few locations for grammar and clarity.
[ ] 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?

Please see comments below. I suggest the addition of at least one reference in the summary.

Summary

In the first sentence, I would restructure it to either say that satellite radar altimeters are excellent instruments or that satellite radar altimetry is an excellent remote sensing technique.
In the second sentence, gramatically it should be restructured to say "These measurements can be used in conjunction with one another ..."
As in the docs, I would suggest citing Chelton 2001 or something similar to back up the gap in satellite operation.
Please rewrite the following sentence for clarity:

Consequently, analysis of this long-term temporal record can lead to significant insights into inter-annual, seasonal and decadal variations in wave yearly seasonality and decadal trend.

I'm not exactly sure what is being said here. E.g., what is "wave yearly seasonality"? How do decadal trends fit into this picture? Perhaps that analyzing the record can lead to insights in interannual, seasonal, and decadal variations in wave statistics (or something similar).

Main Text

Please reformulate this sentence as well. It seems like there are words missing (e.g. "allows the user to query"?):

RADWave allows to query over a range of spatial and temporal scales altimeter parameters in specific geographical regions and subsequently calculates significant wave heights, periods, group velocities, average wave energy densities and wave energy fluxes.

Perhaps it would be good to follow the line about there being no open-source code available for this purpose with a suggestion that users currently have to download the data manually (or write by hand THREDDS retrieval code) and write custom analysis and visualization functions using pandas, numpy, matplotlib, etc. And that RADWave combines this all into a simple object-oriented framework.

CourtneySmith32 commented 4 years ago

Hi Riley,

Thanks very much for your comments and feedback, they all make sense. Will get on it soon!

Thanks, Courtney

On Sat, Mar 7, 2020 at 10:06 AM Riley Brady notifications@github.com wrote:

Review of RADWave

Thank you to @CourtneySmith32 https://github.com/CourtneySmith32 and colleagues for submitting this software and manuscript. The documentation is extensive and I found the binder examples impressive and quite useful. I appreciate that all of the binder analysis was done with THREDDS to show that data can be pulled from remote servers and need not be stored locally for this package to work. It's clear that RADWave serves a need in the community and will make analyzing altimetry data a lot smoother. Nice work!

I have comments below on the software, documentation, and summary paper that should be addressed prior to publication with JOSS. Generally, some more care needs to be taken with package management (testing, CI, etc.) and the code base needs to be cleaned up a bit (consistent naming and returns, linting, etc.). However, once these are addressed I think it's a great fit for the journal. General Comments/Questions

I would consider renaming the package to radwave. PEP guidelines suggest that python packages should be named in all lowercase, and only use underscores to improve readability ( https://www.python.org/dev/peps/pep-0008/#package-and-module-names).

Does this only work with the setup from AODN, or will it work with any THREDDS altimetry data? From the summary paper, it seems like AODN hosts all altimetry mission output, so this might not be relevant. If that's the case, I would suggest making this clear in the docs. Currently the docs/manuscript say AODN is used to illustrate the package capabilities, but has any testing been done on other servers?

Why are the notebooks/tutorial replicated in both /Notebooks/ and /src/RADWave/Notebooks/? I imagine these can be consolidated into one location. Typically for python, everything from src can be moved to the main folder.

I would encourage the use of a CI service like Travis for this package. This ensures that the package can be built/installed for a given PR's updates, and will run a testing suite as well (which I suggest in the next section).

Is 30 days the common moving average window in the field for wave time series? Currently, the 30-day average is hard-coded into the class methods for plotting time series. It might be useful for the user to be able to designate the moving average window length.

Code Comments

I don't think the empty return statements are necessary throughout the class methods.

I would strongly recommend running flake8 or a similar linter on the code. There's currently 100 errors that come through from flake8 on the code base. It might also help to have a column-width limitation for user and developer readability. E.g. black, or just enforce an 80 or 88 line limit.

I think functions can generally be renamed for clarity. E.g. processingAltimeterData can become processAltimeterData and readingAltimeterData to readAltimeterData. seriesSeasonMonth can be renamed something more clear like computeSeasonalCharacteristics (or something less verbose). timeSeries should be something more descriptive like generate_time_series or something in camelCase. It currently reads like a class attribute.

Time series options ('H', 'T', 'P', 'E' and 'Cg' ) should be clearly defined in the docs and/or in the docstring for plotTimeSeries.

I would consider returning the derived df's from functions instead of just adding them as object attributes. E.g. from timeSeries and close2Track. Generally it's intuitive for the user to be returned the computation result from a method like these. Since there's no repr on the main class, the user has no interaction with their object and can't see when timeSeries has already been computed. Further, there's inconsistencies with seriesSeasonMonth which returns the df, but the former two mentioned methods which don't.

cycloneAltiPoint should probably be renamed to plotCycloneAltiPoint for consistency and clarity.

Review Checklist General checks

Contribution and authorship: Has the submitting author ( @CourtneySmith32 https://github.com/CourtneySmith32) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Could the lead author please outline their contribution and Dr. Vila-Concejo's contribution to the software? The repository suggests that all of the code was written by @tristan-salles https://github.com/tristan-salles, and the Sphinx copyright and contact email on the documentation goes to @tristan-salles https://github.com/tristan-salles as well. Documentation

-

Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.

I think the installation page is comprehensive and I appreciate the multiple methods to install. However, I would also suggest registering RADWave with conda-forge, since this is probably the best package management solution out there right now.

Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?

The only testing available is testInstall.py, which seems to just test that RADWave can be imported and the main THREDDS method run. First, it's currently breaking for me (see pyReef-model/RADWave#1 https://github.com/pyReef-model/RADWave/issues/1).

Secondly, RADWave should have unit testing well beyond this. I would suggest having, e.g. a pytest suite that is run with continuous integration, such as Travis, on all PRs. You can use coveralls or a similar service to check how much of the code base is covered by testing. At the minimum, I would test all of the methods in the waveAnalysis object and ensure that they run without breaking. You should probably use pytest.parametrize to loop through different keyword options as well.

If the authors don't have too much experience with this level of unit testing, I suggest checking out our testing suite at climpred: https://github.com/bradyrx/climpred/tree/master/climpred/tests. I think we have generally minimal examples there, which are easier to base testing off of than a bigger package like numpy or xarray.

Software paper

-

Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?

Please see comments below. I suggest that the paper be carefully revised in a few locations for grammar and clarity.

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 https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html#citation_syntax ?

Please see comments below. I suggest the addition of at least one reference in the summary.

Summary

In the first sentence, I would restructure it to either say that satellite radar altimeters are excellent instruments or that satellite radar altimetry is an excellent remote sensing technique.

In the second sentence, gramatically it should be restructured to say "These measurements can be used in conjunction with one another ..."

As in the docs, I would suggest citing Chelton 2001 or something similar to back up the gap in satellite operation.

Please rewrite the following sentence for clarity:

Consequently, analysis of this long-term temporal record can lead to significant insights into inter-annual, seasonal and decadal variations in wave yearly seasonality and decadal trend.

I'm not exactly sure what is being said here. E.g., what is "wave yearly seasonality"? How do decadal trends fit into this picture? Perhaps that analyzing the record can lead to insights in interannual, seasonal, and decadal variations in wave statistics (or something similar). Main Text

Please reformulate this sentence as well. It seems like there are words missing (e.g. "allows the user to query"?):

RADWave allows to query over a range of spatial and temporal scales altimeter parameters in specific geographical regions and subsequently calculates significant wave heights, periods, group velocities, average wave energy densities and wave energy fluxes.

Perhaps it would be good to follow the line about there being no open-source code available for this purpose with a suggestion that users currently have to download the data manually (or write by hand THREDDS retrieval code) and write custom analysis and visualization functions using pandas, numpy, matplotlib, etc. And that RADWave combines this all into a simple object-oriented framework.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/joss-reviews/issues/2083?email_source=notifications&email_token=AL3QBXLTP3OYQHECOCF2H6LRGF6YJA5CNFSM4KRMARIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEODELUI#issuecomment-596002257, or unsubscribe https://github.com/notifications/unsubscribe-auth/AL3QBXK3NGEJIWQKKTDFC6LRGF6YJANCNFSM4KRMARIA .

scivision commented 4 years ago

Review checklist for @scivision

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 repository url?
[x] 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 (@CourtneySmith32) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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?
[x] 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: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] 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?

Review comments

General Checks:contribution: it looks like a lot of work was done at https://github.com/CourtneySmith32/RADWave but doesn't seem to be in the Git history of this repo. This may be due to the particular Git workflow being used. One way to preserve Git history if desired across teams is to use branches and periodically merge to a master branch.
Functionality:installation: The package uses the src/ directory as the top level for Python code, which is a popular layout choice. However, I believe such package still generally keep the setup.cfg and setup.py at the topmost level of the repo, as the repo won't install without descending into the src/ directory, which would be remediated by moving setup.py and setup.cfg up to the top. Also, this repo doesn't actually need a setup.py, all the metadata can go into setup.cfg, but that's optional. The Classifier metadata goes down to Python 3.3, but even Python 3.4 is challenging to use for the past year or more. The CI is set to Python 3.5 and probably the classifier metadata could also be set from Python 3.5 to 3.8.
automated test: please consider pytest.approx instead of using round() to compare

It looks like a lot of improvements were made recently, including in response to the first reviewer's comments. The biggest gaps to be "accepted" have been already addressed as a result.

danielskatz commented 4 years ago

👋 @scivision - you already have a checklist in the first comment in this review thread - you shouldn't create your own

scivision commented 4 years ago

Thanks Daniel, for some reason I don't have access to that, I can't edit that comment. It may be an invitation issue. I can move that information to the first comment upon gaining access

sjpfenninger commented 4 years ago

@whedon re-invite @scivision as reviewer

whedon commented 4 years ago

Sorry, I couldn't re-invite @scivision.

sjpfenninger commented 4 years ago

@danielskatz hm, any idea what's going wrong here?

scivision commented 4 years ago

I had my status set to Away, that might have blocked the invite. I just turned off Away.

danielskatz commented 4 years ago

@scivision - can you check again now? @openjournals/dev - if not, can you help?

scivision commented 4 years ago

I think the invite has to be sent again, now that my status in Github is not away

tristan-salles commented 4 years ago

We would like to thank @bradyrx for his really useful and helpful comments. They have all helped to improve significantly the quality of the package!

Below is a point by point revisions of his suggestions.

General Comments/Questions

I would consider renaming the package to radwave. PEP guidelines suggest that python packages should be named in all lowercase, and only use underscores to improve readability (https://www.python.org/dev/peps/pep-0008/#package-and-module-names).

we have changed the package name to radwave as suggested by the reviewer.

Why are the notebooks/tutorial replicated in both /Notebooks/ and /src/RADWave/Notebooks/? I imagine these can be consolidated into one location. Typically for python, everything from src can be moved to the main folder.

We have removed the duplicated tutorials.

I would encourage the use of a CI service like Travis for this package. This ensures that the package can be built/installed for a given PR's updates, and will run a testing suite as well (which I suggest in the next section).

We are now using Travis with pytest for RADwave

Is 30 days the common moving average window in the field for wave time series? Currently, the 30-day average is hard-coded into the class methods for plotting time series. It might be useful for the user to be able to designate the moving average window length.

Monthly (30 days) average window is commonly used for wave time series analysis saying that one might want to use another time interval and following reviewer’s comment we have modified the code to allow user to pick a specific number of days in the function timeSeries that now accepts an argument: def timeSeries(self, days=30)

Does this only work with the setup from AODN, or will it work with any THREDDS altimetry data? From the summary paper, it seems like AODN hosts all altimetry mission output, so this might not be relevant. If that's the case, I would suggest making this clear in the docs. Currently the docs/manuscript say AODN is used to illustrate the package capabilities, but has any testing been done on other servers?

As pointed out by the reviewer, the package in its current form only works with AODN altimetry data. In a future version of the code we could make it work with other THREDDS server but as AODN currently hosts all altimetry missions this is not an issue for now. Following reviewer advice we have making it clear in the docs.

Code Comments

I don't think the empty return statements are necessary throughout the class methods.

As suggested by the reviewer, we have removed the empty return statements.

I would strongly recommend running flake8 or a similar linter on the code. There's currently 100 errors that come through from flake8 on the code base. It might also help to have a column-width limitation for user and developer readability. E.g. black, or just enforce an 80 or 88 line limit.

Following reviewer’s comment we have used flake8 and black to reformat the main code contained in altiwave.py. There are still some line running over the 80 line mark but they are mostly comments and documentation related parts of the files.

I think functions can generally be renamed for clarity. E.g. processingAltimeterData can become processAltimeterData and readingAltimeterData to readAltimeterData. seriesSeasonMonth can be renamed something more clear like computeSeasonalCharacteristics (or something less verbose). timeSeries should be something more descriptive like generate_time_series or something in camelCase. It currently reads like a class attribute.

We have renamed all the functions based on the reviewer’s comment: e.g. processAltimeterData, readAltimeterData, computeSeasonalCharacteristics and generate_time_series.

Time series options ('H', 'T', 'P', 'E' and 'Cg' ) should be clearly defined in the docs and/or in the docstring for plotTimeSeries.

We have added the options in the docs and the docstring for clarity.

I would consider returning the derived df's from functions instead of just adding them as object attributes. E.g. from timeSeries and close2Track. Generally it's intuitive for the user to be returned the computation result from a method like these. Since there's no repr on the main class, the user has no interaction with their object and can't see when timeSeries has already been computed. Further, there's inconsistencies with seriesSeasonMonth which returns the df, but the former two mentioned methods which don't.

Following reviewer’s comment we are now returning derived data frames for the generate_time_series and close2Track functions.

cycloneAltiPoint should probably be renamed to plotCycloneAltiPoint for consistency and clarity.

The function has been renamed accordingly.

Review Checklist

General checks

Contribution and authorship: Has the submitting author (@CourtneySmith32) made major contributions to the software? Does the full list of paper authors seem appropriate and complete? Could the lead author please outline their contribution and Dr. Vila-Concejo's contribution to the software? The repository suggests that all of the code was written by @tristan-salles, and the Sphinx copyright and contact email on the documentation goes to @tristan-salles as well.

The submitting author CS designed an initial version of RADWave as part of her Honours under the supervision of AVC and TS. Subsequently TS wrapped the main functions and extended the code functionalities. The tests were designed by all the three co-authors.

Documentation

Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution. I think the installation page is comprehensive and I appreciate the multiple methods to install. However, I would also suggest registering RADWave with conda-forge, since this is probably the best package management solution out there right now.

The package is available via pypi and can easily be installed in Anaconda using the pip command. We have decided to leave it as is for now as this does not seem to add an extra installation steps to the user as far as we can see plus it limits the number of packages that we will have to maintain in the future.

Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified? The only testing available is testInstall.py, which seems to just test that RADWave can be imported and the main THREDDS method run. First, it's currently breaking for me (see pyReef-model/RADWave#1).

This has been fixed, we now use Travis and pytest for automated tests.

 + Secondly, RADWave should have unit testing well beyond this. I would suggest having, e.g. a pytest suite that is run with continuous integration, such as Travis, on all PRs. You can use coveralls or a similar service to check how much of the code base is covered by testing. At the minimum, I would test all of the methods in the waveAnalysis object and ensure that they run without breaking. You should probably use pytest.parametrize to loop through different keyword options as well. If the authors don't have too much experience with this level of unit testing, I suggest checking out our testing suite at climpred: https://github.com/bradyrx/climpred/tree/master/climpred/tests. I think we have generally minimal examples there, which are easier to base testing off of than a bigger package like numpy or xarray.

Following reviewer’s comment we have added the pytest suite to our package and use Travis for continuous integration as well as coveralls.

Software paper

In the first sentence, I would restructure it to either say that satellite radar altimeters are excellent instruments or that satellite radar altimetry is an excellent remote sensing technique.

We have followed reviewer’s comment and changed the first sentence accordingly.

In the second sentence, gramatically it should be restructured to say "These measurements can be used in conjunction with one another ..." As in the docs, I would suggest citing Chelton 2001 or something similar to back up the gap in satellite operation.

We have modified the sentence and added the Chelton 2001 reference.

Consequently, analysis of this long-term temporal record can lead to significant insights into inter-annual, seasonal and decadal variations in wave yearly seasonality and decadal trend.

The sentence has been modified accordingly.

Please reformulate this sentence as well. It seems like there are words missing (e.g. "allows the user to query"?): RADWave allows to query over a range of spatial and temporal scales altimeter parameters in specific geographical regions and subsequently calculates significant wave heights, periods, group velocities, average wave energy densities and wave energy fluxes.

We have followed reviewer’s comment and changed these sentences accordingly in the paper and the documentation.

Perhaps it would be good to follow the line about there being no open-source code available for this purpose with a suggestion that users currently have to download the data manually (or write by hand THREDDS retrieval code) and write custom analysis and visualization functions using pandas, numpy, matplotlib, etc. And that RADWave combines this all into a simple object-oriented framework.

We have added a sentence about this in the paper.

bradyrx commented 4 years ago

Thank you for the quick turnaround @tristan-salles! I suggest that this is accepted/published after addressing the two minor comments below:

We have renamed all the functions based on the reviewer’s comment: e.g. processAltimeterData, readAltimeterData, computeSeasonalCharacteristics and generate_time_series.

I would make it generateTimeSeries for consistency with camelCase. I should have noted that.

While domain experts are able to extract satellite radar altimetry dataset, they currently have to download the data manually and write custom analysis and visualization functions using pandas, numpy, matplotlib to extract wave characteristics.

The above is from the updated text. There's still some grammatical issues here. I would change it to:

"While domain experts are able to assess satellite radar altimetry datasets, they currently have to download the data manually and write custom analysis and visualization functions using, e.g., numpy, pandas, and matplotlib to extract wave characteristics.

And here's some ranting thoughts on package management below. You don't need to address these comments, but I thought they might help moving forward.

Following reviewer’s comment we have used flake8 and black to reformat the main code contained in altiwave.py. There are still some line running over the 80 line mark but they are mostly comments and documentation related parts of the files.

We use a black line limit of 88, and impose that on black and flake8 in our setup.cfg file here: https://github.com/bradyrx/climpred/blob/master/setup.cfg. 80 ends up pretty short. Anyways, with whatever line limit you use, you can manually force your comments to adhere to this limit. For long comment lines just make them multi-lined. For docstring things (like arguments) if they are multiline, just tab out the second line like a hanging indent.

This all sounds really tedious but makes the code more readable for future developers. We also have a run_linter.sh script (https://github.com/bradyrx/climpred/blob/master/ci/run-linter.sh) that we run at the end of our Travis to make sure everything looks good for new code. Note that we add all of our code through Pull Requests so that one can't merge the new code until it is cleaned up like this.

Not that climpred is the bible for this. :) We've set up all of these CI/pre-commit workflows from advice from other packages. It's tedious to get going, but then makes the workflow very straight forward. pre-commit totally changed our development (https://github.com/bradyrx/climpred/blob/master/.pre-commit-config.yaml). It's worth trying out to see how awesome it is! Once you do pip install pre-commit, have a config file like I linked in your repo and do pre-commit install. Then you can set up a bunch of rules (like in my example) and every time you try to commit code it will run those checks. The black/flake8 hook on there just runs it automatically as you commit the code so you don't even have to think about it.

tristan-salles commented 4 years ago

Thanks! The 2 comments have been resolved and the docker image regenerated and tested as well as the binder one! Again thanks for all the feedbacks and insights!

tristan-salles commented 4 years ago

Thanks @scivision for the reviews & suggestions. We have addressed all your comments.

The package uses the src/ directory as the top level for Python code, which is a popular layout choice. However, I believe such package still generally keep the setup.cfg and setup.py at the topmost level of the repo, as the repo won't install without descending into the src/ directory, which would be remediated by moving setup.py and setup.cfg up to the top.

We have moved the setup.py file to the topmost level of the repo.

The Classifier metadata goes down to Python 3.3, but even Python 3.4 is challenging to use for the past year or more. The CI is set to Python 3.5 and probably the classifier metadata could also be set from Python 3.5 to 3.8.

We have changed the classifier to be set from Python 3.5 to 3.8

Automated test: please consider pytest.approx instead of using round() to compare

We have changed round to pytest.approx as suggested by the reviewer and have checked that Travis CI is still building without issues. on your comments we

tristan-salles commented 4 years ago

Hi @sjpfenninger, I think we have answered to all the reviewers comments.

arfon commented 4 years ago

Dear authors and reviewers

We wanted to notify you that in light of the current COVID-19 pandemic, JOSS has decided to suspend submission of new manuscripts and to handle existing manuscripts (such as this one) on a "best efforts basis". We understand that you may need to attend to more pressing issues than completing a review or updating a repository in response to a review. If this is the case, a quick note indicating that you need to put a "pause" on your involvement with a review would be appreciated but is not required.

Thanks in advance for your understanding.

Arfon Smith, Editor in Chief, on behalf of the JOSS editorial team.

tristan-salles commented 4 years ago

Hi @sjpfenninger, is there anything else that needs to be done on our side?

sjpfenninger commented 4 years ago

@tristan-salles Apologies for the delay, I will likely get to this next week.

tristan-salles commented 4 years ago

Thanks @sjpfenninger for letting us know!

sjpfenninger commented 4 years ago

@bradyrx @scivision Thanks both for your reviews, can you confirm whether you are happy with the changes made in response to your comments?

sjpfenninger commented 4 years ago

@whedon generate pdf

whedon commented 4 years ago

:point_right: Check article proof :page_facing_up: :point_left:

sjpfenninger commented 4 years ago

@scivision You did not tick "Installation: Does installation proceed as outlined in the documentation?" in your checklist -- does that mean there are issues with installing the package?

sjpfenninger commented 4 years ago

@tristan-salles You seem to have duplicated setup.py and setup.cfg (it's at both the top level and inside src/) -- are you sure this is intended? It ought to only be in one place.

bradyrx commented 4 years ago

@sjpfenninger , I am happy with the revisions. Thanks!

tristan-salles commented 4 years ago

@sjpfenninger, you were right, I did forget to remove the setup files in the src. I have made the changes to ensure that there were no more duplications.

scivision commented 4 years ago

@sjpfenninger thanks all set, I checked install box

sjpfenninger commented 4 years ago

@tristan-salles I suggested some minor changes to the paper here: https://github.com/pyReef-model/RADWave/pull/2

sjpfenninger commented 4 years ago

@tristan-salles Your only tagged release on GitHub is v0.0.2 but PyPI has v0.1.1. Can you make sure you have a tagged release for the most recent version, and report back the correct version number here? Please then make an archive of the software in Zenodo/figshare/other service and update this thread with the DOI of the archive. For the Zenodo/figshare archive, please make sure that:

The title of the archive is the same as the JOSS paper title
That the authors of the archive are the same as the JOSS paper authors

Once that's done, we can move forward with accepting this!

tristan-salles commented 4 years ago

Thanks @sjpfenninger! I have merged the PR and updated the version number to 1.0.0 as well as attached it to a new Zenodo archive

the title of the archive is the same as the JOSS paper title
the authors of the archive are the same as the JOOS paper authors

sjpfenninger commented 4 years ago

@whedon set v1.0.0 as version

whedon commented 4 years ago

OK. v1.0.0 is the version.

sjpfenninger commented 4 years ago

@whedon set 10.5281/zenodo.3733848 as archive

whedon commented 4 years ago

OK. 10.5281/zenodo.3733848 is the archive.

sjpfenninger commented 4 years ago

@whedon accept

whedon commented 4 years ago

Attempting dry run of processing paper acceptance...

whedon commented 4 years ago

Reference check summary:

OK DOIs

- 10.1016/J.RSE.2018.06.006 is OK
- 10.1038/s41597-019-0083-9 is OK

MISSING DOIs

- None

INVALID DOIs

- None

whedon commented 4 years ago

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

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/1398

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

@whedon accept deposit=true

sjpfenninger commented 4 years ago

@CourtneySmith32 @tristan-salles Thanks both, this is ready to go as far as I'm concerned. And thanks @bradyrx and @scivision for your work reviewing!

tristan-salles commented 4 years ago

Thanks all for your reviews! This is awesome!

arfon commented 4 years ago

@whedon accept deposit=true

whedon commented 4 years ago

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

whedon commented 4 years ago

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

whedon commented 4 years ago

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

Here's what you must now do:

Check final PDF and Crossref metadata that was deposited :point_right: https://github.com/openjournals/joss-papers/pull/1399
Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02083
If everything looks good, then close this review issue.
Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

openjournals / joss-reviews

[REVIEW]: RADWave: Python code for ocean surface wave analysis by satellite radar altimeter #2083

Status

Reviewer instructions & questions

Review checklist for @bradyrx

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Review checklist for @scivision

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Review of `RADWave`

General Comments/Questions

Code Comments

Review Checklist

General checks

Documentation

Software paper

Summary

Main Text

I think the installation page is comprehensive and I appreciate the multiple methods to install. However, I would also suggest registering RADWave with conda-forge, since this is probably the best package management solution out there right now.

Please see comments below. I suggest that the paper be carefully revised in a few locations for grammar and clarity.

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper