ckanext-citations 0.1.8__tar.gz

ckanext_citations-0.1.8/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.2
+Name: ckanext-citations
+Version: 0.1.8
+Summary: Citation tracking (cited-by via OpenAlex/DataCite Event Data), dataset disruption index and per-researcher S-index, displayed on the dataset page.
+Author-email: ICS <groupe-info-ics@igbmc.fr>
+License: AGPL-3.0-or-later
+Keywords: CKAN,data,citations,bibliometrics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Provides-Extra: test
+Requires-Dist: pytest==7.4.4; extra == "test"
+Requires-Dist: pytest-cov==4.1.0; extra == "test"
+Requires-Dist: responses; extra == "test"
+
+![CKAN](https://img.shields.io/badge/CKAN-2.12.0-orange)
+![License](https://img.shields.io/badge/license-AGPL--3.0-blue)
+
+# ckanext-citations
+
+Citation tracking (cited-by, via OpenAlex with a DataCite Event Data
+fallback), a per-dataset disruption index, and a per-researcher S-index
+("how many unique researchers has your data enabled" - see
+[s-index.science](https://s-index.science/)), displayed on the dataset
+page.
+
+## v1 scope
+
+This first iteration deliberately does **not** implement the 17
+FAIRsFAIR/F-UJI metrics, a merged "FAIR score", or the metadata-enrichment
+assistant described in the original design note. It covers only the
+citation/impact-tracking half:
+
+- Citation count (cited-by) per dataset.
+- [Disruption index](https://doi.org/10.1038/s41586-019-0941-9) (Wu, Wang &
+  Evans, 2019): `DI = (N_F - N_B) / (N_F + N_B + N_R)`.
+- S-index per ORCID: count of distinct researchers (deduplicated by ORCID,
+  falling back to normalised name) who authored a work citing any of that
+  researcher's FAIR3R datasets.
+- Display on the dataset page (citation count, disruption index, S-index
+  with a co-author breakdown, a citing-works table).
+
+## Why dedicated tables, not `package_extra`
+
+Citations and scores are refreshed by a periodic batch job, not by the user
+editing the dataset. Writing them through `package_update`/`package_extra`
+would create a `package_revision` row and trigger a full Solr reindex for
+every dataset on every refresh run - pure overhead for data nobody searches
+on. Instead this plugin owns five Postgres tables of its own
+(`fair_citation_stats`, `fair_citing_works`, `fair_citing_researchers`,
+`fair_author_sindex`, `fair_score_history`), created via the same
+Alembic-based migration mechanism as `ckanext-doi`
+(`ckan db upgrade -p citations`).
+
+`fair_citing_researchers` exists only to make the S-index's "unique
+researchers" dedup correct across an author's several datasets: it's one
+row per (FAIR3R author ORCID, citing-researcher identity) pair, and
+`fair_author_sindex.s_index_current` is the cached `COUNT(DISTINCT ...)`
+over it. Both the citation count and the S-index are also tracked as
+high-water marks (`*_max`) so a researcher's score never visibly regresses
+just because an external API temporarily deduplicates differently between
+two refresh runs.
+
+## The disruption index needs a reference list the dataset usually doesn't have
+
+The Wu/Wang/Evans formula needs to know what the focal work's own
+references are, to tell "citing works that also build on the same sources"
+(`N_B`) apart from "citing works that only cite the focal work" (`N_F`).
+OpenAlex rarely has a populated reference list for a dataset-type Work,
+which would make `N_B`/`N_R` collapse to 0 and the index trivially tend to
+`+1.0` for almost every dataset with any citations at all.
+
+To get a meaningful signal, the reference set is enriched with the
+dataset's own DataCite `relatedIdentifiers` whose `relationType` is
+`References` or `Cites` (already supported by the FDF schema via
+`ckanext-doi`) - each such DOI is resolved to an OpenAlex work id and added
+to the focal work's reference set before classifying citing works.
+
+## Config
+
+```ini
+# Contact email sent as OpenAlex's "polite pool" mailto param (better rate
+# limits, not auth). Optional but recommended.
+ckanext.citations.contact_email = your-team@example.org
+
+# Pause between outbound API calls during a refresh, in seconds.
+ckanext.citations.request_pause_seconds = 0.1
+```
+
+## Running a refresh
+
+```bash
+ckan citations refresh --min-age-days 7
+```
+
+Idempotent and safe to run repeatedly: only datasets whose
+`fair_citation_stats.last_checked` is older than `--min-age-days` (or
+`NULL`, i.e. never checked) are touched. Intended to run from a weekly cron
+job, same pattern as `fair3r update-schema`.
+
+## Tests
+
+Two `test.ini` files, same convention as the other FAIR3R extensions:
+
+- `test.ini` at the repo root: Docker DEV (`/srv/app/src/ckan/test-core.ini`).
+- `ckanext/citations/tests/test.ini`: shipped with the package, used by
+  `deploy/ckanext_test.py` on integration/validation (`/usr/lib/ckan/default/...`).
+
+```shell
+docker exec -u ckan -it ckan-app pytest --ckan-ini=/plugins/ckanext-citations/test.ini /plugins/ckanext-citations/ckanext/citations/tests
+```

ckanext_citations-0.1.8/README.md

@@ -0,0 +1,96 @@
+![CKAN](https://img.shields.io/badge/CKAN-2.12.0-orange)
+![License](https://img.shields.io/badge/license-AGPL--3.0-blue)
+
+# ckanext-citations
+
+Citation tracking (cited-by, via OpenAlex with a DataCite Event Data
+fallback), a per-dataset disruption index, and a per-researcher S-index
+("how many unique researchers has your data enabled" - see
+[s-index.science](https://s-index.science/)), displayed on the dataset
+page.
+
+## v1 scope
+
+This first iteration deliberately does **not** implement the 17
+FAIRsFAIR/F-UJI metrics, a merged "FAIR score", or the metadata-enrichment
+assistant described in the original design note. It covers only the
+citation/impact-tracking half:
+
+- Citation count (cited-by) per dataset.
+- [Disruption index](https://doi.org/10.1038/s41586-019-0941-9) (Wu, Wang &
+  Evans, 2019): `DI = (N_F - N_B) / (N_F + N_B + N_R)`.
+- S-index per ORCID: count of distinct researchers (deduplicated by ORCID,
+  falling back to normalised name) who authored a work citing any of that
+  researcher's FAIR3R datasets.
+- Display on the dataset page (citation count, disruption index, S-index
+  with a co-author breakdown, a citing-works table).
+
+## Why dedicated tables, not `package_extra`
+
+Citations and scores are refreshed by a periodic batch job, not by the user
+editing the dataset. Writing them through `package_update`/`package_extra`
+would create a `package_revision` row and trigger a full Solr reindex for
+every dataset on every refresh run - pure overhead for data nobody searches
+on. Instead this plugin owns five Postgres tables of its own
+(`fair_citation_stats`, `fair_citing_works`, `fair_citing_researchers`,
+`fair_author_sindex`, `fair_score_history`), created via the same
+Alembic-based migration mechanism as `ckanext-doi`
+(`ckan db upgrade -p citations`).
+
+`fair_citing_researchers` exists only to make the S-index's "unique
+researchers" dedup correct across an author's several datasets: it's one
+row per (FAIR3R author ORCID, citing-researcher identity) pair, and
+`fair_author_sindex.s_index_current` is the cached `COUNT(DISTINCT ...)`
+over it. Both the citation count and the S-index are also tracked as
+high-water marks (`*_max`) so a researcher's score never visibly regresses
+just because an external API temporarily deduplicates differently between
+two refresh runs.
+
+## The disruption index needs a reference list the dataset usually doesn't have
+
+The Wu/Wang/Evans formula needs to know what the focal work's own
+references are, to tell "citing works that also build on the same sources"
+(`N_B`) apart from "citing works that only cite the focal work" (`N_F`).
+OpenAlex rarely has a populated reference list for a dataset-type Work,
+which would make `N_B`/`N_R` collapse to 0 and the index trivially tend to
+`+1.0` for almost every dataset with any citations at all.
+
+To get a meaningful signal, the reference set is enriched with the
+dataset's own DataCite `relatedIdentifiers` whose `relationType` is
+`References` or `Cites` (already supported by the FDF schema via
+`ckanext-doi`) - each such DOI is resolved to an OpenAlex work id and added
+to the focal work's reference set before classifying citing works.
+
+## Config
+
+```ini
+# Contact email sent as OpenAlex's "polite pool" mailto param (better rate
+# limits, not auth). Optional but recommended.
+ckanext.citations.contact_email = your-team@example.org
+
+# Pause between outbound API calls during a refresh, in seconds.
+ckanext.citations.request_pause_seconds = 0.1
+```
+
+## Running a refresh
+
+```bash
+ckan citations refresh --min-age-days 7
+```
+
+Idempotent and safe to run repeatedly: only datasets whose
+`fair_citation_stats.last_checked` is older than `--min-age-days` (or
+`NULL`, i.e. never checked) are touched. Intended to run from a weekly cron
+job, same pattern as `fair3r update-schema`.
+
+## Tests
+
+Two `test.ini` files, same convention as the other FAIR3R extensions:
+
+- `test.ini` at the repo root: Docker DEV (`/srv/app/src/ckan/test-core.ini`).
+- `ckanext/citations/tests/test.ini`: shipped with the package, used by
+  `deploy/ckanext_test.py` on integration/validation (`/usr/lib/ckan/default/...`).
+
+```shell
+docker exec -u ckan -it ckan-app pytest --ckan-ini=/plugins/ckanext-citations/test.ini /plugins/ckanext-citations/ckanext/citations/tests
+```

ckanext_citations-0.1.8/ckanext/__init__.py

@@ -0,0 +1,8 @@
+try:
+    import pkg_resources
+
+    pkg_resources.declare_namespace(__name__)
+except ImportError:
+    import pkgutil
+
+    __path__ = pkgutil.extend_path(__path__, __name__)

ckanext_citations-0.1.8/ckanext/citations/cli.py

@@ -0,0 +1,89 @@
+import logging
+import time
+from datetime import datetime, timedelta, timezone
+
+import click
+from ckan.model import Package, Session
+
+log = logging.getLogger(__name__)
+
+DEFAULT_MIN_AGE_DAYS = 7
+DEFAULT_PAUSE_SECONDS = 0.1
+
+
+def get_commands():
+    return [citations]
+
+
+@click.group()
+def citations():
+    """Citation/impact tracking commands."""
+
+
+@citations.command(name='refresh')
+@click.option(
+    '--min-age-days',
+    default=DEFAULT_MIN_AGE_DAYS,
+    show_default=True,
+    help='Only refresh datasets whose citation stats were last checked more '
+    'than this many days ago (or never checked at all).',
+)
+@click.option(
+    '--limit',
+    default=None,
+    type=int,
+    help='Process at most this many datasets this run.',
+)
+@click.option(
+    '--pause-seconds',
+    default=DEFAULT_PAUSE_SECONDS,
+    show_default=True,
+    help='Pause between datasets, on top of the per-API-call pause already '
+    'applied inside each dataset refresh.',
+)
+def refresh(min_age_days, limit, pause_seconds):
+    """Batched, idempotent citation refresh across every published-DOI
+    dataset due for a check. Safe to run on a cron - only datasets whose
+    last check is older than --min-age-days (or never checked) are touched.
+    """
+    from ckanext.citations.lib.refresh import refresh_dataset
+
+    package_ids = _packages_due_for_refresh(min_age_days)
+    if limit:
+        package_ids = package_ids[:limit]
+
+    click.echo(f'{len(package_ids)} dataset(s) due for a citation refresh.')
+
+    for i, package_id in enumerate(package_ids, start=1):
+        try:
+            refresh_dataset(package_id)
+            click.echo(f'[{i}/{len(package_ids)}] refreshed {package_id}')
+        except Exception:
+            log.exception('Citation refresh failed for dataset %s', package_id)
+            click.secho(f'[{i}/{len(package_ids)}] FAILED {package_id}', fg='red')
+            Session.rollback()
+        time.sleep(pause_seconds)
+
+
+def _packages_due_for_refresh(min_age_days):
+    """Queries ckan.model directly (not the package_search action) so this
+    maintenance job sees every dataset - public or private - and doesn't
+    depend on Solr being in sync."""
+    from ckanext.citations.model import CitationStats
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=min_age_days)
+
+    already_checked_recently = {
+        row.package_id
+        for row in Session.query(CitationStats.package_id).filter(
+            CitationStats.last_checked.isnot(None), CitationStats.last_checked > cutoff
+        )
+    }
+
+    all_active_ids = [
+        row.id
+        for row in Session.query(Package.id).filter(
+            Package.state == 'active', Package.type == 'dataset'
+        )
+    ]
+    return [pid for pid in all_active_ids if pid not in already_checked_recently]

ckanext_citations-0.1.8/ckanext/citations/i18n/ckanext-citations.pot

@@ -0,0 +1,116 @@
+# Translations template for ckanext-citations.
+# Copyright (C) 2026 ORGANIZATION
+# This file is distributed under the same license as the ckanext-citations
+# project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: ckanext-citations 0.1.6\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-10-05 15:53+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:20
+msgid "FAIR & Impact"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:29
+msgid "Completeness"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:30
+msgid ""
+"How complete the FAIR3R metadata of this dataset is: the weighted share of "
+"the fields that apply (required fields count double), CKAN basics included. "
+"Conditional fields that are hidden are ignored."
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:38
+msgid "Missing fields"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:50
+msgid "Citations"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:55
+msgid "last checked"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:62
+msgid "Disruption index"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:63
+msgid ""
+"Wu, Wang & Evans (2019). Between -1 and +1: close to +1 means the works "
+"citing this dataset tend to replace it; close to -1 means they build on it "
+"together with its own references. Uses the dataset References/Cites related "
+"identifiers when present."
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:69
+msgid "not enough data yet"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:76
+#: ckanext/citations/templates/package/snippets/citations_panel.html:87
+msgid "S-index"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:77
+msgid ""
+"Number of distinct researchers (identified by ORCID) who have cited at least "
+"one of this author FAIR3R datasets. Shown for the highest co-author with an "
+"ORCID."
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:82
+msgid "highest among co-authors"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:84
+msgid "All co-authors"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:99
+msgid "Not checked yet: citations are tracked once the dataset has a published DOI."
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:103
+msgid "Citing works"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:107
+msgid "Title"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:108
+msgid "Authors"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:109
+msgid "Year"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:110
+msgid "Venue"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:111
+msgid "DOI"
+msgstr ""
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:134
+#, python-format
+msgid "Show all %(count)s citing works"
+msgstr ""
+

ckanext_citations-0.1.8/ckanext/citations/i18n/fr/LC_MESSAGES/ckanext-citations.po

@@ -0,0 +1,130 @@
+# French translations for ckanext-citations.
+# Copyright (C) 2026 ORGANIZATION
+# This file is distributed under the same license as the ckanext-citations
+# project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: ckanext-citations 0.1.6\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-10-05 15:53+0000\n"
+"PO-Revision-Date: 2026-10-05 15:53+0000\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: fr <LL@li.org>\n"
+"Language: fr\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:20
+msgid "FAIR & Impact"
+msgstr "FAIR & Impact"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:29
+msgid "Completeness"
+msgstr "Complétude"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:30
+msgid ""
+"How complete the FAIR3R metadata of this dataset is: the weighted share of "
+"the fields that apply (required fields count double), CKAN basics included. "
+"Conditional fields that are hidden are ignored."
+msgstr ""
+"Niveau de complétude des métadonnées FAIR3R de ce dataset : part pondérée "
+"des champs applicables (les champs obligatoires comptent double), en "
+"incluant les champs de base de CKAN. Les champs conditionnels masqués sont "
+"ignorés."
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:38
+msgid "Missing fields"
+msgstr "Champs manquants"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:50
+msgid "Citations"
+msgstr "Citations"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:55
+msgid "last checked"
+msgstr "dernière vérification"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:62
+msgid "Disruption index"
+msgstr "Indice de disruption"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:63
+msgid ""
+"Wu, Wang & Evans (2019). Between -1 and +1: close to +1 means the works "
+"citing this dataset tend to replace it; close to -1 means they build on it "
+"together with its own references. Uses the dataset References/Cites related "
+"identifiers when present."
+msgstr ""
+"Wu, Wang & Evans (2019). Entre -1 et +1 : proche de +1, les œuvres citant ce"
+" dataset tendent à le remplacer ; proche de -1, elles s'appuient aussi sur "
+"ses références. Utilise les identifiants liés References/Cites du dataset "
+"quand ils existent."
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:69
+msgid "not enough data yet"
+msgstr "pas assez de données pour l'instant"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:76
+#: ckanext/citations/templates/package/snippets/citations_panel.html:87
+msgid "S-index"
+msgstr "S-index"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:77
+msgid ""
+"Number of distinct researchers (identified by ORCID) who have cited at least"
+" one of this author FAIR3R datasets. Shown for the highest co-author with an"
+" ORCID."
+msgstr ""
+"Nombre de chercheurs distincts (identifiés par ORCID) ayant cité au moins un"
+" des datasets FAIR3R de cet auteur. Affiché pour le co-auteur ayant le plus "
+"haut score, parmi ceux qui ont un ORCID."
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:82
+msgid "highest among co-authors"
+msgstr "le plus élevé parmi les co-auteurs"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:84
+msgid "All co-authors"
+msgstr "Tous les co-auteurs"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:99
+msgid ""
+"Not checked yet: citations are tracked once the dataset has a published DOI."
+msgstr ""
+"Pas encore vérifié : les citations sont suivies une fois le dataset publié "
+"avec un DOI."
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:103
+msgid "Citing works"
+msgstr "Œuvres citantes"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:107
+msgid "Title"
+msgstr "Titre"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:108
+msgid "Authors"
+msgstr "Auteurs"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:109
+msgid "Year"
+msgstr "Année"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:110
+msgid "Venue"
+msgstr "Revue"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:111
+msgid "DOI"
+msgstr "DOI"
+
+#: ckanext/citations/templates/package/snippets/citations_panel.html:134
+#, python-format
+msgid "Show all %(count)s citing works"
+msgstr "Afficher les %(count)s œuvres citantes"

ckanext_citations-0.1.8/ckanext/citations/lib/datacite_events_client.py

@@ -0,0 +1,88 @@
+"""Fallback citation source: DataCite's Event Data API.
+
+Used only to top up the citation count when OpenAlex hasn't indexed the
+dataset's DOI at all. Event Data exposes bare subject/object DOI pairs, not
+author/ORCID/reference-list metadata, so works discovered this way cannot
+feed the disruption index or the S-index - they only contribute to
+citation_count_current.
+"""
+
+import logging
+import time
+
+import requests
+
+log = logging.getLogger(__name__)
+
+BASE_URL = 'https://api.datacite.org/events'
+REQUEST_TIMEOUT = 20
+MAX_RETRIES = 4
+INITIAL_BACKOFF_SECONDS = 1.0
+
+
+class DataciteEventsError(Exception):
+    pass
+
+
+def _get_with_backoff(params):
+    backoff = INITIAL_BACKOFF_SECONDS
+    last_error = None
+    for attempt in range(1, MAX_RETRIES + 1):
+        try:
+            resp = requests.get(BASE_URL, params=params, timeout=REQUEST_TIMEOUT)
+        except requests.RequestException as e:
+            last_error = f'DataCite Event Data request failed: {e}'
+            log.warning(
+                '%s (attempt %s/%s, retrying in %.1fs)',
+                last_error,
+                attempt,
+                MAX_RETRIES,
+                backoff,
+            )
+            time.sleep(backoff)
+            backoff *= 2.0
+            continue
+
+        if resp.status_code == 200:
+            return resp.json()
+        if resp.status_code == 429 or resp.status_code >= 500:
+            last_error = (
+                f'DataCite Event Data returned {resp.status_code}: {resp.text[:200]}'
+            )
+            log.warning(
+                '%s (attempt %s/%s, retrying in %.1fs)',
+                last_error,
+                attempt,
+                MAX_RETRIES,
+                backoff,
+            )
+            time.sleep(backoff)
+            backoff *= 2.0
+            continue
+        raise DataciteEventsError(
+            f'DataCite Event Data returned {resp.status_code}: {resp.text[:200]}'
+        )
+
+    raise DataciteEventsError(
+        f'DataCite Event Data request failed after {MAX_RETRIES} attempts: {last_error}'
+    )
+
+
+def get_citing_dois(doi):
+    """Return the list of citing DOIs for `doi` via the is-cited-by relation.
+    Returns [] if DataCite has no events for this DOI (not an error - most
+    datasets simply won't have any yet)."""
+    params = {
+        'doi': doi,
+        'relation-type-id': 'is-cited-by',
+        'page[size]': 200,
+    }
+    data = _get_with_backoff(params)
+    citing_dois = []
+    for event in data.get('data', []):
+        attrs = event.get('attributes', {})
+        subj_id = attrs.get('subjId') or ''
+        # subjId is the citing work's DOI as a URL (https://doi.org/10.xxx/yyy).
+        if 'doi.org/' in subj_id:
+            citing_dois.append(subj_id.split('doi.org/', 1)[-1])
+    return citing_dois