openalex-reporting 0.1.0__tar.gz

openalex_reporting-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gael Bernard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openalex_reporting-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: openalex-reporting
+Version: 0.1.0
+Summary: A bibliometric data warehouse for any set of OpenAlex works
+Author-email: Gael Bernard <gael.bernard@epfl.ch>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/epfl-p-data/OpenAlexReporting
+Project-URL: Repository, https://github.com/epfl-p-data/OpenAlexReporting
+Project-URL: Issues, https://github.com/epfl-p-data/OpenAlexReporting/issues
+Keywords: bibliometrics,OpenAlex,DuckDB,reporting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=2.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: build
+Requires-Dist: openalex-metrics>=0.5; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# OAR — bibliometric reporting from OpenAlex
+
+[![PyPI](https://img.shields.io/pypi/v/openalex-reporting)](https://pypi.org/project/openalex-reporting/)
+
+OAR builds a bibliometric database for any set of papers: a university, a researcher, a country, a funder's portfolio or a list of DOIs. It answers the questions a research office asks of InCites. How many papers, how often they are cited relative to their field, who the institution publishes with, and how much of the output is open access.
+
+The citation scores come from [OAM](https://github.com/epfl-p-data/OpenAlexImpactMetrics). OAM compares each paper with papers of the same subfield, the same publication year and the same kind of venue, journal or conference, and it stores the result as ids. OAR keeps those scores and adds what they leave out: titles, authors, affiliations and the open-access copy. The result is one DuckDB file. After the build, nothing calls OAM or the network, and the file can be handed to someone who does not have either installed.
+
+A paper is scored only when it is in OAM's scope, peer-reviewed research in English, about 13% of OpenAlex. `P_all` counts every work in the set, of every OpenAlex type, including datasets and software. `P_scored` counts the ones the impact indicators use. For EPFL the two differ by about a third, and a report should say so.
+
+## Get started
+
+Python 3.11 or newer.
+
+```bash
+pip install openalex-reporting             # query a database that already exists
+pip install 'openalex-reporting[build]'    # also install OAM, which oar.build reads
+```
+
+Querying needs DuckDB 2.0 or newer. The install above provides it. An older DuckDB cannot open a file this package writes.
+
+`oar.build` reads an OAM dataset. Install it once, from the machine that builds the database. One call fetches both Zenodo files: the scores, and the citation links published beside them.
+
+```python
+import oam
+oam.download(edges=True)       # 12 GB plus the citation links, 9.9 GB, into ~/oam-data
+```
+
+`oam.download()` without `edges=True` skips the links, and `oar.build` then stops. From archives already on disk, give the folder that holds both `oam-<snapshot>.tar` and `edges-<snapshot>.tar`: `oam.download("path/to/dist", edges=True)`. OAR still reads one OAM data directory.
+
+Then build. This one is EPFL. The same call works for an author, an ORCID, a country, a funder or a list of DOIs.
+
+```python
+import oar
+
+oar.build(name="epfl", institution="I5124864")
+oar.indicators(by=None)
+```
+
+The file lands in `./data` when Python imports this checkout, which it does when you run it from the repository directory, and in `~/oar-data` otherwise. `oar.set_data_dir(path)` or the environment variable `OAR_DATA_DIR` puts it somewhere else. Set `OPENALEX_API_KEY` before building. A university is a few thousand requests; without a key the daily limit is too low. Copy `.env.example` to `.env` to keep the key out of the shell history.
+
+A second call with the same selection does nothing if that snapshot was already built. The API responses are cached per work, so the next institution reuses the papers the two share.
+
+## What a build stores
+
+The file has two parts.
+
+The **entity** is this selection, described by the API: title, abstract, authors, affiliations, funders, locations, and the citation count in each recent year. The publication year, the subfield and the journal-or-conference flag are taken from the OAM snapshot, not from the API. Those three are what a score was computed from. When the API disagrees, the API values are kept beside them and the work is flagged `cohort_changed`. The build prints how often that happens.
+
+The **world** is every work's id, score and institutional affiliation, copied from OAM, about 8 GB. That is what a baseline is computed from: the world, a country, or another institution. It is ids and names, not the text of every paper. `world="all"` also copies authors, DOIs and ORCIDs, so a researcher can be a peer. `world=None` keeps only the selection, and baselines are then unavailable.
+
+A paper in a cohort of fewer than 500 works keeps its row and its raw citation count, but its normalised score, percentile and top-10% and top-1% flags are NULL. An impact average skips those NULLs, so it does not need a reliability filter. `count(ncs)` is the number of scored papers.
+
+The file stores who cited the selection, in which year, and whether the citation is a self-citation. That comes from OAM's citation links, which `oam.download(edges=True)` installs. The build stops when they are missing.
+
+The build writes a markdown file next to the database, with the same stem: `epfl-2026-10-14.md` beside `epfl-2026-10-14.duckdb`. It describes every table and column, explains which papers are scored and which are not, gives queries, and records reference values taken from that file. The text is `oar/doc_template.md`, the same for every database; the build fills in the numbers and the table list, and `oar.doc()` rewrites the file after the template changes.
+
+The full OpenAlex snapshot is not stored. It is more than a terabyte, and the baselines do not need it.
+
+## The indicators
+
+`oar.indicators()` returns one row per group. `counting="full"` gives every paper weight 1. `counting="frac"` gives a paper shared with other institutions a weight of one over the number of institutions. Impact uses scored papers, the ones with a normalised score, which is OAM's rule of cohorts of at least 500, so `MNCS_full` matches `oam.aggregate`.
+
+```python
+oar.indicators(by="publication_year")          # this selection
+oar.baseline(world=True)                        # every scored paper
+oar.baseline(country="CH")                      # Switzerland
+oar.baseline(institution="I35440088")           # ETH Zurich
+oar.partners().head(20)                         # who EPFL publishes with
+oar.works().head(20)                            # one row per paper, with its scores
+```
+
+The same queries are stored in the file for a SQL client:
+
+```sql
+SELECT * FROM indicators_by_year();
+SELECT * FROM indicators_overall();
+SELECT * FROM baseline_world_by_year();
+SELECT * FROM baseline_country_by_year('CH');
+```
+
+[Indicators](docs/indicators.md) maps each of these columns to the InCites list they stand in for, and records the ones that are not computed. [Building](docs/building.md) is the build, [querying](docs/querying.md) is every function, and [schema](docs/schema.md) is every table.
+
+## An example
+
+`examples/epfl.py` builds EPFL and prints it next to ETH Zurich and next to Switzerland.
+
+## Data and licence
+
+The descriptive fields come from the [OpenAlex API](https://openalex.org). The scores and the world tables come from OAM's snapshot, which is released under CC0. Say which snapshot you used. `oar.status()` prints it.
+
+OAR is released under the MIT licence. See [LICENSE](LICENSE).

openalex_reporting-0.1.0/README.md

@@ -0,0 +1,92 @@
+# OAR — bibliometric reporting from OpenAlex
+
+[![PyPI](https://img.shields.io/pypi/v/openalex-reporting)](https://pypi.org/project/openalex-reporting/)
+
+OAR builds a bibliometric database for any set of papers: a university, a researcher, a country, a funder's portfolio or a list of DOIs. It answers the questions a research office asks of InCites. How many papers, how often they are cited relative to their field, who the institution publishes with, and how much of the output is open access.
+
+The citation scores come from [OAM](https://github.com/epfl-p-data/OpenAlexImpactMetrics). OAM compares each paper with papers of the same subfield, the same publication year and the same kind of venue, journal or conference, and it stores the result as ids. OAR keeps those scores and adds what they leave out: titles, authors, affiliations and the open-access copy. The result is one DuckDB file. After the build, nothing calls OAM or the network, and the file can be handed to someone who does not have either installed.
+
+A paper is scored only when it is in OAM's scope, peer-reviewed research in English, about 13% of OpenAlex. `P_all` counts every work in the set, of every OpenAlex type, including datasets and software. `P_scored` counts the ones the impact indicators use. For EPFL the two differ by about a third, and a report should say so.
+
+## Get started
+
+Python 3.11 or newer.
+
+```bash
+pip install openalex-reporting             # query a database that already exists
+pip install 'openalex-reporting[build]'    # also install OAM, which oar.build reads
+```
+
+Querying needs DuckDB 2.0 or newer. The install above provides it. An older DuckDB cannot open a file this package writes.
+
+`oar.build` reads an OAM dataset. Install it once, from the machine that builds the database. One call fetches both Zenodo files: the scores, and the citation links published beside them.
+
+```python
+import oam
+oam.download(edges=True)       # 12 GB plus the citation links, 9.9 GB, into ~/oam-data
+```
+
+`oam.download()` without `edges=True` skips the links, and `oar.build` then stops. From archives already on disk, give the folder that holds both `oam-<snapshot>.tar` and `edges-<snapshot>.tar`: `oam.download("path/to/dist", edges=True)`. OAR still reads one OAM data directory.
+
+Then build. This one is EPFL. The same call works for an author, an ORCID, a country, a funder or a list of DOIs.
+
+```python
+import oar
+
+oar.build(name="epfl", institution="I5124864")
+oar.indicators(by=None)
+```
+
+The file lands in `./data` when Python imports this checkout, which it does when you run it from the repository directory, and in `~/oar-data` otherwise. `oar.set_data_dir(path)` or the environment variable `OAR_DATA_DIR` puts it somewhere else. Set `OPENALEX_API_KEY` before building. A university is a few thousand requests; without a key the daily limit is too low. Copy `.env.example` to `.env` to keep the key out of the shell history.
+
+A second call with the same selection does nothing if that snapshot was already built. The API responses are cached per work, so the next institution reuses the papers the two share.
+
+## What a build stores
+
+The file has two parts.
+
+The **entity** is this selection, described by the API: title, abstract, authors, affiliations, funders, locations, and the citation count in each recent year. The publication year, the subfield and the journal-or-conference flag are taken from the OAM snapshot, not from the API. Those three are what a score was computed from. When the API disagrees, the API values are kept beside them and the work is flagged `cohort_changed`. The build prints how often that happens.
+
+The **world** is every work's id, score and institutional affiliation, copied from OAM, about 8 GB. That is what a baseline is computed from: the world, a country, or another institution. It is ids and names, not the text of every paper. `world="all"` also copies authors, DOIs and ORCIDs, so a researcher can be a peer. `world=None` keeps only the selection, and baselines are then unavailable.
+
+A paper in a cohort of fewer than 500 works keeps its row and its raw citation count, but its normalised score, percentile and top-10% and top-1% flags are NULL. An impact average skips those NULLs, so it does not need a reliability filter. `count(ncs)` is the number of scored papers.
+
+The file stores who cited the selection, in which year, and whether the citation is a self-citation. That comes from OAM's citation links, which `oam.download(edges=True)` installs. The build stops when they are missing.
+
+The build writes a markdown file next to the database, with the same stem: `epfl-2026-10-14.md` beside `epfl-2026-10-14.duckdb`. It describes every table and column, explains which papers are scored and which are not, gives queries, and records reference values taken from that file. The text is `oar/doc_template.md`, the same for every database; the build fills in the numbers and the table list, and `oar.doc()` rewrites the file after the template changes.
+
+The full OpenAlex snapshot is not stored. It is more than a terabyte, and the baselines do not need it.
+
+## The indicators
+
+`oar.indicators()` returns one row per group. `counting="full"` gives every paper weight 1. `counting="frac"` gives a paper shared with other institutions a weight of one over the number of institutions. Impact uses scored papers, the ones with a normalised score, which is OAM's rule of cohorts of at least 500, so `MNCS_full` matches `oam.aggregate`.
+
+```python
+oar.indicators(by="publication_year")          # this selection
+oar.baseline(world=True)                        # every scored paper
+oar.baseline(country="CH")                      # Switzerland
+oar.baseline(institution="I35440088")           # ETH Zurich
+oar.partners().head(20)                         # who EPFL publishes with
+oar.works().head(20)                            # one row per paper, with its scores
+```
+
+The same queries are stored in the file for a SQL client:
+
+```sql
+SELECT * FROM indicators_by_year();
+SELECT * FROM indicators_overall();
+SELECT * FROM baseline_world_by_year();
+SELECT * FROM baseline_country_by_year('CH');
+```
+
+[Indicators](docs/indicators.md) maps each of these columns to the InCites list they stand in for, and records the ones that are not computed. [Building](docs/building.md) is the build, [querying](docs/querying.md) is every function, and [schema](docs/schema.md) is every table.
+
+## An example
+
+`examples/epfl.py` builds EPFL and prints it next to ETH Zurich and next to Switzerland.
+
+## Data and licence
+
+The descriptive fields come from the [OpenAlex API](https://openalex.org). The scores and the world tables come from OAM's snapshot, which is released under CC0. Say which snapshot you used. `oar.status()` prints it.
+
+OAR is released under the MIT licence. See [LICENSE](LICENSE).

openalex_reporting-0.1.0/oar/__init__.py

@@ -0,0 +1,48 @@
+"""OAR — a bibliometric warehouse for any set of OpenAlex works.
+
+    import oar
+
+    oar.build(name="epfl", institution="I5124864")
+    oar.indicators()                  # output, impact, collaboration, open access
+    oar.baseline(country="CH")        # the same indicators for a reference set
+    oar.partners()                    # who the set publishes with
+
+The build reads OAM for the work set and the citation scores, and the OpenAlex
+API for titles, authors and affiliations. The result is one DuckDB file. After
+that, nothing here needs OAM or the network.
+
+See the README for the indicators and for what a baseline compares against.
+"""
+
+import re
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .build import build, status
+from .config import set_data_dir
+from .db import connect
+from .doc import doc
+from .indicators import baseline, indicators, partners, works
+
+
+def _package_version():
+    try:
+        return version("openalex-reporting")
+    except PackageNotFoundError:
+        text = (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text()
+        match = re.search(r'(?m)^version = "([^"]+)"', text)
+        if match is None:
+            raise RuntimeError("pyproject.toml has no version")
+        return match.group(1)
+
+
+__version__ = _package_version()
+
+__all__ = [
+    "baseline", "build", "connect", "doc", "indicators", "partners",
+    "set_data_dir", "status", "works",
+]
+
+
+def __dir__():
+    return sorted(__all__ + ["__version__"])