[REVIEW]: PolarToolkit: Python Tools for Convenient, Reproducible, and Open Polar Science

[editorialbot]

Submitting author: @mdtanker (Matt Tankersley)
Repository: https://github.com/mdtanker/polartoolkit
Branch with paper.md (empty if default branch): JOSS_paper
Version: v0.5.1
Editor: @hugoledoux
Reviewers: @PennyHow, @JessicaS11
Archive: 10.5281/zenodo.13218540

Status

Status badge code:

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

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

@PennyHow & @JessicaS11, 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 @hugoledoux 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 @PennyHow

📝 Checklist for @JessicaS11

[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's md or bib files, type:

@editorialbot generate pdf

[editorialbot]

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

OK DOIs

- 10.1016/j.rse.2008.07.006 is OK
- 10.1594/PANGAEA.951482 is OK
- 10.1594/PANGAEA.819147 is OK
- 10.5194/tc-7-375-2013 is OK
- 10.1016/j.cageo.2016.08.003 is OK
- 10.5334/jors.148 is OK
- 10.21105/joss.01943 is OK
- 10.5281/zenodo.5607255 is OK
- 10.21105/joss.00957 is OK
- 10.1029/2019GC008515 is OK

MISSING DOIs

- No DOI given, and none found for title: MEaSUREs Antarctic Boundaries for IPY 2007-2009 fr...
- No DOI given, and none found for title: QGIS Geographic Information System

INVALID DOIs

- None

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.90  T=0.26 s (281.9 files/s, 319038.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          14           1584           3237           7037
Markdown                        16            369              0           1253
Jupyter Notebook                17              0          64286            977
TeX                              2             63              0            892
YAML                            12             64             83            764
CSV                              1              0              0            265
TOML                             1             21              4            249
SVG                              1              1              1            165
make                             1             25              9             59
JSON                             1              0              0             32
reStructuredText                 6              3             27             12
-------------------------------------------------------------------------------
SUM:                            72           2130          67647          11705
-------------------------------------------------------------------------------

Commit count by author:

   401	mdtanker
    44	Matt Tankersley
    14	semantic-release
     9	Matthew Tankersley
     9	dependabot[bot]
     5	github-actions
     3	Matt Tankerlsey
     1	Hugo Ledoux

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 1532

✅ The paper includes a Statement of need section

[editorialbot]

License info:

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

[editorialbot]

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

[PennyHow]

Review checklist for @PennyHow

Conflict of interest

• 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

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

General checks

• Repository: Is the source code for this software available at the https://github.com/mdtanker/polartoolkit?
• 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 (@mdtanker) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• 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

Software paper

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

[JessicaS11]

Review checklist for @JessicaS11

Conflict of interest

• 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

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

General checks

• Repository: Is the source code for this software available at the https://github.com/mdtanker/polartoolkit?
• 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 (@mdtanker) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• 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

Software paper

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

[hugoledoux]

@JessicaS11 @PennyHow just a friendly reminder not to forget this review

[PennyHow]

I am struggling to install PolarToolkit and have been trying to follow the instructions for constructing it with conda in Python 3.9, 3.10, 3.11 and 3.12 environments. Mainly it is unable to solve the environment with the stated dependencies and packages with C bindings. @mdtanker, could you please provide an environment.yml file so that I can construct an environment and install polartoolkits from a local copy of your repo? I.e.

conda my_env export > environment.yml

In terms of the paper and documentation, I think these are generally looking good. I've made some suggestions and put them into a PR here. The main points are:

• An Introductory description of polartoolkit has been added to the repo readme, which I have merely taken from the paper. Starting the repo readme with a disclaimer is confusing as it is difficult to discern what the package is

• An Introductory description of polartoolkit has been added to the readthedocs front page, for similar reasonings to those above

• Installation instructions have been added to the repo readme (taken from readthedocs) as the repo readme is a primary user entry point. Therefore, basic installation instructions should be provided here also

I can provide a review on the package functionality once I can run polartoolkit.

[mdtanker]

@PennyHow sorry that there are issues with the install! I used to encounter lots of issues due to the C dependencies but thought all of that had been fixed. I guess not...

GitHub is not letting me attach a .yml, so I've just changed it to a .txt

polartoolkit.txt

Please let me know if that works.

[PennyHow]

Please let me know if that works.

It works! Thank you.

[JessicaS11]

Hello @mdtanker! Great toolkit. Below please find my review comments, notwithstanding mdtanker/polartoolkit#193, mdtanker/polartoolkit#194, mdtanker/polartoolkit#62, and agreement with review comments from @PennyHow on adding more information to the documentation.

Documentation

I really like all the invitations for contributions, including reminders and notes that it's okay if your submission isn't perfect or you don't know how to use all the tools.

Example Usage

Do you have any examples of a scientific workflow (perhaps as part of a tutorial or publication) containing one of the figures generated by this software?

Community guidelines

For updates (or new) notebooks, should contributors run them locally and push with outputs, or clear all outputs?

Software Paper

There's a link typo (to the old repo) on line 38.

Summary and Statement of Need

The summary is well written, though it suggests the current functionality enables all "Polar" research while in reality it is still limited to Antarctica, with plans to expand to the Arctic/Greenland (yay!). This technicality is important from a user perspective and also because expanding the current package to the north pole will include substantial additions that are not captured in the software release with the current paper.

It would also be helpful for more details in the paper (and documentation) around what types of datasets are available, and what types of polar research they are enabling. For instance, it appears that most (all?) of the source datasets are gridded.

State of the field

Could you please elaborate on how this fits into the broader tool landscape? For instance, as noted in the documentation, the fetch module uses icepack's EarthDataDownloader class.

[PennyHow]

Thanks for a nice submission, @mdtanker! Generally I feel that this is a great package with good entry-level functionality for beginners in programming, and also handy tools for seasoned cryospheric coders to quickly generate publication-ready figures. The documentation and package structuring reflects these two target user types, with thorough documentation and tutorials.

I have two major comments that need to be addressed before accepting, along with some minor comments:

The functionality is limited to Antarctica

The term "polar" places an expectation on the package being usable with Antarctic and Arctic datasets. Currently functionality only accomodates datasets for Antarctica. You say that ideally you would like polartoolkit to develop further for use with data from Greenland and the Arctic. On the readthedocs home page, it is stated that this is happening "soon". When is "soon" and would this be within the timeframe of this review process?

Whilst I do not need to see a full implementation of these Greenland/Arctic developments, I think there should be certain changes in the naming conventions and package structuring so that it is easy to foresee how Greenland/Arctic datasets and analysis could be incorporated. For example, I see that the names of the currently available datasets are generically named and not place-specific:

>>> import polartoolkit.fetch
>>> print("\n".join(polartoolkit.fetch.get_fetches()))
basal_melt
basement
bedmachine
bedmap2
bedmap_points
crustal_thickness
deepbedmap
etopo
geoid
geomap
ghf
gia
gravity
groundingline
ibcso
ibcso_coverage
ice_vel
imagery
magnetics
mass_change
measures_boundaries
modis_moa
moho
rema
rosetta_gravity
rosetta_magnetics
sediment_thickness

These should be changed accordingly so that Greenland/Arctic dataset names could be easily incorporated, i.e. basal_melt >> antarctic_basal_melt.

If you think it is possible, I would also like to request one Greenland/Arctic example be developed and placed in the tutorials/gallery to demonstrate the viability of this future development.

The installation needs to be more straightforward for beginner users

The extensive list of package dependencies mean that it takes a long time for mamba/conda to solve the environment with installation. Even the Binder online build did not work for me as it cannot solve the environment in a timely manner.

As this package is partially aimed at beginners in programming, the set-up needs to be simple otherwise it is not accessible for these users. Whilst the installation troubleshooting documentation is good, I think that the package should be modified to make the installation easier. You can solve this problem however you think is best, whether it be changing the package distribution itself, or adding more extensive installation guidance.

Suggestion: I would look at the number of dependencies and refine them by trying to find common functionality between them. And I would also look at alternatives to geopandas, cartopy and pygmt that do not have C bindings (as this is may resolve the issues with the online Binder build).

Minor comments

Functionality

• Indentation error in subplots tutorial mdtanker/polartoolkit#198
• Plot viewing procedures differ in the Download Antarctica datasets tutorial mdtanker/polartoolkit#199
• EarthDataDownloader object to retain user login credentials mdtanker/polartoolkit#200

Installation

• The repo is quite big for cloning. Is there anything you can remove to slim down the repo contents and size?
• For conda installation, please define that users should make sure they should add the conda-forge channel
• Can you provide some install tests for users in the documentation and repo readme to ensure that their installation works. It could be a simple version call, or some form of unit tests.
• Please can you add the environment yml file to the repo which you previously provided me. I think it is a good option to have if a user is troubleshooting their install (like me!)

Documentation

• Most of the issues with documentation have already been addressed in this PR

Software paper

• Regarding the state of the field: I think there are other resources/commonly-used packages out there for arctic data handling - check out the cryosphere awesome list. I would include earthspy at least. I see you also reference Fatiando in the readthedocs documentation, which should probably be added here also.

Other

• The logo for polartoolkits looks fairly similar to other software logos I have come across, such as this. It's not really anything that needs specifically changing (maybe it is hard to avoid!), but I just thought I would make you aware that this type of logo is quite common for software related to cryospheric sciences.

[hugoledoux]

@mdtanker could you please let us know when you plan to address the reviewers' suggestions/issues?

[mdtanker]

Hi all, thank you all for the prompt and thorough reviews! I really appreciate all the time you have put in. Apologies for not responding sooner, but I've been trying to address many of the suggestions before doing a line-by-line response. I've made lots of commits in the past two weeks to the PR: joss-edits.

Some of these suggestions will take some more time to correctly implement, but I anticipate being done within 2-3 weeks. The major things left for me to do are add all the available datasets to a gallery, add a few more Greenland-specific datasets, and try and reduce the dependencies and size of the repo.

Once I have accomplished most of these tasks, I will address all your comments here 😃

[mdtanker]

Another update: this turned into a slightly bigger task than I had anticipated. Adding support for Greenland and the Arctic required some pretty significant refactoring of the code, but I think it is done now.

Remaining tasks to do:

• expand the state of the field in the paper
• EarthDataDownloader object to retain user login credentials mdtanker/polartoolkit#200
• release v0.4.0 by merging Joss edits mdtanker/polartoolkit#212

I should be able to get these done soon and give line-by-line responses to the suggestions. Thanks again for all of your patience with this!

[hugoledoux]

@editorialbot set v0.5.1 as version

[editorialbot]

Done! version is now v0.5.1

[hugoledoux]

@editorialbot recommend-accept

[editorialbot]

Attempting dry run of processing paper acceptance...

[editorialbot]

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

OK DOIs

- 10.1016/j.rse.2008.07.006 is OK
- 10.1594/PANGAEA.951482 is OK
- 10.1594/PANGAEA.819147 is OK
- 10.5194/tc-7-375-2013 is OK
- 10.1016/j.cageo.2016.08.003 is OK
- 10.5334/jors.148 is OK
- 10.21105/joss.04912 is OK
- 10.5281/zenodo.7897023 is OK
- 10.21105/joss.01943 is OK
- 10.5281/zenodo.5607255 is OK
- 10.21105/joss.00957 is OK
- 10.1029/2019GC008515 is OK

MISSING DOIs

- No DOI given, and none found for title: Earthspy
- No DOI given, and none found for title: ITSLIVE
- No DOI given, and none found for title: MEaSUREs Antarctic Boundaries for IPY 2007-2009 fr...
- No DOI given, and none found for title: QGIS Geographic Information System

INVALID DOIs

- None

[editorialbot]

👋 @openjournals/ese-eics, this paper is ready to be accepted and published.

Check final proof 👉📄 Download article

If the paper PDF and the deposit XML files look good in openjournals/joss-papers#5782, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[mdtanker]

@editorialbot accept

[editorialbot]

I'm sorry @mdtanker, I'm afraid I can't do that. That's something only eics are allowed to do.

[mdtanker]

Looks good to me!

[kthyng]

Hi! I'll take over now as Track Associate Editor in Chief to do some final submission editing checks. After these checks are complete, I will publish your submission!

• Are checklists all checked off?
• Check that version was updated and make sure the version from JOSS matches github and Zenodo.
• Check that software archive exists, has been input to JOSS, and title and author list match JOSS paper (or purposefully do not).
• Check paper.

[kthyng]

@mdtanker I am delighted by your histogram colorbar! I would love to see that available in a more general toolbox, something like matplotlib! Might you consider that?

[mdtanker]

Yes I'd love to see that implemented in matplotlib! I'll have a look sometime at their code and how to implement it. I find it so useful to show the distribution!

[kthyng]

Sorry I didn't dig deep enough to see whose code it was. But regardless, very cool, along with the rest of the package! Everything looks ready to go!

[kthyng]

@editorialbot accept

[editorialbot]

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

[editorialbot]

Ensure proper citation by uploading a plain text CITATION.cff file to the default branch of your repository.

If using GitHub, a Cite this repository menu will appear in the About section, containing both APA and BibTeX formats. When exported to Zotero using a browser plugin, Zotero will automatically create an entry using the information contained in the .cff file.

You can copy the contents for your CITATION.cff file here:

CITATION.cff

cff-version: "1.2.0"
authors:
- family-names: Tankersley
  given-names: Matthew D.
  orcid: "https://orcid.org/0000-0003-4266-8554"
doi: 10.5281/zenodo.13218540
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Tankersley
    given-names: Matthew D.
    orcid: "https://orcid.org/0000-0003-4266-8554"
  date-published: 2024-08-22
  doi: 10.21105/joss.06502
  issn: 2475-9066
  issue: 100
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 6502
  title: "PolarToolkit: Python Tools for Convenient, Reproducible, and
    Open Polar Science"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.06502"
  volume: 9
title: "PolarToolkit: Python Tools for Convenient, Reproducible, and
  Open Polar Science"

If the repository is not hosted on GitHub, a .cff file can still be uploaded to set your preferred citation. Users will be able to manually copy and paste the citation.

Find more information on .cff files here and here.

[editorialbot]

🐘🐘🐘 👉 Toot for this paper 👈 🐘🐘🐘

[editorialbot]

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

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.06502 joss-papers#5804
1. Wait five minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.06502
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[kthyng]

Congratulations on your new publication @mdtanker! Many thanks to editor @hugoledoux and to reviewers @PennyHow and @JessicaS11 for your time, hard work, and expertise!! JOSS wouldn't be able to function nor succeed without your efforts.

@mdtanker If you're interested in joining JOSS as a reviewer, please sign up at https://reviewers.joss.theoj.org/!

[editorialbot]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.06502/status.svg)](https://doi.org/10.21105/joss.06502)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.06502">
  <img src="https://joss.theoj.org/papers/10.21105/joss.06502/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.06502/status.svg
   :target: https://doi.org/10.21105/joss.06502

This is how it will look in your documentation:

We need your help!

The Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://reviewers.joss.theoj.org/join
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

[mdtanker]

Wohoo! Thanks for all the time and energy everyone! I enjoyed this review process and think PolarToolkit is much better due to it! I've signed up to be a reviewer 🙂

[PennyHow]

Wohoo! Thanks for all the time and energy everyone! I enjoyed this review process and think PolarToolkit is much better due to it! I've signed up to be a reviewer 🙂

@mdtanker, I think you are a great addition to the team of reviewers behind JOSS.Welcome!