JOSS Review 1

[ThibaultMarzullo]

Hi Samuel and Louis, this issue relates to the JOSS review of your paper. Here are the detailed comments mentioned in the review page.

Paper summary:
I would suggest writing just a few words to give more high-level context to the non-expert, for example:

• a few words on Energy+: what it does (BES) and why it's important (major software in the domain)
• a few words on UMI: what it does (UBEM), and why its building models are different from Energy+
• a few words on TRNSYS: why do you consider this software and not, for example, IDA-ICE?

All of that could fit in 3-4 sentences, no need to give over-detailed explanations.

Misc comments on the paper:

• I'm a little confused by your definition of an archetype. It's not simply an advanced physical model or BEM, which might represent a real building, but rather the model of a theoretical building representative of the building stock.
• The need is stated at the end of each section. It would be easier to understand if you stated the need at the beginning of each section (problem -> solution), or you could state it in a separate section that would serve as a justification to developing archetypal.
• Please support the following statement in the TRNBuild conversion section: "archetypal answers a need from researchers [...]". Either rephrase or support with a reference.
• The E+ simulation environment functionality is not described clearly in the paper or the documentation.
• You mention the shoeboxer method. It is not clear if your method expands or modifies the shoeboxer method, or if it implements it. If it modifies or expands it, it would be good to see mathematical details in a companion paper or in the documentation.
• You would like to provide a scripting language for the modification of UMI template files. Could that not be considered an additional feature, rather than what sounds like a sub-feature of the conversion from E+ to UMI?

Documentation:
Generally speaking it seems incomplete: there are examples for using the E+ to UMI conversion, E+ to TRNBuild, but it is very vague on using archetypal as a simulation environment, the modification of UMI Templates is not covered by examples, the "getting started" section is left blank and the tutorials are incomplete or blank.
The user is left to finding out on their own how to use archetypal for any task other than converting models.

You seem to have done a great deal of work, nevertheless some more work on the documentation is in my opinion necessary if You wish to release the software.

Let me know what are your thoughts on these comments.
Kind regards
Thibault

[louisleroy5]

Hello Thibault,

Thank you very much for the review !
I find the comments really constructive. I'll try to put some time this week to improve the documentation. Then I'll work on the paper.

Best regards,
Louis

[samuelduchesne]

Hi @ThibaultMarzullo, as per your recommendations, many improvements have been made to the paper (see #47 and c2823b3 ) and the documentation (see #62).

The documentation has been thoroughly upgraded with examples of workflows. All relevant packages and methods are also documented.

[ThibaultMarzullo]

Hi @samuelduchesne and @louisleroy5 ,
I'm happy with the many improvements you did on the documentation and with the quality of the paper.

I have 2 additional suggestions for the paper. They are just small changes and English is not my first language, so I might be very wrong!

• In the "Summary" section: "archetypal is a Python package that helps handle collections of such archetypes and to enable the interoperability [...]", could it become "archetypal is a Python package that helps handling collections of such archetypes and enabling the interoperability [...]" ?

• In the "E+ simulation environment" section, end of paragraph 1: "Other user-specified output names can also be specified." Could it become "Other output names can be specified by the user" to remove repetition?

Regardless of my last 2 comments, this issue can be closed.
Thank you!

[samuelduchesne]

Comments handled by f98fedb