Let’s try to keep the matter simple. General rules apply:
- Have a narrative
- Get a scheme
- Cope with the basics
- Have in mind the specific of a paper vs other forms of communication
- Have in mind what reviewer thinks (this video gives further insights for the specific case of hydrological modelling)
Analyzing back the general scheme, in the case of software presenting, you need a specific part dedicated to the availability and delivery of the software. The main parts required here were already illustrated in explaining the Zero Notebook contents.
Because you are talking about scientific software your methodology has two parts. One related to the science you have to produce and one related to the science of writing good software.
Taking the example of Evapotranspiration. The science could be the one included in the sub-models you are implementing. Meaning, what is the science behind Priestley-Taylor, which the one behind FAO approach, and which the one one behind, for instance, our Prospero model ? Here the material is very large so you have to work usually by extracting the essentials and citing the literature. Part of it can easily fit actually inside the introduction. The informatics has to do with the way your system is built. Which is the framework you use, in our case, OMS3, and why you use it, instead of others. It also the system you are working with, like in our case GEOframe that provides ancillary tools. Finally the informatics can boil down to the algorithms and their organization in classes. Algorithms can be new or old and irrelevant. Just in the first case it is important to mention them with details, otherwise just a a little note can be done. Classes, assuming we are talking of some OO programming, have two scopes, one is to contain the algorithms, the other is to orchestrate the software relations in order to make easy the reuse of the softwares and their expansion. This part will be routine in future, maybe, but now it is not part of the common knowledge of hydrologist, and therefore it is worth to be explained if well engineered. In explaining classes and the overall working of the software using of UML diagrams is mandatory.
In a software paper, it is debatable what is the test of the contents. Let’s say that, because we are hydrologists, we need to test both the software running, and the models’ physics.
The software running test for who is programming in Java, like we do, is obtained through the appropriate Unit Tests and this part is commented, in case, inside the section which inherit from the Notebook Zero. For the physics we have, in turn, two modes. If we are solving problems, i.e. equations, that have an analytical solution, then we have to reproduce the analytical results. Secondly the nasty reviewer, would also see that the model reproduces measurement. Getting some measurements to reproduce is then important. A third case is also ideally possible, which is that, no measurements are available and therefore eventually the model provide a possibility to test something that was never tried before. In this case it must be emphasized that the model makes possible something that before was not not, and we have to rely to some virtual, behavioural, experiment.
If measurements are involved, new methodological steps come in: explaining the case study, first. Secondly, not differently from other cases, we have to say if parameters to calibrate and to mention the techniques we use for doing it. Explaining how we assess the goodness of the results, and finally commenting the results are the rest of the story. An exceptionally good software that does not reproduce reality is simply not useful from the hydrology point of view, even if its implementation can still provide novelties worth to be explained. The physical test, however, should not extend to be very complicate but just functional to convince that the software is doing what it is designed to do. In the mentioned case of evapotranspiration, another issue is relevant, which is the comparison among sub-models or models alternative. It is clear that different models produce different results, so assessing in which case they work or work netter is important. However, that can be pursued with moderation in a “software presentation” paper, because this is clearly an argument which requires a paper by itself. For example , in a recent paper, Clark et al., 2021, they talk of “laugh test” for emphasizing this aspect.
At the end of the post, you have some ingredients and an idea of the procedure. To cook them together for a nice result is a little of art. In general, a good example to follow is the WHETGEO paper.
