[REVIEW]: Digital Twins for Ocean Robots

[editorialbot]

Submitting author: @gaelforget (Gael Forget)
Repository: https://github.com/JuliaOcean/OceanRobots.jl
Branch with paper.md (empty if default branch): JuliaConProceedings2023
Version: v0.2.0
Editor: @luraess
Reviewers: @jonathanlilly, @Alexander-Barth
Archive: Pending

Status

Status badge code:

HTML: <a href="https://proceedings.juliacon.org/papers/060c050c82adb94c5151fbe824cfe1a7"><img src="https://proceedings.juliacon.org/papers/060c050c82adb94c5151fbe824cfe1a7/status.svg"></a>
Markdown: [![status](https://proceedings.juliacon.org/papers/060c050c82adb94c5151fbe824cfe1a7/status.svg)](https://proceedings.juliacon.org/papers/060c050c82adb94c5151fbe824cfe1a7)

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

@jonathanlilly & @Alexander-Barth, 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 @luraess 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 @Alexander-Barth

📝 Checklist for @jonathanlilly

[editorialbot]

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 source files, type:

@editorialbot generate pdf

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.90  T=0.11 s (364.3 files/s, 206720.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Julia                           19           3720          12837           3206
TeX                              8            302            181           2576
Markdown                         6             69              0            131
YAML                             4              4              0            119
TOML                             3              4              0             57
Ruby                             1              8              4             45
-------------------------------------------------------------------------------
SUM:                            41           4107          13022           6134
-------------------------------------------------------------------------------

Commit count by author:

   307	gaelforget
    11	Gael Forget
     2	CompatHelper Julia
     1	Julia TagBot
     1	ggebbie
     1	github-actions[bot]

[editorialbot]

Paper file info:

📄 Wordcount for paper.tex is 2782

🔴 Failed to discover a Statement of need section in paper

[editorialbot]

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

OK DOIs

- 10.3389/fmars.2018.00328 is OK
- 10.3389/fmars.2017.00128 is OK
- 10.1137/141000671 is OK
- 10.17226/26894 is OK
- 10.21105/joss.03349 is OK
- 10.21105/joss.00602 is OK
- 10.5281/zenodo.11144554 is OK
- 10.21105/joss.02018 is OK
- 10.21105/joss.04207 is OK
- 10.21105/joss.02813 is OK
- 10.5194/gmd-8-939-2015 is OK
- 10.5194/gmd-9-1937-2016 is OK
- 10.3389/fmars.2019.00439 is OK
- 10.21105/joss.03814 is OK
- 10.1175/JPO-D-14-0023.1 is OK
- 10.5194/gmd-8-3071-2015 is OK
- 10.5194/os-11-839-2015 is OK
- 10.1016/j.pocean.2015.06.002 is OK
- 10.1175/2009JPO4043.1 is OK
- 10.1175/JPO3072.1 is OK

MISSING DOIs

- No DOI given, and none found for title: MITgcm.jl: a Julia Interface to the MITgcm
- 10.21203/rs.3.rs-3979671/v1 may be a valid DOI for title: Energy Imbalance in the Sunlit Ocean Layer
- 10.1029/96jc02775 may be a valid DOI for title: A finite-volume, incompressible Navier Stokes mode...
- 10.1016/s1463-5003(03)00009-x may be a valid DOI for title: Conservation of properties in a free surface model
- 10.1016/j.future.2004.11.010 may be a valid DOI for title: An efficient exact adjoint of the parallel MIT gen...

INVALID DOIs

- None

[editorialbot]

License info:

✅ License found: MIT License (Valid open source OSI approved license)

[editorialbot]

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

[Alexander-Barth]

Review checklist for @Alexander-Barth

Conflict of interest

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

Code of Conduct

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

General checks

• Repository: Is the source code for this software available at the https://github.com/JuliaOcean/OceanRobots.jl?
• 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 (@gaelforget) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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

Paper format

• Authors: Does the paper.tex file include a list of authors with their affiliations?
• 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?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Content

• Context: is the scientific context motivating the work correctly presented?
• Methodology: is the approach taken in the work justified, presented with enough details and reference to reproduce it?
• Results: are the results presented and compared to approaches with similar goals?

[Alexander-Barth]

Hi @gaelforget, this is a nice paper!

I try to run the first code snipped on the your paper (Code 1).

using OceanRobots , ArgoData , CairoMakie
files_list = GDAC.files_list() ; wmo = 6900900
argo = read(ArgoFloat() , wmo = wmo , files_list = lst )
fig = plot(argo , option = : standard , pol = pol )

It it seems that lst should be files_list. Also pol is undefined.
Should such issues be discussed here, or rather directly in https://github.com/JuliaOcean/OceanRobots.jl ?

[Alexander-Barth]

Concerning "Does installation proceed as outlined in the documentation?": I did not see any specific instruction (or did I miss them?), but I can confirm that package can be installed as any julia package.

[Alexander-Barth]

I am trying to run the notebook Buoy_NWP_NOAA.jl, but I cannot change the station number. It will always show 41046 even if I select 44065.

I am wondering if there is not an issue with this line:

https://github.com/JuliaOcean/OceanRobots.jl/blob/c5179c048d504366ba2175161759261a4242ceb7/examples/Buoy_NWP_NOAA.jl#L69

Should it not be: buoy=read(NOAAbuoy(),sta) (rather than hard coding the station number) ?

[Alexander-Barth]

The notebook Buoy_NWP_NOAA_monthly.jl: can you add unit to the x and y axis? It it in °Fahrenheit ?

Drifter_GDP.jl:

• it would be useful to define ve and vn ( zonal and meridional velocity I guess :-) )
• the y axis is just time and the labels number like 300. Can you add more information about the time unit and origin (like "days since 2000-01-01" ?)

References of the PDF paper:

• please check capitalization of reference 1 (e.g. co2 -> CO2,...), 3 (cmip6 - CMIP6), 6 (argo -> Argo), 11 (mitgcm -> MITgcm)... see https://stackoverflow.com/questions/2800527/preserving-all-capitalization-in-bibtex

[luraess]

Should such issues be discussed here, or rather directly in https://github.com/JuliaOcean/OceanRobots.jl ?

@Alexander-Barth Issues specific to the code, OceanRobots.jl, could be directly discussed in the respective repo (as issue) which can reference this Review issue. Issues, comments and suggestions related to the manuscript and the revision should be discussed here. Hope this helps - thanks!

[gaelforget]

@editorialbot generate pdf

[editorialbot]

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

[gaelforget]

updated code snippet in #164 (comment)

addresses #164 (comment)

Good points! Thank you

[gaelforget]

I am trying to run the notebook Buoy_NWP_NOAA.jl, but I cannot change the station number. It will always show 41046 even if I select 44065.

I am wondering if there is not an issue with this line:

https://github.com/JuliaOcean/OceanRobots.jl/blob/c5179c048d504366ba2175161759261a4242ceb7/examples/Buoy_NWP_NOAA.jl#L69

Should it not be: buoy=read(NOAAbuoy(),sta) (rather than hard coding the station number) ?

Done.

[gaelforget]

The notebook Buoy_NWP_NOAA_monthly.jl: can you add unit to the x and y axis? It it in °Fahrenheit ?

Done

Drifter_GDP.jl:

• it would be useful to define ve and vn ( zonal and meridional velocity I guess :-) )
• the y axis is just time and the labels number like 300. Can you add more information about the time unit and origin (like "days since 2000-01-01" ?)

Done

References of the PDF paper:

• please check capitalization of reference 1 (e.g. co2 -> CO2,...), 3 (cmip6 - CMIP6), 6 (argo -> Argo), 11 (mitgcm -> MITgcm)... see https://stackoverflow.com/questions/2800527/preserving-all-capitalization-in-bibtex

Done in JuliaOcean/OceanRobots.jl@6bb4d8e

[Alexander-Barth]

For people not familiar with Pluto (or Julia), I think it would be nice to mention somewhere that all you need to do is to install julia and Pluto. The installation of OceanRobots.jl and other will be done automatically when you run the notebook. Is this information already somewhere?

[gaelforget]

For people not familiar with Pluto (or Julia), I think it would be nice to mention somewhere that all you need to do is to install julia and Pluto. The installation of OceanRobots.jl and other will be done automatically when you run the notebook. Is this information already somewhere?

Good point! Thanks for the suggestion.

I added on this in the new How-To section , https://juliaocean.github.io/OceanRobots.jl/dev/examples/#How-To

[gaelforget]

Concerning "Does installation proceed as outlined in the documentation?": I did not see any specific instruction (or did I miss them?), but I can confirm that package can be installed as any julia package.

I added installation docs in the new How-To section , https://juliaocean.github.io/OceanRobots.jl/dev/examples/#How-To

[gaelforget]

@editorialbot generate pdf

[editorialbot]

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

[editorialbot]

Hello @luraess, here are the things you can ask me to do:

# List all available commands
@editorialbot commands

# Add to this issue's reviewers list
@editorialbot add @username as reviewer

# Remove from this issue's reviewers list
@editorialbot remove @username from reviewers

# Get a list of all editors's GitHub handles
@editorialbot list editors

# Assign a user as the editor of this submission
@editorialbot assign @username as editor

# Remove the editor assigned to this submission
@editorialbot remove editor

# Remind an author, a reviewer or the editor to return to a review after a 
# certain period of time (supported units days and weeks)
@editorialbot remind @reviewer in 2 weeks

# Adds a checklist for the reviewer using this command
@editorialbot generate my checklist

# Set a value for version
@editorialbot set v1.0.0 as version

# Set a value for branch
@editorialbot set juliacon-paper as branch

# Set a value for repository
@editorialbot set https://github.com/organization/repo as repository

# Set a value for the archive DOI
@editorialbot set 10.5281/zenodo.6861996 as archive

# Mention the EiCs for the correct track
@editorialbot ping track-eic

# Reject paper
@editorialbot reject

# Withdraw paper
@editorialbot withdraw

# Invite an editor to edit a submission (sending them an email)
@editorialbot invite @(.*) as editor

# Run checks and provide information on the repository and the paper file
@editorialbot check repository

# Check the references of the paper for missing DOIs
@editorialbot check references

# Generates the pdf paper
@editorialbot generate pdf

# Recommends the submission for acceptance
@editorialbot recommend-accept

# Accept and publish the paper
@editorialbot accept

# Update data on an accepted/published paper
@editorialbot reaccept

# Generates a LaTeX preprint file
@editorialbot generate preprint

# Flag submission with questionable scope
@editorialbot query scope

# Get a link to the complete list of reviewers
@editorialbot list reviewers

# Creates a post-review checklist with editor and authors tasks
@editorialbot create post-review checklist

# Open the review issue
@editorialbot start review

[luraess]

@jonathanlilly could you please react to this message and provide a time estimate for when you can hand in the revision? If you no longer have time, this is also fine, but please tell it - as we could then find another reviewer and not hold back further the process. I'll set a reminder in 4 days. Thanks

[luraess]

@editorialbot remind @jonathanlilly in 4 days

[gaelforget]

@jonathanlilly could you please react to this message and provide a time estimate for when you can hand in the revision? If you no longer have time, this is also fine, but please tell it - as we could then find another reviewer and not hold back further the process. I'll set a reminder in 4 days. Thanks

Thanks @luraess for the reminders. I was still hoping that @jonathanlilly could complete the checklist quickly, but I agree that we might need to find another reviewer to avoid even more delay.

[jonathanlilly]

Review checklist for @jonathanlilly

Conflict of interest

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

Code of Conduct

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

General checks

• Repository: Is the source code for this software available at the https://github.com/JuliaOcean/OceanRobots.jl?
• 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 (@gaelforget) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

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

Paper format

• Authors: Does the paper.pdf file include a list of authors with their affiliations?
• A statement of need: Does the paper clearly explain the problem it addresses, its importance to the broader community, the intended audience, and how it connects to existing work in the field?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Content

• Context: is the scientific context motivating the work correctly presented?
• Methodology: is the approach taken in the work justified, presented with enough details and reference to reproduce it?
• Results: are the results presented and compared to approaches with similar goals?

[jonathanlilly]

@jonathanlilly could you please react to this message and provide a time estimate for when you can hand in the revision? If you no longer have time, this is also fine, but please tell it - as we could then find another reviewer and not hold back further the process. I'll set a reminder in 4 days. Thanks

My apologies for the long delay, this had fallen off my radar. I'll try to get in done in the next few days.

[luraess]

Thanks for your reply @jonathanlilly - looking fwd to your review!

[gaelforget]

@jonathanlilly could you please react to this message and provide a time estimate for when you can hand in the revision? If you no longer have time, this is also fine, but please tell it - as we could then find another reviewer and not hold back further the process. I'll set a reminder in 4 days. Thanks

My apologies for the long delay, this had fallen off my radar. I'll try to get in done in the next few days.

That would be awesome!

And quite timely as I am schedule to give a presentation related to this work in a couple weeks @ https://www.oceanpredict24.org

Thank you in advance for your review @jonathanlilly

[luraess]

Let's try to get this wrapped up before your event @gaelforget

[jonathanlilly]

I should be able to get this done by Tuesday

[gaelforget]

@editorialbot generate pdf

Regenerating pdf following package name update (Drifters.jl in place of IndividualDisplacements.jl),
plus another round of proofreading. This is the diff : JuliaOcean/OceanRobots.jl@ddb52f8...JuliaConProceedings2023

[editorialbot]

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

[jonathanlilly]

This is a useful package... particularly just having the tools to download all this data in the same place.

Some small comments on the paper

In the abstract, "let's" should be "lets".
The word choice "restful" on the 5th line of section 2 is odd.
sea level pressure along their trajectories.
On p 2, last line, time-variability should not be hyphenated
On p 4, first column, there is a missing reference and partiucularly is misspelled.

Comments on the package

It would be good to have installation instructions in the Readme. I think the information in the example HowTo would be better placed in the Readme.

I don't really think the term "Ocean Robots" is particularly apt. This appears to include all major in situ observing platforms. Of these, I would say drifters, buoys, and ships are definitely not robots. I don't think the term is going to resonate with people, and consequently, I think that with the current name a lot of people who could use this notebook will not manage to find it.

Regarding Community guidelines: "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"

I see guidelines for 1) and 2) in /docs/src/contributing.md. I don't see guidelines for seeking support.

I was able to verify the behavior of the notebooks locally. However, I had a warning in Code 1 (JuliaOcean/OceanRobots.jl#118 (comment)), an error in Code 2 (JuliaOcean/OceanRobots.jl#119 (comment)), an error in running the testset (JuliaOcean/OceanRobots.jl#117 (comment)), and a warning when running the notebooks (JuliaOcean/OceanRobots.jl#120 (comment)).

@luraess, you may want to know that the format used for the paper makes it difficult to copy and paste the code examples. When I do so I get text that looks like this, with extra spaces:

u s i n g O c e a n R o b o t s , A r g o D a t a , C a i r o M a k i e
l s t = G D A C . f i l e s _ l i s t ( ) ; w m o = 6 9 0 0 9 0 0
a r g o = r e a d ( A r g o F l o a t ( ) , w m o = w m o , f i l e s _ l i s t = l s t )

[luraess]

Thanks @jonathanlilly for your feedback. I will see if we can improve the font format I future versions in order to circumvent the copy-paste issue detailed here.

@gaelforget Going reading through the latest draft, I see you have a . instead of a space in the author name which you may want to address.

[gaelforget]

In the abstract, "let's" should be "lets".
The word choice "restful" on the 5th line of section 2 is odd.
sea level pressure along their trajectories.
On p 2, last line, time-variability should not be hyphenated
On p 4, first column, there is a missing reference and partiucularly is misspelled.

• In the abstract, "let's" should be "lets".
• The word choice "restful" on the 5th line of section 2 is odd.
  • this word refers to https://restfulapi.net
  • have now capitalized the acronym part
• sea level pressure along their trajectories.
  • replaced with trajectory, which I think was what you meant
• On p 2, last line, time-variability should not be hyphenated
• On p 4, first column, there is a missing reference and partiucularly is misspelled.
  • fixed partiucularly
  • could not find missing ref; if it's still there in the revised version below, please quote the sentence I should looking for

@editorialbot generate pdf

[luraess]

@editorialbot generate pdf

[editorialbot]

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

[luraess]

@gaelforget your author name still displays with a . which would be good to fix

[gaelforget]

@gaelforget your author name still displays with a . which would be good to fix

Done. Thanks for pointing this out!

[gaelforget]

Regarding Community guidelines: "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"
I see guidelines for 1) and 2) in /docs/src/contributing.md. I don't see guidelines for seeking support.

Done, in 3681ddf1655635741b1901dd60f5c287342b89bc , in section that was renamed as User Directions

[gaelforget]

I don't really think the term "Ocean Robots" is particularly apt. This appears to include all major in situ observing platforms. Of these, I would say drifters, buoys, and ships are definitely not robots. I don't think the term is going to resonate with people, and consequently, I think that with the current name a lot of people who could use this notebook will not manage to find it.

Not sure what do about this one.

• Maybe that depends on how you think of / define what robots are. "A machine or device that operates automatically or by remote control." is a definition that applies to drifters, buoys, or a CTD rosette in my view. Also I envision this package to include more AUVs and ROVs moving forward. So I like the name robots for these reasons.
• I feel there is tradeoff between a specialized audience, and a broader one. Robots speaks to everyone on some level, including high-school students and younger, even though it might not be the most technically accurate. I am open to suggestions but I don't have a better idea at this time for a name that would align better with my goals.
• Could rename package later but would prefer to keep the name as is, and in alignment with the Juliacon presentation.

[gaelforget]

@luraess, you may want to know that the format used for the paper makes it difficult to copy and paste the code examples. When I do so I get text that looks like this, with extra spaces:

I noticed this too, would love to resolve this issue, but don't know how.

Is there a way to avoid the blank spaces @luraess ? is it that I messed up on my end somehow?

[gaelforget]

I was able to verify the behavior of the notebooks locally. However, I had a

• warning in Code 1 (warning in running Code 1 JuliaOcean/OceanRobots.jl#118 (comment))
• an error in Code 2 (error in running Code 2 JuliaOcean/OceanRobots.jl#119 (comment))
• an error in running the testset (error in running testset JuliaOcean/OceanRobots.jl#117 (comment))
• a warning when running the notebooks (warning in opening notebooks JuliaOcean/OceanRobots.jl#120 (comment)).

[luraess]

Is there a way to avoid the blank spaces @luraess ? is it that I messed up on my end somehow?

Could be an issue with the font used in the template. I could check that and let you know.

[luraess]

I just checked and it is not an issue on your side. Realistically, we won't have bandwidth to change something soon enough wrt this getting published so I would just keep it as such for now. It is anyway challenging to select code from snippet via copy & paste because of the two-column layout. I will discuss with the others EiCs to see how we can improve the template in the future.

[gaelforget]

an error in Code 2 (JuliaOcean/OceanRobots.jl#119 (comment))

As said in JuliaOcean/OceanRobots.jl#119 , but just to explain slight delay on my side.

Unfortunately, I am going to have to get back to this one when back from this week's conference though, since I left the u,v file and script back home on a different computer

[gaelforget]

@editorialbot generate pdf

[editorialbot]

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

[gaelforget]

I just checked and it is not an issue on your side. Realistically, we won't have bandwidth to change something soon enough wrt this getting published so I would just keep it as such for now. It is anyway challenging to select code from snippet via copy & paste because of the two-column layout. I will discuss with the others EiCs to see how we can improve the template in the future.

I removed the line numbers on the equations and added semi-colons. This way a copy and paste of a whole snippet will execute.

[gaelforget]

I feel we may be all set after confirming that the two following items have been adressed satisfactorily, or otherwise :

• @Alexander-Barth : Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• @jonathanlilly : error in running Code 2 JuliaOcean/OceanRobots.jl#119 (comment)

Please let me know if anything else remains outstanding.

Thanks!