# Cookbooks Citation

**Context:** TBA

**Motivation:** TBA

### Useful Resources
- [How to cite and describe software](https://software.ac.uk/how-cite-software)

### 20-06-23
#### Attendees
- Alejandro

#### Solutions

The table below includes some potential solutions to make Pythia Cookbooks citable according to the existing [cookbook-template](https://github.com/ProjectPythia/cookbook-template) repository.

| ID | Short name | Difficulty | Implementation |
| ---- | ---------------- | -------- | -------- |
| 0 | Zenodo/GitHub | + | https://github.com/acocac/pythia-citation-zenodo |
| 1 | Zenodo.json | ++ | Text |
| 2 | CITATION.cff | ++ | https://github.com/acocac/pythia-citations-cff |
| 3 | RoHub | +++ | Text |
| 4 | Bot | +++ | Text |

0. Zenodo 3rd Party

The naivest solution.

* Resources
* [Step-by-Step guide](https://coderefinery.github.io/github-without-command-line/doi/)

1. Zenodo.json

Add a custom Zenodo.json file in the GitHub repository which could include more metadata than the naivest solution.

Implemented in EarthCube Notebooks. See for instance [Miron et al. 2022's submission](https://github.com/earthcube2022/ec22_miron_etal).

{
    "description": "This cookbook.",
    "license": "Apache-2.0",
    "title": "Cirq",
    "upload_type": "software",
    "creators": [
        {
            "name": "Cookbook [NAME] Developers"
        }
    ],
    "access_right": "open",
    "notes": "See full list of authors on Github: https://github.com/GITHUB-USER/REPO-NAME/graphs/contributors"
}

2. CITATION.cff

A widely adopted alternative format and schema for software citation.

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "CONTRIBUTOR1-SURNAME"
  given-names: "CONTRIBUTOR1-FORENAME"
  orcid: "CONTRIBUTOR1-ORCID"
- family-names: "CONTRIBUTOR2-SURNAME"
  given-names: "CONTRIBUTOR2-FORENAME"
  orcid: "CONTRIBUTOR1-ORCID"
- name: "COOKBOOK-NAME contributors"
  website: "https://github.com/[GITHUB-HANDLE]/[REPO-NAME]/graphs/contributors"
title: [TITLE]
version: [VERSION]
doi: [PERMANENT-DOI]
date-released: YYYY-MM-DD
url: "https://github.com/[GITHUB-HANDLE]/[REPO-NAME]"

- Manual process
- Create a CITATION.cff file
- Activate the repository in Zenodo
- Release a version
- Add a badge in README or Rendered JupyterBook?

- Automated process
- [The Turing Way](https://github.com/alan-turing-institute/the-turing-way/blob/main/.github/workflows/release-workflow.yml)

3. RoHub-generated DOI

See example of [EDS book notebooks](https://reliance.rohub.org/16b9c078-a01d-4f14-8268-4c40cfe9d467?activetab=overview).

The process is still very manual. RoHub doesn't have yet a given human/machine readable file such as zenodo.json or CITATION.cff.

4. Custom bot to support citations

Examples:
- [buffy](https://github.com/openjournals/buffy)
- [roboneuro](https://github.com/neurolibre/roboneuro-neo)

See below some archival tasks in roboneuro.

ARCHIVAL TASKS (Auth level editor)

# Displays Zenodo deposit, upload and publish status
@roboneuro zenodo status

# Create Zenodo records for archiving resources
@roboneuro zenodo deposit

# Uploads all resources to respective Zenodo deposits for archival
@roboneuro zenodo archive-all

# Zenodo uploads can be performed individually
@roboneuro zenodo archive-docker
@roboneuro zenodo archive-book
@roboneuro zenodo archive-repository
@roboneuro zenodo archive-data

# Destroy all the zenodo resources (cannot be called after publishing, cannot be performed for individual items)
@roboneuro zenodo flush

### 21-06-23

#### Steps taken with Zenodo on Foundations and HRRR-AWS Cookbook
We're using Zenodo already for this, there is some weirdness in who "owns" the Zenodo release page (and we don't know how to transfer this ownership), but the Zenodo page doesn't need to be edited once the repository is activated so maybe this is a non-issue. Perhaps we can set up a Zenodo bot/user that multiple people can log into?

1. Create a CITATION.cff file in the root level of the repository. Merge.

    cff-version: 1.2.0
    message: 'If you use this cookbook, please cite it as below.'
    authors:
      - family-names: Tyle
        given-names: Kevin
        orcid: https://orcid.org/0000-0001-5249-9665
      - name: "HRRR-AWS contributors"
        website: "https://github.com/ProjectPythia/HRRR-AWS-Cookbook/graphs/contributors"
    title: 'HRRR-AWS-Cookbook'

2. *Someone* activates the repository on Zenodo (Profile -> GitHub -> toggle on/off switch on repo)
3. Back on GitHub, make a release!
4. Grab the DOI badge and add it to the README.md, also create a how-to-site.md page (in preamble of foundations book, where should it go in Cookbooks?)

    # How to Cite This Book

    The material in Pythia Foundations is licensed for free and open consumption and reuse. All code is served under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0), while all non-code content is licensed under [Creative Commons BY 4.0 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). Effectively, this means you are free to share and adapt this material so long as you give appropriate credit to the Project Pythia community.

    The source code for the book is [released on GitHub](https://github.com/ProjectPythia/pythia-foundations) and archived on Zenodo. This DOI will always resolve to the latest version of the book source:
    <https://doi.org/10.5281/zenodo.7884571>

    If material in Pythia Foundations is useful in published work, you can cite a specific version of the book as:

        > Rose, B. E. J., Kent, J., Tyle, K., Clyne, J., Banihirwe, A., Camron, D., May, R., Grover, M., Ford, R. R., Paul, K., Morley, J., Eroglu, O., Kailyn, L., & Zacharias, A. (2023). Pythia Foundations (Version v2023.05.01) [https://doi.org/10.5281/zenodo.7884572](https://doi.org/10.5281/zenodo.7884572)

    [![DOI](https://zenodo.org/badge/338145160.svg)](https://zenodo.org/badge/latestdoi/338145160)

Can we grab the DOI link from the GitHub Zenodo webhooks? And reading that file can grab what the DOI badge for the README and the sample sitation for the how-to-cite?

From James Munroe:
- Indexing DOIs? Pathway for submitting for CrossRef (facilitates sharing of references, and seeing networks of citations). We want to make DOIs discoverable. Important for career benefits. Typically have to work with a publisher to talk to CrossRef.
- [AGU Notebooks Now!](https://data.agu.org/notebooks-now/) Answering similar questions about publishing notebooks as a primary product. Perhaps a special edition of a journal to publish digital notebooks with more rigorous/varried peer reviewers. Pythia is a pre-publishing step. Maintenance of journal archive shared by all journals, dependent on shared journal format called .jax (sp?) file. Notebooks Now! building pathway from notebook to that same journal format. Connect with Shelley Stall (sp?).
- How formal is our peer review process to be accepted into the gallery? Formalize and decentralize editorial process

Creating a Zenodo community (ProjectPythia):
https://zenodo.org/communities/projectpythia/

The "community" has been created but we don't have anything in it yet. Unfortunately a limitation seems to be that only a single individual has privileges to "curate" the community.

We can create the Zenodo badge from GitHub ID https://gist.github.com/seignovert/ae6771f400ca464d294261f42900823a, this can be done in a GitHub workflow at release.

## Some issues around how we will maintain author/contributor metadata in cookbook repos

### CITATION.cff vs. .zenodo.json

We are currently experimenting with using a `CITATION.cff` file to store author info in a cookbook repo: <https://github.com/ProjectPythia/HRRR-AWS-cookbook/blob/main/CITATION.cff>

#### Advantages:
- it's a simple, easy to use format
- Both GitHub and Zenodo support it
- We could pull author info from this file for listing in the [Cookbook Gallery](https://cookbooks.projectpythia.org)

In our experiments with Zenodo integration on the HRRR-AWS repo, we found that this "bare bones" file is all that Zenodo needs in order to generate DOIs when a GitHub release is created:

cff-version: 1.2.0
message: 'If you use this cookbook, please cite it as below.'
authors:
  - family-names: Tyle
    given-names: Kevin
    orcid: https://orcid.org/0000-0001-5249-9665
  - name: "HRRR-AWS contributors"
    website: "https://github.com/ProjectPythia/HRRR-AWS-Cookbook/graphs/contributors"
title: 'HRRR-AWS-Cookbook'

There's no need for further GitHub automation, the Zenodo webhook takes care of everything.

#### Disadvantages

We don't seem to have access to all the metadata options that Zenodo supports. E.g. [here](https://developers.zenodo.org/#representation) there's a description of metadata including both `creators` and `contributors`.

If we stored metadata in a [.zenodo.json file](https://developers.zenodo.org/#add-metadata-to-your-github-repository-release) instead of `CITATION.cff`, we could maintain a distinction between "authors" (mapping to `creators`) and "contributors".

But the `.zenodo.json` is more esoteric, maybe harder for people to understand how to maintain, and is not interpreted by GitHub.

#### Conclusion

At least in the short term, we should choose the simplest path forward, which is to use the `CITATION.cff` file.
> [name=Alejandro]Great conclusion `CITATION.cff` is a very versatile format/schema which can also acknowledges secondary work

A descrition of the format is [here](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md)

### 22-06-23

#### Suggestions
- [name=Alejandro]
- What about adding a new section in README how to cite? The citation should be automatically updated according to the cookbook version.

We are going to "un-franken" the `_config.yml` file which has extraneous fields not used for Jupyterbook (description, thumbnail. email, tags), and move them into appropriate places. Email field can be removed entirely

The `CITATION.cff` can have author websites (link to GitHub but authors can choose a different site if necessary), an `abstract` field (to replace `description` currently in our franken-`_config.yml`).

We may make a new `_gallery_info.yml` file to contain the tags and thumbnail fields which don't easily fit into `CITATION.cff`.

The reason we might need a custom `_gallery_info.yml` is because we have nested tags that we use on the gallery and there is no convenient way to include the nested tags in `CITATION.cff`.

Then, perhaps the README.md can be updated intermittently to make sure its authors include all authors in the `CITATION.cff`.

Change gallery generator to read `CITATION.cff` and `_gallery_info.yml`.

Create a manually triggered action "on workflow dispatch" that updates the github id in the DOI badge, on the how-to-cite page and any links to the GitHub repository that currently will point to the cookbook-template repository.