JOSS Review

[mcflugen]

@DirkEilander, @hboisgon, @markhegnauer Thank you for your JOSS submission for HydroMT. I think it's a great contribution and I don't see any major changes you need to make. I'll use this issue as a place to provide comments.

In the interest of getting things going, I have some minor edit suggestions to the paper that I'll provided now. The line numbers refer to those in the build of the paper here.

Minor edits:

• [x] Line 8: replace “requires” with “require”
• [x] Line 8: remove “that are”
• [x] Line 9: drop “the” before “manual setup”
• [x] Line 9: remove “very”
• [x] Line 31/32: remove “a lot of”
• [x] Line 35: I'm not sure "peculiar" is the correct word, maybe instead use “idiosyncratic”?
• [x] Line 60: replace “package” with “packages”
• [x] Line 63: “different models that”, not “difference models which”
• [x] Line 73: remove “globally”?
• [x] Line 79/80: replace “each of the HydroMT components” with “each HydroMT component”
• [x] Line 88/89: I think the sentence that begins with “tables for” should be reworded. Maybe “tables that can be used to, for example, convert land classes to roughness values”?
• [x] Line 100: “that” not “which”
• [x] Line 116: “Second, the user defines…”
• [x] Line 117: “that” not “which”
• [x] Line 119: “Third, the user configures…”
• [x] Line 124: “Finally, the user runs…”
• [x] In data_catalog.py: I think the cross-reference is incorrect.

  -            See :py:func:`~hydromt.data_adapter.DataCatalog.from_yml` for accepted yaml format.
  +            See :py:func:`~hydromt.data_catalog.DataCatalog.from_yml` for accepted yaml format.

openjournals/joss-reviews#4897

[mcflugen]

A few additional comments:

• I think the paper could benefit from a definition of terms. In particular, what do the authors mean by a "model"? For me, the term "model" refers to what might be called a software model and is, I think, what the authors refer to in the Summary section. That is, a piece of software that ingests input data, solves a set of equations that represent a physical process, and then writes output data (other terms could be a computational model, numerical model or model kernel). Later on, though, I think the word "model" transitions more to the definition used in HydroMT's online docs. That is,

  A set of files describing the schematization, forcing, states, simulation configuration and results for any supported model kernel and model classes.

  Instead of a definition of terms, perhaps using a qualifier with the word "model" that clarifies which meaning is being used would help.

• Thus far it seems as though HydroMT has been used with hydrological models. Is this a limitation of HydroMT? It certainly doesn't seem like it to me. It might be good to add a sentence somewhere that explicitly states the generality of HydroMT and that it can be used within any domain.
• The Summary section several times refers to HydroMT being used to analyze model results. In the body of the paper, however, there doesn't seem to be any explanation of how HydroMT can be used in this way. Since it sounds as though this it is one of the main capabilities of HydroMT a description of this capability would be useful.
• The Summary section states that HydroMT "provides a common interface to data and models". This is also exactly the goal of the Basic Model Interface^1 (BMI). While the BMI defines an interface standard, the CSDMS Data Components ^2 provide implementations of the BMI for a collection of datasets. I think it would be interesting to hear how HydroMT compares to this other approach and how BMI could be used with HydroMT. Would it be possible, for example, to build a generalized HydroMT plugin that could access any BMI Data Component? Because this is my own work, I am somewhat uncomfortable making this suggestion so if this doesn't resonate with the authors or they find it off topic, I'm totally fine if they disregard this suggestion.

[DirkEilander]

Dear @mcflugen,

Many thanks for the useful review which has certainly improved the manuscript! Hereby a reply to your comments:

• We agree that we used the term model to refer both to the software and a model instance in the paper. We have tried to clarify this by adding a qualifier like "instance" of "software" to distinguish between both uses.
• While the package is not restricted to hydrological models, there are quite some hydrology-specific workflow available which makes the package most suitable for hydrological applications. We have clarified this in the paper by adding the following line to the end of the "statement of need" section:

  While the package is sufficiently general to support model software outside the domain of hydro models, the focus of many workflows is on typical hydrological data and parameters and hence hydro models benefit most from the tool.

• The model analysis part was indeed not explained that well in the manuscript and has compared to the model building part also less functionality. We have added some explanation of this functionality, most importantly in the "Methods and workflows" component of the "functionality" section.
• I'm a big fan of BMI and use it mainly for online model coupling (e.g. with GLOFRIM https://github.com/openearth/glofrim) or interacting with model simulations. To my mind BMI and the HydroMT Model API serve different complementary purposes, where the power of HydroMT is in the pre- and postprocessing of model instances, the power of BMI is during the model runtime. However, the idea of a general HydroMT plugin for models with BMI is intriguing as it could allow users to view (and possibly interact with) a model instance on runtime or use the model software to read the model data. However, many model software that I work with store the data internally different from how the input data (e.g. gridded data is often flattened during the model initialization) which might make it difficult to make such a general plugin.

[mcflugen]

@DirkEilander Sounds good. Thank you!

I found a couple more typos:

• [x] LIne 19: "get an initial results" should be "get an initial result"
• [x] Line 117: "how to build a model instances" should be "how to build a model instance"

Regarding BMI, I was thinking of datasets (i.e. ERA5, WAVEWATCHIII, etc.)—not software models—that expose a BMI through, for example, a Python class. Would it be possible to create a generalized HydroMT data adapter that can gather input data (typically, maybe exclusively, gridded datasets) for a software model from a BMI dataset? And, maybe more importantly, would it be useful? My thinking is that, with such an adapter, it may make it easier for you to add new datasets to your catalog if a BMI has already been implemented for those datasets. I'm really just thinking out loud here, no need to address this in your paper.

[DirkEilander]

Thanks @mcflugen for typos and suggestion!

I'm not too familiar with the BMI datasets, but if I understand it correctly it's basically a common API to retrieve datasets from different APIs/sources, am I correct? I do think that would be compatible with the HydroMT RasterDataset adapter and it becomes especially useful if different datasets can be accessed in the same way. Where can I find a full overview of the different datasets which are available? This overview on the PyMT documentation seems to be outdated? I've opened a new issue to discuss this further: https://github.com/Deltares/hydromt/issues/271.