garmin-golf-analytics 0.0.4__tar.gz

garmin_golf_analytics-0.0.4/LICENSE

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

garmin_golf_analytics-0.0.4/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: garmin-golf-analytics
+Version: 0.0.4
+Summary: Turn Garmin Connect golf rounds into per-club distances and a score debrief that isn't fooled by Garmin's defaults.
+Author: Etienne Troulland
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/etroulland/garmin-golf-analytics
+Project-URL: Changelog, https://github.com/etroulland/garmin-golf-analytics/blob/main/CHANGELOG.md
+Keywords: garmin,golf,garmin-connect,sports-analytics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: garminconnect<0.3,>=0.2.19
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+# garmin-golf-analytics
+
+[![tests](https://github.com/etroulland/garmin-golf-analytics/actions/workflows/tests.yml/badge.svg)](https://github.com/etroulland/garmin-golf-analytics/actions/workflows/tests.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Pull your Garmin Connect golf rounds and turn them into numbers you can act on: measured shot
+distances per club, split by lie, plus a round debrief that isn't fooled by Garmin's own
+defaults.
+
+Garmin already stores every shot its sensors caught. This repo reads that data through the
+`garminconnect` API instead of asking you to download a `DI_CONNECT` zip by hand, then applies
+the parsing rules that make the numbers trustworthy.
+
+## Why this exists
+
+The Garmin golf data looks clean and isn't. Things that silently corrupt a naive analysis:
+
+- **No putt detection without the sensors.** The watch only counts putts with the Garmin club
+  sensors on the putter. Without them nothing is measured: any `putts` value is whatever was typed
+  in by hand, and Garmin's own default fill is `putts: 2` on every hole. Averaging that gives a
+  perfect two-putt game you don't have, and `sensorOnPutter` is your only way to know which is
+  which.
+- **No per-hole par on the hole itself.** `holes[].par` is always `null`, but the pars of the
+  course are in `courseSnapshots[].holePars`, a digit string ordered 1..18, in the same response.
+  Garmin's own `score` field is a NET score and uses `handicappedStrokes`, not the course handicap.
+- **Uneven sampling.** One club can read 185 m off the tee and 108 m from the fairway, because
+  most of its fairway shots are punch-outs. Pooling the two produces a number that describes no
+  shot you ever hit.
+- **Short-game pollution.** A gap wedge chips from 20 m all day long. Include those in its average
+  and it looks 40 m shorter than it plays with a full swing.
+- **Club identity gaps.** `clubId: 0` marks swings the watch could not attribute to a club. They
+  are not a club and must never appear as one.
+- **Partial rounds.** Abandoned rounds and range sessions land in the same feed as real ones.
+
+## Install
+
+```bash
+pipx install garmin-golf-analytics
+```
+
+Or from a clone, with the test suite:
+
+```bash
+git clone https://github.com/etroulland/garmin-golf-analytics
+cd garmin-golf-analytics
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+Log in once. `garminconnect` writes a token store, so no credentials ever live in this repo:
+
+```bash
+python -c "from garminconnect import Garmin; Garmin().login()"
+# answer the prompts once; the session is cached in ~/.garminconnect
+```
+
+## Fetch rounds
+
+```bash
+export GARMINTOKENS=~/.garminconnect
+gga-fetch                 # latest round only
+gga-fetch --days 30       # every round played in the window
+gga-fetch --scid 383676990
+```
+
+The same commands are available as subcommands of a single `gga` dispatcher:
+`gga fetch`, `gga clubs`, `gga rounds`.
+
+Each round becomes `rounds/round_<YYYY-MM-DD>_<scid>.json`:
+
+```json
+{
+  "scorecard": { "startTime": "...", "strokes": 46, "handicappedStrokes": 9, "holes": [...] },
+  "course": { "name": "Golf Club St. Meard", "roundPar": 32, "pars": { "1": 3, "2": 3, "...": 0 } },
+  "shots": { "1": [{"clubId": 788036363, "meters": 181.9, "startLoc": {"lie": "TeeBox"}}] },
+  "playedHoles": 9
+}
+```
+
+`course` comes from `courseSnapshots`, a sibling of `scorecardDetails` in the same API response.
+It carries the per-hole par that `holes[].par` never does. `pars` is keyed by hole **number**: a
+`BACK_9` round lists holes 10..18, so join on the number, never on the position in the array.
+
+Club names need `Golf-CLUB.json` and `Golf-CLUB_TYPES.json`, which only ship inside a Garmin
+data export. Point `--zipref` (or `$GARMIN_ZIPREF`) at a `DI-GOLF` directory to get them joined in.
+Club names come from the API (`get_golf_club_stats`), which returns every club with its
+`clubTypeId` but never the label. `--zipref` is still accepted and overrides it, because only a
+data export carries the loft per club. Shots whose club cannot be named are excluded from the
+distance report rather than shown as `clubId:<n>`, which no one can act on.
+
+## Club distances
+
+```bash
+gga-clubs rounds/
+gga-clubs rounds/ --lie TeeBox      # first shot of a hole (see caveat below)
+gga-clubs rounds/ --min-meters 40   # raise the floor to drop chips
+```
+
+Median, p75, p90 and max per club **per lie**, because that is how the numbers are actually usable
+on the course. Clubs under 5 tracked shots are flagged `(low n)`.
+
+Every distance is a **total** distance: Garmin stores one `meters` value per shot, from the start
+point to the end point, roll included. Carry is not in the data and is not reported.
+`startLoc.lie == "TeeBox"` means "first shot played on that hole", not "hit from the tee": a par 4
+played 5-iron then wedge tags the 5-iron TeeBox and the wedge Fairway.
+
+Garmin records only a fraction of the swings you take, so n is small for a long time. Treat
+anything under 5 shots as noise and never let one low-n club outrank a measured one.
+
+## Round debrief
+
+```bash
+gga-rounds rounds/
+```
+
+Strokes per hole distribution, blow-up rate, penalties per round, and three-putt rate. Rounds with
+fewer than 9 played holes, or under 35 strokes on 9 / 60 on 18, are dropped as practice or
+abandoned before anything is averaged.
+
+## Layout
+
+```
+src/garmin_golf_analytics/
+  garmin_golf_fetch.py  fetch rounds from the Garmin API
+  club_report.py        distance tables per club, split by lie
+  round_report.py       score, penalties, blow-up holes, putting
+  rounds_common.py      which rounds count, shared by both reports
+  scoring.py            per-hole par and relative score
+  hole_sync.py          tracked shots vs scorecard reconciliation
+  cli.py                the `gga` dispatcher
+tests/                  125 tests, 97% coverage
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+./run_tests.sh        # pytest + coverage gate at 90%
+```
+
+CI runs the suite on Python 3.10 to 3.13 and checks that every console script
+resolves (`.github/workflows/tests.yml`).
+
+## License
+
+MIT
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).

garmin_golf_analytics-0.0.4/README.md

@@ -0,0 +1,150 @@
+# garmin-golf-analytics
+
+[![tests](https://github.com/etroulland/garmin-golf-analytics/actions/workflows/tests.yml/badge.svg)](https://github.com/etroulland/garmin-golf-analytics/actions/workflows/tests.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Pull your Garmin Connect golf rounds and turn them into numbers you can act on: measured shot
+distances per club, split by lie, plus a round debrief that isn't fooled by Garmin's own
+defaults.
+
+Garmin already stores every shot its sensors caught. This repo reads that data through the
+`garminconnect` API instead of asking you to download a `DI_CONNECT` zip by hand, then applies
+the parsing rules that make the numbers trustworthy.
+
+## Why this exists
+
+The Garmin golf data looks clean and isn't. Things that silently corrupt a naive analysis:
+
+- **No putt detection without the sensors.** The watch only counts putts with the Garmin club
+  sensors on the putter. Without them nothing is measured: any `putts` value is whatever was typed
+  in by hand, and Garmin's own default fill is `putts: 2` on every hole. Averaging that gives a
+  perfect two-putt game you don't have, and `sensorOnPutter` is your only way to know which is
+  which.
+- **No per-hole par on the hole itself.** `holes[].par` is always `null`, but the pars of the
+  course are in `courseSnapshots[].holePars`, a digit string ordered 1..18, in the same response.
+  Garmin's own `score` field is a NET score and uses `handicappedStrokes`, not the course handicap.
+- **Uneven sampling.** One club can read 185 m off the tee and 108 m from the fairway, because
+  most of its fairway shots are punch-outs. Pooling the two produces a number that describes no
+  shot you ever hit.
+- **Short-game pollution.** A gap wedge chips from 20 m all day long. Include those in its average
+  and it looks 40 m shorter than it plays with a full swing.
+- **Club identity gaps.** `clubId: 0` marks swings the watch could not attribute to a club. They
+  are not a club and must never appear as one.
+- **Partial rounds.** Abandoned rounds and range sessions land in the same feed as real ones.
+
+## Install
+
+```bash
+pipx install garmin-golf-analytics
+```
+
+Or from a clone, with the test suite:
+
+```bash
+git clone https://github.com/etroulland/garmin-golf-analytics
+cd garmin-golf-analytics
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+Log in once. `garminconnect` writes a token store, so no credentials ever live in this repo:
+
+```bash
+python -c "from garminconnect import Garmin; Garmin().login()"
+# answer the prompts once; the session is cached in ~/.garminconnect
+```
+
+## Fetch rounds
+
+```bash
+export GARMINTOKENS=~/.garminconnect
+gga-fetch                 # latest round only
+gga-fetch --days 30       # every round played in the window
+gga-fetch --scid 383676990
+```
+
+The same commands are available as subcommands of a single `gga` dispatcher:
+`gga fetch`, `gga clubs`, `gga rounds`.
+
+Each round becomes `rounds/round_<YYYY-MM-DD>_<scid>.json`:
+
+```json
+{
+  "scorecard": { "startTime": "...", "strokes": 46, "handicappedStrokes": 9, "holes": [...] },
+  "course": { "name": "Golf Club St. Meard", "roundPar": 32, "pars": { "1": 3, "2": 3, "...": 0 } },
+  "shots": { "1": [{"clubId": 788036363, "meters": 181.9, "startLoc": {"lie": "TeeBox"}}] },
+  "playedHoles": 9
+}
+```
+
+`course` comes from `courseSnapshots`, a sibling of `scorecardDetails` in the same API response.
+It carries the per-hole par that `holes[].par` never does. `pars` is keyed by hole **number**: a
+`BACK_9` round lists holes 10..18, so join on the number, never on the position in the array.
+
+Club names need `Golf-CLUB.json` and `Golf-CLUB_TYPES.json`, which only ship inside a Garmin
+data export. Point `--zipref` (or `$GARMIN_ZIPREF`) at a `DI-GOLF` directory to get them joined in.
+Club names come from the API (`get_golf_club_stats`), which returns every club with its
+`clubTypeId` but never the label. `--zipref` is still accepted and overrides it, because only a
+data export carries the loft per club. Shots whose club cannot be named are excluded from the
+distance report rather than shown as `clubId:<n>`, which no one can act on.
+
+## Club distances
+
+```bash
+gga-clubs rounds/
+gga-clubs rounds/ --lie TeeBox      # first shot of a hole (see caveat below)
+gga-clubs rounds/ --min-meters 40   # raise the floor to drop chips
+```
+
+Median, p75, p90 and max per club **per lie**, because that is how the numbers are actually usable
+on the course. Clubs under 5 tracked shots are flagged `(low n)`.
+
+Every distance is a **total** distance: Garmin stores one `meters` value per shot, from the start
+point to the end point, roll included. Carry is not in the data and is not reported.
+`startLoc.lie == "TeeBox"` means "first shot played on that hole", not "hit from the tee": a par 4
+played 5-iron then wedge tags the 5-iron TeeBox and the wedge Fairway.
+
+Garmin records only a fraction of the swings you take, so n is small for a long time. Treat
+anything under 5 shots as noise and never let one low-n club outrank a measured one.
+
+## Round debrief
+
+```bash
+gga-rounds rounds/
+```
+
+Strokes per hole distribution, blow-up rate, penalties per round, and three-putt rate. Rounds with
+fewer than 9 played holes, or under 35 strokes on 9 / 60 on 18, are dropped as practice or
+abandoned before anything is averaged.
+
+## Layout
+
+```
+src/garmin_golf_analytics/
+  garmin_golf_fetch.py  fetch rounds from the Garmin API
+  club_report.py        distance tables per club, split by lie
+  round_report.py       score, penalties, blow-up holes, putting
+  rounds_common.py      which rounds count, shared by both reports
+  scoring.py            per-hole par and relative score
+  hole_sync.py          tracked shots vs scorecard reconciliation
+  cli.py                the `gga` dispatcher
+tests/                  125 tests, 97% coverage
+```
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+./run_tests.sh        # pytest + coverage gate at 90%
+```
+
+CI runs the suite on Python 3.10 to 3.13 and checks that every console script
+resolves (`.github/workflows/tests.yml`).
+
+## License
+
+MIT
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).

garmin_golf_analytics-0.0.4/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "garmin-golf-analytics"
+dynamic = ["version"]
+description = "Turn Garmin Connect golf rounds into per-club distances and a score debrief that isn't fooled by Garmin's defaults."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Etienne Troulland" }]
+keywords = ["garmin", "golf", "garmin-connect", "sports-analytics"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Games/Entertainment",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = ["garminconnect>=0.2.19,<0.3"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5"]
+
+[project.urls]
+Homepage = "https://github.com/etroulland/garmin-golf-analytics"
+Changelog = "https://github.com/etroulland/garmin-golf-analytics/blob/main/CHANGELOG.md"
+
+[project.scripts]
+gga = "garmin_golf_analytics.cli:main"
+gga-fetch = "garmin_golf_analytics.garmin_golf_fetch:main"
+gga-clubs = "garmin_golf_analytics.club_report:main"
+gga-rounds = "garmin_golf_analytics.round_report:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "garmin_golf_analytics.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.coverage.run]
+source = ["garmin_golf_analytics"]
+
+[tool.coverage.report]
+fail_under = 90

garmin_golf_analytics-0.0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

garmin_golf_analytics-0.0.4/src/garmin_golf_analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Garmin Connect golf rounds into distances and score numbers you can act on."""
+
+__version__ = "0.0.4"
+
+__all__ = ["__version__"]

garmin_golf_analytics-0.0.4/src/garmin_golf_analytics/cli.py

@@ -0,0 +1,44 @@
+"""Console entry points for the garmin-golf-analytics commands.
+
+Each command is a thin wrapper around the ``main(argv)`` of one module, so the
+CLIs stay testable and nothing imports garminconnect unless you actually fetch.
+"""
+from __future__ import annotations
+
+import sys
+
+
+def fetch() -> int:
+    from .garmin_golf_fetch import main
+
+    return main()
+
+
+def clubs() -> int:
+    from .club_report import main
+
+    return main()
+
+
+def rounds() -> int:
+    from .round_report import main
+
+    return main()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Dispatch on the first argument: ``cli fetch|clubs|rounds ...``."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    commands = {"fetch": fetch, "clubs": clubs, "rounds": rounds}
+    if not args or args[0] in ("-h", "--help"):
+        print("usage: cli {fetch,clubs,rounds} [options]\n"
+              "  fetch   pull rounds from Garmin Connect\n"
+              "  clubs   per-club distances, split by lie\n"
+              "  rounds  round debrief (score, penalties, putting)")
+        return 0 if args else 2
+    command = commands.get(args[0])
+    if command is None:
+        print(f"unknown command: {args[0]} (expected fetch, clubs or rounds)", file=sys.stderr)
+        return 2
+    sys.argv = [f"cli {args[0]}", *args[1:]]
+    return command()

garmin_golf_analytics-0.0.4/src/garmin_golf_analytics/club_report.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Club distance report built from the JSON bundles written by garmin_golf_fetch.py.
+
+Prints, per club and per lie, the median TOTAL distance, the share of shots that
+end on the fairway or the green, and the count of mishits. Percentiles alone hide
+the thing that actually costs strokes: a club whose p25-p75 looks tight can still
+put two thirds of its balls in the rough, and a median computed with tops and
+chips mixed in describes a shot nobody plays.
+
+Garmin records one "meters" value per shot, from the start point to the end
+point: ground distance, roll included. Carry is NOT in the data and is never
+reported here.
+
+Usage:
+    python club_report.py rounds/                 # all bundles in a directory
+    python club_report.py rounds/ --lie TeeBox    # one lie only
+    python club_report.py rounds/ --min-meters 40 --min-shots 5
+    python club_report.py rounds/ --keep-excluded # keep Garmin's excluded rounds
+
+Only shots actually tracked by the watch are present (Garmin records a fraction
+of the swings played), so a club with n < 5 gets flagged low-confidence.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections import defaultdict
+from typing import Iterable
+
+from .rounds_common import load_bundles, played_holes, select
+
+LIE_ORDER = ("TeeBox", "Fairway", "Rough", "Bunker", "Green", "Recovery")
+GOOD_LIES = ("Fairway", "Green")
+# The putter is a real club off the green on dry, fast turf: a putt hit from the
+# green is a stroke of the short game, a putt hit from anywhere else is an
+# approach and deserves its own row. Garmin gives both the same shotType.
+PUTTER = "Putter"
+# A shot this short is a top, a duff or a mis-hit: it never describes the club.
+MISHIT_METERS = 60
+# No distance floor by default: a floor applied to every club silently deletes
+# the wedges from their own table, and mishits are already counted separately.
+DEFAULT_MIN_METERS = 0.0
+DEFAULT_MIN_SHOTS = 5
+
+# Garmin only stores a single "meters" value per shot: the GPS distance from the
+# start point to the end point, roll included. There is no carry in the data, so
+# every number this report prints, and the floor below it, is a TOTAL distance.
+DISTANCE_LABEL = "total (GPS, roll included)"
+
+
+def percentile(values: list[float], fraction: float) -> float:
+    """Linear-interpolated percentile on a sorted list."""
+    if not values:
+        raise ValueError("percentile of empty list")
+    ordered = sorted(values)
+    position = (len(ordered) - 1) * fraction
+    low = int(position)
+    high = min(low + 1, len(ordered) - 1)
+    weight = position - low
+    return ordered[low] * (1 - weight) + ordered[high] * weight
+
+
+def iter_shots(bundles: Iterable[dict]) -> Iterable[dict]:
+    for bundle in bundles:
+        for hole_shots in bundle.get("shots", {}).values():
+            yield from hole_shots
+
+
+def collect(shots: Iterable[dict], min_meters: float, lie: str | None) -> dict[tuple, list[tuple[float, str]]]:
+    """Group shots by (club, lie) as (distance, ending lie) pairs.
+
+    A putt hit ON the green is dropped: it is short-game, not a club distance.
+    A putt hit anywhere else is kept as "Putter (approach)", because Garmin tags
+    both the same way and the off-green one is a real shot the player chose.
+    """
+    grouped: dict[tuple, list[tuple[float, str]]] = defaultdict(list)
+    for shot in shots:
+        meters = shot.get("meters")
+        # clubId=0 means the watch could not identify the club: those shots
+        # carry an UNKNOWN shotType and must never be shown as a "club".
+        if not shot.get("clubId") or shot.get("excludeFromStats"):
+            continue
+        shot_lie = (shot.get("startLoc") or {}).get("lie") or "Unknown"
+        end_lie = (shot.get("endLoc") or {}).get("lie") or "Unknown"
+        if shot.get("shotType") == "PUTT" and shot_lie == "Green":
+            continue
+        # No name means an unmapped clubTypeId (or a club the watch faked):
+        # an id in a club table is noise, and it cannot be compared to anything.
+        club = shot.get("clubName")
+        if not club:
+            continue
+        # Keep putts played off the green: they are approaches with a flat club.
+        if club == PUTTER and shot_lie == "Green":
+            continue
+        if club == PUTTER:
+            # A putt that never reaches the green is not an approach either.
+            if end_lie != "Green":
+                continue
+            club = "Putter (approach)"
+        if meters is None or meters < min_meters:
+            continue
+        if lie and shot_lie != lie:
+            continue
+        grouped[(club, shot_lie)].append((float(meters), end_lie))
+    return grouped
+
+
+def report(grouped: dict[tuple, list[tuple[float, str]]], min_shots: int) -> None:
+    by_lie: dict[str, list[tuple[str, list[tuple[float, str]]]]] = defaultdict(list)
+    for (club, lie), shots in grouped.items():
+        by_lie[lie].append((club, shots))
+
+    lies = sorted(by_lie, key=lambda name: (LIE_ORDER.index(name) if name in LIE_ORDER else 99, name))
+    for lie in lies:
+        print(f"\n## {lie}")
+        print(f"{'club':22} {'n':>3} {'med':>6} {'good%':>6} {'max':>6} {'mishits':>8}   (total m)")
+        rows = sorted(by_lie[lie], key=lambda row: -percentile([d for d, _ in row[1]], 0.5))
+        for club, shots in rows:
+            # The club's own floor: a wedge never plays 60 m, a driver never plays 12.
+            floor = min(MISHIT_METERS, percentile([d for d, _ in shots], 0.5) * 0.5)
+            played = [d for d, _ in shots if d >= floor]
+            mishits = len(shots) - len(played)
+            good = sum(1 for _, lie_out in shots if lie_out in GOOD_LIES)
+            med = percentile(played, 0.5) if played else float("nan")
+            good_pct = f"{100 * good / len(shots):5.0f}" if shots else "    -"
+            flag = "  (low n)" if len(played) < min_shots else ""
+            print(
+                f"{club[:22]:22} {len(played):3d} {med:6.0f} {good_pct}% "
+                f"{max(played) if played else float('nan'):6.0f} {mishits:8d}{flag}"
+            )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("directory", nargs="?", default="rounds", help="directory of round_*.json (default: rounds)")
+    parser.add_argument("--lie", help="restrict to one lie (TeeBox, Fairway, Rough, ...)")
+    parser.add_argument("--min-meters", type=float, default=DEFAULT_MIN_METERS,
+                        help="drop shots below this total distance (default: no floor)")
+    parser.add_argument("--min-shots", type=int, default=DEFAULT_MIN_SHOTS,
+                        help=f"flag clubs under this sample size (default: {DEFAULT_MIN_SHOTS})")
+    parser.add_argument("--min-holes", type=int, default=9,
+                        help="drop rounds with fewer played holes (default: 9)")
+    parser.add_argument("--keep-excluded", action="store_true",
+                        help="also use rounds Garmin flagged excludeFromStats")
+    args = parser.parse_args(argv)
+
+    if not os.path.isdir(args.directory):
+        print(f"no such directory: {args.directory}", file=sys.stderr)
+        return 2
+
+    bundles = load_bundles(args.directory)
+    if not bundles:
+        print(f"no round_*.json in {args.directory}", file=sys.stderr)
+        return 1
+
+    # Same round selection as round_report.py: one sample, one set of rules.
+    selection = select(bundles, args.min_holes, keep_excluded=args.keep_excluded)
+    kept = [b for b in selection.kept if played_holes(b)]
+    shots = list(iter_shots(kept))
+    grouped = collect(shots, args.min_meters, args.lie)
+    print(f"{selection.describe()}, {len(shots)} tracked shots, distances are {DISTANCE_LABEL}")
+    if not grouped:
+        print("no shot above the distance floor", file=sys.stderr)
+        return 1
+    report(grouped, args.min_shots)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())