What we need for a first PyGMT paper?

[leouieda]

In #653 we started discussing a possible PyGMT paper. The key question is "when should we publish our first paper?". Here are a few things we need before that can be done:

• An authorship policy. It's really important that we agree on this before doing any work a paper. See the Fatiando policy which was generated after long discussion and research into similar policies. (Done at Add authorship policy #726)
• Define a minimum viable product. What does PyGMT need to have in order to be fully usable? I'd say we're pretty close to having a usable alternative to Cartopy (if not there already). We don't necessarily need a "complete" product (when is software ever "done"?) but the package should be in usable state.
• Documentation! There is a lot of work to be done here and if we ignore the docs now and keep piling on features it will be hard to do it later. I would suggest basing the structure on the Divio system. Thinking about this now will help us define the mvp.
• Decide on a journal. I see 2 options:
  • JOSS (pro = easy + free + actual code review | con = not as well known yet)
  • G³ (pro = highly visible in geoscience + GMT is already published there | con = expensive + no code review)

[weiji14]

The key question is "when should we publish our first paper?"

TLDR: Not in >10 years (c.f. NumPy), but perhaps in the medium-term (2021-2022).

Long answer: I don't think we need to rush this, but good to have this issue up so that people are aware of how software is becoming a citable unit and worth putting effort into! See e.g. https://research-software.org/citation/ and the FORCE11 Software Citation Implementation Working Group at https://github.com/force11/force11-sciwg.

• An authorship policy. It's really important that we agree on this before doing any work a paper. See the Fatiando policy which was generated after long discussion and research into similar policies.

👍 Just want to point out CRediT – Contributor Roles Taxonomy too. We should acknowledge not just those who write software, but also the people that help us get funding, manage the project, etc. Also need to work on our diversity, let's try and avoid an 'all male' author paper 🙂

• Define a minimum viable product. What does PyGMT need to have in order to be fully usable? I'd say we're pretty close to having a usable alternative to Cartopy (if not there already). We don't necessarily need a "complete" product (when is software ever "done"?) but the package should be in usable state.

Subplots (#20) 😄 We've got most of the main GMT plotting modules covered, which is good if we want to just be a 'Cartopy' alternative.

But, if we want PyGMT to be more than a plotting library, then there's there's more work to do. Still a long way to go before reaching even half of all GMT modules (including supplementary ones) at https://docs.generic-mapping-tools.org/6.1/modules.html.

• Documentation! There is a lot of work to be done here and if we ignore the docs now and keep piling on features it willn be hard to do it later. I would suggest basing the structure on the Divio system. Thinking about this now will help us define the mvp.

I actually looked at the Divio documentation when making the changes at #643! We've made some good progress on the tutorial and gallery (how-to guide) front for the PyGMT v0.2.1 release (#665), and there's a backlog of new contributions to work through. Some more long-form presentation/workshop-style outreach material would certainly be welcome, just need to attend more conferences and get the name out!

• Decide on a journal. I see 2 options:

  • JOSS (pro = easy + free + actual code review | con = not as well known yet)
  • G³ (pro = highly visible in geoscience + GMT is already published there | con = expensive + no code review)

I do like the JOSS option with its GitHub issue based open review process. There's also many options at https://www.software.ac.uk/which-journals-should-i-publish-my-software that could be a good fit.

That said, a G³ paper is tempting. I've had my eye on Authorea for a while, which is a preprint server that allows direct submission to AGU journals (like G³) and allows for hosting data and code alongside figures. Still some rough edges (unsure how well they support third-party code like pygmt but certainly in the next year or two perhaps.

[leouieda]

TLDR: Not in >10 years (c.f. NumPy), but perhaps in the medium-term (2021-2022).

💯

But, if we want PyGMT to be more than a plotting library, then there's there's more work to do. Still a long way to go before reaching even half of all GMT modules (including supplementary ones)

I would challenge whether "wrapping GMT modules" is a metric we should have. From using PyGMT the past few months, I've come to think that simply wrapping GMT modules in functions/methods doesn't make for a good Python library. It may be powerful but it's not pleasant. But I agree 100% that it should be more than a plotting library.

Authorea

I've used it before but I kind of don't like a lot of aspects. I would push for writing the paper on GitHub in LaTeX or Markdown. We already work on this platform all the time anyway.

Also need to work on our diversity, let's try and avoid an 'all male' author paper

Yes! And this takes long term effort on our part. Real effort, not just having the door open but search for people to invite inside. GMT has had an open door for 30 years and that hasn't worked. Same with Numpy. Things only change when we actively push for it.

[MarkWieczorek]

I think that it would be great to have a scientific research paper that describes pygmt (like GMT). It is also great for a CV, and such articles are guaranteed to be highly cited. I did the same thing with pyshtools (also at G3), but in retrospect, writing such a paper is a lot of work, and given that the code is always changing, a static article isn't the best tool for someone trying to learn how to use the code.

What I would probably do is the following:

1. Focus on making the web documentation as complete as possible.
2. Add a couple of jupyter notebooks to show how to use key modules, and increase the number of examples in the gallery.
3. Write an advertisement in something like EOS, which is where the original GMT announcement was published. This could be as short as ~6 paragraphs, or something that is more like GRL in length.
4. Write a scientific article afterwards, which would be largely a cut-n-paste of the above.

I don't think that pygmt needs to reach parity with GMT, only that the quality of the documentation needs to be as good as it is for GMT.

[PaulWessel]

We will put in bucks for a G3 article for PyGMT in the NASA proposal we are submitting this week. If it gets funded then you have funds to pursue an Open publication with no access restrictions, like the GMT paper.

[weiji14]

Just putting down some notes from Day 1 after SciPy 2021, in particular after a Birds of a Feather session on PyOpenSci. From what I understand, going through the PyOpenSci process seems like a good way to:

1. Ensure that PyGMT meets established best practices in the Python/Open Science/Open Source ecosystem in terms of documentation/Continuous Integration/packaging/etc
2. Make us ready for a more thorough peer review process for publication in JOSS or G3 at a later date.

If people are keen, we could put in a pre-submission inquiry or proper submission at https://github.com/pyOpenSci/software-review. The review process takes place in a GitHub issue, and would take about 1-2 months (https://www.pyopensci.org/contributing-guide/open-source-software-peer-review/intro.html#the-peer-review-timeline), depending on how much we need to do. I/@meghanrjones could also find out more on the SciPy 2021 #pyopensci Slack channel this week to find out more if people think this is a good idea.

P.S. Geochemistry, Geophysics, Geosystems (G3) will be fully open access for all submissions after 8 Sep 2021. The price will drop from $3500 to $2750 according to https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Publication-fees 🎉

[leouieda]

@weiji14 I think this is a great idea! Leah and the rest of the pyOpenSci team are wonderful and there is a lot to gain from this. If submitting to JOSS, we can fasttrack the review process. And if going with G3, then the code will get reviewed (since the journal reviewers are unlikely to do this).

[weiji14]

Cool, sounds like a plan. I'll send in a pre-submission inquiry today (done at pyOpenSci/software-submission#43). Meanwhile, I've put up an editable document at https://hackmd.io/@pygmt/pyopensci for the full PyOpenSci review process, feel free anybody to edit it (let me know if you need access to hackmd). I will leave the document up for a week until Friday 30 Jul (UTC 12:00), depending on how the pre-submission inquiry goes, and then proceed to submit it to the PyOpenSci repo.

Edit: Haven't heard back from the pre-submission issue because the main editor is away on leave I think. Will report how things go once I hear back!