[PRE REVIEW]: ocean_data_tools: A MATLAB toolbox for interacting with bulk freely-available oceanographic data

[whedon]

Submitting author: @lnferris (L. N. Ferris)
Repository: https://github.com/lnferris/ocean_data_tools
Version: v1.0.0
Editor: @kthyng
Reviewers: @castelao, @chadagreene
Managing EiC: Daniel S. Katz

⚠️ JOSS reduced service mode ⚠️

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

Author instructions

Thanks for submitting your paper to JOSS @lnferris. Currently, there isn't an JOSS editor assigned to your paper.

@lnferris if you have any suggestions for potential reviewers then please mention them here in this thread (without tagging them with an @). In addition, this list of people have already agreed to review for JOSS and may be suitable for this submission (please start at the bottom of the list).

Editor instructions

The JOSS submission bot @whedon is here to help you find and assign reviewers and start the main review. To find out what @whedon can do for you type:

@whedon commands

[whedon]

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

⚠️ JOSS reduced service mode ⚠️

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

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]

Failed to discover a Statement of need section in paper

[whedon]

Software report (experimental):

github.com/AlDanial/cloc v 1.84  T=0.35 s (145.3 files/s, 9301.0 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
MATLAB                          38            551            328           1597
Python                           5             90             90            233
Markdown                         2             36              0             92
C Shell                          5             49             64             79
TeX                              1              5              0             50
-------------------------------------------------------------------------------
SUM:                            51            731            482           2051
-------------------------------------------------------------------------------


Statistical information for the repository '2433' was gathered on 2020/07/03.
The following historical commit information, by author, was found:

Author                     Commits    Insertions      Deletions    % of changes
Laur Ferris                      1             0              8            0.29
Lauren Newell Ferris            13           544            372           33.52
lnferris                        15          1029            780           66.19

Below are the number of rows from each author that have survived and are still
intact in the current revision:

Author                     Rows      Stability          Age       % in comments
Laur Ferris                 413          100.0         17.0               21.79

[whedon]

Reference check summary:

OK DOIs

- 10.11646/zootaxa.4802.1.5 is OK
- 10.1111/ddi.13079 is OK
- 10.5281/zenodo.3928714 is OK
- 10.1126/science.277.5334.1956 is OK
- 10.5670/oceanog.2016.66 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[lnferris]

@whedon generate pdf

[whedon]

👉 Check article proof 📄 👈

[castelao]

Hi @kthyng , I'm not a regular Matlab user for a long time now but I still do a few bits when necessary. Therefore, I won't be able to evaluate it as a modern Matlab way of doing things. If that's fine, I can review this submission.

[ooo]

👋 Hey @castelao...

Letting you know, @kthyng is currently OOO until Monday, July 20th 2020. ❤️

[chadagreene]

Interesting. Yes, I can do the review, but I'll be swamped for the next few weeks. If you find someone who can do it sooner, then by all means, have them do the review. Otherwise I can do it after August 1 (I might need a reminder).

[lnferris]

Thanks for your time, @castelao and @chadagreene. Please let me know if you have any questions.

[kthyng]

@castelao That's fine — I think you focusing on the data access and oceanography in particular would be excellent, and @chadagreene is active in MATLAB so he could focus a bit more on that, so everything will be covered.

@chadagreene after August 1st is totally fine. I'll set you both up as reviewers and then set a reminder for you for August 2nd.

[kthyng]

@whedon assign @castelao as reviewer

[whedon]

OK, @castelao is now a reviewer

[kthyng]

@whedon add @chadagreene as reviewer

[whedon]

OK, @chadagreene is now a reviewer

[kthyng]

@lnferris I know you've asked questions about your submission in a pre-submission inquiry, so here is a little more info. Our review process is usually fairly interactive between the author(s) and reviewers, and it can be a great opportunity to learn code/package best practices, so I encourage you to take advantage of your reviewer expertise! Your package looks useful, though a little thin, so if there are clear places that come up in review to add in some additional functionality, that could make your package used quite a bit more. Let me know if you have questions along the way!

[kthyng]

@whedon start review

[whedon]

OK, I've started the review over in #2497.

[chadagreene]

@lnferris as I mentioned, it will be a few weeks before I can focus on a detailed review, but based on a quick glance through the .m files, one request I will have is that each function be given a header that can be accessed by typing help myfunction into the command line. Ideally, I'd like to see either .mlx or .html files with rich documentation as well so users can see and follow along with examples, but for starters it's important to at least include headers for every function.

If you want to get started on that now, I recommend following the template of official Matlab documentation, listing Syntax, Description, and Examples. The Syntax is generally a list of all the different ways users can specify inputs. The Description section describes in words what each type of syntax does and when you might want to use it. And provide a couple of Examples, starting with the simplest case scenario and then getting more complex. The Examples are good not only to help users learn how to use your functions, but the Examples also serve as reliable tests to ensure your function is working as expected. Here's a dummy template:

function b = myfunction(a,varargin)
% myfunction magically transforms a into b. 
% 
%% Syntax
% 
%  b = myfunction(a) 
%  b = myfunction(a,'Option',Value)
% 
%% Description 
% 
% b = myfunction(a) converts a into b. Input a can be any MxN matrix
% containing numerical values. 
%  
% b = myfunction(a,'Option',Value) specifies a value of an optional
% input 'Option'. By default, Value is 0, but may be set to any finite
% scalar value. 
% 
%% Example 1
% Determine the value of b if a equals five: 
% 
%  a=5; 
%  b=myfunction(a)
%
%% Example 2
% Convert a 5x4 matrix of values of a into b, and specify an Option  
% value of 16: 
% 
%  a=rand(5,4); 
%  b=myfunction(a,'Option',16)
%
%% Citation Info 
% Link to your GitHub here. 
% 
% See also myotherfunction and myotherotherfunction.

[kthyng]

@chadagreene This is excellent to have as a starting point in the meantime! Could you start an issue in the repo with this comment, and provide a link into the review issue? This is the best way to keep track of issues that come up in the review so that details are linked in but not taking up the review issue space.

[lnferris]

@chadagreene thanks for the feedback, will start on it immediately.

[chadagreene]

@lnferris Sounds good.

Sorry to bread-crumb the suggestions here, but you might also want to provide some sort overview page, where all the functions are organized in a way that users can quickly find the function they need based on the task they're trying to accomplish. I'm thinking something along these lines, and it could take the form of a documentation page accessible in the Matlab Documentation Viewer, or it could just be detailed in the README.md. Or perhaps you'll come up with some other way to do it, but you know, just something to help users figure out which functions they need for a given task.

[kthyng]

@chadagreene Again, these suggestions are great, but please put them each in a separate issue on the github repo, then provide a link in the issue to the review issue (which is not this page). Nothing else should go here in the pre-review issue. Let me know if you need any help with this part of the JOSS review since it's unusual.

[lnferris]

I added help-accessible headers (Syntax, Description, Examples, Info) to all functions. 👍 I don't know what bread-crumb is but will expand README.md into an overview page.