Methods

Every day the app names how yesterday departed from your own norms, in your own units, with the arithmetic printed beside each line. There is no daily score, no weighting, and no number that combines metrics — the rule below is the entire decision, and it is the same rule the app prints on its own “how this works” disclosure. Changing any constant on this page is an amendment to the decision record behind it, not a tuning pass.

The same 40 minutes of missing sleep is news for a metronome sleeper and weather for a shift worker. That is not a rough edge in the rule; it is the whole point of a scale built out of your own days, and it is the answer a product with one fixed threshold — or one proprietary weighting — cannot give you.

The norm

Your norm for a metric is the mean of the trailing 28 days ending the day before the day being judged — four weeks, the same window the weekly letter uses, so two surfaces of one product cannot disagree about what normal means.

• Observed days only, never interpolated. A day with no reading is dropped from the mean, not filled in and not counted as a zero. A day your phone recorded no steps at all is a real zero and does count; a day it recorded nothing because it was off is unknown, and unknown never becomes a number.
• At least 8 observed days in those 28, or there is no norm and the metric is not checked. The surface says so and names the floor rather than going quiet.
• A rhythm gate of 8 active days for the count-shaped metrics — the ones that accrue events over a day. Something that happens twice a month has no weekly rhythm and therefore cannot have a daily one.

The scale — your own swing

The bar cannot be a percentage: 5% is nothing for steps and enormous for a resting heart rate. So the scale is your own typical day-to-day distance from your own norm, over those same observed days:

swing = mean( |value on day i − norm| )

That is the mean absolute deviation about the mean, and two properties earned it the job. Both are worth stating, because one of them is a cost.

• It does not collapse on ties. The median absolute deviation — the usual robust choice — is exactly zero whenever more than half the window ties, which every integer count and every 1–5 rating arranges routinely; the interquartile range is zero on the same shape. A zero scale would make every departure infinite. This one is zero only when every observed day equals your norm exactly, and a metric with genuinely no daily scale is one we then decline to speak about.
• It is inflated by one wild day, on purpose. A single extreme day raises your swing, and a raised swing raises the bar for a fortnight. That makes the surface quieter after unusual days rather than louder — the opposite of what a standard deviation would do. For a surface whose failure mode is chattiness, an estimator that errs quiet is the one you want, and we would rather say that out loud than have you find it.

Both numbers — the norm and the swing — come from the 28 days before the day being judged, so that day is genuinely out of sample.

The bar, and the cap of 3

A metric earns a mention when the day lands at least 2.0× your swing away from your norm, it has a norm, the day has a known reading, and the difference is still non-zero once rounded to the precision it prints at. Absence is never a deviation.

At most 3 mentions print. They are ordered by how many swings out they are — a number that is never displayed, because a displayed ranking number across metrics is the score this product refuses to ship. Metrics that measure one construct (a resting heart rate from two devices, sleep summed from two apps) collapse to a single line before the cut; two instruments that disagree about the direction suppress each other entirely, because that is a data-quality fact and not a deviation.

The multiple is editorial, not inferential, and we will say where it came from: under the usual bell-curve assumption this swing runs about 0.8 of a standard deviation, so the bar sits near 1.6 of one — roughly a one-in-nine chance per metric per day, which leaves a typical reader with zero or one line most days. Lower, and something is “off” nearly every day, which is a score with extra steps. Higher, and the surface speaks once a week and stops being worth opening. It is revisited on a published cadence, and revising it means amending the record, not editing a config.

A quiet day is an answer and prints as one, with its denominator: “nothing unusual — 7 metrics were within your 4-week norms”. A surface that says nothing unusual while silently checking two metrics is lying, and printing the count is what makes the sentence checkable.

The day being judged

One complete day, on your own calendar — the timezone your account declares. The day in progress is never judged, for any metric: a partial day would report “steps 6,000 below your norm” at nine every morning. So the newest day the verdict can speak about is the one that has just ended, and the block prints which day it means, every time it renders.

Sleep is filed under the day you woke up, which is the convention the rest of the app uses. A night therefore reaches the verdict once that waking day is over — a newspaper is today’s paper about yesterday.

What is not here: no p-value, no correction

Elsewhere on this platform, findings that make a statistical claim carry a q-value and a multiple-comparison correction. These sentences carry neither, and that is a decision rather than an oversight. “You slept 6h05, 40 minutes under your 4-week norm of 6h45” is a description of four stored numbers: it is true whatever is or is not going on underneath, there is no hypothesis in it, and so there is nothing to reject and no p to correct.

What multiplicity buys instead is the editorial discipline above — a fixed bar, a hard cap, a deterministic order — so that adding metrics to the roster can never add claims to a day. The moment any copy here calls a day abnormal rather than saying what it was, that is a hypothesis and it needs the full apparatus before it ships.

What is checked — 9 things

The roster is curated and short, with the reason attached to each member. A metric being available is not a reason to check it daily.

• Sleep /health/sleep/asleep_minutes — The line the whole surface is for. Additive across sources, so it enters split by source and collapses to one line before it prints.
• Resting heart rate /health/cardio/resting_heart_rate · /health/cardio/nightly_resting_heart_rate — Two names for one construct, joined in the manifests and printed once. An elevated morning resting heart rate is the one daily number with a real-world action behind it.
• Heart-rate variability /health/cardio/hrv_rmssd — The input the incumbents bury inside a recovery score. Shown raw, against your own swing.
• Respiratory rate /health/cardio/respiratory_rate — A nightly level whose day-scale departure is a classic early illness signal, and one that means nothing without a personal baseline.
• Steps /health/activity/steps — A complete-day total with a strong personal rhythm; your swing absorbs the weekday shape a fixed goal cannot.
• Exercise minutes /health/activity/exercise_minutes — A covered day with no training is a real zero, so a training gap is a value like any other. It clears the bar only when your norm is at least twice your swing — news for someone who trains almost every day, and not for someone whose week already contains rest days.
• Screen time /screen/time/total — The drift you suspect and cannot see, and a complete-day total.
• Mood /journal/mood/level — A 1–5 rating, which is exactly the tie-heavy shape that a median-based scale collapses on — see the swing below. A day well off your own mood norm is the single most useful thing this surface can name.
• Mean glucose /health/glucose/mean — For a CGM reader, a complete-day level whose daily departure is directly actionable.

What is deliberately not checked

This list is as much the design as the roster is, and the first entry is permanent.

• Every vendor composite. Recovery score, readiness, sleep score, day strain. Permanent, not a v1 deferral: naming a black box's deviation amplifies the black box, and its inputs are on the roster above already. We still display a vendor's own score where they publish one — rendering a number its publisher stands behind is a different act from minting one.
• Weight, VO₂max and body fat. Clock speed. A day's departure in weight is water, and the quarter's drift is the real story; the other two have no daily value to depart from.
• Bedtime. Clock arithmetic is circular — the mean of 23:50 and 00:10 is not noon — and the regularity ruler already owns consistency.
• Skin temperature deviation. Already a deviation from a vendor's baseline. Double-baselining is not a second opinion.
• Blood oxygen. Quantized at 98–99%, so the swing would be a rounding artefact rather than your own variability.
• Fitness load — CTL, ATL and form. Trailing-window constructions whose day-to-day movement is arithmetic on their own window, not news.
• Money, ratings and ladders. Lumpy and rent-shaped, or a standing — and a standing is the rest of this page's business, not a day's.
• Anything yes/no. A yes/no day is 0 or 1, so “deviation from the rate” fires exactly when you did the rarer thing, every time you do it — a tautology dressed as a finding. Habits ask a better question of the same fact.
• Lab results, ranks, and per-thing metrics. Refused structurally, whatever a manifest asks for: a few blood draws a year has no daily anything, a ladder rank is somebody else's number, and a metric keyed per game or per app has no single daily value to be a deviation of.

A category shows a named standing only when the ruler is external, absolute and instrument-compatible: published by someone else and citable, statable in your own units, and derived from measurements like the ones we hold. Where any of those fails, the surface prints the refusal and its reason where the rank would have been.

That is a deliberately hard bar, and most things do not clear it. Sleep duration has a U-shaped mortality curve, so a high percentile would be a warning dressed as a win. Books per year is self-reported and Goodhart-corrupted, and ranking it optimises the wrong life. Resting heart rate is not monotone-good — beta blockers and illness both move it the “right” way. HRV, steps and screen time fail on the same grounds. None of those get a standing, and none of them will get one because somebody asked nicely.

What we show. A tier per barbell lift — squat, bench press, deadlift — from your best estimated one-rep max over the last 90 days, read against lifters of the same published column and a similar bodyweight.

The formula. Your one-rep max is an Epley estimate — weight × (1 + reps ÷ 30)— taken over your non-warmup sets of 1–12 reps, with a true single counting as its own weight. Your bodyweight is the most recent one we hold, and if you have no scale connected, the one you typed into your profile. A measured weight always wins over a typed one.

The pool, and its skew. people who compete in raw powerlifting: everyone in this table entered a raw powerlifting meet, which is a self-selected group who train these three lifts on purpose. It is not the general population. A low percentile here is a statement about that pool, not about you.

The gap we cannot close. Your number is an estimate off a working set. Theirs is a third attempt on a platform with three judges. Expect the estimate to read a little high against them, and more so the further your sets are from a single. We say this on the sheet as well as here.

The table

Reduced from the OpenPowerlifting bulk archive, snapshot 2026-08-15. Public domain dedication; attribution requested, not required. The archive we used hashes to 339a08c5217e0a11….

This ruler uses data from the OpenPowerlifting project, https://www.openpowerlifting.org. You may download a copy of the data at https://gitlab.com/openpowerlifting/opl-data.

4,001,901 rows in, 1,814,639 kept after the filters, 580,708 distinct lifters after deduplication. Download the same archive and run the script below to get these numbers back.

The cut points, and whose they are

The tier names are ours. The percentiles they sit at are 5, 20, 50, 80 and 95, read off the table above. So “Advanced” means “at or above the 80th percentile of people who compete in raw powerliftingat your bodyweight” and nothing else — it is not a certification and no federation issues it.

Everything below the 5th percentile of that pool is the first band, Untrained. Against people who compete, that is where most people who lift start.

The reduction, in full

This is the script that turned the archive into the tables above, verbatim. It is here because a ruler nobody can re-derive is a black box with a citation stapled to it.

#!/usr/bin/env python3
"""Reduce the OpenPowerlifting bulk CSV to a frozen strength ruler (ADR 0134).

This is a ONE-OFF, OFFLINE reduction. Nothing in the running platform calls
it; it produces a versioned JSON table that is checked in, cited, and served
verbatim. It is published on /methods so anybody can re-run it against the
same input and get the same table — a ruler nobody can audit is a black box
wearing a citation.

Input
    The OpenPowerlifting bulk CSV distribution, dedicated to the public
    domain by the project:
        https://openpowerlifting.gitlab.io/opl-csv/files/openpowerlifting-latest.zip

Usage
    python3 scripts/rulers/reduce_openpowerlifting.py \
        --csv  openpowerlifting-YYYY-MM-DD/openpowerlifting-YYYY-MM-DD-HASH.csv \
        --zip  openpowerlifting-latest.zip \
        --snapshot YYYY-MM-DD \
        --out  go/platform/rulers/tables/strength_openpowerlifting.json

The pipeline, in the order the steps run
    1. RAW ONLY. Keep Equipment == "Raw" (bare knees or knee sleeves). Wraps
       and every equipped category add kilos no gym est-1RM has, so mixing
       them in would move the whole curve away from the instrument we
       measure people with.
    2. TWO PUBLISHED COLUMNS. Keep Sex in {M, F}. These are the columns
       OpenPowerlifting itself splits on, and the only ones the table can
       honestly offer. "Mx" is left out because its n is far too small to
       make a stable per-bodyweight curve, and a noisy curve presented as a
       ruler is worse than no ruler. An account whose reference_table is
       NONE or unset gets no placement at all, by design.
    3. DROP NON-RESULTS. Skip Place in {DQ, DD, G, NS} and any lift whose
       Best3xxxKg is missing or <= 0 — a failed or unattempted lift is
       recorded as zero or negative, not as a small number.
    4. PLAUSIBLE BODYWEIGHT. Require 35 <= BodyweightKg <= 200.
    5. DEDUP TO ONE ROW PER LIFTER PER LIFT. A lifter with 40 meets in the
       archive would otherwise be counted 40 times, tilting every percentile
       toward whoever competes most often. We keep each lifter's best-ever
       result for each lift, paired with the bodyweight they weighed in at
       for THAT result: a lifter is one person in this table, at their best.
       Lifters are keyed by the archive's own disambiguated Name (the
       project appends "#2" to a second John Doe), which is the only lifter
       identity the CSV carries.
    6. BIN BY BODYWEIGHT. For each sex and lift, take knots every
       KNOT_STEP kg and pool the lifters within +/- WINDOW_KG of the knot.
       A knot is emitted only when its window holds at least MIN_SAMPLES
       lifters; a thin tail is dropped rather than published as a curve.
    7. PERCENTILES. At each knot the sorted window is read at the percentile
       grid below by linear interpolation between order statistics (the
       "linear" / type-7 definition). Between knots a lookup interpolates
       linearly in bodyweight; outside the emitted knots it clamps to the
       nearest one, and the surface says that it did.
    8. DOTS. The DOTS total distribution is reduced the same way but WITHOUT
       bodyweight bins, because DOTS already normalises for bodyweight. Only
       full-power (SBD) results contribute.

What the output deliberately does NOT contain
    No names, no meets, no dates, no rows — only order statistics over pools
    of at least MIN_SAMPLES people. The reduction is one-way.
"""

import argparse
import csv
import hashlib
import json
import sys
from collections import defaultdict

# The percentile grid every emitted curve is sampled at. The five tier cut
# points (5/20/50/80/95) are members of it, so a tier boundary is read from
# the table rather than re-derived; the rest exist so a face can draw the
# distribution and invert it to place one lifter without ever shipping a row.
PERCENTILE_GRID = [1, 2.5, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 97.5, 99]

# The tier cut points (ADR 0134). The NAMES are ours; the percentiles they
# sit at are published on /methods so nobody has to trust the naming.
TIER_CUTS = [5, 20, 50, 80, 95]
TIER_NAMES = ["Untrained", "Beginner", "Novice", "Intermediate", "Advanced", "Elite"]

KNOT_STEP = 5.0  # kg between bodyweight knots
WINDOW_KG = 5.0  # +/- this much around a knot is pooled
MIN_SAMPLES = 500  # a knot below this is not published

LIFTS = {
    # our lift key -> the CSV column holding the best of three
    "squat": "Best3SquatKg",
    "bench": "Best3BenchKg",
    "deadlift": "Best3DeadliftKg",
}

BAD_PLACES = {"DQ", "DD", "G", "NS"}

# The DOTS polynomial, published by OpenPowerlifting and reproduced verbatim
# on /methods. DOTS = total_kg * 500 / poly(bodyweight_kg), with bodyweight
# clamped to the range the polynomial was fitted over.
DOTS_COEFFICIENTS = {
    "M": (-0.000001093, 0.0007391293, -0.1918759221, 24.0900756, -307.75076),
    "F": (-0.0000010706, 0.0005158568, -0.1126655495, 13.6175032, -57.96288),
}
DOTS_BW_CLAMP = {"M": (40.0, 210.0), "F": (40.0, 150.0)}


def quantile(sorted_values, pct):
    """The type-7 quantile: linear interpolation between order statistics.

    Matches numpy's default and R's type 7, spelled out here so the pipeline
    carries no dependency a reader would have to go and check.
    """
    if not sorted_values:
        return None
    if len(sorted_values) == 1:
        return sorted_values[0]
    pos = (len(sorted_values) - 1) * (pct / 100.0)
    low = int(pos)
    high = min(low + 1, len(sorted_values) - 1)
    frac = pos - low
    return sorted_values[low] + (sorted_values[high] - sorted_values[low]) * frac


def parse_float(text):
    if not text:
        return None
    try:
        return float(text)
    except ValueError:
        return None


def dots(sex, total_kg, bodyweight_kg):
    a, b, c, d, e = DOTS_COEFFICIENTS[sex]
    low, high = DOTS_BW_CLAMP[sex]
    bw = min(max(bodyweight_kg, low), high)
    denom = a * bw**4 + b * bw**3 + c * bw**2 + d * bw + e
    if denom <= 0:
        return None
    return total_kg * 500.0 / denom


def read_lifters(csv_path):
    """Steps 1-5: stream the CSV down to one record per lifter.

    Returns {(sex, name): {"squat": (kg, bodyweight), ..., "total": (kg, bw)}}
    """
    best = defaultdict(dict)
    kept_rows = 0
    total_rows = 0
    with open(csv_path, newline="", encoding="utf-8") as handle:
        for row in csv.DictReader(handle):
            total_rows += 1
            if row["Equipment"] != "Raw":  # step 1
                continue
            sex = row["Sex"]
            if sex not in ("M", "F"):  # step 2
                continue
            if row["Place"] in BAD_PLACES:  # step 3
                continue
            bodyweight = parse_float(row["BodyweightKg"])
            if bodyweight is None or not (35.0 <= bodyweight <= 200.0):  # step 4
                continue
            entry = best[(sex, row["Name"])]
            kept_rows += 1
            for lift, column in LIFTS.items():  # step 5
                kilos = parse_float(row[column])
                if kilos is None or kilos <= 0:
                    continue
                if lift not in entry or kilos > entry[lift][0]:
                    entry[lift] = (kilos, bodyweight)
            # Step 8's input: a DOTS total needs all three lifts, one meet.
            if row["Event"] == "SBD":
                total = parse_float(row["TotalKg"])
                if total and total > 0:
                    if "total" not in entry or total > entry["total"][0]:
                        entry["total"] = (total, bodyweight)
    return best, total_rows, kept_rows


def reduce_lift(records, sex, lift):
    """Steps 6-7 for one sex and one lift: knots -> percentile curves."""
    by_bin = defaultdict(list)
    for (row_sex, _name), entry in records.items():
        if row_sex != sex or lift not in entry:
            continue
        kilos, bodyweight = entry[lift]
        by_bin[int(bodyweight)].append(kilos)

    knots = []
    knot = 35.0
    while knot <= 200.0:
        pooled = []
        for whole_kg in range(int(knot - WINDOW_KG), int(knot + WINDOW_KG) + 1):
            pooled.extend(by_bin.get(whole_kg, ()))
        if len(pooled) >= MIN_SAMPLES:
            pooled.sort()
            knots.append(
                {
                    "bodyweight_kg": knot,
                    "n": len(pooled),
                    "kg": [round(quantile(pooled, p), 2) for p in PERCENTILE_GRID],
                }
            )
        knot += KNOT_STEP
    return knots


def reduce_dots(records, sex):
    """Step 8: one bodyweight-free DOTS distribution per sex."""
    scores = []
    for (row_sex, _name), entry in records.items():
        if row_sex != sex or "total" not in entry:
            continue
        total, bodyweight = entry["total"]
        score = dots(sex, total, bodyweight)
        if score:
            scores.append(score)
    if len(scores) < MIN_SAMPLES:
        return None
    scores.sort()
    return {
        "n": len(scores),
        "dots": [round(quantile(scores, p), 2) for p in PERCENTILE_GRID],
    }


def sha256(path):
    digest = hashlib.sha256()
    with open(path, "rb") as handle:
        for chunk in iter(lambda: handle.read(1 << 20), b""):
            digest.update(chunk)
    return digest.hexdigest()


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--csv", required=True, help="the extracted bulk CSV")
    parser.add_argument("--zip", required=True, help="the downloaded zip, hashed into the citation")
    parser.add_argument("--snapshot", required=True, help="the distribution date, YYYY-MM-DD")
    parser.add_argument("--out", required=True)
    args = parser.parse_args()

    records, total_rows, kept_rows = read_lifters(args.csv)
    print(f"rows: {total_rows}  kept: {kept_rows}  lifters: {len(records)}", file=sys.stderr)

    table = {
        "id": "strength_openpowerlifting_v1",
        "version": 1,
        "snapshot_date": args.snapshot,
        # How this ruler ages (ADR 0154). The archive is a feed, so the table
        # DRIFTS and the monitor can watch it with a clock.
        "staleness": {
            "policy": "DRIFTS",
            "max_age_days": 180,
            "rationale": (
                "OpenPowerlifting republishes the bulk archive continuously as meets are "
                "entered, so the same reduction re-run today returns different percentiles. "
                "The snapshot date is the clock: past six months the tiers are quoting a pool "
                "that has moved on, and the fix is mechanical — re-run the reduction and "
                "commit the new snapshot."
            ),
        },
        "source": {
            "name": "OpenPowerlifting",
            "url": "https://www.openpowerlifting.org",
            "data_url": "https://openpowerlifting.gitlab.io/opl-csv/files/openpowerlifting-latest.zip",
            "license": "Public domain dedication; attribution requested, not required.",
            "attribution": (
                "This ruler uses data from the OpenPowerlifting project, "
                "https://www.openpowerlifting.org. You may download a copy of "
                "the data at https://gitlab.com/openpowerlifting/opl-data."
            ),
            "archive_sha256": sha256(args.zip),
        },
        "pipeline": {
            "script": "scripts/rulers/reduce_openpowerlifting.py",
            "equipment": "Raw",
            "dedup": "one row per lifter per lift: their best-ever result, at that meet's bodyweight",
            "knot_step_kg": KNOT_STEP,
            "window_kg": WINDOW_KG,
            "min_samples": MIN_SAMPLES,
            "quantile": "type-7 (linear interpolation between order statistics)",
            "rows_read": total_rows,
            "rows_kept": kept_rows,
            "lifters": len(records),
        },
        "pool_label": "people who compete in raw powerlifting",
        "percentile_grid": PERCENTILE_GRID,
        "tier_cuts": TIER_CUTS,
        "tier_names": TIER_NAMES,
        "lifts": {},
        "dots_total": {},
    }

    for lift in LIFTS:
        table["lifts"][lift] = {}
        for sex in ("F", "M"):
            knots = reduce_lift(records, sex, lift)
            table["lifts"][lift]["FEMALE" if sex == "F" else "MALE"] = knots
            print(f"{lift} {sex}: {len(knots)} knots", file=sys.stderr)

    for sex in ("F", "M"):
        reduced = reduce_dots(records, sex)
        if reduced:
            table["dots_total"]["FEMALE" if sex == "F" else "MALE"] = reduced

    with open(args.out, "w", encoding="utf-8") as handle:
        json.dump(table, handle, indent=1, sort_keys=True)
        handle.write("\n")
    print(f"wrote {args.out}", file=sys.stderr)


if __name__ == "__main__":
    main()

The earlier audit stopped at three refusals. A second pass found a licensed, instrument-compatible route: FitnessVolt publishes versioned, CC BY 4.0 gym distributions for overhead press and pull-up, and a separately labelled Romanian-deadlift model. We keep those evidence types separate instead of making the model look like a measured population.

The common clock. Like squat, bench and deadlift, these rows use your best qualifying estimate from the last 90 days, read at weekly boundaries with the same 14-day hold and 60-day stale rule. They do not enter DOTS, and they do not borrow the OpenPowerlifting pool or citation.

Snapshot 2026-08-19; API version 1.0.0, data version 2026-06-09. The API’s bodyweight classes are discrete: we select the published class and never smooth across its boundary. Read the FitnessVolt methodology.

The four full API responses and the extracted, licensed RDL table facts are frozen in one dated source archive, SHA-256 dce09287788e45e23b990512a64245482d296ebdef64ca153222c3ffd8581383. Every lift citation names those exact checked-in bytes; the mutable API endpoints and article page are discovery sources, not archives.

The vendor pipeline, in full

This is the script that fetches the four API tables, preserves only the RDL page’s licensed whole-pound facts, verifies the evidence labels, and writes both the canonical dated source archive and the smaller serving artifact.

#!/usr/bin/env python3
"""Vendor FitnessVolt accessory-lift standards.

This table deliberately keeps two different kinds of evidence separate:

* overhead press and pull-up are measured percentile tables from the
  Symmetric Strength self-reported gym population, republished by the
  FitnessVolt Strength Standards API under CC BY 4.0;
* Romanian deadlift is FitnessVolt's published MODELLED level table.  Its
  page says the figures are ratio-derived from base lifts anchored to
  OpenPowerlifting and are not direct competition percentiles.  We preserve
  that statement in the artifact and never attach a percentile grid to RDL.

The API's bodyweight rows are competition-style classes, not points on a
continuous curve.  In particular, ``120kg`` and ``120+kg`` (``84kg`` and
``84+kg`` for women) are distinct cohorts.  The output therefore retains
the ordinary rows as inclusive upper bounds and the final plus row as an
open-ended class.  It never interpolates between cohorts.

Each run writes two artifacts:

* one dated, canonical source archive containing the four complete API JSON
  responses plus only the licensed RDL facts extracted from the HTML page;
* the smaller serving table derived from that archive.

The archive is the byte sequence named by every ``archive_sha256`` and
``data_url`` in the serving table.  We do not hash mutable endpoints or retain
FitnessVolt's full HTML page and then point readers somewhere else.

Run from anywhere in the repository:

    python3 scripts/rulers/vendor_fitnessvolt_strength.py

The fetch is intentionally strict.  A changed API version, percentile grid,
source population, HTML table shape, or RDL evidence statement stops the
script instead of silently changing what the ruler means.
"""

from __future__ import annotations

import argparse
import datetime
from decimal import Decimal, ROUND_HALF_UP
import hashlib
import html
from html.parser import HTMLParser
import json
import pathlib
import re
import sys
import urllib.request


REPO = pathlib.Path(__file__).resolve().parents[2]
DEFAULT_OUT = (
    REPO
    / "go"
    / "platform"
    / "rulers"
    / "tables"
    / "strength_fitnessvolt.json"
)
SOURCE_ARCHIVE_DIR = DEFAULT_OUT.parent / "sources"
SOURCE_ARCHIVE_ID = "fitnessvolt_strength_source_archive_v1"
SOURCE_ARCHIVE_REPOSITORY_URL = (
    "https://raw.githubusercontent.com/JuicyPasta/QuantifiedLife/main/"
    "go/platform/rulers/tables/sources/{filename}"
)

API_BASE = "https://fitnessvolt.com/wp-json/fvss/v1"
OPEN_DATA_URL = "https://fitnessvolt.com/strength-standards/strength-data/"
METHODOLOGY_URL = "https://fitnessvolt.com/strength-standards/methodology/"
RDL_URL = "https://fitnessvolt.com/strength-standards/romanian-deadlift/"
RDL_LICENSE_URL = "https://opendatacommons.org/licenses/odbl/1-0/"
CC_BY_LICENSE_URL = "https://creativecommons.org/licenses/by/4.0/"
EXPECTED_API_VERSION = "1.0.0"
EXPECTED_DATA_VERSION = "2026-06-09"
PERCENTILES = [10, 25, 50, 75, 90, 95, 99]
PERCENTILE_KEYS = [f"p{p}" for p in PERCENTILES]
KG_PER_LB_DECIMAL = Decimal("0.45359237")

USER_AGENT = (
    "QuantifiedLife ruler snapshot "
    "(https://quantifiedlife.io/methods; one manual fetch per refresh)"
)

OBSERVED_LIFTS = {
    "overhead_press": {
        "api_slug": "overhead_press",
        "display_name": "Overhead press",
        "formula_id": "strength_fitnessvolt_overhead_press_gym_v1",
        "pool_label": "Symmetric Strength self-reported overhead-press samples",
        "value_basis": (
            "Standing barbell overhead-press one-repetition maximum in kilograms: "
            "the external barbell load, read against the lifter's sex-specific "
            "bodyweight class."
        ),
        "caveat": (
            "Self-reported gym lifts are not competition-judged: technique, range of "
            "motion, 1RM estimation, rounding, and selection into a strength-tracking "
            "site can all shift this population away from the lifter being compared."
        ),
    },
    "weighted_pullup": {
        "api_slug": "pullup",
        "display_name": "Weighted pull-up",
        "formula_id": "strength_fitnessvolt_pullup_system_weight_gym_v1",
        "pool_label": "Symmetric Strength self-reported pull-up samples",
        "value_basis": (
            "Pull-up one-repetition maximum in kilograms of TOTAL SYSTEM WEIGHT "
            "(bodyweight plus external load), read against the lifter's sex-specific "
            "bodyweight class.  An added-weight-only estimate is not this measure."
        ),
        "caveat": (
            "Self-reported pull-ups are not competition-judged and may differ in grip, "
            "range of motion, assistance, kipping, and 1RM estimation.  The source "
            "requires total system weight, so an external-load-only metric is "
            "instrument-incompatible."
        ),
    },
}

OBSERVED_BAND_NAMES = [
    "Below published 10th percentile",
    "10th-24th percentile",
    "25th-49th percentile",
    "50th-74th percentile",
    "75th-89th percentile",
    "90th-94th percentile",
    "95th-98th percentile",
    "99th percentile or above",
]

RDL_LEVEL_NAMES = ["Beginner", "Novice", "Intermediate", "Advanced", "Elite"]
RDL_BAND_NAMES = ["Below Beginner", *RDL_LEVEL_NAMES]


def fetch(url: str) -> bytes:
    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
    with urllib.request.urlopen(request, timeout=45) as response:
        if response.status != 200:
            raise SystemExit(f"{url}: HTTP {response.status}")
        return response.read()


def canonical_json(value: object) -> bytes:
    """The single byte representation hashed, checked in, and regenerated."""
    return (
        json.dumps(value, indent=1, sort_keys=True, ensure_ascii=True) + "\n"
    ).encode("utf-8")


def archive_filename(snapshot_date: str) -> str:
    return f"fitnessvolt_strength_{snapshot_date}.json"


def archive_url(snapshot_date: str) -> str:
    return SOURCE_ARCHIVE_REPOSITORY_URL.format(
        filename=archive_filename(snapshot_date)
    )


def archive_source(archive_hash: str, data_url: str) -> dict[str, str]:
    """Fields shared by the collective table and every per-lift source."""
    return {"archive_sha256": archive_hash, "data_url": data_url}


def write_immutable_archive(path: pathlib.Path, body: bytes) -> None:
    """Create a dated archive, or prove that an existing one is identical."""
    if path.exists() and path.read_bytes() != body:
        raise SystemExit(
            f"{path}: refusing to replace a dated source archive with different "
            "bytes; choose a new --snapshot-date (or inspect with --archive-out)"
        )
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(body)


def clean_api_kg(value: object) -> float:
    """Collapse PHP's binary-float JSON noise to the published 0.1 kg."""
    if not isinstance(value, (int, float)):
        raise SystemExit(f"API threshold {value!r} is not numeric")
    rounded = float(
        Decimal(str(value)).quantize(Decimal("0.1"), rounding=ROUND_HALF_UP)
    )
    if rounded <= 0:
        raise SystemExit(f"API threshold {value!r} is not positive")
    return rounded


def api_url(slug: str, sex: str) -> str:
    return (
        f"{API_BASE}/standards/{slug}?format=table&sex={sex}"
        "&source=gym&unit=kg"
    )


def parse_bodyweight_class(label: str) -> tuple[float, bool]:
    match = re.fullmatch(r"(\d+)(\+)?kg", label)
    if match is None:
        raise SystemExit(f"unknown FitnessVolt bodyweight class {label!r}")
    return float(match.group(1)), match.group(2) is not None


def fetch_observed_lift(key: str, spec: dict[str, str]) -> tuple[dict, list[dict]]:
    tables: dict[str, list[dict]] = {}
    table_sizes: dict[str, int] = {}
    archived_payloads: list[dict] = []
    request_urls: list[str] = []
    versions: set[str] = set()
    data_versions: set[str] = set()
    attribution: dict | None = None

    for sex in ("female", "male"):
        url = api_url(spec["api_slug"], sex)
        raw = fetch(url)
        try:
            payload = json.loads(raw)
        except json.JSONDecodeError as exc:
            raise SystemExit(f"{url}: invalid JSON: {exc}") from exc

        if payload.get("success") is not True:
            raise SystemExit(f"{url}: API did not report success")
        if payload.get("lift") != spec["api_slug"]:
            raise SystemExit(f"{url}: lift = {payload.get('lift')!r}")
        if payload.get("sex") != sex or payload.get("unit") != "kg":
            raise SystemExit(f"{url}: wrong sex or unit")
        if payload.get("source") != "self_reported_gym":
            raise SystemExit(f"{url}: source = {payload.get('source')!r}")
        if payload.get("format") != "table":
            raise SystemExit(f"{url}: format = {payload.get('format')!r}")
        request_urls.append(url)
        archived_payloads.append(
            {
                "lift_key": key,
                "request_url": url,
                "response": payload,
                "sex": sex,
            }
        )

        versions.add(payload.get("api_version", ""))
        data_versions.add(payload.get("data_version", ""))
        if attribution is None:
            attribution = payload.get("attribution")
        elif payload.get("attribution") != attribution:
            raise SystemExit(f"{url}: attribution changed between responses")

        total = payload.get("total_sample_size")
        if not isinstance(total, int) or total <= 0:
            raise SystemExit(f"{url}: invalid total_sample_size {total!r}")

        rows = payload.get("weight_classes")
        if not isinstance(rows, list) or len(rows) < 2:
            raise SystemExit(f"{url}: no bodyweight classes")
        all_rows = [row for row in rows if row.get("weight_class") == "all"]
        if len(all_rows) != 1 or all_rows[0].get("sample_size") != total:
            raise SystemExit(f"{url}: missing or inconsistent all-bodyweights row")

        cohorts: list[dict] = []
        previous_upper = 0.0
        for row in rows:
            label = row.get("weight_class")
            if label == "all":
                continue
            if not isinstance(label, str):
                raise SystemExit(f"{url}: class with no label")
            boundary, plus = parse_bodyweight_class(label)
            if (plus and boundary != previous_upper) or (
                not plus and boundary <= previous_upper
            ):
                raise SystemExit(
                    f"{url}: bodyweight classes are not ascending at {label}"
                )
            n = row.get("sample_size")
            if not isinstance(n, int) or n < 30:
                raise SystemExit(f"{url}: {label} sample_size = {n!r}")
            raw_percentiles = row.get("percentiles")
            if not isinstance(raw_percentiles, dict) or list(raw_percentiles) != PERCENTILE_KEYS:
                raise SystemExit(
                    f"{url}: {label} percentile grid = {list(raw_percentiles or {})!r}"
                )
            values = [clean_api_kg(raw_percentiles[name]) for name in PERCENTILE_KEYS]
            if any(values[i] < values[i - 1] for i in range(1, len(values))):
                raise SystemExit(f"{url}: {label} thresholds descend: {values}")

            cohort = {
                "bodyweight_class": label,
                "kg": values,
                "n": n,
                "plus": plus,
            }
            if plus:
                cohort["lower_bound_exclusive_kg"] = boundary
            else:
                cohort["upper_bodyweight_kg"] = boundary
                previous_upper = boundary
            cohorts.append(cohort)

        if sum(1 for row in cohorts if row["plus"]) != 1 or not cohorts[-1]["plus"]:
            raise SystemExit(f"{url}: final bodyweight class is not the sole plus class")
        if cohorts[-1]["lower_bound_exclusive_kg"] != previous_upper:
            raise SystemExit(f"{url}: plus class does not begin above the preceding class")

        table = sex.upper()
        tables[table] = cohorts
        table_sizes[table] = total

    if versions != {EXPECTED_API_VERSION}:
        raise SystemExit(f"{key}: API versions = {sorted(versions)!r}")
    if data_versions != {EXPECTED_DATA_VERSION}:
        raise SystemExit(f"{key}: data versions = {sorted(data_versions)!r}")
    if not attribution or attribution.get("required") is not True:
        raise SystemExit(f"{key}: API no longer requires visible attribution")

    lift = {
        "band_names": OBSERVED_BAND_NAMES,
        "caveat": spec["caveat"],
        "display_name": spec["display_name"],
        "evidence": {
            "api_version": EXPECTED_API_VERSION,
            "data_version": EXPECTED_DATA_VERSION,
            "has_distribution": True,
            "kind": "OBSERVED_SELF_REPORTED_PERCENTILES",
            "request_urls": request_urls,
            "statement": (
                "FitnessVolt republishes sex-by-bodyweight-class percentile tables "
                "from the Symmetric Strength self-reported gym population.  The "
                "population is measured but self-reported, and is kept separate "
                "from verified competition results."
            ),
        },
        "formula_id": spec["formula_id"],
        "percentile_grid": PERCENTILES,
        "pool": {
            "label": spec["pool_label"],
            "population": "Symmetric Strength self-reported gym sample",
            "table_sizes": table_sizes,
            "total_size": sum(table_sizes.values()),
        },
        "source": {
            "attribution": (
                "Strength standards data by FitnessVolt, sourced from the "
                "Symmetric Strength self-reported gym dataset."
            ),
            "license": (
                "CC BY 4.0; FitnessVolt requires a visible attribution link on "
                "every page or product displaying the data."
            ),
            "name": "FitnessVolt Strength Standards API",
            "url": OPEN_DATA_URL,
        },
        "tables": tables,
        "tier_cuts": PERCENTILES,
        "value_basis": spec["value_basis"],
    }
    return lift, archived_payloads


class RDLTableParser(HTMLParser):
    """Extract only the two server-rendered bodyweight table bodies."""

    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self.active_sex: str | None = None
        self.in_cell = False
        self.cell_text: list[str] = []
        self.row: list[int] | None = None
        self.rows: dict[str, list[list[int]]] = {"female": [], "male": []}
        self.all_text: list[str] = []

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        attributes = dict(attrs)
        if tag == "tbody" and attributes.get("id") in {"bw-female", "bw-male"}:
            self.active_sex = attributes["id"][3:]
        elif self.active_sex is not None and tag == "tr":
            self.row = []
        elif self.row is not None and tag == "td":
            self.in_cell = True
            self.cell_text = []

    def handle_data(self, data: str) -> None:
        self.all_text.append(data)
        if self.in_cell:
            self.cell_text.append(data)

    def handle_endtag(self, tag: str) -> None:
        if tag == "td" and self.in_cell:
            text = " ".join("".join(self.cell_text).split())
            if not re.fullmatch(r"\d+", text):
                raise SystemExit(f"RDL table cell is not a whole number: {text!r}")
            assert self.row is not None
            self.row.append(int(text))
            self.in_cell = False
            self.cell_text = []
        elif tag == "tr" and self.row is not None:
            if len(self.row) != 6:
                raise SystemExit(f"RDL bodyweight row has {len(self.row)} cells: {self.row}")
            assert self.active_sex is not None
            self.rows[self.active_sex].append(self.row)
            self.row = None
        elif tag == "tbody" and self.active_sex is not None:
            self.active_sex = None


def lb_to_kg(value: int) -> float:
    return float(
        (Decimal(value) * KG_PER_LB_DECIMAL).quantize(
            Decimal("0.01"), rounding=ROUND_HALF_UP
        )
    )


def fetch_rdl() -> tuple[dict, dict, str]:
    raw = fetch(RDL_URL)
    page = raw.decode("utf-8")
    parser = RDLTableParser()
    parser.feed(page)
    text = " ".join(html.unescape(" ".join(parser.all_text)).split())
    required_claims = [
        "modeled level tables, ratio-derived from base lifts",
        "modeled estimates, not direct competition percentiles",
    ]
    for claim in required_claims:
        if claim not in text:
            raise SystemExit(
                f"{RDL_URL}: evidence statement {claim!r} disappeared; "
                "do not infer what the table means"
            )
    if RDL_LICENSE_URL not in page:
        raise SystemExit(
            f"{RDL_URL}: Dataset license {RDL_LICENSE_URL!r} disappeared; "
            "do not vendor the modeled rows without a data license"
        )

    modified_match = re.search(r'"dateModified":"([^"T]+)(?:T[^"]*)?"', page)
    if modified_match is None:
        raise SystemExit(f"{RDL_URL}: no dateModified in page metadata")
    page_version = modified_match.group(1)

    tables: dict[str, list[dict]] = {}
    archived_tables: dict[str, list[dict]] = {}
    for sex in ("female", "male"):
        rows = parser.rows[sex]
        if len(rows) < 10:
            raise SystemExit(f"{RDL_URL}: only {len(rows)} {sex} bodyweight rows")
        previous_bw = 0
        model_rows: list[dict] = []
        archived_rows: list[dict] = []
        for row in rows:
            bodyweight_lb, *values_lb = row
            if bodyweight_lb <= previous_bw:
                raise SystemExit(f"{RDL_URL}: {sex} bodyweights are not ascending")
            if any(values_lb[i] <= values_lb[i - 1] for i in range(1, len(values_lb))):
                raise SystemExit(f"{RDL_URL}: {sex}/{bodyweight_lb} thresholds do not ascend")
            model_rows.append(
                {
                    "bodyweight_kg": lb_to_kg(bodyweight_lb),
                    "bodyweight_lb": bodyweight_lb,
                    "kg": [lb_to_kg(value) for value in values_lb],
                    "lb": values_lb,
                }
            )
            archived_rows.append(
                {
                    "bodyweight_lb": bodyweight_lb,
                    "level_thresholds_lb": values_lb,
                }
            )
            previous_bw = bodyweight_lb
        tables[sex.upper()] = model_rows
        archived_tables[sex.upper()] = archived_rows

    evidence_statement = (
        "FitnessVolt labels these as modeled level tables, ratio-derived "
        "from base lifts anchored to OpenPowerlifting, and explicitly says "
        "they are modeled estimates rather than direct competition "
        "percentiles."
    )
    lift = {
        "band_names": RDL_BAND_NAMES,
        "caveat": (
            "This is a ratio-derived training model, not an observed distribution "
            "of Romanian-deadlift lifters.  RDL range of motion is not federation-"
            "standardized, so logged lifts may not be the same movement; no "
            "percentile, sample size, or stronger-than share may be inferred."
        ),
        "display_name": "Romanian deadlift",
        "evidence": {
            "has_distribution": False,
            "kind": "MODELLED",
            "page_last_modified": page_version,
            "request_urls": [RDL_URL],
            "statement": evidence_statement,
        },
        "formula_id": "strength_fitnessvolt_rdl_model_v1",
        "level_names": RDL_LEVEL_NAMES,
        "pool": {
            "label": "FitnessVolt ratio-derived model; no measured RDL cohort",
            "population": "No direct Romanian-deadlift population",
            "table_sizes": {},
            "total_size": 0,
        },
        "source": {
            "attribution": (
                "FitnessVolt Romanian Deadlift Standards by Bodyweight; modeled "
                "level table derived from base lifts anchored to OpenPowerlifting."
            ),
            "license": (
                "The page's Dataset metadata licenses these modeled rows under "
                "ODbL 1.0 (https://opendatacommons.org/licenses/odbl/1-0/).  The "
                "re-keyed RDL database component is offered under the same terms; "
                "see go/platform/rulers/tables/LICENSE-DATA.md."
            ),
            "name": "FitnessVolt Romanian Deadlift Standards",
            "url": RDL_URL,
        },
        "tables": tables,
        "value_basis": (
            "Five published one-repetition-maximum level thresholds by bodyweight. "
            "The source's whole-pound rows are retained verbatim and converted to "
            "kilograms with 1 lb = 0.45359237 kg; lookup uses the nearest published "
            "bodyweight row rather than inventing an interpolation."
        ),
    }
    archived_source = {
        "columns": [
            "bodyweight_lb",
            *[f"{name.lower()}_lb" for name in RDL_LEVEL_NAMES],
        ],
        "evidence": {
            "claims_verified_on_source_page": required_claims,
            "kind": "MODELLED",
            "statement": evidence_statement,
        },
        "extraction": (
            "Only the server-rendered bodyweight table facts were retained; "
            "the source page HTML is not archived."
        ),
        "license": {
            "evidence": "Dataset metadata on the source page",
            "name": "Open Data Commons Open Database License 1.0",
            "url": RDL_LICENSE_URL,
        },
        "page_last_modified": page_version,
        "request_url": RDL_URL,
        "tables": archived_tables,
    }
    return lift, archived_source, page_version


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--snapshot-date",
        default=datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d"),
        help="date to stamp on the fetched snapshot (default: today, UTC)",
    )
    parser.add_argument(
        "--out",
        type=pathlib.Path,
        default=DEFAULT_OUT,
        help=f"output path (default: {DEFAULT_OUT})",
    )
    parser.add_argument(
        "--archive-out",
        type=pathlib.Path,
        help=(
            "source-archive output path (default: "
            f"{SOURCE_ARCHIVE_DIR}/fitnessvolt_strength_<snapshot-date>.json)"
        ),
    )
    args = parser.parse_args()
    try:
        datetime.date.fromisoformat(args.snapshot_date)
    except ValueError as exc:
        raise SystemExit(f"invalid --snapshot-date {args.snapshot_date!r}: {exc}") from exc

    lifts: dict[str, dict] = {}
    api_payloads: list[dict] = []
    for key, spec in OBSERVED_LIFTS.items():
        lift, archived_payloads = fetch_observed_lift(key, spec)
        lifts[key] = lift
        api_payloads.extend(archived_payloads)
        sizes = lift["pool"]["table_sizes"]
        print(
            f"{key}: FEMALE n={sizes['FEMALE']:,}; MALE n={sizes['MALE']:,}",
            file=sys.stderr,
        )

    rdl, archived_rdl, rdl_page_version = fetch_rdl()
    lifts["romanian_deadlift"] = rdl
    print(
        "romanian_deadlift: "
        f"FEMALE rows={len(rdl['tables']['FEMALE'])}; "
        f"MALE rows={len(rdl['tables']['MALE'])} (MODELLED, no distribution)",
        file=sys.stderr,
    )

    source_archive = {
        "api": {
            "license": {
                "attribution_requirement": (
                    "FitnessVolt requires a visible attribution link wherever "
                    "the API data is displayed."
                ),
                "name": "Creative Commons Attribution 4.0 International",
                "source_url": OPEN_DATA_URL,
                "url": CC_BY_LICENSE_URL,
            },
            "payloads": api_payloads,
        },
        "id": SOURCE_ARCHIVE_ID,
        "license_notice": "go/platform/rulers/tables/LICENSE-DATA.md",
        "romanian_deadlift": archived_rdl,
        "snapshot_date": args.snapshot_date,
        "version": 1,
    }
    source_archive_bytes = canonical_json(source_archive)
    source_archive_hash = hashlib.sha256(source_archive_bytes).hexdigest()
    source_archive_filename = archive_filename(args.snapshot_date)
    source_archive_url = archive_url(args.snapshot_date)
    source_archive_path = (
        f"go/platform/rulers/tables/sources/{source_archive_filename}"
    )
    source_pointer = archive_source(source_archive_hash, source_archive_url)
    for lift in lifts.values():
        lift["source"].update(source_pointer)

    table_source = {
        **source_pointer,
        "attribution": (
            "FitnessVolt Strength Standards.  OHP and pull-up data sourced from "
            "the Symmetric Strength self-reported gym dataset; Romanian deadlift "
            "is FitnessVolt's separately labeled modeled level table."
        ),
        "license": (
            "FitnessVolt's public API data is CC BY 4.0 with a required visible "
            "attribution link.  The modeled RDL rows are ODbL 1.0; see each "
            "lift's source and go/platform/rulers/tables/LICENSE-DATA.md."
        ),
        "name": "FitnessVolt Strength Standards",
        "url": OPEN_DATA_URL,
    }

    table = {
        "id": "strength_fitnessvolt_accessory_v1",
        "version": 1,
        "snapshot_date": args.snapshot_date,
        "staleness": {
            "policy": "DRIFTS",
            "max_age_days": 180,
            "rationale": (
                "FitnessVolt republishes the API cohorts and the web model in place, "
                "so a later fetch can change both the self-reported percentile rows "
                "and the modeled RDL thresholds.  Refreshing is mechanical: rerun "
                "the vendor script, review the provenance and evidence labels, and "
                "commit the new dated snapshot."
            ),
        },
        "source": table_source,
        "pipeline": {
            "api_version": EXPECTED_API_VERSION,
            "conversion": "kg = lb * 0.45359237, rounded half-up to 0.01 kg",
            "data_version": EXPECTED_DATA_VERSION,
            "methodology_url": METHODOLOGY_URL,
            "note": (
                "OHP and pull-up preserve discrete API bodyweight classes and exact "
                "published percentile points; the aggregate all-bodyweights rows are "
                "excluded.  RDL preserves the page's whole-pound model table and has "
                "no percentile grid."
            ),
            "rdl_page_last_modified": rdl_page_version,
            "script": "scripts/rulers/vendor_fitnessvolt_strength.py",
            "source_archive": source_archive_path,
        },
        "lifts": lifts,
    }

    archive_out = args.archive_out or SOURCE_ARCHIVE_DIR / source_archive_filename
    write_immutable_archive(archive_out, source_archive_bytes)
    print(f"wrote {archive_out} (sha256 {source_archive_hash})")

    args.out.parent.mkdir(parents=True, exist_ok=True)
    args.out.write_bytes(canonical_json(table))
    print(f"wrote {args.out}")


if __name__ == "__main__":
    main()

DOTS normalises a powerlifting total for bodyweight. We show it one tap down on the strength sheet and never as a headline, because our version adds three estimates made on three different days from three different rep ranges — that is not a meet total and must not be compared with one as if it were.

The polynomial is OpenPowerlifting’s, not ours:

DOTS = total_kg × 500 ÷ (A·bw⁴ + B·bw³ + C·bw² + D·bw + E)

A, B, C, D, E —
  female: -0.0000010706, 0.0005158568, -0.1126655495, 13.6175032, -57.96288
  male  : -0.000001093, 0.0007391293, -0.1918759221, 24.0900756, -307.75076

Bodyweight is clamped to the range the polynomial was fitted over (40–210 kg for the male coefficients, 40–150 kg for the female ones), which is the formula’s own rule rather than a smoothing of ours.

Female tables, 131,321 lifters with a full-power total: Beginner at 199.53, Novice at 250.59, Intermediate at 305.65, Advanced at 364.26, Elite at 424.97.

Male tables, 281,282 lifters with a full-power total: Beginner at 232.58, Novice at 296.47, Intermediate at 351.75, Advanced at 403.71, Elite at 454.29.

What we show. Your rating in each pool — bullet, blitz, rapid — exactly as the site issues it, plus the highest 100-point club you have ever reached, with the date you reached it. Six pools in all: three on Lichess and three on Chess.com, which are separate ladders on separate scales and are never merged.

We do not rate you.There is no chess Elo of ours anywhere. Lichess runs Glicko-2 and Chess.com runs Glicko; both see every game every player plays and we see one player’s, so their number is better than anything we could compute and we pass it through untouched — no smoothing, no weekly average, no conversion between the two sites.

A club is absolute, dated and never taken away. “1600 club — member since 3 November 2025” means your rating touched 1600 on that day. Losing rating afterwards does not remove it. There is no demotion event anywhere on this platform, and for a club there is not even a drop to record; the rating chart above it tells the truth about now.

The rating lives one tap down. Chess ratings arrive pre-loaded with rating anxiety, so the surfaces that lead are games played and how you have been going. A losing streak must not become a reason to avoid opening the app.

Lichess — the published distribution

Lichess publishes a weekly histogram of every established rating in each pool, and uses it itself to tell members they are “better than X%”. We read the same table with the same rule: you count as above a 25-point bucket when your rating exceeds that bucket’s midpoint. Buckets run 400–2800, which is Lichess’s own axis, not ours.

Snapshot 2026-08-18. Lichess publishes this histogram on its own public statistics page; its database exports are released under CC0 and its site code under AGPL-3.0. We reproduce the counts with attribution and a link back.

Weekly rating distribution published by Lichess (lichess.org/stat/rating/distribution).

Percentiles are reported to whole percents on the sheet, against 336,259 bullet, 663,877 blitz, 472,854 rapid rated players. The pool is people who play enough online chess to hold an established rating — not chess players in general, and not the general population. Read the same page we snapshotted.

Chess.com — no distribution, and we say so

Chess.com publishes no rating distribution. It removed the percentile page it used to have and offers no endpoint that replaces it, so there is no honest percentile for a Chess.com rating and we show none. We will not estimate one from our own users, and we will not borrow Lichess’s — the two sites rate different people on different scales, and a number read off the wrong pool is worse than no number. Your rating and your club are Chess.com’s own; the sheet says exactly this where a Lichess sheet shows a percentile.

The snapshot, in full

This is the script that fetched the histogram above, verbatim. It runs by hand and the result is committed, because a reference table that can change while you are reading the page citing it is not a citation.

#!/usr/bin/env python3
"""Vendor Lichess's published weekly rating distribution (ADR 0134/0147).

Lichess publishes, for every leaderboardable pool, a histogram of how many
established players sit in each 25-point rating group:

    https://lichess.org/stat/rating/distribution/blitz

That histogram is the only external, absolute, instrument-compatible ruler
that exists for a chess rating — it is Lichess's own count of Lichess's own
players, and it is the same number Lichess itself uses to tell a member they
are "better than 47.3% of blitz players". We reproduce it rather than
recompute anything, and we reproduce it as a DATED SNAPSHOT compiled into the
binary rather than fetching it per request: a reference table that can change
under the product is not a citation (ADR 0144).

Run it, commit the JSON it writes, re-run scripts/gen-chess-ruler.py so the
public /methods page shows the same numbers, and the snapshot date every
surface renders moves with the commit.

    python3 scripts/rulers/fetch_lichess_distribution.py

The histogram is embedded in the page as JSON rather than served by an API:
there is no documented /api/rating/distribution endpoint and the obvious
guess 404s (checked 2026-08-18), so the page is the source. The extraction is
deliberately narrow and asserts the shape it expects, because a scrape that
degrades quietly is worse than one that fails.

The bucket axis is Lichess's, not ours. lila builds the list as

    (Glicko.minRating.value to 2800 by percentileOf.group)

with `Glicko.minRating = 400` and `percentileOf.group = 25`
(modules/perfStat/src/main/PerfStatApi.scala,
modules/perfStat/src/main/package.scala), so bucket i covers ratings
[400 + 25i, 400 + 25i + 25) and there are 97 of them. The count is asserted
below: if Lichess moves its axis, this script stops rather than silently
re-labelling somebody else's numbers.
"""
import argparse
import datetime
import json
import os
import re
import sys
import urllib.request

REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
OUT = os.path.join(REPO, "go/platform/rulers/tables/chess_lichess_distribution.json")

PAGE = "https://lichess.org/stat/rating/distribution/{perf}"

# Lichess's own axis. See the module docstring for where each comes from.
MIN_RATING = 400
GROUP = 25
MAX_RATING = 2800
BUCKETS = (MAX_RATING - MIN_RATING) // GROUP + 1  # 97

# The three pools a standing is offered in. Lichess rates far more than
# these, but a category nobody plays is a row of "no signal" on a surface,
# and these are the three that the two platforms both run.
POOLS = {
    "bullet": "Lichess bullet players with an established rating",
    "blitz": "Lichess blitz players with an established rating",
    "rapid": "Lichess rapid players with an established rating",
}

FREQ = re.compile(r'\{"freq":\s*\[[^\]]*\][^{}]*\}')


def fetch(perf):
    url = PAGE.format(perf=perf)
    request = urllib.request.Request(
        url,
        headers={
            # Lichess asks that bots identify themselves. This runs by hand,
            # three times, when a human regenerates the table.
            "User-Agent": "QuantifiedLife ruler snapshot (https://quantifiedlife.io/methods)",
        },
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        if response.status != 200:
            raise SystemExit(f"{url}: HTTP {response.status}")
        html = response.read().decode("utf-8")
    match = FREQ.search(html)
    if match is None:
        raise SystemExit(
            f"{url}: no embedded rating histogram found. Lichess has changed the "
            "page shape; do not guess at the numbers, read the page and fix this script."
        )
    freq = json.loads(match.group(0))["freq"]
    if len(freq) != BUCKETS:
        raise SystemExit(
            f"{url}: {len(freq)} buckets, expected {BUCKETS} "
            f"({MIN_RATING}..{MAX_RATING} by {GROUP}). Lichess has moved its axis; "
            "re-read lila's PerfStatApi before touching the constants above."
        )
    if any(not isinstance(n, int) or n < 0 for n in freq):
        raise SystemExit(f"{url}: histogram holds a non-count")
    if sum(freq) <= 0:
        raise SystemExit(f"{url}: empty histogram")
    return freq


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--snapshot-date",
        default=datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d"),
        help="the date this snapshot is stamped with (default: today, UTC)",
    )
    args = parser.parse_args()

    pools = {}
    for perf, label in POOLS.items():
        freq = fetch(perf)
        pools[perf] = {
            "pool_label": label,
            "n": sum(freq),
            "freq": freq,
        }
        print(f"{perf}: {sum(freq):,} rated players across {BUCKETS} groups", file=sys.stderr)

    table = {
        "id": "chess_lichess_distribution_v1",
        "version": 1,
        "snapshot_date": args.snapshot_date,
        # How this ruler ages (ADR 0154). Lichess publishes only the current
        # histogram, so the table DRIFTS from the day after it is scraped.
        "staleness": {
            "policy": "DRIFTS",
            "max_age_days": 90,
            "rationale": (
                "Lichess recomputes this histogram weekly and publishes only the current one, "
                "so our copy starts diverging the day after it is scraped. Re-fetching costs "
                "one page load, which is why the threshold here is tighter than the strength "
                "ruler's."
            ),
        },
        "source": {
            "name": "Lichess",
            "url": "https://lichess.org",
            "data_url": "https://lichess.org/stat/rating/distribution/blitz",
            "license": "Lichess publishes this histogram on its own public statistics page; its "
            "database exports are released under CC0 and its site code under AGPL-3.0. "
            "We reproduce the counts with attribution and a link back.",
            "attribution": "Weekly rating distribution published by Lichess "
            "(lichess.org/stat/rating/distribution).",
        },
        "pipeline": {
            "script": "scripts/rulers/fetch_lichess_distribution.py",
            "min_rating": MIN_RATING,
            "group": GROUP,
            "max_rating": MAX_RATING,
            "note": "Lichess's own histogram, copied verbatim. Nothing is fitted, smoothed, "
            "interpolated or pooled across speeds. Bucket i counts established players "
            f"rated [{MIN_RATING} + {GROUP}i, {MIN_RATING} + {GROUP}i + {GROUP}). The "
            "percentile read off it is Lichess's own rule: a player counts as above a "
            "bucket when their rating exceeds that bucket's midpoint.",
        },
        "pools": pools,
    }
    with open(OUT, "w", encoding="utf-8") as handle:
        json.dump(table, handle, indent=1, sort_keys=True)
        handle.write("\n")
    print(f"wrote {OUT}")


if __name__ == "__main__":
    main()

What we show.One League standing: the highest current rank across ranked solo, ranked flex and every configured Riot account. The band is Riot’s tier and division — “Gold II”, or the bare apex name “Master” — and the number beside it is Riot’s whole in-division LP from the lptag. The metric’s numeric value is a continuous ladder encoding for charts; it is not display LP and never appears on the receipt as if it were.

No rating of ours.We do not calculate MMR, smooth Riot’s rank, or rename their tiers. A demotion changes the current row without ceremony and is not an event. A newly higher all-time named peak is a promotion: the weekly letter dates it, and the receipt keeps the full-history line “Peak: Gold II — 12 May 2026” permanently even if the current row later moves down.

Best of, never a blend.Each (queue, account) pair is its own entity with its own history, and the standing is the one whole entity currently standing highest — its tier, its division, its LP, its account name on the receipt. Ties break by LP, then queue and account name in fixed order, so the answer is deterministic. Accounts are never pooled: a peak from one account cannot attach to another account’s current rank, and the receipt lists every entity’s own current rank so “best” is inspectable rather than asserted.

Riot serves current ladder snapshots through LEAGUE-V4, not a history endpoint. QuantifiedLife observes those snapshots daily, replays the history it has actually seen, freezes gaps, and marks a standing stale after 60 days without a valid observation for the leading entity.

The population context, and whose it is.Riot does not publish a ranked distribution alongside the ladder, so the “above N%” line on a League receipt cites League of Graphs’ rank distribution — their published shares of recently active ranked players, computed from the Riot API — frozen at a dated capture: patch 16.6, all regions, archived 2026-03-26. It is not Riot’s official figure, and the pool is players who queued recently, not everyone with an account.

Which sums are ours.The source publishes each rung’s share; the cumulative “share below your rung” is our addition over their published numbers, disclosed as ours on every receipt that prints one. Solo/duo is published per division, so a Gold II reader gets the share below Gold II exactly; flex is published per tier only, so a flex receipt says “at least” and refuses to resolve the division position the source does not publish. We still derive no MMR, scrape no league tables — this is a hand transcription of one archived page, dated and attributed — and estimate nothing from our own users.

Rank distribution from League of Graphs (leagueofgraphs.com), all regions, as archived 26 March 2026 (patch 16.6). League of Legends and Riot Games are trademarks of Riot Games, Inc.; League of Graphs is not endorsed by Riot Games.

The transcription, in full

The source’s terms rule out automated pulls, so this table is a hand transcription of one archived page, and the script below is what wrote it — with the checks it refuses to write without. Solo division shares ride in it too; the tier table above is their sums.

#!/usr/bin/env python3
"""Vendor League of Graphs' ranked-tier distribution as a frozen snapshot.

A ONE-OFF, OFFLINE re-keying on vendor_friend_vo2max.py's pattern: it writes a
versioned JSON table that is checked in, cited, and served verbatim, published
on /methods so anybody can re-run it and get the same table.

Source
    League of Graphs, "Rank distribution", all regions, as captured by the
    Internet Archive on 2026-03-26 (patch 16.6) — the newest archived capture;
    the live page 403s automated fetches and its terms prohibit automated
    queries, so the pipeline here is a HAND transcription of one dated
    archived page, which is neither scraping nor a scheduled pull:
    http://web.archive.org/web/20260326144525/https://www.leagueofgraphs.com/rankings/rank-distribution

    League of Graphs computes its statistics from the Riot Games API. This
    table is their published distribution reproduced as a small dated factual
    excerpt with attribution; it is not Riot's official figure, and nothing
    here derives an MMR or a rating (the ruler rule, ADR 0134).

    Riot's 2026-03-02 /dev post ("MMR-to-Rank Distribution",
    https://www.leagueoflegends.com/en-us/news/dev/dev-mmr-to-rank-distribution/)
    is the citation for why any pre-March-2026 distribution is stale: the
    ladder was recalibrated that week. This snapshot post-dates it.

What we take, and in what form
    Ranked SOLO/DUO: the per-division "Rank %" shares (I/II/III/IV per tier)
    plus the apex-tier shares. Ranked FLEX: the per-tier shares — League of
    Graphs publishes flex at tier grain only. Shares are percentages of the
    recently-active ranked population as League of Graphs counts it; the
    page's own rounding makes each queue sum to roughly, not exactly, 100.

    Any cumulative ("top X%" / "above N%") number a surface prints is OUR
    addition over these published shares, and every surface that prints one
    says so — the ADR 0155 disclosure rule for arithmetic of ours over
    numbers of theirs.

VERIFICATION
    Shares below were transcribed by hand from the archived page and are
    checked before writing: every division share is positive, division sums
    match the transcription, and each queue's total lands inside [97, 103]
    (the page's own rounding tolerance).
"""

import json
import pathlib

OUT = pathlib.Path(__file__).resolve().parents[2] / (
    "go/platform/rulers/tables/lol_leagueofgraphs_distribution.json"
)

# Ranked solo/duo, all regions, 2026-03-26 (patch 16.6): tier -> division
# shares in LADDER order (IV lowest first), apex tiers as a bare share.
SOLO = [
    ("iron", {"iv": 0.15, "iii": 0.23, "ii": 0.61, "i": 1.4}),
    ("bronze", {"iv": 4.6, "iii": 3.9, "ii": 4.3, "i": 4.1}),
    ("silver", {"iv": 6.9, "iii": 6.0, "ii": 5.9, "i": 4.7}),
    ("gold", {"iv": 8.6, "iii": 6.2, "ii": 5.6, "i": 4.0}),
    ("platinum", {"iv": 7.1, "iii": 4.5, "ii": 3.6, "i": 2.4}),
    ("emerald", {"iv": 4.4, "iii": 2.4, "ii": 1.8, "i": 1.5}),
    ("diamond", {"iv": 1.8, "iii": 0.78, "ii": 0.57, "i": 0.62}),
    ("master", 1.1),
    ("grandmaster", 0.082),
    ("challenger", 0.034),
]

# Ranked flex, all regions, same capture: tier shares only.
FLEX = [
    ("iron", 2.2),
    ("bronze", 13.0),
    ("silver", 26.0),
    ("gold", 22.0),
    ("platinum", 18.0),
    ("emerald", 13.0),
    ("diamond", 4.3),
    ("master", 0.48),
    ("grandmaster", 0.057),
    ("challenger", 0.03),
]

DIVISION_ORDER = ["iv", "iii", "ii", "i"]


def queue(rows: list, label: str, granularity: str) -> dict:
    tiers = []
    total = 0.0
    for tier, shares in rows:
        if isinstance(shares, dict):
            divisions = []
            for division in DIVISION_ORDER:
                share = shares[division]
                assert share > 0, f"{tier} {division} share must be positive"
                divisions.append({"division": division, "share": share})
                total += share
            tiers.append(
                {
                    "tier": tier,
                    "share": round(sum(d["share"] for d in divisions), 3),
                    "divisions": divisions,
                }
            )
        else:
            assert shares > 0, f"{tier} share must be positive"
            tiers.append({"tier": tier, "share": shares})
            total += shares
    assert 97 <= total <= 103, f"{label} shares sum to {total:.2f}, outside [97, 103]"
    return {"pool_label": label, "granularity": granularity, "tiers": tiers}


def main() -> None:
    table = {
        "id": "lol_leagueofgraphs_distribution_v1",
        "version": 1,
        "snapshot_date": "2026-03-26",
        "source": {
            "name": "League of Graphs rank distribution",
            "url": "https://www.leagueofgraphs.com/rankings/rank-distribution",
            "data_url": "http://web.archive.org/web/20260326144525/https://www.leagueofgraphs.com/rankings/rank-distribution",
            "license": (
                "League of Graphs states no reuse license; this is a small "
                "dated factual excerpt reproduced with attribution, "
                "transcribed by hand from an archived capture, never an "
                "automated query. League of Graphs computes its statistics "
                "from the Riot Games API. This is not Riot's official "
                "distribution, and no MMR or rating is derived from it."
            ),
            "attribution": (
                "Rank distribution from League of Graphs "
                "(leagueofgraphs.com), all regions, as archived 26 March 2026 "
                "(patch 16.6). League of Legends and Riot Games are "
                "trademarks of Riot Games, Inc.; League of Graphs is not "
                "endorsed by Riot Games."
            ),
        },
        "staleness": {
            "policy": "DRIFTS",
            "max_age_days": 210,
            "rationale": (
                "The live distribution refreshes continuously and moves with "
                "season resets and Riot recalibrations (the 2026-03-02 "
                "MMR-to-rank recalibration reshaped Iron in a week, which is "
                "also why nothing older than March 2026 may replace this "
                "table). 210 days spans a ranked split with slack; the fix is "
                "re-transcribing a newer dated capture by hand — the source's "
                "terms rule out an automated pull."
            ),
        },
        "pipeline": {
            "script": "scripts/rulers/vendor_leagueofgraphs_lol.py",
            "capture": "Internet Archive, 2026-03-26 14:45:25 UTC",
            "patch": "16.6",
            "regions": "all",
            "note": (
                "Hand transcription of one dated archived page. Solo/duo is "
                "published per division; flex per tier only. Cumulative "
                "'above N%' figures a surface prints are our sums over these "
                "published shares, disclosed as ours."
            ),
        },
        "queues": {
            "ranked_solo": queue(
                SOLO,
                "recently active ranked solo/duo players across all regions",
                "division",
            ),
            "ranked_flex": queue(
                FLEX,
                "recently active ranked flex players across all regions",
                "tier",
            ),
        },
    }
    OUT.write_text(json.dumps(table, indent=1, sort_keys=True) + "\n")
    print(f"wrote {OUT}")


if __name__ == "__main__":
    main()

What we show.A band for your VO₂max — how much oxygen your body can use at full effort, in millilitres per kilogram of you per minute — read against people of the same published column and age decade. The number we place is the median of your last 28 days, not your best day: a VO₂max is a level, and a wrist estimate is noisy enough that taking its maximum would find your luckiest reading and call it fitness.

The gap we cannot close, and will not dress up. Your number is an estimate, worked out by a watch from your heart rate against your pace on an outdoor walk or run. Every number in the table below was measured, off a mask, on a treadmill, by a laboratory taking someone to exhaustion. Wrist estimates have run several mL/kg/min below a laboratory test in validation work, so expect this placement to read low. That gap is a bias, not a wobble — which is exactly why you will never see a plus-or-minus next to it here or in the app. An interval would dress a known, one-directional offset up as random noise, and that is the kind of false precision this whole page exists to refuse.

The pool, and its skew. apparently healthy US adults tested to exhaustion on a treadmill with a metabolic cart. Most of them turned up because somebody wanted their fitness measured, so this is not the general population either. A percentile here is a statement about that pool.

The table

The treadmill reference standards from the FRIEND registry, published 2022-02-01 and covering registry data through 2021-03-31: 16,278 maximal tests from 34 laboratories across the United States, with a maximal-effort criterion of peak RER >= 1.0. The article is open access under CC BY-NC-ND 4.0. The values below are facts re-keyed into our own structure, not a reproduction of the publisher's typeset table.

Kaminsky LA, Arena R, Myers J, Peterman JE, Bonikowske AR, Harber MP, Medina Inojosa JR, Lavie CJ, Squires RW. Updated Reference Standards for Cardiorespiratory Fitness Measured with Cardiopulmonary Exercise Testing: Data from the Fitness Registry and the Importance of Exercise National Database (FRIEND). Mayo Clinic Proceedings. 2022;97(2):285-293.

We take the treadmill column and not the cycle-ergometer one the same paper publishes, because the two sit about 4.5 mL/kg/min apart and your watch estimates from walking and running. Reading a wrist estimate against a cycle table would place you on an instrument nobody put you on. Read the paper — it is open access — and check every number below against its Table 3 (percentiles), Table 1 (sample sizes).

What sits between the printed numbers

The paper prints seven age decades and nine percentiles, and we interpolate straight lines between them — nothing smoother. Age: linear between decade midpoints, clamped flat outside 25-85. Each decade’s column is pinned at its midpoint (25, 35, … 85) and read linearly between midpoints, so your band cannot change on your birthday. Value: linear between published decile anchors; saturates at the 10th and 90th— beyond them we report “below the 10th” or “above the 90th” rather than inventing a 3rd or a 97th the paper never published.

We deliberately do not fit a curve through these anchors. A smooth model would look better and would be ours— it would turn somebody else’s cited facts into our own estimate while keeping their citation, which is the wrong direction for a page like this one.

The cut points, and whose they are

The band names are ours. The percentiles they sit at are 10, 30, 50, 70 and 90, read off the table above. So “Excellent” means “at or above the 90th percentile of apparently healthy US adults tested to exhaustion on a treadmill with a metabolic cartin your age decade” and nothing else. No registry, no professional body and no watch manufacturer issues these words — we chose them, and everything below the 10th percentile of that pool is the first band, Low.

The re-keying, in full

There is no archive to reduce here — FRIEND publishes a paper, not a dataset — so the numbers above were typed in by hand from the printed table. That is a step where a mistake is silent, so the script below refuses to write the table at all unless the re-keyed numbers reproduce the paper’s own sample sizes, its per-cell means from a second table, and the two decline statistics in its abstract. It is here, verbatim, for the same reason the other scripts are: a ruler nobody can re-derive is a black box with a citation stapled to it.

#!/usr/bin/env python3
"""Vendor the 2022 FRIEND VO2max reference standards as a frozen ruler (ADR 0134).

This is a ONE-OFF, OFFLINE re-keying. Nothing in the running platform calls it;
it writes a versioned JSON table that is checked in, cited, and served
verbatim. It is published on /methods so anybody can re-run it and get the same
table -- a ruler nobody can audit is a black box wearing a citation.

Unlike scripts/rulers/reduce_openpowerlifting.py there is no bulk archive to
reduce here. FRIEND publishes its reference standards as a PAPER, so the input
is a printed table and the honest pipeline is: re-key the numbers by hand, then
verify them hard enough that a transcription slip cannot survive. That is what
the VERIFICATION section below is for, and it is the whole reason this file
exists rather than a hand-written JSON blob.

Source
    Kaminsky LA, Arena R, Myers J, Peterman JE, Bonikowske AR, Harber MP,
    Medina Inojosa JR, Lavie CJ, Squires RW. "Updated Reference Standards for
    Cardiorespiratory Fitness Measured with Cardiopulmonary Exercise Testing:
    Data from the Fitness Registry and the Importance of Exercise National
    Database (FRIEND)." Mayo Clin Proc. 2022;97(2):285-293.
    https://doi.org/10.1016/j.mayocp.2021.08.020

    The version of record is open access under CC BY-NC-ND 4.0
    (http://creativecommons.org/licenses/by-nc-nd/4.0/), stated on the
    article's own first page.

What we take, and in what form
    The NUMBERS ONLY, re-keyed into our own structure (#559's licensing pass):
    Table 3's treadmill rows and Table 1's per-cell sample sizes and Table 4's
    per-cell means. We never reproduce the publisher's typeset table, never
    crop or screenshot it, and /methods redraws the cut points in our own
    design with the full citation beside them. Facts are not copyrightable
    (Feist v. Rural, 499 U.S. 340) and Elsevier's own permissions policy asks
    for no permission when creating an original table from factual data; what
    IS theirs is the typesetting, which we do not take.

    Anchor on the 2022 paper and NEVER mix the 2015 anchors into it: the 2022
    treadmill values run 1.5-4.6 mLO2/kg/min lower than 2015's, so a table
    holding some of each would be a ruler that measures nothing.

TREADMILL ONLY, and why
    The paper publishes treadmill and cycle-ergometer standards separately,
    and they are 4.5 mLO2/kg/min apart on average -- the same person places
    differently depending on which machine they were tested on. Every VO2max
    we hold is a wrist estimate derived from outdoor walking and running
    (Apple's HKQuantityTypeIdentifierVO2Max), so treadmill is the mode our
    instrument resembles. Vendoring cycle as well would be shipping a column
    nothing may honestly read.

RER >= 1.0, and why
    The paper's Table 3 uses peak RER >= 1.0 as its maximal-effort criterion
    and reports the RER >= 1.1 variant in a supplement. We take the printed
    Table 3. The paper itself observes the two criteria differ by <= 1.0
    mLO2/kg/min in the mean across every cell, which is smaller than the
    wearable bias the sheet already discloses.

Usage
    python3 scripts/rulers/vendor_friend_vo2max.py \
        --out go/platform/rulers/tables/cardio_friend_vo2max.json

    Run with --check to verify without writing.
"""

import argparse
import json
import sys

TABLE_ID = "cardio_friend_vo2max_v1"

# The article's own dates. SNAPSHOT_DATE is the issue the version of record
# appeared in; DATA_THROUGH is when the registry data behind it ends. A
# published reference standard does not drift the way a scraped histogram
# does -- it goes stale when a newer edition is published -- and /methods says
# so rather than letting a large "days old" number imply a decay that is not
# happening.
SNAPSHOT_DATE = "2022-02-01"
DATA_THROUGH = "2021-03-31"

# The day a human last read the DOI and confirmed this is still the current
# edition. This, not SNAPSHOT_DATE, is what the staleness monitor's clock runs
# from (ADR 0154): a re-check that finds nothing new changes no number here, so
# it must be recordable without touching the snapshot. Bump it when you look.
LAST_CHECKED_DATE = "2026-08-19"

# The percentiles the paper publishes: deciles, 10th through 90th. NOT the
# 5/10/25/50/75/90/95 grid #559's licensing pass guessed at from the 2015
# paper's shape -- the 2022 update prints deciles, and the anchors a ruler
# interpolates between have to be the ones its source actually published.
PERCENTILE_GRID = [10, 20, 30, 40, 50, 60, 70, 80, 90]

# The age axis. The paper bins by decade; we pin each decade's column at its
# MIDPOINT and interpolate linearly between midpoints, so nobody's band jumps
# on a birthday (#559). Outside 25..85 the nearest column is used unchanged
# and the surface says that it clamped.
AGE_KNOTS = [25, 35, 45, 55, 65, 75, 85]
AGE_LABELS = ["20-29", "30-39", "40-49", "50-59", "60-69", "70-79", "80-89"]

# The band cuts, on the published grid, and OUR names for the bands they
# start. ADR 0134: the names are ours, the percentiles they sit at are the
# table's, and /methods says exactly that. TIER_NAMES is one longer than
# TIER_CUTS -- the first name is the band BELOW the first cut.
TIER_CUTS = [10, 30, 50, 70, 90]
TIER_NAMES = ["Low", "Below average", "Fair", "Above average", "Good", "Excellent"]

# ---------------------------------------------------------------------------
# The re-keyed numbers. Everything below this line came off the printed page.
# ---------------------------------------------------------------------------

# Table 3, treadmill rows. percentile -> sex -> one value per age group, in
# AGE_LABELS order. Keyed exactly as printed, in mLO2*kg-1*min-1.
TREADMILL_PERCENTILES = {
    90: {
        "MALE": [58.6, 55.5, 50.8, 43.4, 37.1, 29.4, 22.8],
        "FEMALE": [49.0, 42.1, 37.8, 32.4, 27.3, 22.8, 20.8],
    },
    80: {
        "MALE": [54.5, 50.0, 45.2, 38.3, 32.0, 25.9, 21.4],
        "FEMALE": [44.8, 37.0, 33.0, 28.4, 24.3, 20.8, 18.4],
    },
    70: {
        "MALE": [51.9, 46.4, 40.9, 34.3, 28.7, 23.8, 20.0],
        "FEMALE": [41.8, 33.6, 30.0, 26.3, 22.4, 19.6, 17.3],
    },
    60: {
        "MALE": [49.0, 43.4, 37.9, 31.8, 26.5, 22.2, 18.4],
        "FEMALE": [39.0, 31.0, 27.7, 24.6, 20.9, 18.3, 16.0],
    },
    50: {
        "MALE": [46.5, 39.7, 35.3, 29.2, 24.6, 20.6, 17.6],
        "FEMALE": [36.6, 28.3, 25.7, 22.9, 19.6, 17.2, 15.4],
    },
    40: {
        "MALE": [43.6, 37.0, 32.4, 26.9, 22.8, 19.1, 16.6],
        "FEMALE": [34.0, 26.4, 23.9, 21.5, 18.3, 16.2, 14.7],
    },
    30: {
        "MALE": [40.0, 33.5, 29.7, 24.5, 20.7, 17.3, 16.1],
        "FEMALE": [30.8, 24.2, 21.8, 20.1, 17.0, 15.2, 13.7],
    },
    20: {
        "MALE": [35.2, 29.8, 26.7, 22.2, 18.5, 15.9, 14.8],
        "FEMALE": [27.2, 21.9, 19.7, 18.5, 15.4, 14.0, 12.6],
    },
    10: {
        "MALE": [28.6, 24.9, 22.1, 18.6, 15.8, 13.6, 12.9],
        "FEMALE": [22.5, 18.6, 17.2, 16.5, 13.4, 12.3, 11.4],
    },
}

# Table 1, treadmill, RER >= 1.0: how many tests each column is drawn from.
TREADMILL_N = {
    "MALE": [1278, 1473, 2119, 2082, 1663, 776, 173],
    "FEMALE": [1142, 1043, 1372, 1457, 1045, 549, 106],
}

# The totals the paper prints for those same cohorts, used below to catch a
# mis-keyed n rather than to be published.
PRINTED_N_TOTALS = {"MALE": 9564, "FEMALE": 6714}
PRINTED_TREADMILL_TESTS = 16278

# Table 4, treadmill, RER >= 1.0: the per-cell MEANS. These are re-keyed from
# a DIFFERENT table for one reason -- to check Table 3 against. They are not
# published in our JSON; nothing on any surface reads a mean.
TREADMILL_MEANS = {
    "MALE": [45.2, 40.0, 35.8, 30.2, 25.4, 21.2, 17.9],
    "FEMALE": [36.3, 29.5, 26.6, 23.8, 20.0, 17.5, 15.9],
}

# The two headline statistics the abstract states, reproduced below from the
# means above. If a re-keyed mean is wrong these stop matching.
PRINTED_DECLINE_PER_DECADE = 4.0  # mLO2*kg-1*min-1, treadmill, over 6 decades
PRINTED_DECLINE_PERCENT = 13.5

POOL_LABEL = (
    "apparently healthy US adults tested to exhaustion on a treadmill "
    "with a metabolic cart"
)

SOURCE = {
    "name": "FRIEND registry (Kaminsky et al., 2022)",
    "url": "https://doi.org/10.1016/j.mayocp.2021.08.020",
    "data_url": "https://www.mayoclinicproceedings.org/article/S0025-6196(21)00645-5/fulltext",
    "license": (
        "The article is open access under CC BY-NC-ND 4.0. The values below are "
        "facts re-keyed into our own structure, not a reproduction of the "
        "publisher's typeset table."
    ),
    "attribution": (
        "Reference values from Kaminsky LA, Arena R, Myers J, et al. Updated "
        "Reference Standards for Cardiorespiratory Fitness Measured with "
        "Cardiopulmonary Exercise Testing: Data from the Fitness Registry and the "
        "Importance of Exercise National Database (FRIEND). Mayo Clin Proc. "
        "2022;97(2):285-293. doi:10.1016/j.mayocp.2021.08.020"
    ),
    "citation": (
        "Kaminsky LA, Arena R, Myers J, Peterman JE, Bonikowske AR, Harber MP, "
        "Medina Inojosa JR, Lavie CJ, Squires RW. Updated Reference Standards for "
        "Cardiorespiratory Fitness Measured with Cardiopulmonary Exercise Testing: "
        "Data from the Fitness Registry and the Importance of Exercise National "
        "Database (FRIEND). Mayo Clinic Proceedings. 2022;97(2):285-293."
    ),
}


# ---------------------------------------------------------------------------
# VERIFICATION. Every check here exists to catch a transcription slip in the
# block above, because a hand-keyed ruler with no check is a rumour.
# ---------------------------------------------------------------------------


def verify(report):
    """Raise SystemExit on the first failure; report() every check that passed."""

    def fail(message):
        raise SystemExit("FRIEND table verification failed: " + message)

    grid = sorted(TREADMILL_PERCENTILES)
    if grid != sorted(PERCENTILE_GRID):
        fail("keyed percentiles %s do not match the grid %s" % (grid, PERCENTILE_GRID))

    for sex in ("MALE", "FEMALE"):
        # 1. Within one age column the value must rise with the percentile.
        for age_index, label in enumerate(AGE_LABELS):
            column = [TREADMILL_PERCENTILES[p][sex][age_index] for p in PERCENTILE_GRID]
            if any(b <= a for a, b in zip(column, column[1:])):
                fail("%s %s is not ascending across percentiles: %s" % (sex, label, column))

        # 2. Along one percentile row fitness must not RISE with age. The
        #    paper's own finding is a monotone decline; equality is allowed
        #    (women's 90th is flat from 70-79 to 80-89) but a rise means a
        #    column was keyed out of order.
        for p in PERCENTILE_GRID:
            row = TREADMILL_PERCENTILES[p][sex]
            if any(b > a for a, b in zip(row, row[1:])):
                fail("%s p%d rises with age: %s" % (sex, p, row))

        if len(TREADMILL_N[sex]) != len(AGE_LABELS):
            fail("%s has %d sample counts for %d age groups" % (sex, len(TREADMILL_N[sex]), len(AGE_LABELS)))
        if sum(TREADMILL_N[sex]) != PRINTED_N_TOTALS[sex]:
            fail("%s sample counts sum to %d, printed total is %d"
                 % (sex, sum(TREADMILL_N[sex]), PRINTED_N_TOTALS[sex]))

    # 3. The two per-sex totals must add to the treadmill test count in the
    #    abstract.
    total = sum(PRINTED_N_TOTALS.values())
    if total != PRINTED_TREADMILL_TESTS:
        fail("sample counts total %d, abstract says %d treadmill tests" % (total, PRINTED_TREADMILL_TESTS))
    report("sample counts: %d men + %d women = %d treadmill tests, as printed"
           % (PRINTED_N_TOTALS["MALE"], PRINTED_N_TOTALS["FEMALE"], total))

    # 4. Men above women in every cell -- the paper states this for every age
    #    group, so a swapped pair of columns dies here.
    for p in PERCENTILE_GRID:
        for age_index, label in enumerate(AGE_LABELS):
            male = TREADMILL_PERCENTILES[p]["MALE"][age_index]
            female = TREADMILL_PERCENTILES[p]["FEMALE"][age_index]
            if male <= female:
                fail("p%d %s: men %.1f is not above women %.1f" % (p, label, male, female))
    report("men above women in all %d cells, as the paper states"
           % (len(PERCENTILE_GRID) * len(AGE_LABELS)))

    # 5. CROSS-TABLE. Each cell's mean (Table 4) must land between that cell's
    #    40th and 60th percentile (Table 3). The two tables were keyed from
    #    different pages, so a slip in either breaks this, and a slip near the
    #    middle of a distribution -- the values a real reading is most likely
    #    to land on -- is exactly what it catches.
    for sex in ("MALE", "FEMALE"):
        for age_index, label in enumerate(AGE_LABELS):
            mean = TREADMILL_MEANS[sex][age_index]
            low = TREADMILL_PERCENTILES[40][sex][age_index]
            high = TREADMILL_PERCENTILES[60][sex][age_index]
            if not low <= mean <= high:
                fail("%s %s: mean %.1f is outside its own 40th-60th percentile [%.1f, %.1f]"
                     % (sex, label, mean, low, high))
    report("every cell's mean sits inside its own 40th-60th percentile (Table 4 vs Table 3)")

    # 6. CROSS-ABSTRACT. Reproduce the abstract's decline-per-decade figures
    #    from the keyed means. Six decades separate the 20s column from the
    #    80s column.
    decades = len(AGE_LABELS) - 1
    absolute = []
    percent = []
    for sex in ("MALE", "FEMALE"):
        youngest = TREADMILL_MEANS[sex][0]
        oldest = TREADMILL_MEANS[sex][-1]
        absolute.append((youngest - oldest) / decades)
        percent.append((1 - (oldest / youngest) ** (1.0 / decades)) * 100)
    got_absolute = sum(absolute) / len(absolute)
    got_percent = sum(percent) / len(percent)
    if abs(got_absolute - PRINTED_DECLINE_PER_DECADE) > 0.1:
        fail("decline per decade computes to %.2f, abstract says %.1f"
             % (got_absolute, PRINTED_DECLINE_PER_DECADE))
    if abs(got_percent - PRINTED_DECLINE_PERCENT) > 0.5:
        fail("percent decline per decade computes to %.2f, abstract says %.1f"
             % (got_percent, PRINTED_DECLINE_PERCENT))
    report("decline per decade recomputes to %.2f mLO2/kg/min and %.1f%%, "
           "abstract says %.1f and %.1f%%"
           % (got_absolute, got_percent, PRINTED_DECLINE_PER_DECADE, PRINTED_DECLINE_PERCENT))

    # 7. Our band cuts have to be ON the published grid, or a band floor would
    #    be a number we invented rather than one the table printed.
    for cut in TIER_CUTS:
        if cut not in PERCENTILE_GRID:
            fail("band cut %s is not on the published percentile grid" % cut)
    if len(TIER_NAMES) != len(TIER_CUTS) + 1:
        fail("%d band names for %d cuts" % (len(TIER_NAMES), len(TIER_CUTS)))
    report("band cuts %s all sit on the published grid" % TIER_CUTS)

    if len(AGE_KNOTS) != len(AGE_LABELS):
        fail("%d age knots for %d age groups" % (len(AGE_KNOTS), len(AGE_LABELS)))
    report("all checks passed")


def build():
    columns = {}
    for sex in ("FEMALE", "MALE"):
        knots = []
        for age_index, age in enumerate(AGE_KNOTS):
            knots.append(
                {
                    "age_years": age,
                    "age_label": AGE_LABELS[age_index],
                    "n": TREADMILL_N[sex][age_index],
                    "vo2max": [
                        TREADMILL_PERCENTILES[p][sex][age_index] for p in PERCENTILE_GRID
                    ],
                }
            )
        columns[sex] = knots

    return {
        "id": TABLE_ID,
        "version": 1,
        "snapshot_date": SNAPSHOT_DATE,
        # How this ruler ages (ADR 0154), and it is not by the calendar. A
        # paper does not drift; it is SUPERSEDED, once, when the registry
        # publishes a newer edition. LAST_CHECKED_DATE is the clock — the day
        # somebody last read the DOI — and bumping it is a one-line commit
        # that records a real check without faking a snapshot.
        "staleness": {
            "policy": "SUPERSEDED",
            "recheck_every_days": 365,
            "last_checked_date": LAST_CHECKED_DATE,
            "recheck_question": (
                "Has the FRIEND registry published a cardiorespiratory-fitness reference "
                "standard newer than the 2022 edition (Kaminsky et al., Mayo Clin Proc "
                "2022;97(2):285-293)?"
            ),
            "recheck_url": "https://doi.org/10.1016/j.mayocp.2021.08.020",
            "rationale": (
                "This is a paper, not a feed. The 2022 percentiles do not change, so the "
                "snapshot date being years ago is not decay, and reporting it as decay would "
                "be a false alarm that trains everyone to ignore the real one. It goes stale "
                "exactly once — when the registry publishes a newer edition, as it did in "
                "2015, 2017, 2019 and 2022 — and no age threshold of ours can detect that, "
                "because the signal is on a DOI a human has to read. So the monitor asks on a "
                "yearly cadence, comfortably inside the shortest gap between editions, and "
                "the clock it runs from is the day somebody last looked rather than the day "
                "the paper was published."
            ),
        },
        "source": SOURCE,
        "pipeline": {
            "script": "scripts/rulers/vendor_friend_vo2max.py",
            "mode": "treadmill",
            "effort_criterion": "peak RER >= 1.0",
            "source_table": "Table 3 (percentiles), Table 1 (sample sizes)",
            "data_through": DATA_THROUGH,
            "tests": PRINTED_TREADMILL_TESTS,
            "age_interpolation": "linear between decade midpoints, clamped flat outside 25-85",
            "value_interpolation": "linear between published decile anchors; saturates at the 10th and 90th",
            "note": (
                "The published percentiles, re-keyed by hand and verified against the "
                "paper's own sample sizes, per-cell means and abstract statistics. "
                "Nothing is fitted, smoothed or regressed: a curve of ours through "
                "somebody else's anchors would be our model wearing their citation."
            ),
        },
        "pool_label": POOL_LABEL,
        "percentile_grid": PERCENTILE_GRID,
        "tier_cuts": TIER_CUTS,
        "tier_names": TIER_NAMES,
        "columns": columns,
    }


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--out", help="where to write the table")
    parser.add_argument("--check", action="store_true", help="verify only, write nothing")
    args = parser.parse_args()

    verify(lambda line: print("ok: " + line, file=sys.stderr))
    if args.check:
        return
    if not args.out:
        raise SystemExit("--out is required unless --check is given")

    table = build()
    with open(args.out, "w", encoding="utf-8") as handle:
        json.dump(table, handle, indent=1, sort_keys=True)
        handle.write("\n")
    print("wrote " + args.out, file=sys.stderr)


if __name__ == "__main__":
    main()

What we show.A band for your nightly heart-rate variability — RMSSD, in milliseconds, the number a WHOOP strap or an Oura ring reports for a night’s sleep. The number we place is the median of your last 28 nights: nightly HRV swings with a late meal or a drink, and the middle of a month is the level, where a best would just find your calmest night and call it fitness.

The pool. Fitbit wearers worldwide in the sleep-dominated 6-7am hour: 8,203,261people, in the study’s own words a sleep-dominated hour, measured as RMSSD over 5-min windows; per user, the median of acceptable windows within the hour. People who bought a fitness tracker and wore it to bed are more health-attentive than the general population, and Fitbit’s nightly arithmetic is not your vendor’s — same construct, a few milliseconds of definitional slack. Both caveats print on the receipt.

Quartiles, and nothing finer.The appendix publishes the 25th, 50th and 75th percentiles per sex per age bin — no tails. So the four bands are the quartiles under our names, the highest placement this ruler can honestly show is the top quarter, and a reading outside the published anchors says “below the 25th” or “above the 75th” rather than inventing a 5th or a 95th. The rank the app wears for it caps one rung below the ladder’s top for the same reason: a ruler that cannot see past the 75th percentile does not award its highest mark.

Natarajan A, Pantelopoulos A, Emir-Farinas H, Natarajan P. Heart rate variability with photoplethysmography in 8 million individuals: a cross-sectional study. Lancet Digital Health. 2020;2(12):e650-e657.

The article is open access under CC BY-NC-ND 4.0. The values here are facts re-keyed into our own structure, not a reproduction of the publisher's typeset appendix. Read the appendix and check every number below against its Supplementary appendix Table S3, RMSSD, 0600-0700h.

Between the printed bins: linear between bin centers, clamped flat outside 20.5-60.5, so a band cannot change on a birthday, and outside 20–61 the nearest published bin is read with the clamp stated on the sheet. Nothing is fitted — the paper’s own power-law model is deliberately not used, because a fitted curve is the authors’ estimate and this page only reproduces their anchors.

Direction, narrowly. A higher nightly RMSSD quartile is the rewarded direction within the ordinary range, which is what lets this category carry a band at all. An HRV far outside that range — either way — is a conversation with a doctor, not a score, and the sheet says so.

The re-keying, in full

The quartiles were typed in by hand from the published appendix and cross-checked against the preprint’s identical table; the script refuses to write the table unless every bin’s quartiles ascend and every column’s medians fall with age, both true of the source.

#!/usr/bin/env python3
"""Vendor the Natarajan 2020 nightly-RMSSD reference values as a frozen ruler.

A ONE-OFF, OFFLINE re-keying, on vendor_friend_vo2max.py's pattern: nothing in
the running platform calls it; it writes a versioned JSON table that is checked
in, cited, and served verbatim, and it is published on /methods so anybody can
re-run it and get the same table.

Source
    Natarajan A, Pantelopoulos A, Emir-Farinas H, Natarajan P. "Heart rate
    variability with photoplethysmography in 8 million individuals: a
    cross-sectional study." Lancet Digital Health. 2020;2(12):e650-e657.
    https://doi.org/10.1016/S2589-7500(20)30246-6

    The article is open access under CC BY-NC-ND 4.0. The percentile values
    live in the supplementary appendix (mmc1.pdf), Table S3 ("HRV Features -
    Time Domain"); the bioRxiv preprint (https://doi.org/10.1101/772285)
    publishes the same medians and quartiles in machine-readable text and is
    the cross-check used below.

What we take, and in what form
    The NUMBERS ONLY, re-keyed into our own structure (the FRIEND licensing
    pass, unchanged): Table S3's RMSSD rows for the 0600-0700h block — the
    sleep-dominated hour, the paper's own words ("significantly more usable
    data when the subjects were asleep") — per sex, per published age bin:
    the 25th percentile, the median, and the 75th percentile, in
    milliseconds. Facts are not copyrightable (Feist v. Rural, 499 U.S. 340);
    the publisher's typeset table is never reproduced, cropped or
    screenshotted, and /methods redraws the quartiles in our own design with
    the full citation beside them.

    The 1800-1900h (awake) block is deliberately NOT vendored: our input is
    the nightly sleep RMSSD a WHOOP strap or an Oura ring reports, and the
    awake block is a different physiological state wearing the same unit.

    The paper's own power-law fit (appendix Table S1) is also NOT vendored:
    a fitted curve is the authors' model, and the ruler rule is anchors only,
    interpolated linearly between the published bins — a curve of ours (or
    theirs) through the anchors would smooth what the source actually says.

Age bins
    The appendix publishes one-year slices at five-year spacing ("age = 20
    includes users between 20 and 21"), 20 through 60. Each bin's knot sits
    at its center (20.5, 25.5, ... 60.5); the platform interpolates linearly
    between knots and clamps flat outside them, stating both on the sheet.

Per-bin sample sizes
    Table S1 publishes user counts by decade, not by the S3 bins, so the
    knots carry n=0 ("not published at this grain") and every surface cites
    the study-level pool instead: 8,203,261 included users.

VERIFICATION
    Every value below was read from the published appendix PDF
    (https://ars.els-cdn.com/content/image/1-s2.0-S2589750020302466-mmc1.pdf,
    rasterized — the digit font defeats text extraction) and cross-checked
    against the bioRxiv preprint's identical table. Two invariants are
    enforced before writing: quartiles strictly ascend within every knot, and
    medians strictly descend with age within every sex — both true of the
    published table, and either failing means a transcription slip.
"""

import json
import pathlib

OUT = pathlib.Path(__file__).resolve().parents[2] / (
    "go/platform/rulers/tables/hrv_natarajan_rmssd.json"
)

# Table S3, RMSSD (ms), 0600-0700h block: age bin -> (p25, p50, p75).
FEMALE = {
    20: (37, 56, 85),
    25: (32, 48, 73),
    30: (31, 45, 67),
    35: (29, 41, 60),
    40: (26, 37, 52),
    45: (24, 33, 46),
    50: (22, 31, 42),
    55: (22, 29, 40),
    60: (21, 28, 38),
}
MALE = {
    20: (45, 66, 96),
    25: (35, 54, 79),
    30: (34, 49, 71),
    35: (31, 43, 62),
    40: (27, 38, 54),
    45: (25, 34, 48),
    50: (23, 31, 42),
    55: (21, 29, 39),
    60: (20, 27, 37),
}

# The study-level pool: 10,424,196 sampled, 8,203,261 included (paper, Methods).
INCLUDED_USERS = 8_203_261


def knots(rows: dict) -> list:
    out = []
    for age, (p25, p50, p75) in sorted(rows.items()):
        assert p25 < p50 < p75, f"quartiles not ascending at age {age}"
        out.append(
            {
                "age_label": f"{age}-{age + 1}",
                "age_years": age + 0.5,
                "n": 0,
                "rmssd": [p25, p50, p75],
            }
        )
    medians = [k["rmssd"][1] for k in out]
    assert medians == sorted(medians, reverse=True), "medians not descending with age"
    return out


def main() -> None:
    table = {
        "id": "hrv_natarajan_rmssd_v1",
        "version": 1,
        "snapshot_date": "2020-12-01",
        "source": {
            "name": "Natarajan et al., Lancet Digital Health 2020",
            "url": "https://doi.org/10.1016/S2589-7500(20)30246-6",
            "data_url": "https://ars.els-cdn.com/content/image/1-s2.0-S2589750020302466-mmc1.pdf",
            "license": (
                "The article is open access under CC BY-NC-ND 4.0. The values "
                "here are facts re-keyed into our own structure, not a "
                "reproduction of the publisher's typeset appendix."
            ),
            "attribution": (
                "Reference values from Natarajan A, Pantelopoulos A, "
                "Emir-Farinas H, Natarajan P. Heart rate variability with "
                "photoplethysmography in 8 million individuals: a "
                "cross-sectional study. Lancet Digit Health. "
                "2020;2(12):e650-e657. doi:10.1016/S2589-7500(20)30246-6"
            ),
            "citation": (
                "Natarajan A, Pantelopoulos A, Emir-Farinas H, Natarajan P. "
                "Heart rate variability with photoplethysmography in 8 million "
                "individuals: a cross-sectional study. Lancet Digital Health. "
                "2020;2(12):e650-e657."
            ),
        },
        "staleness": {
            "policy": "SUPERSEDED",
            "last_checked_date": "2026-08-20",
            "recheck_every_days": 365,
            "recheck_question": (
                "Has a larger consumer-PPG, sleep-window RMSSD percentile "
                "reference been published that supersedes Natarajan 2020 — in "
                "particular, a peer-reviewed Apple Heart & Movement Study or "
                "All of Us HRV reference table with age/sex percentiles?"
            ),
            "recheck_url": "https://doi.org/10.1016/S2589-7500(20)30246-6",
            "rationale": (
                "A paper does not drift: the 2020 quartiles do not change, so "
                "snapshot age is not decay. It goes stale exactly once — when "
                "a larger compatible-instrument reference is published — and "
                "only a human reading the literature can see that, so the "
                "monitor asks yearly."
            ),
        },
        "pipeline": {
            "script": "scripts/rulers/vendor_natarajan_hrv.py",
            "source_table": "Supplementary appendix Table S3, RMSSD, 0600-0700h",
            "hour_block": "0600-0700h, the sleep-dominated hour",
            "window_method": (
                "RMSSD over 5-min windows; per user, the median of acceptable "
                "windows within the hour"
            ),
            "age_interpolation": "linear between bin centers, clamped flat outside 20.5-60.5",
            "value_interpolation": "linear between published quartile anchors; saturates at the 25th and 75th",
            "included_users": INCLUDED_USERS,
            "note": (
                "The published quartiles, re-keyed by hand and cross-checked "
                "against the bioRxiv preprint (10.1101/772285). Nothing is "
                "fitted or smoothed; the paper's own power-law fit is "
                "deliberately not used."
            ),
        },
        "pool_label": "Fitbit wearers worldwide in the sleep-dominated 6-7am hour",
        "percentile_grid": [25, 50, 75],
        "tier_cuts": [25, 50, 75],
        "tier_names": ["Bottom quarter", "Below median", "Above median", "Top quarter"],
        "columns": {"FEMALE": knots(FEMALE), "MALE": knots(MALE)},
    }
    OUT.write_text(json.dumps(table, indent=1, sort_keys=True) + "\n")
    print(f"wrote {OUT}")


if __name__ == "__main__":
    main()

What we show.A band for your daily step count, as Apple Health’s cross-source daily total or an Oura ring reports it. The number we place is the median across your last 28 days: a single day swings with the weather, the middle of a month is the level, and a best would just find your one long hike.

The pool. All of Us research participants who wore a Fitbit, combined bring-your-own-device and free-device cohorts: 54,509participants of the All of Us Research Program’s general activity cohort, each contributing their own median daily steps over their whole donation window. The paper itself calls the cohort a broad convenience sample, not representative of the US population — many participants were given their device free by the program’s device-distribution study — and that caveat prints on the receipt.

The sex column, and nothing crossed. Table 2 publishes sex and age strata separately, never jointly; this ruler places against the sex column alone and the sheet says so. The published age rows ride in age_context for /methods only. Fabricating a joint sex-by-age distribution from two published marginals would be modeling, and this page only reproduces anchors.

Quartiles, and nothing finer.Table 2 publishes the 25th, 50th and 75th percentiles per stratum — no tails. So the four bands are the quartiles under our names, the highest placement this ruler can honestly show is the top quarter, and a reading outside the published anchors says “below the 25th” or “above the 75th” rather than inventing a 5th or a 95th. The rank the app wears for it caps one rung below the ladder’s top for the same reason.

The number is gameable, and the sheet says so. Steps are the easiest metric on the standings page to inflate — a wrist swung at a desk counts, and no ruler can tell it from a walk. The receipt carries that sentence verbatim, because a placement that pretends otherwise is a placement you can buy with a hand gesture.

The instrument.The pool wore Fitbit devices and the program ingests Fitbit’s own summaries; your steps come from a different vendor’s algorithm. The paper notes step estimates are algorithm-sensitive — cohorts measured with raw accelerometry report roughly 9,000–9,600 steps a day where this pool’s median is 6,454. As a sanity cross-check on the consumer-wearable construct: eFHS (Shapira-Daniels et al., JMIR 2023;25:e43123, CC BY; Apple Watch, n = 923): median 7,227 (IQR 5,699-8,970) daily steps — a different instrument, cited as a sanity cross-check only.

Patten T, Preble EA, Master H, et al. The All of Us Research Program's wearables dataset. Nature Medicine. 2026;32:2302-2310.

The article is open access under CC BY 4.0. The values here are facts re-keyed into our own structure, not a reproduction of the publisher's table. Read the table and check every number below against its Table 2, median (IQR) daily steps, general activity cohort.

The re-keying, in full

The quartiles were typed in by hand from the journal’s own HTML table (the article is CC BY 4.0); the script refuses to write the table unless every stratum’s quartiles ascend and the published female quartiles sit below the male at every anchor, both true of the source.

#!/usr/bin/env python3
"""Vendor the All of Us daily-steps reference quartiles as a frozen ruler.

A ONE-OFF, OFFLINE re-keying on vendor_natarajan_hrv.py's pattern: nothing in
the running platform calls it; it writes a versioned JSON table that is
checked in, cited, and served verbatim, and it is published on /methods so
anybody can re-run it and get the same table.

Source
    Patten T, Preble EA, Master H, et al. "The All of Us Research Program's
    wearables dataset." Nature Medicine. 2026;32:2302-2310.
    https://doi.org/10.1038/s41591-026-04352-3

    The article is open access under CC BY 4.0 (verified on the article's
    "Rights and permissions" section, 2026-08-22), which permits reuse and
    adaptation with attribution. The values live in Table 2 ("Baseline
    wearables outcomes by cohort with select demographic group comparisons"),
    which the journal publishes as an HTML table — no PDF rasterization was
    needed; the numbers below were read from
    https://www.nature.com/articles/s41591-026-04352-3/tables/2 on
    2026-08-22.

What we take, and in what form
    The NUMBERS ONLY, re-keyed into our own structure (the FRIEND licensing
    pass, unchanged): Table 2's median (IQR) daily steps for the GENERAL
    ACTIVITY COHORT column — the combined BYOD + WEAR pool, n = 54,509 —
    per published sex-at-birth stratum. Facts are not copyrightable (Feist
    v. Rural, 499 U.S. 340); the publisher's table is never reproduced,
    and /methods redraws the quartiles in our own design with the full
    citation beside them.

    The BYOD-only and WEAR-only columns are deliberately NOT vendored: the
    split is a recruitment artifact (bring-your-own-device versus a free
    distributed device), not a population a reader belongs to, and the
    combined cohort is the paper's own headline pool.

    ⚠ Table 2's strata cross sex OR age, NEVER both — no joint sex x age
    distribution is published, so this ruler places against the sex column
    alone and SAYS SO. The age rows and the full-cohort row are carried in
    the JSON as published context for /methods (the age gradient is real:
    the 75-84 row's median is 5,098 and the 85+ row's 3,460, against 6,454
    overall), but nothing places against them: fabricating a joint
    distribution from two marginals is exactly the modeling the ruler rule
    refuses.

    Suppressed strata (Intersex, Other, "Prefer not to answer" — n < 20
    under the All of Us Data and Statistics Dissemination Policy) publish
    no quartiles and therefore cannot be columns.

Instrument
    The pool wore Fitbit devices (41 models; the program ingests Fitbit API
    summaries, not raw accelerometry). Our metric is /health/activity/steps
    from Apple Health's cross-source daily dedup or an Oura ring. The paper
    itself notes step estimates are algorithm-sensitive (UK Biobank and
    NHANES report ~9,000-9,600 steps/day from raw accelerometry, versus
    6,454 here) — the sheet carries that caveat. Compatible-instrument
    cross-check, NOT vendored (different device, small n): Shapira-Daniels
    et al., eFHS, J Med Internet Res 2023;25:e43123 (CC BY; Apple Watch;
    n = 923) reports median 7,227 (IQR 5,699-8,970) daily steps.

VERIFICATION
    Every value below was read from the published HTML table and the
    invariants enforced before writing: quartiles strictly ascend within
    every stratum, the female medians sit below the male medians (true of
    the published table), and the per-stratum n values sum to less than the
    cohort n (Unknown/Intersex/Other rows are suppressed or unpublished).
    Any failure means a transcription slip.
"""

from __future__ import annotations

import json
import pathlib

OUT = (
    pathlib.Path(__file__).resolve().parents[2]
    / "go"
    / "platform"
    / "rulers"
    / "tables"
    / "steps_allofus_daily.json"
)

# Table 2, "General activity cohort" column: median (n; IQR) daily steps.
FULL_COHORT = {"n": 54509, "steps": [4432.0, 6454.0, 8958.0]}
COLUMNS = {
    "FEMALE": {"label": "Female", "n": 37161, "steps": [4225.0, 6114.0, 8442.0]},
    "MALE": {"label": "Male", "n": 17134, "steps": [5046.0, 7264.0, 10001.0]},
}
# The published age rows, context only (see the module docstring): the ruler
# never places against them because sex x age is not published jointly.
AGE_CONTEXT = [
    {"age_label": "18-24", "n": 2878, "steps": [5112.0, 6948.0, 9017.0]},
    {"age_label": "25-34", "n": 8583, "steps": [4908.0, 6732.0, 8848.0]},
    {"age_label": "35-44", "n": 9373, "steps": [4582.0, 6564.0, 9045.0]},
    {"age_label": "45-54", "n": 9393, "steps": [4500.0, 6500.0, 8955.0]},
    {"age_label": "55-64", "n": 10677, "steps": [4448.0, 6608.0, 9460.0]},
    {"age_label": "65-74", "n": 10338, "steps": [4061.0, 6169.0, 8908.0]},
    {"age_label": "75-84", "n": 3068, "steps": [3225.0, 5098.0, 7427.0]},
    {"age_label": "85+", "n": 199, "steps": [1774.0, 3460.0, 5353.0]},
]

TABLE = {
    "id": "steps_allofus_daily_v1",
    "version": 1,
    "snapshot_date": "2026-04-27",
    "source": {
        "name": "Patten et al., Nature Medicine 2026 (All of Us wearables dataset)",
        "url": "https://doi.org/10.1038/s41591-026-04352-3",
        "data_url": "https://www.nature.com/articles/s41591-026-04352-3/tables/2",
        "license": (
            "The article is open access under CC BY 4.0. The values here are "
            "facts re-keyed into our own structure, not a reproduction of the "
            "publisher's table."
        ),
        "citation": (
            "Patten T, Preble EA, Master H, et al. The All of Us Research "
            "Program's wearables dataset. Nature Medicine. 2026;32:2302-2310."
        ),
        "attribution": (
            "Reference values from Patten T, Preble EA, Master H, et al. The "
            "All of Us Research Program's wearables dataset. Nat Med. "
            "2026;32:2302-2310. doi:10.1038/s41591-026-04352-3 (CC BY 4.0)"
        ),
    },
    "staleness": {
        "policy": "SUPERSEDED",
        "rationale": (
            "A paper does not drift: the published quartiles do not change, so "
            "snapshot age is not decay. It goes stale exactly once — when a "
            "larger compatible-instrument reference is published, or when All "
            "of Us publishes a newer characterization of the same growing "
            "dataset — and only a human reading the literature can see that, "
            "so the monitor asks yearly."
        ),
        "recheck_every_days": 365,
        "last_checked_date": "2026-08-22",
        "recheck_question": (
            "Has a newer or larger consumer-wearable daily-steps percentile "
            "reference been published that supersedes Patten 2026 — in "
            "particular a newer All of Us wearables characterization, or a "
            "peer-reviewed Apple Heart & Movement Study steps table with "
            "sex/age percentiles?"
        ),
        "recheck_url": "https://doi.org/10.1038/s41591-026-04352-3",
    },
    "pipeline": {
        "script": "scripts/rulers/vendor_allofus_steps.py",
        "source_table": "Table 2, median (IQR) daily steps, general activity cohort",
        "cohort": (
            "The combined BYOD + WEAR general activity cohort (n = 54,509); "
            "per-participant median daily steps over each participant's whole "
            "donation window"
        ),
        "value_interpolation": (
            "linear between published quartile anchors; saturates at the 25th "
            "and 75th"
        ),
        "strata_note": (
            "Table 2 publishes sex and age strata separately, never jointly; "
            "this ruler places against the sex column alone and the sheet "
            "says so. The published age rows ride in age_context for "
            "/methods only."
        ),
        "included_participants": 54509,
        "cross_check": (
            "eFHS (Shapira-Daniels et al., JMIR 2023;25:e43123, CC BY; Apple "
            "Watch, n = 923): median 7,227 (IQR 5,699-8,970) daily steps — a "
            "different instrument, cited as a sanity cross-check only."
        ),
        "note": (
            "The published quartiles, re-keyed by hand from the journal's own "
            "HTML table. Nothing is fitted, smoothed, or combined across "
            "strata."
        ),
    },
    "pool_label": (
        "All of Us research participants who wore a Fitbit, combined "
        "bring-your-own-device and free-device cohorts"
    ),
    "percentile_grid": [25.0, 50.0, 75.0],
    "tier_cuts": [25.0, 50.0, 75.0],
    "tier_names": ["Bottom quarter", "Below median", "Above median", "Top quarter"],
    "full_cohort": FULL_COHORT,
    "columns": {
        key: {"label": c["label"], "n": c["n"], "steps": c["steps"]}
        for key, c in COLUMNS.items()
    },
    "age_context": AGE_CONTEXT,
}


def check() -> None:
    for key, c in COLUMNS.items():
        q = c["steps"]
        assert q == sorted(q) and len(set(q)) == 3, f"{key} quartiles not ascending"
    assert FULL_COHORT["steps"] == sorted(FULL_COHORT["steps"])
    for row in AGE_CONTEXT:
        assert row["steps"] == sorted(row["steps"]), f"{row['age_label']} not ascending"
    for i in range(3):
        assert (
            COLUMNS["FEMALE"]["steps"][i] < COLUMNS["MALE"]["steps"][i]
        ), "published female quartiles sit below male at every anchor"
    assert COLUMNS["FEMALE"]["n"] + COLUMNS["MALE"]["n"] < FULL_COHORT["n"], (
        "sex strata must undercount the cohort (suppressed rows exist)"
    )


def main() -> None:
    check()
    OUT.write_text(json.dumps(TABLE, indent=2, ensure_ascii=False) + "\n")
    print(f"wrote {OUT}")


if __name__ == "__main__":
    main()

Two categories below are compared against the population without a percentile anywhere on them, and the absence is the honest part. An anchor is what we build when a category has a published, citable average from an instrument like yours — but no distribution: bands at stated offsets from that average, with the reason there is no percentile printed in the slot a curve would fill. Nothing is fitted. We do not assume the spread is bell-shaped, convert an offset into a percentile, or invent tails the source never printed. The offsets and the band names are ours; the numbers are theirs; both sheets say which is which.

Your number is the spread — the standard deviation — of your weekday bedtimes over the trailing 28 days, from the onset of each night’s sleep as your ring or strap recorded it. Duration is deliberately not ranked (its relationship with health is U-shaped; see the refusals below); consistency is the one axis of sleep where the research points a single direction, and it is compared as a spread in minutes, never as hours slept.

The anchor is the largest published pool measured on an instrument like yours: 220,000 Oura Ring wearers across 35 countries (Willoughby et al. 2023, Sleep Medicine, Supplementary Table S2f, CC BY 4.0). Its USA column: an average weekday bedtime spread of 52.64 minutes per person, give or take 28.25across people. Across the paper’s countries the average runs from 45.27 (New Zealand) to 71.33 (Japan) minutes.

Why no percentile: the paper publishes means and spreads, not a distribution, and bedtime spreads are right-skewed — reading a percentile off a mean and an SD would be a normality assumption dressed as a citation. The one percentile grid that exists is UK Biobank’s sleep-regularity work (Windred 2021/2024), measured on research accelerometers — a different instrument, which is exactly why the app cites it as context (the most-regular fifth of 60,977 adults held onset spreads of roughly 20–40 minutes) and never as your rank. The National Sleep Foundation’s timing consensus (Sletten 2023) found the evidence insufficient to set any single number, so no surface of ours claims one; the quantified risk anchors the app does cite — a one-hour onset spread associated with 23% higher metabolic-syndrome and 18% higher cardiovascular risk — are Huang & Redline’s (2019, 2020), named as such.

Two more constructions, stated: the statistic is weekday nights only (the nights that end on a Monday-to-Friday morning), because that is what the paper measured; and vendor sleep scores are refused as inputs — Oura’s score and WHOOP’s performance are single-vendor composites, and a standing on a composite would launder a model through a mirror. The onset clock alone feeds this.

We do not rank your screen time. We do not even decide what “distracting” means: you pick the apps that count, the standing averages exactly those apps’ daily minutes over the trailing 28 reported days, and changing the set changes the number — it is your own definition, which is the point. A day your phone reported but your chosen apps never appeared counts as a real zero; averaging only the days you opened them would rank you on your worst days.

The anchor is a metered panel, not a survey — self-reported screen time is famously off by hours: Ofcom’s Online Nation 2025 (Ipsos iris, ~10,000 metered UK participants, May 2025) prints, per UK online adult per day: Meta apps 70 minutes and ByteDance apps 15 minutes. The 85-minute anchor is their sum, and the addition is ours — the report never sums them. Alphabet’s bucket is excluded on purpose: it folds search and mail in with YouTube, and an anchor should not launder a search engine into distraction.

Why no percentile: nobody publishes a distribution of logged app minutes for adults. Metered panels and market reports publish averages only, and the one logged distribution in print covers two hundred US teenagers on Android — the wrong pool twice over. Until better data exists, the published average above is the whole comparison. Two instrument facts ride every sheet: the panel meters phones, tablets and computers together while your number is your phone alone (expect to read low against it), and iPhone per-app minutes are floors rounded down to the phone’s reporting step while Android’s are exact.

A blood or urine result is the one place where a comparison is genuinely available off the shelf and genuinely easy to get wrong. Every row of a lab report already carries an H or an L and a printed reference interval, and turning that column into a rank would take about four lines of code. We do not, for three reasons. A reference interval belongs to one laboratory, computed on its own analyser against its own reference population — two laboratories flag the same blood differently. A flag has no direction: an H on ferritin, an H on HDL cholesterol and an H on sodium are three unrelated statements. And a 95% interval flags one healthy person in twenty by construction, which the WHO says out loud about its own haemoglobin cutoffs.

So the flag and the interval travel with your result as provenance, printed on the receipt in their own block, and they never decide a band. What decides a band is a clinical decision limit: a line a named body drew in a dated publication, in the unit your report prints, for the kind of assay that produced your number. That is a fourth shape of ruler — it has no distribution behind it, so the clinical block has no percentile and says why. For ten compatible measurements, a second block can now describe where the measured value sits in a US population distribution. It never changes the clinical band or turns the decision limit into a curve.

We audited all 84 measurements the importer reads, one at a time. 14 earned a threshold. 70 did not, and each of those carries the citation that establishes why — a refusal with no citation is an opinion. Nothing here is a diagnosis or medical advice; a guideline category is a population-level classification, and what it means for you is a conversation with a clinician who can see the rest of your history.

Transcribed by hand from the publishers’ own documents on 2026-08-19, each threshold carrying the sentence it came from. There is no pipeline to re-run here: a clinical guideline is a document a person reads, and claiming a script would be a lie about how this table is maintained. The file itself is go/platform/rulers/tables/labs_biomarker_rulers.json.

What we show.A neutral percentile by measured value among US adults represented by the CDC’s NHANES 2017–March 2020 pre-pandemic survey, split into the published female or male table and age 20–39, 40–59 or 60+. It reads “59th percentile by measured value”, never “top 41%”, “better than” or “healthier than”. A high value can be helpful, harmful, both, or neither depending on the biomarker and the person. This is position, not a target.

The pool.Examined adults age 20 or older in the US civilian, noninstitutionalized population represented by that survey. Participants recorded as pregnant are excluded. Everyone else remains: people with diagnoses, prescriptions and interventions are not filtered out, so this is not a “healthy-control” range. The chosen table tells us which published column to read; it is not an identity inferred by the platform. Age at the draw is derived from the birth year on the profile, because the profile does not hold a birthday.

The reduction. The script joins the ten pinned CDC public-use files by participant, uses the full-exam weight WTMECPRP except for fasting glucose and triglycerides, which use WTSAFPRP, and computes a survey-weighted midpoint empirical CDF. It publishes each whole percentile from P5 through P95. A result beyond that grid is called only “below P5” or “at or above P95”; no tail is invented. Every cell has at least 300 observed participants. These are point estimates; no confidence interval is calculated.

Estimated GFR is the one derived input: the script applies the 2021 CKD-EPI creatinine equation to the NHANES standardized creatinine value. The other nine rows use the named NHANES measurement or the stated arithmetic derivation.

Public longevity dashboards are useful as dated examples, but one person’s biomarker panel is an N=1 benchmark, not a percentile distribution. That is why the receipt uses NHANES for population position rather than presenting a public Blueprint biomarker value as though it described a population.

Re-run scripts/rulers/reduce_nhanes_labs.py to download and SHA-256 verify every source file and rebuild the Go table. The complete P5–P95 table used by the API is reproduced below; sample size n is the unweighted observed count in that cell.