openalex-metrics 0.1.0__tar.gz

openalex_metrics-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

openalex_metrics-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,22 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: pip install ".[test,build]"
+      - name: Test
+        run: pytest

openalex_metrics-0.1.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+title: "OAM: OpenAlex Metrics"
+message: If you use OAM, please cite it using the metadata below.
+type: software
+authors:
+  - family-names: Bernard
+    given-names: Gael
+    affiliation: EPFL
+    email: gael.bernard@epfl.ch
+repository-code: https://github.com/epfl-p-data/OpenAlexImpactMetrics
+url: https://github.com/epfl-p-data/OpenAlexImpactMetrics
+license: MIT
+version: 0.1.0
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.23493154
+    description: "Data release on Zenodo, all versions. Each snapshot has its own version DOI."

openalex_metrics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OAM contributors
+
+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_metrics-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CITATION.cff
+recursive-include tests *.py
+recursive-include docs *
+recursive-include examples *.py
+recursive-include .github *.yml

openalex_metrics-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: openalex-metrics
+Version: 0.1.0
+Summary: Field-normalised citation impact (MNCS, PP top 10%) 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/OpenAlexImpactMetrics
+Project-URL: Repository, https://github.com/epfl-p-data/OpenAlexImpactMetrics
+Project-URL: Issues, https://github.com/epfl-p-data/OpenAlexImpactMetrics/issues
+Keywords: bibliometrics,citation impact,OpenAlex,MNCS
+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>=1.2
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: build
+Requires-Dist: pyarrow>=14; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# OAM — citation impact from OpenAlex
+
+OAM tells you whether a set of papers was cited more or less than comparable papers. You can score a university, a researcher, a country, a funder's portfolio or a list of DOIs. It runs on your own machine, and the data comes from [OpenAlex](https://openalex.org).
+
+## Get started
+
+Python 3.11 or newer.
+
+```bash
+pip install openalex-metrics
+```
+
+Download the data once. This fetches the latest release from [Zenodo](https://doi.org/10.5281/zenodo.23493154), about 12 GB, and checks every file:
+
+```python
+import oam
+
+oam.download()
+```
+
+The files go to `~/oam-data`. To put them somewhere else, call `oam.set_data_dir(path)` before downloading, or set the `OAM_DATA_DIR` environment variable. You need about 25 GB free while the archive is unpacked.
+
+Then score a set of papers:
+
+```python
+ids = oam.resolve(institution="I5124864", year=(2020, 2024))  # EPFL
+oam.aggregate(ids).round(2)
+```
+
+`oam.resolve` finds the papers. `oam.aggregate` scores the ones that can be compared with similar papers. To find an institution's id, search by name:
+
+```python
+oam.dimension("institutions", search="Lausanne")
+```
+
+## Three examples
+
+These numbers come from the OpenAlex snapshot of 14 October 2026.
+
+### A university, over five years
+
+EPFL, 2020 to 2024. Of the 36,475 works with EPFL's name on them, 22,207 are scored.
+
+```python
+ids = oam.resolve(institution="I5124864", year=(2020, 2024))
+oam.aggregate(ids).round(2)
+```
+
+```
+ publication_year    P  P_weighted      TCS   MCS  MNCS  PP_top10  PP_top1
+             2020 4433      4433.0 200062.0 45.13  1.95     21.52     3.41
+             2021 4498      4498.0 150841.0 33.54  1.80     20.08     3.11
+             2022 4349      4349.0 120403.0 27.69  1.89     20.74     2.90
+             2023 4470      4470.0  85462.0 19.12  1.74     20.25     3.02
+             2024 4457      4457.0  58542.0 13.13  1.83     21.11     3.43
+```
+
+### A researcher
+
+Jennifer Doudna, from her [ORCID](https://orcid.org/0000-0001-9161-999X). Of 755 works, 391 are scored. `by=None` gives one row for the whole set.
+
+```python
+ids = oam.resolve(orcid="0000-0001-9161-999X")
+oam.aggregate(ids, by=None).round(2)
+```
+
+```
+  P  P_weighted     TCS   MCS  MNCS  PP_top10  PP_top1
+391       391.0 91886.0 235.0  5.97     59.34    14.83
+```
+
+### A country
+
+Switzerland, 2020 to 2024. Of 490,707 works, 265,954 are scored.
+
+```python
+ids = oam.resolve(country="CH", year=(2020, 2024))
+oam.aggregate(ids).round(2)
+```
+
+```
+ publication_year     P  P_weighted       TCS   MCS  MNCS  PP_top10  PP_top1
+             2020 52142     52142.0 2108683.0 40.44  1.80     18.78     2.87
+             2021 55231     55231.0 1744205.0 31.58  1.78     18.79     3.02
+             2022 53311     53311.0 1206510.0 22.63  1.71     18.77     2.88
+             2023 52502     52502.0  887357.0 16.90  1.71     19.19     3.08
+             2024 52768     52768.0  605921.0 11.48  1.75     19.27     2.99
+```
+
+You can select papers the same way by author, funder, journal, field or DOI. [Querying](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/querying.md) lists every option.
+
+## Reading the numbers
+
+- **P** is the number of papers that received a score.
+- **MNCS** compares those papers with similar papers worldwide. The world average is 1. A value of 2 means cited twice as much.
+- **PP_top10** is the share of papers among the 10% most cited of their group. For the world, that share is about 10%. **PP_top1** is the same for the top 1%.
+
+[How the scores work](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/metrics.md) explains the other columns, and full and fractional counting.
+
+## How this differs from OpenAlex
+
+OpenAlex already gives most works a citation score, the FWCI. It compares each work with everything OpenAlex indexes, and it counts citations from anything, including preprints, datasets and theses. OAM compares a paper only with peer-reviewed research papers like it, and counts only the citations that come from such papers.
+
+## Which papers are scored
+
+A paper is scored when it passes all seven rules. On the snapshot of 14 October 2026, 62,493,369 of 464,765,485 works pass, which is 13.45%.
+
+1. It is in a core journal or a conference proceedings.
+2. It has a reference list.
+3. It has at least one institutional affiliation.
+4. It is in English.
+5. It has an OpenAlex subfield.
+6. It is not paratext, such as an editorial, erratum or table of contents.
+7. It is not retracted.
+
+Each paper is then compared with papers of the same subfield, publication year and venue type (journal or conference).
+
+These rules are fixed for the data you download. To score a different set of papers, for example to keep papers in every language, edit the rules and rebuild the data. [Scope](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/scope.md) explains each rule, and [Building the data](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/building.md) explains the rebuild.
+
+## Data and licence
+
+The data is built from the public OpenAlex snapshot and released under CC0. `oam.download()` installs the latest version. To keep one snapshot, pass its Zenodo record id, listed under Versions on the [Zenodo page](https://doi.org/10.5281/zenodo.23493154):
+
+```python
+oam.download(record=23493155)    # always the 2026-10-14 snapshot
+```
+
+If you publish results, cite the version you used. Each version has its own DOI, and `oam.status()` shows which snapshot is installed.
+
+OAM is released under the MIT licence. See [LICENSE](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/LICENSE).

openalex_metrics-0.1.0/README.md

@@ -0,0 +1,130 @@
+# OAM — citation impact from OpenAlex
+
+OAM tells you whether a set of papers was cited more or less than comparable papers. You can score a university, a researcher, a country, a funder's portfolio or a list of DOIs. It runs on your own machine, and the data comes from [OpenAlex](https://openalex.org).
+
+## Get started
+
+Python 3.11 or newer.
+
+```bash
+pip install openalex-metrics
+```
+
+Download the data once. This fetches the latest release from [Zenodo](https://doi.org/10.5281/zenodo.23493154), about 12 GB, and checks every file:
+
+```python
+import oam
+
+oam.download()
+```
+
+The files go to `~/oam-data`. To put them somewhere else, call `oam.set_data_dir(path)` before downloading, or set the `OAM_DATA_DIR` environment variable. You need about 25 GB free while the archive is unpacked.
+
+Then score a set of papers:
+
+```python
+ids = oam.resolve(institution="I5124864", year=(2020, 2024))  # EPFL
+oam.aggregate(ids).round(2)
+```
+
+`oam.resolve` finds the papers. `oam.aggregate` scores the ones that can be compared with similar papers. To find an institution's id, search by name:
+
+```python
+oam.dimension("institutions", search="Lausanne")
+```
+
+## Three examples
+
+These numbers come from the OpenAlex snapshot of 14 October 2026.
+
+### A university, over five years
+
+EPFL, 2020 to 2024. Of the 36,475 works with EPFL's name on them, 22,207 are scored.
+
+```python
+ids = oam.resolve(institution="I5124864", year=(2020, 2024))
+oam.aggregate(ids).round(2)
+```
+
+```
+ publication_year    P  P_weighted      TCS   MCS  MNCS  PP_top10  PP_top1
+             2020 4433      4433.0 200062.0 45.13  1.95     21.52     3.41
+             2021 4498      4498.0 150841.0 33.54  1.80     20.08     3.11
+             2022 4349      4349.0 120403.0 27.69  1.89     20.74     2.90
+             2023 4470      4470.0  85462.0 19.12  1.74     20.25     3.02
+             2024 4457      4457.0  58542.0 13.13  1.83     21.11     3.43
+```
+
+### A researcher
+
+Jennifer Doudna, from her [ORCID](https://orcid.org/0000-0001-9161-999X). Of 755 works, 391 are scored. `by=None` gives one row for the whole set.
+
+```python
+ids = oam.resolve(orcid="0000-0001-9161-999X")
+oam.aggregate(ids, by=None).round(2)
+```
+
+```
+  P  P_weighted     TCS   MCS  MNCS  PP_top10  PP_top1
+391       391.0 91886.0 235.0  5.97     59.34    14.83
+```
+
+### A country
+
+Switzerland, 2020 to 2024. Of 490,707 works, 265,954 are scored.
+
+```python
+ids = oam.resolve(country="CH", year=(2020, 2024))
+oam.aggregate(ids).round(2)
+```
+
+```
+ publication_year     P  P_weighted       TCS   MCS  MNCS  PP_top10  PP_top1
+             2020 52142     52142.0 2108683.0 40.44  1.80     18.78     2.87
+             2021 55231     55231.0 1744205.0 31.58  1.78     18.79     3.02
+             2022 53311     53311.0 1206510.0 22.63  1.71     18.77     2.88
+             2023 52502     52502.0  887357.0 16.90  1.71     19.19     3.08
+             2024 52768     52768.0  605921.0 11.48  1.75     19.27     2.99
+```
+
+You can select papers the same way by author, funder, journal, field or DOI. [Querying](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/querying.md) lists every option.
+
+## Reading the numbers
+
+- **P** is the number of papers that received a score.
+- **MNCS** compares those papers with similar papers worldwide. The world average is 1. A value of 2 means cited twice as much.
+- **PP_top10** is the share of papers among the 10% most cited of their group. For the world, that share is about 10%. **PP_top1** is the same for the top 1%.
+
+[How the scores work](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/metrics.md) explains the other columns, and full and fractional counting.
+
+## How this differs from OpenAlex
+
+OpenAlex already gives most works a citation score, the FWCI. It compares each work with everything OpenAlex indexes, and it counts citations from anything, including preprints, datasets and theses. OAM compares a paper only with peer-reviewed research papers like it, and counts only the citations that come from such papers.
+
+## Which papers are scored
+
+A paper is scored when it passes all seven rules. On the snapshot of 14 October 2026, 62,493,369 of 464,765,485 works pass, which is 13.45%.
+
+1. It is in a core journal or a conference proceedings.
+2. It has a reference list.
+3. It has at least one institutional affiliation.
+4. It is in English.
+5. It has an OpenAlex subfield.
+6. It is not paratext, such as an editorial, erratum or table of contents.
+7. It is not retracted.
+
+Each paper is then compared with papers of the same subfield, publication year and venue type (journal or conference).
+
+These rules are fixed for the data you download. To score a different set of papers, for example to keep papers in every language, edit the rules and rebuild the data. [Scope](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/scope.md) explains each rule, and [Building the data](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/docs/building.md) explains the rebuild.
+
+## Data and licence
+
+The data is built from the public OpenAlex snapshot and released under CC0. `oam.download()` installs the latest version. To keep one snapshot, pass its Zenodo record id, listed under Versions on the [Zenodo page](https://doi.org/10.5281/zenodo.23493154):
+
+```python
+oam.download(record=23493155)    # always the 2026-10-14 snapshot
+```
+
+If you publish results, cite the version you used. Each version has its own DOI, and `oam.status()` shows which snapshot is installed.
+
+OAM is released under the MIT licence. See [LICENSE](https://github.com/epfl-p-data/OpenAlexImpactMetrics/blob/main/LICENSE).

openalex_metrics-0.1.0/docs/building.md

@@ -0,0 +1,146 @@
+# Building the data
+
+Most users download the data with `oam.download()` and never build it. Build it yourself when you want:
+
+- a different scope, for example keeping non-English papers
+- a newer OpenAlex snapshot than the published release
+- to publish a release for others to download
+
+## What you need
+
+- `pip install "openalex-metrics[build]"`. The `build` extra installs PyArrow, which step 1 uses to read the snapshot. Downloading the data does not need it.
+- About 60 GB of free disk space during the build, and about 23 GB once it is finished
+- A few hours. The first step downloads about 67 GB from the public OpenAlex snapshot, so its duration is set by your bandwidth: about 1 hour 40 minutes at 100 Mbit/s
+- No account or API key. The snapshot is public
+
+## Build
+
+```python
+import oam
+
+oam.set_data_dir("/Volumes/data/oam")   # optional: somewhere with enough space
+oam.build()
+oam.status()
+```
+
+`oam.build()` can be interrupted and called again; it continues where it stopped. Everything it prints is also saved under `logs/` in the data directory.
+
+It runs three steps in order:
+
+| Step | What it does | Time |
+|---|---|---|
+| `"store"` | Reads the OpenAlex snapshot, applies the scope, keeps the citations between in-scope papers | Your bandwidth |
+| `"metrics"` | Computes citation counts, bin averages and every paper's scores | About 2 minutes |
+| `"resolve"` | Builds the lookup tables `oam.resolve` uses | About 25 minutes |
+
+To run one step on its own, pass `steps="metrics"`, or a list such as `steps=["metrics", "resolve"]`.
+
+The download uses 8 parallel connections. If your connection is fast, raise it until the speed in the log stops improving; each connection uses about 1 GB of memory:
+
+```python
+oam.build(workers=16)
+```
+
+## Check the result
+
+```python
+oam.check()      # consistency checks, a few seconds
+oam.profile()    # what the data contains: scope funnel, citations, world averages
+```
+
+`oam.profile()` must show a world MNCS of **1.0000**. That confirms each paper was divided by its own bin's average.
+
+## Change the scope
+
+1. Edit `SCOPE` in [`oam/config.py`](../oam/config.py). Each rule is a line of SQL. [Scope](scope.md) documents the defaults and how to write a rule.
+2. Rebuild from scratch:
+
+   ```python
+   oam.build(reset=True)
+   ```
+
+A scope cannot be changed on existing data: the build stored only the papers and citations the old scope kept. `oam.build()` detects an edited scope and stops with a message rather than mixing the two.
+
+## Move to a new snapshot
+
+OpenAlex publishes a new snapshot about once a quarter. To use it:
+
+```python
+oam.build(reset=True, refresh_manifest=True)
+```
+
+`refresh_manifest=True` fetches the list of files of the current snapshot. `reset=True` deletes the data built from the previous one. Data from two snapshots cannot be merged.
+
+## Publish a release
+
+From a finished build, write the archive `oam.download()` installs:
+
+```python
+oam.export("dist")    # dist/oam-<snapshot>.tar, 11.9 GiB for the 2026-10-14 snapshot
+```
+
+Then upload the file to [Zenodo](https://zenodo.org) under the CC0 licence, as a new version of the [existing record](https://doi.org/10.5281/zenodo.23493154). Set the version to the snapshot date. Keep the file name `oam.export` wrote: `oam.download()` finds the file whose name starts with `oam-` and ends with `.tar`, and reads the snapshot date from it.
+
+Nothing in OAM needs to change. `ZENODO_RECORD` in [`oam/config.py`](../oam/config.py) holds the record's all-versions id, `23493154`, which Zenodo resolves to the newest version, so every install of OAM downloads the new snapshot from then on.
+
+The archive records its snapshot date, its scope and a checksum of every file. `oam.download()` checks all three. It refuses to mix two snapshots in one data directory unless called with `replace=True`.
+
+To share a build without Zenodo, send the archive file itself. The recipient installs it with:
+
+```python
+oam.download(source="oam-2026-10-14.tar")
+```
+
+To publish under a record of your own, set `OAM_ZENODO_RECORD` to its all-versions id, or pass `record=` to `oam.download()`.
+
+## Other settings
+
+| Environment variable | Default | Effect |
+|---|---|---|
+| `OAM_DATA_DIR` | `~/oam-data`, or `./data` in a clone | Where the data is stored |
+| `OAM_ZENODO_RECORD` | `23493154`, the latest version | The Zenodo record `oam.download()` fetches. A version's own id pins that snapshot |
+| `OAM_MEMORY_LIMIT` | `20GB` | Memory DuckDB may use in the metrics and resolve steps |
+| `OAM_THREADS` | `8` | Threads DuckDB may use |
+
+Set them in the environment before starting Python.
+
+To try the whole build on a few files first. The result is not usable for scoring:
+
+```python
+oam.set_data_dir("/tmp/oam-trial")
+oam.build(steps="store", limit=3, smallest=True)
+```
+
+To keep the xpack records, a third of OpenAlex that the default build leaves out of the comparison, use `oam.build(include_xpack=True)`. See [Scope](scope.md#what-is-not-configurable).
+
+## Release checklist
+
+The uploads themselves are done by hand.
+
+1. `oam.export("dist")` from a finished build, then install that archive into an empty directory and re-run the examples in the README.
+2. On the [Zenodo record](https://doi.org/10.5281/zenodo.23493154), click New version. Set the version and the collected date to the snapshot date, the publication date to today, and update the snapshot figures in the description.
+3. Upload `dist/oam-<snapshot>.tar`, keeping the file name `oam.export` wrote. The browser upload often stalls on a file this size; the API is more reliable. Create a token with the `deposit:write` and `deposit:actions` scopes, and run these with the draft's id from the address bar:
+
+   ```bash
+   API=https://zenodo.org/api/records/<draft id>/draft/files
+   NAME=oam-<snapshot>.tar
+   curl -f -X POST -H "Authorization: Bearer $ZENODO_TOKEN" -H "Content-Type: application/json" -d "[{\"key\":\"$NAME\"}]" "$API"
+   curl -f -X PUT -H "Authorization: Bearer $ZENODO_TOKEN" -H "Content-Type: application/octet-stream" --upload-file "dist/$NAME" "$API/$NAME/content"
+   curl -f -X POST -H "Authorization: Bearer $ZENODO_TOKEN" "$API/$NAME/commit"
+   ```
+
+   The checksum Zenodo shows must equal `md5 dist/oam-<snapshot>.tar`. Then publish.
+4. Add the snapshot to the README figures. `ZENODO_RECORD` does not change: it already points at the newest version.
+
+A new version of the package is only needed when the code changes. A new snapshot does not need one: `oam.download()` always fetches the latest version on Zenodo.
+
+## Release the package
+
+Publishing happens from GitHub, with no token stored in the repository. The first time, on [PyPI](https://pypi.org), add a pending publisher for the project `openalex-metrics`: owner `epfl-p-data`, repository `OpenAlexImpactMetrics`, workflow `publish.yml`, environment `pypi`.
+
+Then, for each release:
+
+1. Set `version` in [`pyproject.toml`](../pyproject.toml) and in [`CITATION.cff`](../CITATION.cff), and push.
+2. On GitHub, create a release named `v` followed by that version, for example `v0.1.0`.
+
+The [publish workflow](../.github/workflows/publish.yml) builds the package and uploads it to PyPI.

openalex_metrics-0.1.0/docs/metrics.md

@@ -0,0 +1,111 @@
+# How the scores work
+
+OAM compares every paper with papers like it, then summarises those comparisons for a set of papers. This page starts with one paper, then moves to a set.
+
+## Comparable papers: the bin
+
+A paper is compared with the papers that share three things with it:
+
+- its **subfield**, as assigned by OpenAlex (for example Artificial Intelligence)
+- its **publication year**
+- its **venue type**: journal article or conference paper
+
+That group is the paper's **bin**. Citation habits differ a lot between fields and years, so comparing within the bin is what makes a mathematics paper from 2014 comparable with a biology paper from 2022.
+
+## One paper
+
+Take `W2103094658`, a 2014 conference paper in Artificial Intelligence. It has 37 citations. Its bin holds 14,122 papers, which have about 18 citations on average.
+
+```python
+oam.get_metrics(["W2103094658"])
+```
+
+```
+ citations   ncs   percentile   decile   is_top10   is_top1
+        37  2.05         0.94        1       True     False
+```
+
+| Column | Meaning | This paper |
+|---|---|---|
+| `citations` | Citations received so far | 37 |
+| `ncs` | Citations divided by the bin's average. 1 means exactly average | 2.05: twice the average |
+| `percentile` | Share of the bin with as many citations or fewer, from 0 to 1 | 0.94: ahead of about 94% of its bin |
+| `decile` | Rank in tenths of the bin: 1 is the top tenth, 10 the bottom | 1: top tenth |
+| `is_top10` | Among the 10% most cited papers of the bin | yes |
+| `is_top1` | Among the 1% most cited papers of the bin | no |
+
+`ncs` stands for *normalised citation score*. It is the number the set-level MNCS is built from.
+
+## A set of papers
+
+For a set of papers — an institution, a lab, a funder's portfolio — OAM summarises the per-paper scores:
+
+| Column | Meaning |
+|---|---|
+| `P` | Number of papers scored |
+| `MNCS` | Average `ncs`. 1 is the world average |
+| `PP_top10` | Percentage of papers with `is_top10`. About 10 for the world |
+| `PP_top1` | Percentage of papers with `is_top1`. About 1 for the world |
+| `TCS` | Total citations |
+| `MCS` | Average citations per paper, not normalised |
+| `P_weighted` | Sum of the paper weights. Equals `P` unless you use fractional counting (below) |
+
+EPFL in 2014:
+
+```python
+ids = oam.resolve(institution="I5124864", year=2014)
+oam.aggregate(ids)
+```
+
+```
+ publication_year     P  P_weighted     TCS    MCS   MNCS  PP_top10  PP_top1
+             2014  4439      4439.0  264771  59.65  1.962     21.83     3.18
+```
+
+`aggregate` returns one row per publication year by default. Pass `by=None` for a single row covering the whole set.
+
+- MNCS 1.96: on average, an EPFL paper from 2014 was cited 1.96 times as much as a typical paper of its bin.
+- PP(top 10%) 21.8%: more than twice the world share.
+- PP(top 1%) 3.2%: about three times the world share.
+
+The percentile and the decile are per-paper columns. The summary does not average them; PP(top 10%) and PP(top 1%) are how the ranking shows up at the set level.
+
+The world values, measured on the 2014–2023 papers: MNCS 1.00, PP(top 10%) 10.27%, PP(top 1%) 1.01%. The top-10% share is slightly above 10 because papers tied at the threshold are all counted in.
+
+## Full and fractional counting
+
+By default every paper counts once, whatever the number of institutions on it. This is **full counting**, and it is what the EPFL numbers above use.
+
+With **fractional counting**, a paper counts as `1 / number of institutions`. A paper written with nine other institutions counts as a tenth of a paper for EPFL. Use it when you compare institutions and do not want a shared paper to be counted in full by everyone who shares it.
+
+```python
+oam.aggregate(ids, counting="full")   # the default
+oam.aggregate(ids, counting="frac")
+```
+
+EPFL in 2014, fractional counting:
+
+```
+ publication_year     P  P_weighted     TCS    MCS   MNCS  PP_top10  PP_top1
+             2014  4439      2118.3  108728  51.33  1.738     19.15     2.72
+```
+
+`P` is still 4,439 papers. `P_weighted` is the sum of the fractions, 2,118. Every other column is a weighted average, so papers shared with many institutions weigh less. Here MNCS falls from 1.96 to 1.74, because EPFL's papers with five or more institutions are also its most cited: their average `ncs` is 2.67, against 1.75 for the others.
+
+## Which papers are scored
+
+EPFL's name is on 6,223 works from 2014, and 4,439 are scored. Two things remove the others.
+
+**Scope.** Only papers inside the scope get a score: by default, English-language articles in a core journal or a conference proceedings, with an institutional affiliation, a subfield and a reference list, and not retracted or front matter. 4,511 of the 6,223 pass. The rest are preprints, datasets, book chapters and similar. Scope also decides which citations count: a citation is only counted when the citing paper is itself in scope. See [Scope](scope.md) for the rules, and [Querying](querying.md#which-papers-are-scored) to see which rule removed which paper.
+
+**Small bins.** A bin with fewer than 500 papers has an unstable average. Its papers still get an `ncs`, with `bin_is_reliable` set to false, but `aggregate` leaves them out. 72 of the 4,511 are in such bins. To keep them, pass `reliable_only=False`.
+
+## Citation window
+
+By default a paper's citations are everything it has received up to the snapshot. A paper from 2014 has had twelve years to collect citations and a paper from 2023 only three, although both are compared within their own year, so the scores stay comparable.
+
+To count only the citations received within three years of publication, pass `window=3`. This is the usual choice when you compare recent years with older ones.
+
+```python
+oam.aggregate(ids, window=3)
+```