How to cite PyGMT

[seisman]

Description of the problem

Searching for "PyGMT" in Google Scholar shows that there are already some papers citing/mentioning/acknowledging PyGMT. Here are the searching results: https://scholar.google.com/scholar?q=PyGMT&hl=en&as_sdt=0%2C23&as_ylo=2017&as_yhi=

From the searching results, you'll see that people are citing PyGMT in various ways:

1. citing the GMT 6 paper
2. citing @leouieda's AGU abstracts
3. citing the Zenodo stable DOI or DOI of a specific version.

PyGMT should document the correct/recommended way for citation.

[weiji14]

This was mentioned before by @liamtoney on Apr 2020 at https://forum.generic-mapping-tools.org/t/how-to-cite-pygmt/382, but that predates v0.1.0 (and hence no Zenodo DOI was available). I still think the GMT 6 paper needs to be cited regardless since that's the real engine, and people should refer to https://www.generic-mapping-tools.org/cite/ for that.

That said, we could have a Bibtex entry on our main README.md page for this. For PyGMT v0.2.0, this is what I got from my Zotero's "Export to BibLaTeX" function:

@software{UiedaLeonardoPyGMTPythoninterface2020,
  title = {{{PyGMT}}: {{A Python}} Interface for the {{Generic Mapping Tools}}},
  shorttitle = {{{PyGMT}}},
  author = {Uieda, Leonardo and Tian, Dongdong and Leong, Wei Ji and Toney, Liam and Newton, Tyler and Wessel, Paul},
  date = {2020-09-12},
  doi = {10.5281/ZENODO.4025418},
  url = {https://zenodo.org/record/4025418},
  urldate = {2020-10-18},
  abstract = {PyGMT is a library for processing geospatial and geophysical data and making publication quality maps and figures. It provides a Pythonic interface for the Generic Mapping Tools (GMT), a command-line program widely used in the Earth Sciences.},
  organization = {{Zenodo}},
  version = {v0.2.0}
}

Or if we use Zenodo's "Export to Bibtex" page at https://zenodo.org/record/4025418/export/hx:

@software{uieda_leonardo_2020_4025418,
  author       = {Uieda, Leonardo and
                  Tian, Dongdong and
                  Leong, Wei Ji and
                  Toney, Liam and
                  Newton, Tyler and
                  Wessel, Paul},
  title        = {{PyGMT: A Python interface for the Generic Mapping 
                   Tools}},
  month        = sep,
  year         = 2020,
  note         = {{The development of PyGMT was supported by NSF 
                   grants 1558403 and 1948602.}},
  publisher    = {Zenodo},
  version      = {v0.2.0},
  doi          = {10.5281/zenodo.4025418},
  url          = {https://doi.org/10.5281/zenodo.4025418}
}

Obviously, this would change for every version release, and also as new contributors from https://github.com/GenericMappingTools/pygmt/blob/master/AUTHORS.md are added. In the long term (i.e. for v1.0.0), we should look at making a JOSS paper or similar to make a stable citation.

[leouieda]

We could point people to the overall Zenodo DOI and instruct them on how to get the BibTeX and citation info from that. Otherwise we would have to remember to update the citation every time we make a release.

I agree that we should think about a paper as we get closer to something "complete". We could go for JOSS (which is very little work but relatively unknown in geophysics) or a more popular journal in geoscience (G³ or the like). We have grant money that could pay for open-access fees so it shouldn't be a huge problem. But that would require a lot more effort for the paper and reviewers generally don't even look at the code...

I opened #677 to discuss what we need for a first paper.

[weiji14]

We could point people to the overall Zenodo DOI and instruct them on how to get the BibTeX and citation info from that. Otherwise we would have to remember to update the citation every time we make a release.

Yes, we should point to the Zenodo DOI, but I think it's worth the effort to update a BibTeX citation on the main README page every release just to make it easy for users wanting to cite PyGMT. I just spent/wasted a whole day fixing 30+ citations for a paper and the last thing I want is to jump through a bunch of links just to get at the BibTeX/RIS metadata!!

That said, I'll open up a Pull Request for this (unless anyone else wants to give this a go).

[seisman]

Yes, we should point to the Zenodo DOI, but I think it's worth the effort to update a BibTeX citation on the main README page every release just to make it easy for users wanting to cite PyGMT.

Looks good to me. We just need to add it to the release checklist.

[leouieda]

I’m OK with that as well 👍🏽