ahl-npm 1.0.0__tar.gz

ahl_npm-1.0.0/.envrc

@@ -0,0 +1,3 @@
+#!/bin/bash
+# MAKE EDITS TO .ENV INSTEAD
+[ -f .env ] && source .env

ahl_npm-1.0.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+# Publishes the package to PyPI when a GitHub release is published, building it from the release's tag, which must
+# match the version (`v` + `__version__` in ahl_npm/__init__.py). Uses PyPI trusted publishing from the `pypi`
+# environment, so no API token is needed. Failed runs can be re-run from the Actions tab, but PyPI never accepts the
+# same version twice.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ahl-npm/
+    permissions:
+      id-token: write # trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Check the tag is the version
+        run: |
+          VERSION=$(sed -nE 's/^__version__ = "([^"]+)".*/\1/p' ahl_npm/__init__.py)
+          if [ "$GITHUB_REF_NAME" != "v$VERSION" ]; then
+            echo "::error::The tag $GITHUB_REF_NAME is not v + __version__ ($VERSION)."
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build the package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

ahl_npm-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+# Runs the tests under each supported Python version, and with the oldest dependency versions allowed (the tox envs
+# in pyproject.toml). Dependencies are resolved from PyPI each time, so the weekly run catches any new numpy or polars
+# release that breaks ahl-npm.
+on:
+  pull_request:
+  push:
+    branches: [dev, main]
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tox:
+    name: tox -e ${{ matrix.env }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        env: [py310, py311, py312, py313, py314, py315, lowest]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install tox
+        run: uv tool install tox --with tox-uv
+
+      - name: Run the tests
+        run: tox run -e ${{ matrix.env }}

ahl_npm-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Builds
+build/
+dist/
+*.egg-info/
+
+# Environments and tools
+.venv/
+.tox/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+
+# Local settings
+.env
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store

ahl_npm-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
+    rev: v0.10.0
+    hooks:
+      - id: pre-commit-update
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-toml
+      - id: check-yaml
+      - id: no-commit-to-branch
+        args: ["-b", dev, "-b", main]
+        pass_filenames: false
+  - repo: https://github.com/nestauk/pre-commit-hooks
+    rev: v1.2.0
+    hooks:
+      - id: nbstripout-preserve-timestamp
+      - id: jupytext-enforce-pairing
+      - id: jupytext-smart-sync
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.3
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+  - repo: https://github.com/prettier/pre-commit
+    rev: v2.1.2
+    hooks:
+      - id: prettier

ahl_npm-1.0.0/LICENSE

@@ -0,0 +1,10 @@
+
+The MIT License (MIT)
+=====================
+Copyright (c) 2026, Nesta
+
+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.

ahl_npm-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: ahl-npm
+Version: 1.0.0
+Summary: Functions and configuration for calculating Nutrient Profiling Model (NPM) scores
+Project-URL: repository, https://github.com/nestauk/ahl_npm
+Project-URL: issues, https://github.com/nestauk/ahl_npm/issues
+Author-email: Harry Wilde <harry.wilde@nesta.org.uk>
+Maintainer-email: Harry Wilde <harry.wilde@nesta.org.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: HFSS,NPM,numpy,nutrient profiling model,nutrition,polars
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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: Programming Language :: Python :: 3.15
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.25
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# AHL NPM Scoring
+
+Two definitions of the UK's Nutrient Profiling Model, [NPM 2004/05](https://www.gov.uk/government/publications/the-nutrient-profiling-model) and [NPM 2018](https://www.gov.uk/government/publications/nutrient-profiling-model-2018/nutrient-profiling-model-2018-technical-guidance), scored on `numpy` arrays or `polars` frames.
+
+## Installing
+
+The package is installable from [PyPI](https://pypi.org/project/ahl-npm/) on Python 3.10+ with `pip`, `uv`, etc.:
+
+```bash
+uv add ahl-npm
+```
+
+## Usage
+
+```python
+import ahl_npm as npm
+
+# numpy: numbers or arrays per 100g, which broadcast together (e.g. one panel against multiple possible free sugars values)
+scored = npm.score(
+    scheme=2018, energy_kj=1500, satfat=4.5, free_sugars=[2.0, 6.5], salt=1.25, protein=10, fibre=3, fvns_pct=0
+)
+scored["npm"]  # array([11., 15.]), with each component's points, the A and C points and whether protein counts
+
+# polars: `columns` maps each input to a column or an expression; without it, the frame's columns named as inputs
+scored = npm.score_frame(
+    frame=df,
+    scheme=2004,
+    columns={
+        "energy_kcal": "kcal_per_100g",
+        "satfat": "satfat_per_100g",
+        "sugars": "sugar_per_100g",
+        "sodium": "sodium_per_100g",
+        "protein": "protein_per_100g",
+        "fibre": "fibre_per_100g",
+        "fvn_pct": pl.col("fvn_share") * 100,
+    },
+)  # adds energy_points_2004, ..., a_points_2004, c_points_2004, protein_counted_2004, npm_2004, cnpm_2004
+```
+
+`outputs` picks which columns to add and, when passed as a mapping, renames them (between `prefix` and `suffix`), e.g. `outputs={"npm": "npm_score", "cnpm": "cnpm_score"}` only adds `npm_score_2004` and `cnpm_score_2004`. Inputs a scheme doesn't use are ignored, so the same mapping can be used for both schemes.
+
+`score_expr` returns the same scoring as a struct expression, and `band` and `band_expr` give the points for a single component, e.g. `npm.band(2018, "free_sugars", values)`.
+
+### Inputs
+
+All inputs are densities (g/100g) as sold. Where a component can be scored from more than one input, each row uses the first one available: the quantity the scheme scores, then a converted stand-in, then the component's points if given.
+
+| Input                      | Unit | Scored by                                                                             |
+| -------------------------- | ---- | ------------------------------------------------------------------------------------- |
+| `energy_kj`, `energy_kcal` | kJ   | both, using kJ if given, else kcal x 4.184                                            |
+| `satfat`                   | g    | both                                                                                  |
+| `sugars`                   | g    | NPM 2004/05 (total sugars)                                                            |
+| `free_sugars`              | g    | NPM 2018                                                                              |
+| `sodium`, `salt`           | g    | NPM 2004/05 scores sodium (else salt / 2.5), NPM 2018 scores salt (else sodium x 2.5) |
+| `protein`                  | g    | both                                                                                  |
+| `fibre`                    | g    | both (AOAC method)                                                                    |
+| `fvn_pct`                  | %    | NPM 2004/05 (fruit, vegetables and nuts)                                              |
+| `fvns_pct`                 | %    | NPM 2018 (fruit, vegetables, nuts and seeds)                                          |
+| `<component>_points`       |      | both, for points already scored, as an alternative to the densities above             |
+
+Points inputs are named the same as the outputs, so a scoring's points can be passed straight back in, and are checked against the points the component can score under the scheme. NPM 2018 includes seeds, so it only uses `fvns_pct` or `fvns_points`: if you only have the NPM 2004/05 share, pass it as `fvns_pct` too. NPM 2018 also needs free sugars. Scoring total sugars as free sugars isn't supported, as it overestimates NPM 2018 scores, but can be done by passing total sugars as `free_sugars`.
+
+Salt is sodium x 2.5, as UK labelling law defines it ([Regulation (EU) No 1169/2011, Annex I](https://www.legislation.gov.uk/eur/2011/1169/annex/I), as retained in UK law).
+
+### Outputs
+
+Each component's points (`<component>_points`), `a_points`, `c_points`, `protein_counted`, `npm` and `cnpm` (70 - 2 x `npm`). The numpy functions return floats with NaN where unknown (or integers with `strict=True`, which raises on missing inputs), and the polars functions return integers (a boolean for `protein_counted`) with nulls where unknown. Protein stops counting from 11 A points, unless fruit, vegetables and nuts score 5 points.
+
+### Checks and warnings
+
+The most likely mistake is an input in the wrong units, so each frame scoring logs (at INFO, to the `ahl_npm` logger) which column or expression each component reads, in what units, and with any conversion. `describe_inputs` gives the same description for any inputs:
+
+```text
+NPM 2004 reads, per 100 g:
+  energy: energy_kcal <- "kcal_per_100g", kcal x 4.184 to kJ
+  sodium: sodium <- "sodium_per_100g", g; else salt <- "salt_per_100g", g / 2.5 to sodium
+  fvn: fvn_pct <- [(col("fvn_share")) * (dyn int: 100)], %
+  ...
+```
+
+- `ImpossibleInputWarning` warns of implausible density values, i.e. below 0, or above 100g, 100% or the energy of pure fat (3,700 kJ or 900 kcal), which usually means an input is in the wrong units (e.g. sodium in mg read as g).
+- `MissingInputWarning` summarises missing inputs (NaN, or null in polars). A missing input scores NaN points rather than the maximum, so any score it feeds into is missing too.
+- `warn=False` turns both warnings off. A frame only warns once, for the first batch of rows with problems.
+
+### Other functions
+
+- `to_cnpm` and `from_cnpm` convert between NPM and cNPM (70 - 2 x the score, s.t. higher is healthier) for numbers, arrays, and polars expressions or series. `clip=True` clips cNPM to between 0 and 100, and `change=True` converts changes in scores (without the offset).
+- `less_healthy(scheme, npm, drink)` gives whether each product is less healthy, i.e. a food scoring 4 or more, or a drink scoring 1 or more. `drink` must be booleans with none missing (in polars, a null gives a null). Whether a product is in scope of HFSS legislation is a separate question.
+- `score_range(scheme, low, high, **fixed)` gives the lowest and highest scores for inputs anywhere between their `low` and `high` values. The score never decreases as an A input increases or a C input decreases, so only two scorings are needed, however many inputs are uncertain.
+
+## Development Setup
+
+This project uses [`uv`](https://docs.astral.sh/uv/) and `direnv`. To set up a development environment, run:
+
+```bash
+direnv allow
+uv sync
+uv run pre-commit install --install-hooks
+uv run pytest
+```
+
+`uv run tox` runs the tests under each Python version from 3.10 to 3.15, and (`lowest`) with the oldest numpy, polars and PyYAML versions allowed. CI runs these on every pull request and push to `dev` or `main`, and weekly.

ahl_npm-1.0.0/README.md

@@ -0,0 +1,102 @@
+# AHL NPM Scoring
+
+Two definitions of the UK's Nutrient Profiling Model, [NPM 2004/05](https://www.gov.uk/government/publications/the-nutrient-profiling-model) and [NPM 2018](https://www.gov.uk/government/publications/nutrient-profiling-model-2018/nutrient-profiling-model-2018-technical-guidance), scored on `numpy` arrays or `polars` frames.
+
+## Installing
+
+The package is installable from [PyPI](https://pypi.org/project/ahl-npm/) on Python 3.10+ with `pip`, `uv`, etc.:
+
+```bash
+uv add ahl-npm
+```
+
+## Usage
+
+```python
+import ahl_npm as npm
+
+# numpy: numbers or arrays per 100g, which broadcast together (e.g. one panel against multiple possible free sugars values)
+scored = npm.score(
+    scheme=2018, energy_kj=1500, satfat=4.5, free_sugars=[2.0, 6.5], salt=1.25, protein=10, fibre=3, fvns_pct=0
+)
+scored["npm"]  # array([11., 15.]), with each component's points, the A and C points and whether protein counts
+
+# polars: `columns` maps each input to a column or an expression; without it, the frame's columns named as inputs
+scored = npm.score_frame(
+    frame=df,
+    scheme=2004,
+    columns={
+        "energy_kcal": "kcal_per_100g",
+        "satfat": "satfat_per_100g",
+        "sugars": "sugar_per_100g",
+        "sodium": "sodium_per_100g",
+        "protein": "protein_per_100g",
+        "fibre": "fibre_per_100g",
+        "fvn_pct": pl.col("fvn_share") * 100,
+    },
+)  # adds energy_points_2004, ..., a_points_2004, c_points_2004, protein_counted_2004, npm_2004, cnpm_2004
+```
+
+`outputs` picks which columns to add and, when passed as a mapping, renames them (between `prefix` and `suffix`), e.g. `outputs={"npm": "npm_score", "cnpm": "cnpm_score"}` only adds `npm_score_2004` and `cnpm_score_2004`. Inputs a scheme doesn't use are ignored, so the same mapping can be used for both schemes.
+
+`score_expr` returns the same scoring as a struct expression, and `band` and `band_expr` give the points for a single component, e.g. `npm.band(2018, "free_sugars", values)`.
+
+### Inputs
+
+All inputs are densities (g/100g) as sold. Where a component can be scored from more than one input, each row uses the first one available: the quantity the scheme scores, then a converted stand-in, then the component's points if given.
+
+| Input                      | Unit | Scored by                                                                             |
+| -------------------------- | ---- | ------------------------------------------------------------------------------------- |
+| `energy_kj`, `energy_kcal` | kJ   | both, using kJ if given, else kcal x 4.184                                            |
+| `satfat`                   | g    | both                                                                                  |
+| `sugars`                   | g    | NPM 2004/05 (total sugars)                                                            |
+| `free_sugars`              | g    | NPM 2018                                                                              |
+| `sodium`, `salt`           | g    | NPM 2004/05 scores sodium (else salt / 2.5), NPM 2018 scores salt (else sodium x 2.5) |
+| `protein`                  | g    | both                                                                                  |
+| `fibre`                    | g    | both (AOAC method)                                                                    |
+| `fvn_pct`                  | %    | NPM 2004/05 (fruit, vegetables and nuts)                                              |
+| `fvns_pct`                 | %    | NPM 2018 (fruit, vegetables, nuts and seeds)                                          |
+| `<component>_points`       |      | both, for points already scored, as an alternative to the densities above             |
+
+Points inputs are named the same as the outputs, so a scoring's points can be passed straight back in, and are checked against the points the component can score under the scheme. NPM 2018 includes seeds, so it only uses `fvns_pct` or `fvns_points`: if you only have the NPM 2004/05 share, pass it as `fvns_pct` too. NPM 2018 also needs free sugars. Scoring total sugars as free sugars isn't supported, as it overestimates NPM 2018 scores, but can be done by passing total sugars as `free_sugars`.
+
+Salt is sodium x 2.5, as UK labelling law defines it ([Regulation (EU) No 1169/2011, Annex I](https://www.legislation.gov.uk/eur/2011/1169/annex/I), as retained in UK law).
+
+### Outputs
+
+Each component's points (`<component>_points`), `a_points`, `c_points`, `protein_counted`, `npm` and `cnpm` (70 - 2 x `npm`). The numpy functions return floats with NaN where unknown (or integers with `strict=True`, which raises on missing inputs), and the polars functions return integers (a boolean for `protein_counted`) with nulls where unknown. Protein stops counting from 11 A points, unless fruit, vegetables and nuts score 5 points.
+
+### Checks and warnings
+
+The most likely mistake is an input in the wrong units, so each frame scoring logs (at INFO, to the `ahl_npm` logger) which column or expression each component reads, in what units, and with any conversion. `describe_inputs` gives the same description for any inputs:
+
+```text
+NPM 2004 reads, per 100 g:
+  energy: energy_kcal <- "kcal_per_100g", kcal x 4.184 to kJ
+  sodium: sodium <- "sodium_per_100g", g; else salt <- "salt_per_100g", g / 2.5 to sodium
+  fvn: fvn_pct <- [(col("fvn_share")) * (dyn int: 100)], %
+  ...
+```
+
+- `ImpossibleInputWarning` warns of implausible density values, i.e. below 0, or above 100g, 100% or the energy of pure fat (3,700 kJ or 900 kcal), which usually means an input is in the wrong units (e.g. sodium in mg read as g).
+- `MissingInputWarning` summarises missing inputs (NaN, or null in polars). A missing input scores NaN points rather than the maximum, so any score it feeds into is missing too.
+- `warn=False` turns both warnings off. A frame only warns once, for the first batch of rows with problems.
+
+### Other functions
+
+- `to_cnpm` and `from_cnpm` convert between NPM and cNPM (70 - 2 x the score, s.t. higher is healthier) for numbers, arrays, and polars expressions or series. `clip=True` clips cNPM to between 0 and 100, and `change=True` converts changes in scores (without the offset).
+- `less_healthy(scheme, npm, drink)` gives whether each product is less healthy, i.e. a food scoring 4 or more, or a drink scoring 1 or more. `drink` must be booleans with none missing (in polars, a null gives a null). Whether a product is in scope of HFSS legislation is a separate question.
+- `score_range(scheme, low, high, **fixed)` gives the lowest and highest scores for inputs anywhere between their `low` and `high` values. The score never decreases as an A input increases or a C input decreases, so only two scorings are needed, however many inputs are uncertain.
+
+## Development Setup
+
+This project uses [`uv`](https://docs.astral.sh/uv/) and `direnv`. To set up a development environment, run:
+
+```bash
+direnv allow
+uv sync
+uv run pre-commit install --install-hooks
+uv run pytest
+```
+
+`uv run tox` runs the tests under each Python version from 3.10 to 3.15, and (`lowest`) with the oldest numpy, polars and PyYAML versions allowed. CI runs these on every pull request and push to `dev` or `main`, and weekly.

ahl_npm-1.0.0/ahl_npm/__init__.py

@@ -0,0 +1,43 @@
+"""ahl_npm: the UK's Nutrient Profiling Model (NPM 2004/05 and NPM 2018), scored on numpy arrays or polars frames."""
+
+__version__ = "1.0.0"
+
+from ahl_npm.constants import KJ_PER_KCAL, SALT_PER_SODIUM
+from ahl_npm.frames import band_expr, score_expr, score_frame
+from ahl_npm.schemes import COMPONENTS, SCHEMES, Component, Scheme, get_scheme, load_scheme
+from ahl_npm.scoring import (
+    INPUTS,
+    ImpossibleInputWarning,
+    MissingInputWarning,
+    band,
+    describe_inputs,
+    output_names,
+    score,
+    score_range,
+)
+from ahl_npm.transforms import from_cnpm, less_healthy, to_cnpm
+
+__all__ = [
+    "COMPONENTS",
+    "INPUTS",
+    "ImpossibleInputWarning",
+    "KJ_PER_KCAL",
+    "SALT_PER_SODIUM",
+    "SCHEMES",
+    "Component",
+    "MissingInputWarning",
+    "Scheme",
+    "band",
+    "band_expr",
+    "describe_inputs",
+    "from_cnpm",
+    "get_scheme",
+    "less_healthy",
+    "load_scheme",
+    "output_names",
+    "score",
+    "score_expr",
+    "score_frame",
+    "score_range",
+    "to_cnpm",
+]

ahl_npm-1.0.0/ahl_npm/constants.py

@@ -0,0 +1,19 @@
+"""Constants used in NPM scoring that are not part of a scheme's thresholds."""
+
+# Kilojoules per kilocalorie, used to convert energy given in kcal, as both schemes score energy in kJ.
+KJ_PER_KCAL: float = 4.184
+
+# Grams of salt per gram of sodium, as UK labelling law defines salt (salt = sodium x 2.5, Regulation (EU) No 1169/2011,
+# Annex I, as retained in UK law).
+SALT_PER_SODIUM: float = 2.5
+
+# cNPM is 70 - 2 x the NPM score, s.t. higher is healthier. It runs from -10 to 100 under NPM 2004/05, and up to 110
+# under NPM 2018. CNPM_BOUNDS are the limits used when clipping.
+CNPM_OFFSET: float = 70
+CNPM_SCALE: float = -2
+CNPM_BOUNDS: tuple[float, float] = (0, 100)
+
+# A value scores a threshold's point only above the threshold by more than BAND_ATOL + BAND_RTOL x the threshold,
+# this prevents floating point error from causing a value to be scored at a different threshold.
+BAND_ATOL: float = 1e-4
+BAND_RTOL: float = 1e-5

ahl_npm-1.0.0/ahl_npm/frames.py

@@ -0,0 +1,185 @@
+"""NPM scores on polars frames and expressions.
+
+The scoring reuses the numpy implementation `ahl_npm.scoring.score`, s.t. scoring a dataframe is consistent with
+scoring an array of its rows, and scoring an expression is consistent with scoring a series of its values.
+"""
+
+import logging
+import threading
+import warnings
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from typing import TypeVar
+
+import polars as pl
+
+from ahl_npm.schemes import Scheme, get_scheme
+from ahl_npm.scoring import INPUTS, _check_inputs, _inputs_used, _score, band, describe_inputs, output_names
+
+logger = logging.getLogger("ahl_npm")
+
+FrameT = TypeVar("FrameT", pl.DataFrame, pl.LazyFrame)
+
+# Temporary column holding a frame's scoring struct before its fields are split into columns.
+_SCORING = "__ahl_npm_scoring"
+
+# Recently logged input descriptions, s.t. each is only logged once however often a scoring is rebuilt (e.g. in a
+# sweep or a dashboard). Only the latest `_LOGGED_MOST` are kept, so memory use stays bounded when inputs vary.
+_LOGGED: dict[str, None] = {}
+_LOGGED_MOST = 256
+
+
+def _log_once(description: str) -> None:
+    if description in _LOGGED:
+        return
+    _LOGGED[description] = None
+    if len(_LOGGED) > _LOGGED_MOST:
+        del _LOGGED[next(iter(_LOGGED))]
+    logger.info(description)
+
+
+def _as_expr(column: str | pl.Expr) -> pl.Expr:
+    return pl.col(column) if isinstance(column, str) else column
+
+
+def _output_dtypes(scheme: str | int | Scheme) -> dict[str, pl.DataType]:
+    """Return the polars dtype of each of `output_names`: integers for points and scores, and a boolean flag."""
+    return {name: pl.Boolean if name == "protein_counted" else pl.Int64 for name in output_names(scheme)}
+
+
+def score_expr(scheme: str | int | Scheme, columns: Mapping[str, str | pl.Expr], *, warn: bool = True) -> pl.Expr:
+    """Return an expression for each row's NPM scoring, as a struct with a field per `output_names`, null if unknown.
+
+    Inputs the scheme doesn't use are ignored, so the same mapping can be used for both schemes. The expression only
+    warns once, with the counts from the first batch of rows with missing or implausible values, which is the whole
+    frame unless it is scored in batches (e.g. by a streaming collect).
+
+    Args:
+        scheme (str | int | Scheme): 2004, 2018 or a `Scheme`.
+        columns (Mapping[str, str | pl.Expr]): A column name or expression for each input, by `score`'s names.
+        warn (bool): Whether to warn, with a summary, of missing inputs and implausible density values.
+
+    Returns:
+        pl.Expr: The scoring as a struct, e.g. to `.struct.unnest()` or `.struct.field()`.
+
+    Raises:
+        TypeError: If an input is not one of `INPUTS`.
+        ValueError: If a component has none of the inputs it can be scored from.
+    """
+    scheme = get_scheme(scheme)
+    _check_inputs(scheme, columns)
+    used = _inputs_used(scheme)
+    names = [name for name in INPUTS if name in columns and name in used]
+    _log_once(describe_inputs(scheme, {name: columns[name] for name in names}))
+    dtypes = _output_dtypes(scheme)
+    warned = not warn
+    claim = threading.Lock()
+
+    def score_batch(rows: pl.Series) -> pl.Series:
+        """Score a batch of rows (a struct of the inputs) with numpy."""
+        nonlocal warned
+        inputs = rows.struct.unnest()
+        scored, problems = _score(scheme, {name: inputs[name].to_numpy() for name in names}, check=not warned)
+        if problems:
+            with claim:  # A streaming collect scores batches concurrently, so only the first batch with problems warns
+                first, warned = not warned, True
+            if first:
+                for category, message in problems:
+                    warnings.warn(message, category, stacklevel=2)
+        fields = [pl.Series(name, values, nan_to_null=True).cast(dtypes[name]) for name, values in scored.items()]
+        return pl.DataFrame(fields).to_struct(rows.name)
+
+    struct = pl.struct([_as_expr(columns[name]).cast(pl.Float64).alias(name) for name in names])
+    return struct.map_batches(score_batch, return_dtype=pl.Struct(dtypes), is_elementwise=True)
+
+
+def score_frame(
+    frame: FrameT,
+    scheme: str | int | Scheme,
+    columns: Mapping[str, str | pl.Expr] | None = None,
+    *,
+    prefix: str = "",
+    suffix: str | None = None,
+    outputs: Sequence[str] | Mapping[str, str] | None = None,
+    warn: bool = True,
+) -> FrameT:
+    """Return `frame` with each row's NPM scoring under `scheme` added as columns.
+
+    The columns added are `outputs` (by default all of `output_names`, i.e. each component's points, `a_points`,
+    `c_points`, `protein_counted`, `npm` and `cnpm`), each named between `prefix` and `suffix`, e.g.
+    `energy_points_2018`, ..., `cnpm_2018` by default.
+
+    Args:
+        frame (FrameT): The rows to score, as a `pl.DataFrame` or `pl.LazyFrame`.
+        scheme (str | int | Scheme): 2004, 2018 or a `Scheme`.
+        columns (Mapping[str, str | pl.Expr] | None): A column name or expression for each input, by `score`'s names.
+            If None, the frame's columns named as inputs are used.
+        prefix (str): Prefix for each new column's name.
+        suffix (str | None): Suffix for each new column's name, `_<scheme>` if None.
+        outputs (Sequence[str] | Mapping[str, str] | None): Which of `output_names` to add: a single name, a sequence
+            of names, or a mapping to new names (placed between `prefix` and `suffix`). None adds all of them.
+        warn (bool): Whether to warn, with a summary, of missing inputs and of implausible density values.
+
+    Returns:
+        FrameT: `frame` with the new columns, of the same type.
+
+    Raises:
+        ValueError: If an output is not one of `output_names`, two outputs would have the same name, a new column
+            would replace an input column, or the frame already has the temporary column the scoring uses.
+    """
+    scheme = get_scheme(scheme)
+    suffix = f"_{scheme.name}" if suffix is None else suffix
+    present = frame.collect_schema().names()
+    if _SCORING in present:
+        raise ValueError(f"The frame already has a column called {_SCORING}, which the scoring uses internally")
+    if columns is None:
+        columns = {name: name for name in INPUTS if name in present}
+    if isinstance(outputs, str):
+        outputs = (outputs,)
+    known = output_names(scheme)
+    chosen = (
+        dict.fromkeys(known)
+        if outputs is None
+        else dict(outputs)
+        if isinstance(outputs, Mapping)
+        else dict.fromkeys(outputs)
+    )
+    unknown = sorted(set(chosen) - set(known))
+    if unknown:
+        raise ValueError(f"No NPM {scheme.name} outputs {unknown}: the outputs are {known}")
+    named = {output: f"{prefix}{name or output}{suffix}" for output, name in chosen.items()}
+    shared = sorted(name for name, count in Counter(named.values()).items() if count > 1)
+    if shared:
+        raise ValueError(f"Outputs would share the names {shared}")
+
+    used = {column for value in columns.values() for column in _as_expr(value).meta.root_names()}
+    clashes = sorted(used & set(named.values()))
+    if clashes:
+        raise ValueError(f"The scoring would replace input columns {clashes}: give a prefix, suffix or other outputs")
+
+    scoring = pl.col(_SCORING)
+    fields = [scoring.struct.field(output).alias(name) for output, name in named.items()]
+    return (
+        frame.with_columns(score_expr(scheme, columns, warn=warn).alias(_SCORING)).with_columns(fields).drop(_SCORING)
+    )
+
+
+def band_expr(scheme: str | int | Scheme, component: str, values: str | pl.Expr) -> pl.Expr:
+    """Return an expression for the points one component gives each value per 100g, null where a value is missing.
+
+    Args:
+        scheme (str | int | Scheme): 2004, 2018 or a `Scheme`.
+        component (str): The component, e.g. "free_sugars", with values in its main input's units (e.g. kJ for energy).
+        values (str | pl.Expr): The values per 100g, as a column name or an expression.
+
+    Returns:
+        pl.Expr: The points as integers.
+    """
+    scheme = get_scheme(scheme)
+    scheme.component(component)  # Raise here, rather than at collect, if the scheme doesn't have the component
+
+    def band_batch(batch: pl.Series) -> pl.Series:
+        """Band a batch of values with numpy."""
+        return pl.Series(batch.name, band(scheme, component, batch.to_numpy()), nan_to_null=True).cast(pl.Int64)
+
+    return _as_expr(values).cast(pl.Float64).map_batches(band_batch, return_dtype=pl.Int64, is_elementwise=True)