Citing oemof

[ckaldemeyer]

In the README.RST we are only mentioning the code versioning via Zenodo DOI.

Should we add the paper on oemof within the README.RST and thus provide a possibility to cite both the code version and the general idea within the paper?

[p-snft]

In another project, we did a similar thing: For every minor release (not for fix releases) we have a paper that explains the mathematical models behind new features. In the readme we list these papers while at the same time suggesting to use the Zenodo DOI to cite a specific version including bugfix releases. (As the project webpage is rendered from the readme, also example results are in the readme.)

I would strongly suggest to do the same with oemof. In fact, in the sense of good scientific practice, not only the software has to be cited but also the underlying model has to be understandable. So, even if the paper is not cited, the references in the readme would help those following the reference to the software.

[uvchik]

I agree and in the long run we could publish in Joss.

e.g.

[ckaldemeyer]

In another project, we did a similar thing: For every minor release (not for fix releases) we have a paper that explains the mathematical models behind new features. In the readme we list these papers while at the same time suggesting to use the Zenodo DOI to cite a specific version including bugfix releases. (As the project webpage is rendered from the readme, also example results are in the readme.)

I would strongly suggest to do the same with oemof. In fact, in the sense of good scientific practice, not only the software has to be cited but also the underlying model has to be understandable. So, even if the paper is not cited, the references in the readme would help those following the reference to the software.

This sounds really interesting and reasonable. Although I can imagine the general idea; do you have an example? Isn't this very close to compiling the docs of a specific version into PDF and putting them on Zenodo including highlighting the WHATSNEW somewhere prominent within the docs?

[ckaldemeyer]

I agree and in the long run we could publish in Joss.

e.g.

Do you mean if we write a second paper?

[henhuy]

Do you mean if we write a second paper?

You don't have to write a whole paper. An abstract and link to code base is enough! The reviewers will tell you, if something is still missing ...

[p-snft]

This sounds really interesting and reasonable. Although I can imagine the general idea; do you have an example? Isn't this very close to compiling the docs of a specific version into PDF and putting them on Zenodo including highlighting the WHATSNEW somewhere prominent within the docs?

Probably, this depends on the point of view. If we include known models, we would proceed as you suggested - citing the original paper. However, oemof might also implement new methods or models. If you like, this could be seen as another "original paper", but it can also also be seen as the paper describing a new feature of an oemof release. Maybe, the two projects are more different than I realized at first. Inovesa (the other project) is more of a showcase for first-time implementation of methods and models, so the publication approach made more sense there.

If we see oemof as a scientific publication (as suggested by JOSS), descriptions of individual models should really be cited more prominently. This would also help making oemof more citable.

[ckaldemeyer]

Do you mean if we write a second paper?

You don't have to write a whole paper. An abstract and link to code base is enough! The reviewers will tell you, if something is still missing ...

So in JOSS it is possible to add just "incremental abstracts" for new software versions without underlying text? I thought that it is mandatory to add a full paper as it is a journal.

Probably, this depends on the point of view. If we include known models, we would proceed as you suggested - citing the original paper. However, oemof might also implement new methods or models. If you like, this could be seen as another "original paper", but it can also also be seen as the paper describing a new feature of an oemof release. Maybe, the two projects are more different than I realized at first. Inovesa (the other project) is more of a showcase for first-time implementation of methods and models, so the publication approach made more sense there.

Your point of including new models made me think that it might be clearer to have publictions and DOIs closer to the functional of parts of the framework. So for example there could be single publications on new versions of core, solph, TESPy, ...

If we see oemof as a scientific publication (as suggested by JOSS), descriptions of individual models should really be cited more prominently. This would also help making oemof more citable.

If it is as @henhuy said with "incremental abstracts" this would also be possible for the different parts of the framework. Maybe the original paper serves for the general idea, then there are more detailed "initial papers" e.g. for solph, TESPy, ... and after these there are only updates of the single papers within JOSS (as one option).

[p-snft]

As far as I understand JOSS, the journal is more of a hack to make the actual code a (citable) publication. The JOSS paper is more of an abstract for the software and should be general enough to have new releases without having to update is. The only problem I see with this model is the list of authors. Significant contributions to the code will not make you appear in the JOSS paper. There has been a discussion about that topic at openjournals/joss#423, concluding that from time to time a new JOSS paper might be the way to proceed. Also not that a JOSS paper will cover one piece of software (e.g. TESPy) and not oemof as a whole.

In summary, I do not see a huge advantage in having a JOSS publication over naming DOI:10.1016/j.esr.2018.07.001 more prominently.

[ckaldemeyer]

As far as I understand JOSS, the journal is more of a hack to make the actual code a (citable) publication. The JOSS paper is more of an abstract for the software and should be general enough to have new releases without having to update is. The only problem I see with this model is the list of authors. Significant contributions to the code will not make you appear in the JOSS paper. There has been a discussion about that topic at openjournals/joss#423, concluding that from time to time a new JOSS paper might be the way to proceed. Also not that a JOSS paper will cover one piece of software (e.g. TESPy) and not oemof as a whole.

Thanks for clarifying! I agree concerning the code contributions.

In summary, I do not see a huge advantage in having a JOSS publication over naming DOI:10.1016/j.esr.2018.07.001 more prominently.

Me neither. What about the others?

By the way: Did we so far agree that adding the oemof-paper or the respective pre-print into the README would improve the status quo? We could then start with that!

[c-moeller]

By the way: Did we so far agree that adding the oemof-paper or the respective pre-print into the README would improve the status quo? We could then start with that!

👍