[JOSS REVIEW]: Tiny changes to manuscript and docs

[dostuffthatmatters]

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

Dear authors of pyfive,

I agree with your arguments in the manuscript and nothing major is missing from it. Below you can find a few things I would update.

Manuscript:

• L11: "pyfive (https://pyfive.readthedo...)" I would avoid the link to the docs here in case you should ever change it (e.g., to an NCAS domain). The paper has the link to the repository on the left column.
• L12: "While it is not a complete implementation of all the specifications and capabilities of HDF5, it includes all the core functionality necessary to read gridded datasets, whether stored contiguously or with chunks." This statement is a bit vague. Could you maybe elaborate a bit, which features of HDF5 pyfive does not support. I would mention compression as one of the supported features. Does pyfive support all kinds of compression HDF5 supports? If this list of supported and unsupported features gets too long, you could also reference a docs page.
• L19: I think you should cite https://github.com/h5py/h5py. Their repo or docs do not have a citation guideline, but you can just cite the GitHub repo with its latest version.
• L27: "While newer formats are starting to get mindshare" it would be good to name and cite these never alternatives.
• L52: "Current Status" is a bit unspecific. Maybe rename it to something like "Current State of pyfive" or "Current State of The Project. Because "Current Status" could also mean state-of-the-art (without pyfive)
• L65: "To improve internal metadata access,pyfive" -> no space between "access" and "pyfive"

Docs:

• It is hard to get from the readthedocs page to GitHub. So maybe just add a link with the GitHub repo on top of the introduction page, or somewhere in the sidebar as a link.

Best,
Moritz Oliveira Makowski

[valeriupredoi]

thanks, Moritz! I'll enlist Bryan and David on this one - cheers!

[valeriupredoi]

It is hard to get from the readthedocs page to GitHub. So maybe just add a link with the GitHub repo on top of the introduction page, or somewhere in the sidebar as a link.

Excellent suggestion! Am on this one right now 🍺

[valeriupredoi]

It is hard to get from the readthedocs page to GitHub. So maybe just add a link with the GitHub repo on top of the introduction page, or somewhere in the sidebar as a link.

Excellent suggestion! Am on this one right now 🍺

done in #185 🍺

[bnlawrence]

Hi @dostuffthatmatters. Thanks for this. I have done most of your manuscript fixes (723c2ce), but I've left two undone (sort of in the case of the first one):

L12: Unfortunately HDF5 has an abundance of (from our point of view "edge-case") features, and the features are very version specific. Your request here is very open ended. I take your point on using documentation rather than doing it in the paper, and we have already done that in the usage section, which outlines all the things we do support. What we don't support is most everything else. (There are a couple of things that are not in the docs, but they aren't really battle tested yet, so I'm happy to not say they are supported or document them yet.) I think we're about as explicit as h5py is about what we support.

(That said, your point about compression is a good one. I have stuffed mention of that in the paper, and added a comment about compression into the main documentation.)

L27: On mindshare and listing things. The main "newer" format is zarr, but I'd prefer not to namecheck it (or anything else), as there is an implied criticism in doing so - I'd rather just talk about pyfive and not make explicit comparisons (we don't have the space).

Are you ok with that?

[dostuffthatmatters]

Hi @bnlawrence

Thank you for the updates.

L12: Unfortunately HDF5 has an abundance of (from our point of view "edge-case") features, and the features are very version specific. Your request here is very open ended. I take your point on using documentation rather than doing it in the paper, and we have already done that in the usage section, which outlines all the things we do support. What we don't support is most everything else. (There are a couple of things that are not in the docs, but they aren't really battle tested yet, so I'm happy to not say they are supported or document them yet.) I think we're about as explicit as h5py is about what we support.

(That said, your point about compression is a good one. I have stuffed mention of that in the paper, and added a comment about compression into the main documentation.)

Very valid point. I agree with explicitly naming what you support. Thank you for mentioning compression. To be fair, so far I did not find a usecase HDF supports that pyfive does not support.

L27: On mindshare and listing things. The main "newer" format is zarr, but I'd prefer not to namecheck it (or anything else), as there is an implied criticism in doing so - I'd rather just talk about pyfive and not make explicit comparisons (we don't have the space).

Valid. I was mainly thinking about ZARR too. I know the 1000 word limit is tough, so a deep comparison here is not feasible.

Best,
Moritz

[valeriupredoi]

very many thanks @dostuffthatmatters and @bnlawrence 🍻