OSCR

The badge

The badge links a paper's code to the paper. Placed in the README of the code, on its Hugging Face card or on a lab's page, it shows what OSCR knows of the paper and links the code's readers to the paper's page, which shows the paper and the code side by side, the tracing map and the citation. You paste one line, and the badge then updates itself.

Quick start

  1. Open the badge page and give your paper's DOI (or your repository's address).
  2. Copy the Markdown line. It looks like this:
    [![OSCR](https://openscicode.org/badge/doi/10.1234/abcd.svg)](https://openscicode.org/badge/doi/10.1234/abcd)
  3. Paste it under the title of your README, and commit. The badge then updates itself every night.

You need no account, no key and no file to host. Signed in as a verified author, your account page lists each of your papers with its badge, and the badge page says which of their repositories still lack it.

What the badge says

OSCR: paper ↔ code

On the left, the OSCR wordmark on its blue; on the right, what the registry knows, drawn from its records:

The badge saysWhenA click goes to
paper ↔ codethe paper has a page, with its authors' codethe paper's page
paper ↔ code · validated (green)an author validated its tracing map, which has a DOIthe paper's page
code on request, data onlywhat the paper's availability statement saysthe paper's page
code of 3 papersa repository's badge, when the repository is the code of several papersthe list of those papers
read, no code found (grey)the paper was read but no code was foundthe DOI lookup
not registered (grey)the registry does not know the paper or the repository yetthe submission form, filled in

A badge added before the paper is in the registry links its readers to the submission form, and becomes the paper's badge on the night the record is published.

Its addresses

A paper's badge is addressed by its DOI, a repository's by its host, owner and name, exactly as in its URL.

A paper's image
https://openscicode.org/badge/doi/10.1234/abcd.svg
A paper's link
https://openscicode.org/badge/doi/10.1234/abcd (it follows the paper's page wherever it moves)
A repository's image
https://openscicode.org/badge/repo/github.com/owner/name.svg
A repository's link
https://openscicode.org/badge/repo/github.com/owner/name
shields.io's endpoint
https://openscicode.org/badge/doi/10.1234/abcd.json
The static images
https://openscicode.org/badge.svg and https://openscicode.org/badge.png (plain files, with no work on the server)

A DOI's characters other than the slash are percent-encoded in the path (the badge page does it for you). A DOI that ends in .svg or .json goes in the query instead: https://openscicode.org/badge/doi.svg?doi=…. A paper's badge is the better choice in a README that serves one paper; a repository's badge needs no DOI and suits a template, a group badge or a repository that is the code of several papers.

Platform by platform

GitHub, Codeberg, Bitbucket, Gitea, Forgejo

The Markdown line, under the README's title. GitHub shows images through its own proxy (camo): the badge is public, needs no cookie and is cached an hour, which is what that proxy expects.

[![OSCR](https://openscicode.org/badge/doi/10.1234/abcd.svg)](https://openscicode.org/badge/doi/10.1234/abcd)
GitLab

The Markdown line in the README, or better, a project badge: Settings, General, Badges, with the link and the image's address above; it then shows under the project's name on every page. A group badge reaches every project of a group at once (below).

Hugging Face (a model, a dataset, a Space)

The card is the repository's README.md: paste the Markdown line in its body, after the YAML block between the two --- lines, and not inside it. Through the website: the card's Edit button, then "Commit changes", or "Open as a pull request" on someone else's repository.

PyPI, Read the Docs, Sphinx

A Markdown README needs nothing more (long_description_content_type = "text/markdown"). In reStructuredText:

.. image:: https://openscicode.org/badge/doi/10.1234/abcd.svg
   :target: https://openscicode.org/badge/doi/10.1234/abcd
   :alt: OSCR
R (README.Rmd, pkgdown), Julia (Documenter), Quarto, MkDocs, a Jupyter notebook

The Markdown line, in the README or in a Markdown cell at the top of the notebook.

AsciiDoc and Org (README.adoc, README.org)
image:https://openscicode.org/badge/doi/10.1234/abcd.svg[OSCR,link="https://openscicode.org/badge/doi/10.1234/abcd"]
[[https://openscicode.org/badge/doi/10.1234/abcd][https://openscicode.org/badge/doi/10.1234/abcd.svg]]
A web page, a lab's site, WordPress, a Zenodo record's description
<a href="https://openscicode.org/badge/doi/10.1234/abcd"><img src="https://openscicode.org/badge/doi/10.1234/abcd.svg" alt="OSCR"></a>

For a page, the card (?style=card) shows the title, the journal and what the registry knows, 420 by 64 pixels; ?style=large is 28 pixels high.

LaTeX (a thesis, slides, a poster), Word, PowerPoint, an email signature

These cannot show SVG images: save /badge.png (the mark, sharp at any size) next to your file and link it to the paper's link. With hyperref:

\href{https://openscicode.org/badge/doi/10.1234/abcd}{\includegraphics[height=1.2em]{oscr-badge.png}}

The options

Added to the image's address as a query, for example https://openscicode.org/badge/doi/10.1234/abcd.svg?style=large&show=doi.

OptionValues
styleflat (20 pixels, the default), large (28), mark (the wordmark alone), card (title, journal, state)
showstatus (the default), doi, map (the validated map's DOI), code (the number of repositories, or of papers), scripts, language, license, journal
themeblue (the default), light (white, framed in blue)
textyour own words for the right part, 40 characters at most
missinghide: an empty image when the registry does not know the key (for a group badge)

And on the link, ?to= chooses where a click goes: paper (the default), reader (the Code ↔ Paper reader), map, cite, code (the repository), doi (the publisher) or api (the record as JSON).

With shields.io

Every badge also answers as a shields.io endpoint, for a README whose other badges are shields' and should look alike (rounded corners, for-the-badge, a colour of your own): the same facts and the same logo, drawn by shields.io.

[![OSCR](https://img.shields.io/endpoint?url=https%3A%2F%2Fopenscicode.org%2Fbadge%2Fdoi%2F10.1234%2Fabcd.json&style=flat-square)](https://openscicode.org/badge/doi/10.1234/abcd)

Every repository at once

  • For a GitLab group, add one badge in the group's Settings, General, Badges, with the link https://openscicode.org/badge/repo/gitlab.com/%{project_path} and the image https://openscicode.org/badge/repo/gitlab.com/%{project_path}.svg?missing=hide. GitLab puts each project's path in place of %{project_path}; a project the registry does not know shows nothing, and a project it learns later shows its badge the next night. On your own GitLab, use its host instead of gitlab.com.
  • For your papers, your account page links each paper you are a verified author of to its badge, and the badge page reads each of its repositories' README, says which lack the badge, and opens each one in the forge's own editor (on GitHub, a repository without a README gets a new one, already filled with the badge).
  • For your clones, use oscr badge --write (below).
  • To keep the badge up to date in your GitHub repositories, use the GitHub Action (below).

From the command line

The researchers' command line writes the badge into a clone's README, between two marks, under its title. On the next run it replaces the badge at the same place, so the badge appears once. It finds the paper the registry links to the repository; if there is none, give the DOI. You then commit and push it yourself.

oscr badge                      # the snippets, for this clone's paper
oscr badge 10.1234/abcd --write # into README.md, between <!-- oscr-badge:start --> and <!-- oscr-badge:end -->
oscr badge --repo-badge --write # the repository's own badge instead of the paper's
oscr badge --format rst         # README.rst, AsciiDoc, Org, HTML: --format rst|asciidoc|org|html
oscr badge --remove             # take it out again

With a GitHub Action

Your repository's own workflow can keep the badge there: it writes the badge between the same two marks, under the README's title, and commits the README when it changed, with the workflow's own token. It does not run any of your code, and it asks the registry for public facts only. Adding the file turns it on; deleting the file turns it off. Save this as .github/workflows/oscr-badge.yml:

name: OSCR badge
on:
  workflow_dispatch:
  release:
    types: [published]
  schedule:
    - cron: "17 4 1 * *"   # once a month
permissions:
  contents: write
jobs:
  badge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: NeuraCrypt/OSCR/github-action/oscr-badge@main

Its options (all optional): doi, repo-badge: true, readme, format, commit: false (write only, for a later step that opens a pull request) and commit-message. Its source.

When a pull request is made for you

OSCR does not open a pull request on a repository unless its owner asked for it, and it sends no mass message (the policies). It opens one in a single case, which you start yourself: when you install OSCR's GitHub App on a public repository that OSCR links to a paper, and its README lacks the badge, the App opens one pull request that adds the badge under the title, between its two marks. That is the only write the App makes, with a token limited to that repository and kept for its hour (one hour). The pull request is offered once on that repository, even if you close it. To decline, close it. To stop the App completely, uninstall it. In every other case you add the badge yourself, in the forge's own editor, with the GitHub Action or with your own command line, and that action is your consent.

How it stays true

  • The badge is drawn from the registry's public records, which change once a night. It shows the same facts as the paper's page.
  • Browsers, GitHub's image proxy and the registry's own cache keep it 1 hour, then ask again (and may show the old one for up to a day while they do). A change made tonight shows on every README by the next morning.
  • Each badge carries an accessible name ("OSCR: paper ↔ code") for screen readers, and a text that stays in its box whatever font the reader has.

Privacy

A badge sets no cookie, runs no script and loads nothing from another site (its logo is inside the image). OSCR keeps no record of who sees a badge and has no view counter. On GitHub, the images go through GitHub's proxy, so the registry does not see the reader's address.

When it does not show

  • If GitHub shows an old badge: GitHub's proxy keeps it an hour. After a day, you can purge its cache as GitHub explains (a PURGE request on the anonymized image URL).
  • If the badge says "not registered" in grey, check the DOI on the DOI lookup. The badge's link opens the submission form, already filled in.
  • If the image is broken: the badges drawn on demand share the registry's free daily allowance. On a day it runs out, they may not show until midnight UTC. The static /badge.svg and /badge.png have no such limit.
  • The rules of use are on the brand page. They allow your own words in the text and forbid changes to the image and its colours.