[REVIEW]: The country converter coco - a Python package for converting country names between different classification schemes

[whedon]

Submitting author: @konstantinstadler (Konstantin Stadler)
Repository: https://github.com/konstantinstadler/country_converter
Version: v0.4
Editor: @labarba
Reviewer: @rgieseke
Archive: 10.5281/zenodo.838248

Status

Status badge code:

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

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) 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 questions

@rgieseke, please carry out your review in this issue by updating the checklist below (please make sure you're logged in to GitHub). The reviewer guidelines are available here: http://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @labarba know.

Conflict of interest

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (such as being a major contributor to the software).

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 repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: Does the release version given match the GitHub release (v0.4)?
• Authorship: Has the submitting author (@konstantinstadler) made major contributions to the software?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: Have any performance claims of the software been confirmed?

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 function 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks for JOSS. @rgieseke it looks like you're currently assigned as the reviewer for this paper 🎉.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As as reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all JOSS reviews 😿

To fix this do the following two things:

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

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

For a list of things I can do to help you, just type:

@whedon commands

[labarba]

@rgieseke : Thanks for volunteering to review. This is the place to enter your comments, as you go through the review checklist, but you are also encouraged to open new issues in the repository of the software, if needed.

[rgieseke]

Will do, thanks!

[rgieseke]

The coco country converter is a very useful Python library for conversion of country name variants as they appear in real-world datasets that through its included command line tool and some hints for Matlab users can be used even beyond the Python eco-system. Its user base will also likely extend beyond the ones mentioned in the accompanying paper, as the functions provided by coco are needed in many data analysis and visualisation problems.

@konstantinstadler
Once the issues opened in the contry_converter repo are discussed and check boxes ticked off, this should be ready for publication.

[konstantinstadler]

Thank you very much for your review! I will address the issues in the next days in the branch joss_review.
I will close the issues as I address them, please reopen if you think I not fully address your suggestions.

[konstantinstadler]

@rgieseke
I went through the issues and responded to all of them. Many thanks for all your comments, in particular the suggestion with the contribution file - this made me actually thinking how I want people to contribute.
So far, all changes are in the "joss_review" branch, I will merge them with the master when I get your ok.

[rgieseke]

Excellent! Thanks for adressing all issues and the detailed descriptions in the CONTRIBUTING file, this should be very helpful for potential contributors!

@labarba The version number will be updated (IndEcol/country_converter#10) after finalizing the review, so this might need changing in the meta-data of this issue (don't know if it's actually used in the submission process)

Another question, ist there a JOSS policy already on using Zenodo's version dois?
https://doi.org/10.5281/zenodo.838035
Likely the specific version reviewed should be used, but the version doi is of course quite useful for software.

[rgieseke]

@konstantinstadler A final (minor) thing: Can you update the meta-data in the Zenodo archive to include the license and maybe update the title (don't know how Zenodo generates this by default). Once the JOSS paper is out you can also add a reference back to the paper. I think there is a way to have a JSON meta-data file but I can't find the documentation for this right now, but you can always edit these when logging in to Zenodo.

You might also consider adding a CITATION file or notice in the Readme on how you would like users to cite coco if they used in their research, see e.g. https://www.software.ac.uk/blog/2013-09-02-encouraging-citation-software-introducing-citation-files (For example asking to cite the JOSS paper.)

Otherwise, once you merged the review branch coco should be ready for publication in JOSS!

[konstantinstadler]

@rgieseke Great. I updated the Zenodo description. I will do the link to JOSS and the CITATION file as soon as I get a doi for coco. I will merge with master now but wait with the push to PyPI after the JOSS process is completed.
Thanks again for the review! Working with the issues tracker is so much more efficient than the traditional scientific paper review process...

[labarba]

I don't know the answers to your questions, @rgieseke — @arfon ?

This submission is ready to accept, once @kaneplusplus enters here the final archive DOI for the revised software.

[rgieseke]

@konstantinstadler I don't see changes on https://zenodo.org/record/838036 yet - can you check again?

Thanks for publishing this as a re-usable tool, I'm sure it will be quite useful to many others!

[konstantinstadler]

Yes, I see. I can save but I get an internal server error if I want to publish the changes (I will try again later). Anyhow, the current upload to Zenodo is just for the history (v0.4). I will re-upload as soon as I can do the cross-reference to the JOSS doi.

[arfon]

Another question, ist there a JOSS policy already on using Zenodo's version dois?
https://doi.org/10.5281/zenodo.838035

Versioned DOIs are 👍 with JOSS.

[rgieseke]

@konstantinstadler Maybe a temporary problem - I thought that depending on how you set-up the Zenodo integration you just would need to tag a new release on GitHub: https://guides.github.com/activities/citable-code/

[rgieseke]

@arfon In that case, it should be ready for publication with the concept doi.

[arfon]

@whedon set 10.5281/zenodo.838035 as archive

[whedon]

OK. 10.5281/zenodo.838035 is the archive.

[arfon]

@arfon In that case, it should be ready for publication with the concept doi.

Sorry, to be clear, we would like to know the explicit version of the DOI that corresponds to the work associated with this JOSS submission before proceeding.

[rgieseke]

Makes sense to have the reviewed final version archived and referenced!

Maybe the JOSS page and/or paper could still link to the concept doi as well?

[arfon]

Maybe the JOSS page and/or paper could still link to the concept doi as well?

You're welcome to cite it in the paper. We're not able to make two links to two different archives of the software on the JOSS page sorry.

[konstantinstadler]

Sorry for complicating the stuff with the zenodo upload and doi. I now could change the meta information in zenodo.
Would it help if I now upload v0.5 (the outcome of the JOSS review) and you set this as the concept doi?

[rgieseke]

I think there only needs to be v0.5 (as it was reviewed) tagged on GitHub and archived on Zenodo (and on PyPI) - did you do a manual upload or did you use the GitHub integration?

If you used the integration I think you just have to tag v0.5.

For the JOSS publication only the reviewed archive is relevant. (Users can then find later versions via the concept doi on Zenodo, or if you mention the concept doi in the paper or Readme.)

[konstantinstadler]

Ok. You have to tag and make a release in github. I have done that, the new zenodo doi is

10.5281/zenodo.838248

[konstantinstadler]

This version is now also available in PyPI

[arfon]

@whedon set 10.5281/zenodo.838248 as archive

[whedon]

OK. 10.5281/zenodo.838248 is the archive.

[arfon]

@rgieseke - many thanks for your review here and to @labarba for editing this one ✨

@konstantinstadler - your paper is now accepted in JOSS and your DOI is http://dx.doi.org/10.21105/joss.00332 ⚡️ 🚀 💥

[konstantinstadler]

@rgieseke @labarba @arfon Many thanks. That was a pleasant experience - would love to see more journals using the issue approach for reviewing!