[JOSS] Paper Commentary

[Zeitsperre]

Context: openjournals/joss-reviews#5916

This is a list of some recommendations that could help with the paper submission:

• The Statement of Need could benefit from some/most of the information found in the first paragraph of the summary. Do the software outputs adhere to/enforce existing standards for weather station data (WMO guidelines, ISOs, CF-Conventions)? Expand on the frameworks/standards/approaches you are building upon?
• "Quality control is performed in the form of a series of checks" - Elaborate? What are you checking for exactly at the time of writing (monotonic timestamps, data gaps, extremes, etc.)?
• "It is to be expected that some novel functionalities will be added in the coming years and the documentation will be updated accordingly." - Unless the features are already planned for and can be described, I'd remove this line. The paper should showcase that the software is feature-complete (even if there are new features being planned; the paper doesn't prevent you from expanding the software in future versions). This statement can be easily rolled into the first line of the preceding paragraph if needed.
• The citation for the Pandas team needs to be fixed: "team, T. pandas development"

There are a handful of phrases that could be tightened as well (if the authors like, I can suggest a few changes in a PR). I might also have some small additional comments after more reflection.

[vergauwenthomas]

Other comments:

• Reproducibility: I believe the results shown in Figure 1 is based on the Examples section in the docs. The author should point out that.
• References: Fix Caluwaerts et al. title The urban climate of ghent, belgium... and the citation for Pandas.

[vergauwenthomas]

@ashwinvis, you mentioned in 5916 an issue in the paper:

• References: Fix Caluwaerts et al. title The urban climate of ghent, belgium... and the citation for Pandas.

(@Zeitsperre, mentioned the pandas citation as well.)

Issue

I am trying to solve them in PR #400. The problem is that the references are correct present in the paper.bib, but are formatted by pandoc assuming the author to be a persons name and not the pandas development team.

Fix

I could not find any option to force full-author-format in pandoc, so i came up with this "fix":

@software{pandas,
  author       = {pandas-dev-team}, #Rather than {The pandas team}
  title        = {pandas-dev/pandas: Pandas},

This is cited as:

and in the Bibliography as:

Is this oke?

I know this is not a clean fix, but I could not find how to do it any other way. Do you think this fix is oke, or do you have a better idea?

[vergauwenthomas]

@ashwinvis, you mentioned this issue:

References: Fix Caluwaerts et al. title The urban climate of ghent, belgium... and the citation for Pandas.

However, I cannot find a way on how to force capital letters for Ghent and Belgium because they are written in capital in the paper.bib:

@article{mocca,
abstract     = {As urban environments have a specific climate that poses extra challenges (e.g. increased heat stress during heat waves), gaining detailed insight into the urban climate is important. This paper presents the high-accuracy MOCCA (MOnitoring the City's Climate and Atmosphere) network, which is monitoring the urban climate of the city of Ghent since July 2016. The study illustrates the complementarity between modelling and observing the urban climate. Two different modelling approaches are used: 1 km resolution runs of the SURFEX land surface model and 100 m resolution runs of the computationally cheaper UrbClim boundary layer model. On the one hand, urban models are able to simulate the spatial variability of the urban climate. As such, these models serve as a tool to help deciding on the locations of the measurement stations. On the other hand, the MOCCA observations are used to validate the high-resolution urban model experiments for the summer (July-August-September) of 2016. Our results demonstrate that the models capture the nighttime intra-urban temperature differences, but they are not able to reproduce the observed daytime temperature differences which are determined by the micro-scale environment.},
articleno    = {100565},
author       = {Caluwaerts, Steven and Hamdi, Rafiq and Top, Sara and Lauwaet, Dirk and Berckmans, Julie and Degrauwe, Daan and Dejonghe, Herwig and De Ridder, Koen and De Troch, Rozemien and Duchêne, Francois and Maiheu, Bino and Van Ginderachter, Michiel and Verdonck, Marie-Leen and Vergauwen, Thomas and Wauters, Guy and Termonia, Piet},
issn         = {2212-0955},
journal      = {Urban Climate},
keywords     = {High-resolution urban modelling,Urban heat island,Urban monitoring network,ALARO-0,SURFEX,UrbClim,HEAT-ISLAND,MODEL,CONVECTION,SCHEME,ENERGY,LAND,ADVECTION,EVOLUTION,BRUSSELS,SYSTEM},
language     = {eng},
pages        = {19},
title        = {The urban climate of Ghent, Belgium : a case study combining a high-accuracy monitoring network with numerical simulations},
url          = {http://dx.doi.org/10.1016/j.uclim.2019.100565},
doi          = {10.1016/j.uclim.2019.100565},
volume       = {31},
year         = {2020}
}

But are not rendered as such

@ashwinvis, any idea on how to solve this?

[ashwinvis]

Yes

title        = {The urban climate of {G}hent, {B}elgium : a case study combining a high-accuracy monitoring network with numerical simulations}, 

[vergauwenthomas]

Your suggestion works also for the pandas citation, thanks!

author = {{The pandas development team}},

[Zeitsperre]

@vergauwenthomas The latest draft of the paper addresses many of the issues I raised (and flows much better). There are a handful of small grammatical errors that I can fix if you'd like (let me know), but I consider this issue addressed!

[vergauwenthomas]

@Zeitsperre thanks! If you could pinpoint the grammatical errors that would be great, but only if you have time for it. (If you do, and prefer to fix the errors in the paper.md you are free to do so.)

btw #400 is merged to master.