search

lnferris / ocean_data_tools

A MATLAB toolbox for interacting with bulk freely-available oceanographic data.
MIT License
83 stars 24 forks source link

Installation instructions #26

Closed kakearney closed 4 years ago

kakearney commented 4 years ago

This issue is part of the JOSS review (openjournals/joss-reviews#2497)

The installation instructions are sufficient, but could be improved. This toolbox is specifically targeted to an audience of users who are new to working with these various oceanographic datasets, and this audience likely skews towards novice Matlab users, including students and early career scientists. Because of this, I recommend a more complete set of instructions for getting up and running with the toolbox. For example, explicitly state which folders need to be added to the path:

and explain how to alter the path (or link to Mathworks documentation: https://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html)

A more in-depth overview of the various data sources would also be very helpful to this target audience. The "Finding Data" section of the README gives a bare bones overview of where to get data, but a paragraph or two devoted to each supported data source would be nice. The data aquisition phase can be intimidating for new users. What sort of data should they expect to find in the various sources? Which datasets need to be downloaded manually via the users, as opposed to those that can be accessed remotely via OpenDAP? (You mention that the mocha url is embedded, but users unfamiliar with Matlab's OpenDAP capabilities may not understand what that means, i.e. that they don't need to download anything.) For the ones that need to be downloaded manually, it may be useful to include a few examples for how to get that data (though I know the various data portals are not guaranteed to maintain their current format). Also note, the following links are broken for me:

The majority of users are probably going to simply download the ocean_data_tools code, rather than clone and maintain via git, but in the case of the latter, you should recommend they store large data files somewhere outside of the main repository. Version control does not play nicely with constantly-evolving collections of netCDF files.

Finally, consider linking the ocean_data_tools repository to the MatlabCentral File Exchange (https://www.mathworks.com/matlabcentral/fileexchange/). Entries in the File Exchange can be downloaded directly from Matlab via the Add-On Explorer (i.e. the APPS > "Get More Apps" button in the Matlab Desktop). The File Exchange can pull directly from GitHub, so linking your existing repo to the FEX should be pretty easy, and the FEX entry will remain synced with any future changes.

lnferris commented 4 years ago

I have expanded the installation instructions, added information about which datasets are manual download vs. remote access, and fixed broken links.

lnferris commented 4 years ago

I have added ocean_data_tools to the MatlabCentral File Exchange.