docs: Add JOSS paper

[matthewfeickert]

Description

Resolves #502

Add the text and references for a JOSS paper submission. The paper is created following the Submitting a paper to JOSS guidelines.

N.B. This branch does not need to be merged to submit to JOSS. (Though it would probably be nice for posterity)

Action Item Checklist

• Write paper
• Check it compiles
• Submit paper to JOSS

Paper Checklist

Your paper should include:

• A list of the authors of the software and their affiliations, using the correct format.
• A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience.
• A clear Statement of Need that illustrates the research purpose of the software.
• A list of key references, including to other software addressing related needs.
• Mention (if applicable) a representative set of past or ongoing research projects using the software and recent scholarly publications enabled by it.
• Acknowledgement of any financial support.

Paper compilation preview: https://whedon.theoj.org/

• Paper repository address: https://github.com/scikit-hep/pyhf
• Custom branch: docs/add-JOSS-paper

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Add text and references of JOSS paper
* Check submission to JOSS off of ROADMAP

[codecov]

Codecov Report

Merging #1089 (5debcc3) into master (4b85957) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1089   +/-   ##
=======================================
  Coverage   97.48%   97.48%           
=======================================
  Files          63       63           
  Lines        3740     3740           
  Branches      531      531           
=======================================
  Hits         3646     3646           
  Misses         55       55           
  Partials       39       39           

Flag	Coverage Δ
unittests	97.48% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4b85957...5debcc3. Read the comment docs.

[matthewfeickert]

For further reference, here is the carl JOSS paper by @glouppe, @cranmer, and @jgpavez.

[matthewfeickert]

@lukasheinrich @kratsg Review and edits to the paper are welcome before I submit it. You can see it built here (but you have to build it each time you push):

Paper compilation preview: https://whedon.theoj.org/

• Paper repository address: https://github.com/scikit-hep/pyhf
• Custom branch: docs/add-JOSS-paper

[matthewfeickert]

Note that there is the optional submission step of

(Optional) create a metadata file describing your software and include it in your repository. We provide a script that automates the generation of this metadata.

which would be part of Issue #891.

[matthewfeickert]

@lukasheinrich @kratsg As you both approved this I'm not going to merge this yet, but I will submit it to JOSS for approval. If we don't have any revisions then I'll merge it.

[matthewfeickert]

@cranmer can you review this and give any thoughts and revision suggestions (c.f. above)? Also please check your ORCID to make sure I copied it right.

[matthewfeickert]

@lukasheinrich @kratsg @cranmer Final thoughts and suggestions before submission? @lukasheinrich I think you had one or two comments?

[matthewfeickert]

Submitted for review with Eloisa Bentivegna as the suggested topic editor.

[matthewfeickert]

I changed the references as requested by @kthyng in openjournals/joss-reviews#2734.

[matthewfeickert]

The paper is currently under review at openjournals/joss-reviews#2823

[matthewfeickert]

The paper has passed JOSS review! 🚀 Final requirements for publication include

Upon successful completion of the review, authors will make a tagged release of the software, and deposit a copy of the repository with a data-archiving service such as Zenodo or figshare, get a DOI for the archive, and update the review issue thread with the version number and DOI.

This would most easily be achieved by merging this branch to master and then cutting a GitHub release to trigger Zenodo and then altering the Zenodo metadata to make the archive title match the submission title.

@lukasheinrich @kratsg Are you both good with having the paper be part of the codebase? Or would you prefer that we have this branch stay orphaned and cut a specific GitHub / Zenodo release for it?

[kratsg]

happy for it to just be part of master