calcpace 1.16.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fd21092789d45d81f1cc1def219122a63cd74ead051cc59ee30b178198702f1
-  data.tar.gz: e67ee4c7a71c194ce57928993ee2e898947465d2647e8ffa5b85277386e652b2
+  metadata.gz: def270498a0b653086ac234f0eb1ad4337f961cc2b93729a4bf32c7e48df78ba
+  data.tar.gz: '075049703348c3cea1194b90a9f64f6cc37552fe360ce51e0d446a9edca5e729'
 SHA512:
-  metadata.gz: ee62a321a8a53d93f36698579ab5bb3a5e87c3ad744191219477492a63daafc100b07fe01421bba40835b8bfef84554698db605ca9279e7619473301b0e366cb
-  data.tar.gz: ed4c5799eeb409dbb595e594417cc9efbcb9a6316bdb93dc6f9288c3deae7291aef63ff78415ca172f8ea86789d894fa7c057ecd4887902a9e5e3b0b962e2add
+  metadata.gz: '083ff71a2666e55994ef03bd8184c435b1006c2029c4af97ab3546683f2d64e1422fb140c6828c001f00ad630bfc05f1caf98af53fbb9ab4d29ec603cad6ef04'
+  data.tar.gz: '00833e0d9c636730852506c360e08cfec7ecc1de2b1993a4a2560dd0f0941328c48c79e6047ca143babe3545f4b57bfd8e1e47b7c1f864c10d42ab85133390e0'

data/.gitignore

@@ -3,3 +3,5 @@ coverage/
 calcpace-*.gem
 !calcpace.gemspec
 improvements_plan.md
+
+.claude/

data/.rubocop.yml

@@ -69,6 +69,10 @@ Metrics/ModuleLength:
   Exclude:
     - 'lib/calcpace/race_splits.rb'
     - 'lib/calcpace/track_calculator.rb'
+    # Training zones now cover paces, heart-rate bands and time in those bands.
+    # Splitting them would put hr_zones and time_in_zones in different files,
+    # which is worse than a long module: one produces exactly what the other reads.
+    - 'lib/calcpace/training_zones.rb'
 
 # Allow both single and double quotes for strings
 Style/StringLiteralsInInterpolation:

data/CHANGELOG.md

@@ -7,6 +7,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-09-06
+
+### Changed
+- `age_grade_label(percent)` — and therefore `age_grade`'s `:category` — splits
+  the old single `"Developing"` band below 60% into three: `"Intermediate"`
+  (50–59.9%), `"Recreational"` (40–49.9%) and `"Active Beginner"` (below 40%).
+  Most recreational runners grade under 60%, so the old catch-all told nearly
+  every one of them the same thing.
+
+  ```ruby
+  calc.age_grade_label(55.0) # => "Intermediate"      (was "Developing")
+  calc.age_grade_label(45.0) # => "Recreational"      (was "Developing")
+  calc.age_grade_label(30.0) # => "Active Beginner"   (was "Developing")
+  ```
+
+  The bands at 60% and above are untouched, and no numeric output changes —
+  `age_grade_percent`, `age_graded_time_seconds` and the rest are identical.
+  This is a label-only change, so callers that match on the string
+  `"Developing"` need updating.
+
+## [1.17.0] - 2026-09-05
+
+### Added
+- `time_in_zones(heartrate:, time:, zones:)` — splits a recorded heart-rate
+  series into the seconds spent in each of the five zones returned by `hr_zones`
+  or `hr_zones_from_max`, plus each zone's share of the counted time. Inputs are
+  two plain arrays, so a Strava `heartrate`/`time` stream pair fits without
+  translation and so does the same pair read out of a FIT file.
+
+  ```ruby
+  zones = calc.hr_zones_from_max(hr_max: 190)
+
+  in_zones = calc.time_in_zones(
+    heartrate: [120, 120, 140, 140, 160],
+    time:      [0, 60, 120, 180, 240],
+    zones:     zones
+  )
+
+  in_zones.map(&:seconds)  # => [0, 120, 120, 60, 0]
+  in_zones.map(&:share)    # => [0.0, 0.4, 0.4, 0.2, 0.0]
+  ```
+
+  A sample lasts until the next one, and the last sample inherits the previous
+  delta so a series does not lose its final seconds. **A pause is a gap in
+  `time`, and the whole gap is booked to the sample before it** — there is no
+  `max_gap` to guess a cut-off with, so a caller holding Strava's `moving`
+  stream should nil the heart rate of every paused sample first.
+
+  A sample with a nil or non-positive heart rate contributes nothing — its
+  duration is dropped, never reassigned to a neighbour. Shares are rounded
+  together, largest remainder first, so the five of them are whole thousandths
+  adding up to 1000 — a bar chart fills its track.
+
+- `hr_zone_for(bpm, zones)` — the zone lookup `time_in_zones` uses, exposed on
+  its own. Returns the `HrZone`, or nil when the reading is nil or not positive.
+
+  ```ruby
+  calc.hr_zone_for(150, calc.hr_zones_from_max(hr_max: 190)).zone  # => 3
+  calc.hr_zone_for(114, calc.hr_zones_from_max(hr_max: 190)).zone  # => 2
+  calc.hr_zone_for(205, calc.hr_zones_from_max(hr_max: 190)).zone  # => 5
+  ```
+
+  **Note for calcpace.app:** the site's own lookup walks the zones with
+  `between?`, which differs from this one in two places. Zones are contiguous,
+  so their bounds are shared: `between?` gives 114 bpm to Z1, while
+  `hr_zone_for` gives it to Z2, the way a watch reads it. And a reading above
+  `hr_max` returns nil from `between?` but Z5 here — a reading above the maximum
+  means the maximum is wrong, not that the beat did not happen. Consumers should
+  migrate to `hr_zone_for` so that a zone split and a live zone badge cannot
+  disagree about the same beat.
+
+- `interval_structure(laps, unit: :km)` — new `LapAnalyzer` module. Detects a
+  structured interval session in a watch's laps by **contrast**, never by a
+  label: a lap is work when it covers at least 0.1 km and is at least 15% faster
+  than every lap touching it. What comes before the first work lap is warm-up,
+  what follows the last is cool-down, and what sits between two work laps is
+  rest.
+
+  ```ruby
+  laps = [{ distance: 2.0, elapsed: 720 }] +
+         ([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }] * 6) +
+         [{ distance: 1.5, elapsed: 495 }]
+
+  calc.interval_structure(laps)
+  # => #<struct reps=6, work_distance=1.0, ... rest_duration=156>
+  ```
+
+  A warm-up or a cool-down has only one neighbour, so contrast alone would be a
+  free pass — a 5:30/km cool-down beats the 6:30/km jog it touches and walks in
+  as an extra rep. An edge lap is therefore admitted only if it also agrees with
+  the reps found in the interior: within ±25% of their median distance and no
+  more than 10% slower than their pace.
+
+  It returns `nil` when the laps describe no structure — fewer than two work
+  laps, work laps more than ±25% away from their median distance (a fartlek or a
+  hilly run), or no work lap that ever beat a *finite* pace. That last rule
+  matters because a standing lap has an infinite pace and everything is 15%
+  faster than infinity: without it, an easy run with two red-light lap presses
+  would come back as three reps. Most runs are not intervals, and inventing reps
+  out of ordinary pace variation would make every easy run look like a workout.
+
+  A distance of `0` is a legal standing recovery, and makes `rest_pace` nil
+  rather than infinite. A lap over 100 km is rejected: it is a caller who passed
+  metres. `unit: :mi` converts both paces; distances stay in kilometres.
+
 ## [1.16.0] - 2026-09-05
 
 ### Added
@@ -515,7 +620,8 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.16.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.17.0...HEAD
+[1.17.0]: https://github.com/0jonjo/calcpace/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/0jonjo/calcpace/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/0jonjo/calcpace/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/0jonjo/calcpace/compare/v1.13.0...v1.14.0

data/README.md

@@ -2,10 +2,12 @@
 
 A Ruby gem for runners: pace, time, and distance calculations, unit conversions, race predictions, GPS track analysis, age grading, VO2max estimation, and training zones.
 
+> **See it in action:** [calcpace.app](https://calcpace.app) — free running calculators, race predictors and a training log, all powered by this gem.
+
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 1.12.0'
+gem 'calcpace', '~> 1.18.0'
 ```
 
 ## Usage
@@ -261,6 +263,24 @@ calc.age_grade_percent(5.0, '00:22:30', age: 40, sex: :female) # => 65.2
 calc.age_grade_label(65.2)                                      # => "Local Class"
 ```
 
+`category` (and `age_grade_label`) returns one of:
+
+| Age grade | Category |
+| --- | --- |
+| 100%+ | Approximate World Record Level |
+| 90–99.9% | World Class |
+| 80–89.9% | National Class |
+| 70–79.9% | Regional Class |
+| 60–69.9% | Local Class |
+| 50–59.9% | Intermediate |
+| 40–49.9% | Recreational |
+| below 40% | Active Beginner |
+
+The bands from Local Class up are the WMA / Alan Jones convention. Those tables
+define nothing below Local Class, so the three bands under 60% are calcpace's
+own extension — most recreational runners land there, and one catch-all label
+for everybody under 60% tells them nothing.
+
 Supported distances: 5K, 10K, half marathon, marathon.
 
 A numeric distance within **2%** of one of those is graded as that standard —
@@ -415,6 +435,155 @@ natively (not converted from the km bands), so they can differ by ±1 s from
 All mile factors derive from the exact international mile (1609.344 m), so distances,
 pace bands, and age-grading tolerances agree to the metre.
 
+#### Time in heart-rate zones
+
+`time_in_zones` splits a recorded heart-rate series into the time spent in each zone.
+It takes two plain arrays and the zones, so a Strava `heartrate`/`time` stream pair
+fits without translation, and so does the same pair read out of a FIT file:
+
+```ruby
+zones = calc.hr_zones_from_max(hr_max: 190)
+
+in_zones = calc.time_in_zones(
+  heartrate: [120, 120, 140, 140, 160],
+  time:      [0, 60, 120, 180, 240],
+  zones:     zones
+)
+
+in_zones.map(&:seconds)  # => [0, 120, 120, 60, 0]
+in_zones.map(&:share)    # => [0.0, 0.4, 0.4, 0.2, 0.0]
+in_zones[1].zone         # => 2
+
+# The same call in one line, if you would rather not name the zones
+calc.time_in_zones(heartrate: [120, 140], time: [0, 60], zones: calc.hr_zones_from_max(hr_max: 190)).map(&:seconds)  # => [0, 60, 60, 0, 0]
+calc.time_in_zones(heartrate: [120, 140], time: [0, 60], zones: calc.hr_zones_from_max(hr_max: 190)).map(&:share)    # => [0.0, 0.5, 0.5, 0.0, 0.0]
+```
+
+Five rows always come back, in zone order, zeros included — `seconds` whole, `share`
+a fraction of the counted time with three decimals. The shares are whole thousandths
+that add up to 1000 — rounded together, largest remainder first — so a bar chart
+drawn from them fills its track (the Float sum may sit one ulp from 1.0).
+
+**A sample lasts until the next one** (`time[i + 1] - time[i]`), and the last sample,
+which has no next, is given the previous delta so a series does not lose its final
+seconds; a single sample lasts 0 s.
+
+That rule has a consequence worth knowing before trusting the numbers. **A pause is a
+gap in `time`, and the whole gap is booked to the sample before it** — stop five
+minutes at a café and those five minutes land in whatever zone the last beat before
+the pause was in. There is no `max_gap` here to guess a cut-off with. If you have
+Strava's `moving` stream, nil the heart rate of every paused sample before calling,
+which hands them to the next rule.
+
+A sample with a nil or non-positive heart rate contributes nothing: its duration is
+**dropped, not reassigned**, because a dropout says nothing about which zone the
+runner was in — so the counted time can be less than the wall clock, and the shares
+are shares of what was counted.
+
+Mismatched array lengths, a series that is not an array, a nil inside `time`, a
+`time` that goes backwards, or a heart rate that is neither nil nor a number all
+raise `Calcpace::Error`. Empty arrays return the five zero rows.
+
+#### Which zone is this beat in?
+
+`hr_zone_for` is the lookup `time_in_zones` uses, exposed on its own:
+
+```ruby
+calc.hr_zone_for(150, calc.hr_zones_from_max(hr_max: 190)).zone  # => 3
+calc.hr_zone_for(114, calc.hr_zones_from_max(hr_max: 190)).zone  # => 2
+calc.hr_zone_for(205, calc.hr_zones_from_max(hr_max: 190)).zone  # => 5
+```
+
+It returns the `HrZone`, or nil when the reading is nil or not positive — a sensor
+dropout. Two rules are worth stating because a hand-rolled `between?` lookup gets
+both wrong:
+
+- **On a shared boundary the higher zone wins.** Zones are contiguous, so 114 bpm is
+  both the top of Z1 and the bottom of Z2; it counts as Z2, the way a watch reads it.
+- **Readings outside the range are clamped**, below Z1 to Z1 and above Z5 to Z5. A
+  reading above `hr_max` means the `hr_max` is wrong, not that the beat did not
+  happen — and an `hr_max` a few beats off is the most common thing an athlete
+  carries around. Clamping keeps that a distortion of the split instead of making
+  minutes of a run disappear.
+
+---
+
+### Lap Analysis
+
+A watch records laps; it does not record intent. `interval_structure` reads the shape
+of a session out of the laps themselves, by **contrast** — never by a label:
+
+```ruby
+# Warm-up, 6 x (1 km hard / 400 m jog), cool-down
+laps = [{ distance: 2.0, elapsed: 720 }] +
+       ([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }] * 6) +
+       [{ distance: 1.5, elapsed: 495 }]
+
+structure = calc.interval_structure(laps)
+# => #<struct reps=6, work_distance=1.0, ... rest_duration=156>
+
+structure.reps           # => 6
+structure.work_distance  # => 1.0   (km, median rep)
+structure.work_pace      # => 252   (seconds per km, distance-weighted)
+structure.rest_pace      # => 390
+structure.rest_duration  # => 156   (mean rest lap, seconds)
+```
+
+`to_a` gives all five at once, which is short enough to show whole. This is the
+smallest session that has a structure — two reps and the jog between them:
+
+```ruby
+calc.interval_structure([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }, { distance: 1.0, elapsed: 252 }]).to_a  # => [2, 1.0, 252, 390, 156]
+
+# unit: converts both paces; distances stay in kilometres
+calc.interval_structure([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }, { distance: 1.0, elapsed: 252 }], unit: :mi).to_a  # => [2, 1.0, 406, 628, 156]
+```
+
+Laps are plain hashes of a distance in kilometres and an elapsed time in seconds —
+what a Strava lap, a FIT lap and a hand-written array all reduce to. Distance `0` is
+legal: it is a standing recovery, and it means an infinite pace.
+
+A lap counts as **work** when it covers at least 0.1 km and is at least 15% faster
+than every lap touching it. Everything before the first work lap is warm-up,
+everything after the last is cool-down, and a lap between two work laps is rest. Two
+work laps can never touch — each would have to be 0.85 of the other — so every pair
+of reps has a recovery between it.
+
+An **edge lap** — the first or the last — has only one neighbour, so contrast alone
+is a free pass: a 5:30/km cool-down beats the 6:30/km jog it happens to touch and
+walks in as an extra rep. So an edge lap is admitted only if it also agrees with the
+reps found in the middle: within ±25% of their median distance, and no more than 10%
+slower than their pace. When the interior found nothing there is nothing to agree
+with, and the plain contrast rule stands — which is why the three-lap example above
+still reads as two reps.
+
+The method returns **nil** when the laps describe no structure, and most runs do not:
+
+```ruby
+# A steady 10 km, ten laps of 1 km within five seconds of each other
+steady = [300, 298, 302, 296, 304, 300, 299, 301, 305, 295].map do |elapsed|
+  { distance: 1.0, elapsed: elapsed }
+end
+
+calc.interval_structure(steady)  # => nil
+
+# An easy 3 km with two red lights: fast next to a pause is not a rep
+calc.interval_structure([{ distance: 1.0, elapsed: 300 }, { distance: 0.0, elapsed: 45 }, { distance: 1.0, elapsed: 300 }])  # => nil
+```
+
+Nil is returned when there are fewer than two work laps, when the work laps disagree
+about distance — more than ±25% from their median makes it a fartlek or a hilly run,
+which has fast laps but no set to report — or when **no work lap ever beat a finite
+pace**. That last rule is what the red-light example trips: a zero-distance lap has
+an infinite pace and everything is 15% faster than infinity, so without it every easy
+run with a paused lap would come back as a set of reps.
+
+`rest_pace` is nil when the recoveries covered no distance at all; a standing
+recovery has a duration but no pace, and reporting infinity would be worse than
+reporting nothing. A lap missing `:distance` or `:elapsed`, a negative distance, a
+distance over 100 km (a caller who passed metres), or a non-positive elapsed time
+raises `Calcpace::Error`; an empty array returns nil.
+
 ---
 
 ### Stride & Cadence

data/lib/calcpace/data/wma_2023_open_standards.yml

@@ -3,6 +3,10 @@ meta:
   url: "https://howardgrubb.co.uk/athletics/wmatnf23.html"
   table_version: "WMA_2023_ONE_YEAR_FACTORS_V1"
 
+# The bands from Local Class up follow the WMA / Alan Jones convention. The
+# WMA tables define nothing below Local Class, so the three bands under 60%
+# are Calcpace's own extension, added to give recreational runners a
+# meaningful label instead of a single catch-all.
 age_grade_classifications:
   - min: 100.0
     label: "Approximate World Record Level"
@@ -14,8 +18,12 @@ age_grade_classifications:
     label: "Regional Class"
   - min: 60.0
     label: "Local Class"
+  - min: 50.0
+    label: "Intermediate"
+  - min: 40.0
+    label: "Recreational"
   - min: 0.0
-    label: "Developing"
+    label: "Active Beginner"
 
 open_standards_seconds:
   M:

data/lib/calcpace/lap_analyzer.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+# Module for reading the shape of a session out of its laps
+#
+# A watch records laps; it does not record intent. Nothing in the data says
+# "6 × 1 km", and the label a runner typed into an app is not evidence — most
+# sessions carry none, and the ones that do are often wrong. What is always in
+# the data is **contrast**: a rep is a lap that is much faster than the laps
+# touching it, and the recovery between two reps is the lap that is not.
+#
+# So the detection here is purely relative. A lap is work when it is at least
+# WORK_PACE_RATIO faster than every lap beside it; everything before the first
+# work lap is warm-up, everything after the last is cool-down, and what sits
+# between two work laps is rest. A session is only called structured when the
+# reps agree with each other on distance — otherwise it is a fartlek or a hilly
+# run, which has fast laps but no structure to report.
+#
+# Format-agnostic by design: laps are plain hashes of a distance in kilometres
+# and an elapsed time in seconds, which is what a Strava lap, a FIT lap and a
+# hand-written array all reduce to.
+module LapAnalyzer
+  # A detected interval session. Paces are seconds per unit, distances km.
+  IntervalStructure = Struct.new(:reps, :work_distance, :work_pace, :rest_pace, :rest_duration)
+
+  # One lap reduced to the three numbers the detection reasons about
+  LapPace = Struct.new(:distance, :elapsed, :pace)
+
+  # How much faster than its neighbours a lap must be to count as work
+  WORK_PACE_RATIO = 0.85
+
+  # Below this a lap is a split, not a rep — a hand-pressed button, a GPS
+  # hiccup, the last metres of a track lap recorded on their own
+  MIN_WORK_DISTANCE_KM = 0.1
+
+  # How far a rep may sit from the median rep distance and still belong to the
+  # same set. Wider than this and the fast laps are not one workout
+  WORK_DISTANCE_TOLERANCE = 0.25
+
+  # How much slower than the reps found in the interior an edge lap may be and
+  # still be read as one of them. A warm-up or cool-down only ever has one
+  # neighbour, so contrast alone would let it in on beating a single jog
+  EDGE_PACE_TOLERANCE = 1.10
+
+  # A lap longer than this was measured in metres by a caller who thinks they
+  # are kilometres. No lap of a running session is 100 km
+  MAX_LAP_DISTANCE_KM = 100
+
+  # Detects a structured interval session in a list of laps
+  #
+  # Returns nil whenever the laps do not describe one: a steady run, a single
+  # hard effort, a fartlek whose surges have nothing in common. Nil is the
+  # honest answer — most runs are not intervals, and inventing reps out of
+  # ordinary pace variation would make every easy run look like a workout.
+  #
+  # @param laps [Array<Hash>] laps in order, each with :distance in kilometres
+  #   (Numeric, 0 up to 100, and 0 means a standing recovery) and :elapsed in
+  #   seconds (Numeric, must be positive). String keys are accepted too
+  # @param unit [Symbol, String] unit of the returned paces — :km (default) or :mi.
+  #   Distances stay in kilometres in both
+  # @return [IntervalStructure, nil] nil when the laps have no structure, else a
+  #   struct of: reps, the number of work laps; work_distance, their median
+  #   distance in km rounded to 2 decimals; work_pace, their distance-weighted
+  #   pace (total elapsed over total distance) in seconds per unit, rounded;
+  #   rest_pace, the same over the rest laps, or nil when they covered no
+  #   distance; and rest_duration, the mean rest lap in whole seconds
+  # @raise [Calcpace::Error] if a lap is missing :distance or :elapsed, its
+  #   distance is negative or over 100 km, or its elapsed time is not positive
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example warm-up, 6 × (1 km hard / 400 m jog), cool-down
+  #   laps = [{ distance: 2.0, elapsed: 720 }] +
+  #          ([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }] * 6) +
+  #          [{ distance: 1.5, elapsed: 495 }]
+  #   structure = calc.interval_structure(laps)
+  #   structure.reps          #=> 6
+  #   structure.work_distance #=> 1.0
+  #   structure.work_pace     #=> 252
+  #   structure.rest_pace     #=> 390
+  #   structure.rest_duration #=> 156
+  #
+  # @example the smallest session that has a structure, every field at once
+  #   calc.interval_structure([{ distance: 1.0, elapsed: 252 },
+  #                            { distance: 0.4, elapsed: 156 },
+  #                            { distance: 1.0, elapsed: 252 }]).to_a
+  #   #=> [2, 1.0, 252, 390, 156]
+  #
+  # @example the same session with paces per mile
+  #   calc.interval_structure(laps, unit: :mi).work_pace #=> 406
+  #
+  # @example a steady 10 km, ten laps of 1 km within five seconds of each other
+  #   steady = [300, 298, 302, 296, 304, 300, 299, 301, 305, 295].map do |elapsed|
+  #     { distance: 1.0, elapsed: elapsed }
+  #   end
+  #   calc.interval_structure(steady) #=> nil
+  def interval_structure(laps, unit: :km)
+    meters = pace_unit_meters(unit)
+    parsed = parse_laps(laps)
+    work = work_lap_indexes(parsed)
+    return nil unless structured?(parsed, work)
+
+    build_interval_structure(parsed, work, meters)
+  end
+
+  private
+
+  # @param laps [Array<Hash>] raw laps
+  # @return [Array<LapPace>] the same laps with their pace in seconds per km
+  def parse_laps(laps)
+    Array(laps).map do |lap|
+      distance = lap_value(lap, :distance)
+      elapsed = lap_value(lap, :elapsed)
+      check_lap(distance, elapsed)
+
+      LapPace.new(distance: distance, elapsed: elapsed,
+                  pace: distance.positive? ? elapsed / distance : Float::INFINITY)
+    end
+  end
+
+  # @raise [Calcpace::Error] if the key is missing or does not hold a number
+  def lap_value(lap, key)
+    value = lap.is_a?(Hash) ? (lap[key] || lap[key.to_s]) : nil
+    return value.to_f if value.is_a?(Numeric)
+
+    raise Calcpace::Error, "Every lap needs a numeric :#{key} (got #{value.inspect})"
+  end
+
+  def check_lap(distance, elapsed)
+    raise Calcpace::Error, "Lap distance cannot be negative (got #{distance})" if distance.negative?
+    raise Calcpace::Error, "Lap elapsed time must be positive (got #{elapsed})" unless elapsed.positive?
+    return if distance <= MAX_LAP_DISTANCE_KM
+
+    raise Calcpace::Error, "Lap distance #{distance} is too long — lap distances are kilometres, not metres"
+  end
+
+  # Interior laps are judged on contrast alone. An edge lap — the first or the
+  # last — has only one neighbour, so contrast is a free pass: a cool-down beats
+  # the jog it happens to touch and walks in as an extra rep, or as a rep of the
+  # wrong length that makes the whole session look unstructured. It is admitted
+  # only if it also looks like the reps already found in the middle.
+  #
+  # When the interior found nothing there is nothing to agree with, so the plain
+  # contrast rule stands and the three-lap session (work, rest, work) still reads.
+  #
+  # @return [Array<Integer>] indexes of the laps that stand out as reps
+  def work_lap_indexes(laps)
+    interior = (1...(laps.size - 1)).select { |index| work_lap?(laps, index) }
+    return laps.each_index.select { |index| work_lap?(laps, index) } if interior.empty?
+
+    edges = [0, laps.size - 1].uniq.select do |index|
+      work_lap?(laps, index) && matches_interior?(laps, index, interior)
+    end
+
+    (interior + edges).sort
+  end
+
+  def matches_interior?(laps, index, interior)
+    lap = laps[index]
+    median = median(interior.map { |i| laps[i].distance })
+
+    (lap.distance - median).abs <= WORK_DISTANCE_TOLERANCE * median &&
+      lap.pace <= EDGE_PACE_TOLERANCE * weighted_pace(laps, interior)
+  end
+
+  # Two work laps can never touch: each would have to be 0.85 of the other.
+  # That is what guarantees a rest lap between every pair of reps.
+  def work_lap?(laps, index)
+    lap = laps[index]
+    return false if lap.distance < MIN_WORK_DISTANCE_KM
+
+    neighbour_paces(laps, index).all? { |pace| lap.pace <= WORK_PACE_RATIO * pace }
+  end
+
+  def neighbour_paces(laps, index)
+    [index - 1, index + 1].select { |i| i >= 0 && i < laps.size }
+                          .map { |i| laps[i].pace }
+  end
+
+  def structured?(laps, work)
+    return false if work.size < 2
+    return false unless beat_a_real_pace?(laps, work)
+
+    distances = work.map { |index| laps[index].distance }
+    median = median(distances)
+
+    distances.all? { |distance| (distance - median).abs <= WORK_DISTANCE_TOLERANCE * median }
+  end
+
+  # A lap of zero distance has an infinite pace, and everything is 15% faster
+  # than infinity. So an easy run with two red-light lap presses looks exactly
+  # like three reps around two standing recoveries. At least one rep has to have
+  # beaten a pace that was actually run; otherwise the contrast is an artefact
+  # of the pauses and there is no evidence of a workout at all.
+  def beat_a_real_pace?(laps, work)
+    work.any? { |index| neighbour_paces(laps, index).any?(&:finite?) }
+  end
+
+  def build_interval_structure(laps, work, meters)
+    rest = rest_lap_indexes(work)
+
+    IntervalStructure.new(
+      reps: work.size,
+      work_distance: median(work.map { |index| laps[index].distance }).round(2),
+      work_pace: converted_pace(weighted_pace(laps, work), meters),
+      rest_pace: converted_pace(weighted_pace(laps, rest), meters),
+      rest_duration: rest.empty? ? nil : mean(rest.map { |index| laps[index].elapsed }).round
+    )
+  end
+
+  # Laps sitting between two consecutive reps. Anything outside the reps is
+  # warm-up or cool-down, which is not part of the session's structure.
+  #
+  # Never empty in practice once there are two reps, because two work laps can
+  # never be adjacent — but reps and rest are counted separately here so that a
+  # change to the work rule shows up as a nil field, not as a NaN.
+  def rest_lap_indexes(work)
+    work.each_cons(2).flat_map { |from, to| ((from + 1)...to).to_a }
+  end
+
+  # Distance-weighted pace, so a longer rep counts for more than a short one.
+  # Nil when the laps covered no distance at all — a standing recovery has a
+  # duration but no pace, and reporting infinity would be worse than reporting
+  # nothing.
+  def weighted_pace(laps, indexes)
+    distance = indexes.sum { |index| laps[index].distance }
+    return nil unless distance.positive?
+
+    indexes.sum { |index| laps[index].elapsed } / distance
+  end
+
+  def converted_pace(pace_per_km, meters)
+    return nil if pace_per_km.nil?
+
+    (pace_per_km * meters / 1000.0).round
+  end
+
+  def median(values)
+    sorted = values.sort
+    middle = sorted.size / 2
+
+    sorted.size.odd? ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2.0
+  end
+
+  def mean(values)
+    values.sum / values.size.to_f
+  end
+end

data/lib/calcpace/training_zones.rb

@@ -33,6 +33,14 @@ module TrainingZones
   # One heart-rate training zone (1 = recovery … 5 = maximal)
   HrZone = Struct.new(:zone, :min_bpm, :max_bpm)
 
+  # Time spent in one heart-rate zone: the zone number, whole seconds, and the
+  # fraction of the counted time that fell in it
+  TimeInZone = Struct.new(:zone, :seconds, :share)
+
+  # Shares are kept as thousandths while they are rounded, so that the five of
+  # them can be made to add up to exactly 1.0 before they become Floats
+  SHARE_UNITS = 1000
+
   # Derives training pace bands from a VO2max value
   #
   # @param vo2max [Numeric] VO2max in ml/kg/min (must be > 0)
@@ -144,8 +152,174 @@ module TrainingZones
     build_hr_zones(HR_ZONE_BOUNDARIES.map { |pct| (pct * max).round })
   end
 
+  # Finds the training zone a heart-rate reading belongs to
+  #
+  # The zones handed in are contiguous, so their boundaries are shared: 114 bpm
+  # is both the top of zone 1 and the bottom of zone 2. The higher zone wins,
+  # the way a watch reads it. Readings outside the range are clamped — below
+  # zone 1 counts as zone 1, above zone 5 as zone 5 — because a reading above
+  # hr_max means the hr_max is wrong, not that the beat did not happen.
+  #
+  # A `between?` lookup written against the zone bounds does neither: it gives a
+  # boundary to the lower zone and returns nothing at all above hr_max.
+  #
+  # @param bpm [Numeric, nil] the reading in beats per minute
+  # @param zones [Array<HrZone>] the zones from #hr_zones or #hr_zones_from_max
+  # @return [HrZone, nil] the zone holding the reading; nil only when bpm is nil
+  #   or not positive, which is what a sensor dropout looks like
+  # @raise [Calcpace::Error] if bpm is neither nil nor Numeric, or zones is empty
+  #
+  # @example
+  #   calc.hr_zone_for(150, calc.hr_zones_from_max(hr_max: 190)).zone #=> 3
+  #   calc.hr_zone_for(114, calc.hr_zones_from_max(hr_max: 190)).zone #=> 2
+  #   calc.hr_zone_for(80, calc.hr_zones_from_max(hr_max: 190)).zone  #=> 1
+  #   calc.hr_zone_for(205, calc.hr_zones_from_max(hr_max: 190)).zone #=> 5
+  def hr_zone_for(bpm, zones)
+    index = hr_zone_index(bpm, zones)
+
+    index && zones[index]
+  end
+
+  # Splits a recorded heart-rate series into the time spent in each zone
+  #
+  # Format-agnostic on purpose: two plain arrays and the zones to sort them
+  # into. A Strava `heartrate`/`time` stream pair fits without translation, and
+  # so does the same pair read out of a FIT file.
+  #
+  # A sample lasts until the next one — <tt>time[i + 1] - time[i]</tt> — and the
+  # last sample, which has no next, is given the previous delta so that a series
+  # does not lose its final seconds. A single sample therefore lasts 0 s.
+  #
+  # That rule has one consequence worth knowing before trusting the numbers: a
+  # **pause is a gap in `time`, and the whole gap is booked to the sample before
+  # it**. Stop for five minutes at a café and those five minutes land in
+  # whatever zone the last beat before the pause was in. There is no max_gap
+  # here to guess a cut-off with. A caller who has Strava's `moving` stream
+  # should nil the heart rate of every paused sample before calling, which is
+  # exactly what the next rule then does with them.
+  #
+  # A sample with a nil or non-positive heart rate contributes nothing at all:
+  # its duration is dropped, never handed to a neighbour, because a dropout says
+  # nothing about which zone the runner was in. So the counted time can be less
+  # than the wall clock, and the shares are shares of what was counted.
+  #
+  # Readings outside the zones are clamped and boundaries go to the higher zone,
+  # exactly as #hr_zone_for describes — an hr_max that is a few beats wrong is
+  # the most common thing an athlete carries around, and clamping keeps that a
+  # distortion of the split instead of making minutes of a run vanish.
+  #
+  # @param heartrate [Array<Numeric, nil>] heart rate in bpm, one entry per sample
+  # @param time [Array<Numeric>] seconds since the start, non-decreasing, same length
+  # @param zones [Array<HrZone>] the five zones from #hr_zones or #hr_zones_from_max
+  # @return [Array<TimeInZone>] one row per zone in zone order, zeros included;
+  #   seconds are Integer, shares Float with 3 decimals that are whole
+  #   thousandths adding up to 1000 over the counted time (all zero when
+  #   nothing was counted)
+  # @raise [Calcpace::Error] if either series is not an Array, if they differ in
+  #   length, if time holds a non-numeric entry or goes backwards, if a heart
+  #   rate is neither nil nor Numeric, or if zones is empty
+  #
+  # @example four minutes of a run against zones for a 190 bpm maximum
+  #   zones = calc.hr_zones_from_max(hr_max: 190)
+  #   in_zones = calc.time_in_zones(heartrate: [120, 120, 140, 140, 160],
+  #                                 time: [0, 60, 120, 180, 240],
+  #                                 zones: zones)
+  #   in_zones.map(&:seconds) #=> [0, 120, 120, 60, 0]
+  #   in_zones.map(&:share)   #=> [0.0, 0.4, 0.4, 0.2, 0.0]
+  #   in_zones[1].zone        #=> 2
+  def time_in_zones(heartrate:, time:, zones:)
+    check_hr_series(heartrate, time, zones)
+
+    totals = zone_seconds(heartrate, time, zones)
+    shares = zone_shares(totals)
+
+    zones.each_with_index.map do |zone, index|
+      TimeInZone.new(zone: zone.zone, seconds: totals[index].round, share: shares[index])
+    end
+  end
+
   private
 
+  # @return [Array<Float>] seconds accumulated in each zone, in zone order
+  def zone_seconds(heartrate, time, zones)
+    totals = Array.new(zones.size, 0.0)
+
+    heartrate.each_with_index do |bpm, index|
+      zone = hr_zone_index(bpm, zones)
+      next if zone.nil?
+
+      totals[zone] += sample_duration(time, index)
+    end
+
+    totals
+  end
+
+  # Rounded on its own each share is out by up to half a thousandth, and five of
+  # those leave a bar chart that does not fill its track. Largest-remainder
+  # rounding spends the residue on the zones that lost the most to rounding, so
+  # the shares add up to exactly 1.0. Ties go to the earlier zone, so the same
+  # series always splits the same way.
+  def zone_shares(totals)
+    counted = totals.sum
+    return Array.new(totals.size, 0.0) unless counted.positive?
+
+    scaled = totals.map { |seconds| seconds * SHARE_UNITS / counted }
+    units = scaled.map(&:floor)
+    largest_remainders(scaled, units, SHARE_UNITS - units.sum).each { |index| units[index] += 1 }
+
+    units.map { |unit| unit / SHARE_UNITS.to_f }
+  end
+
+  # @return [Array<Integer>] the indexes that give up the most to rounding down
+  def largest_remainders(scaled, units, residue)
+    return [] unless residue.positive?
+
+    scaled.each_index.sort_by { |index| [units[index] - scaled[index], index] }.first(residue)
+  end
+
+  # The last sample has no successor, so it inherits the previous delta
+  def sample_duration(time, index)
+    last = time.size - 1
+    return 0.0 if last.zero?
+
+    from = index == last ? last - 1 : index
+    (time[from + 1] - time[from]).to_f
+  end
+
+  # The highest zone the reading reaches, clamped to zone 1 below the bottom
+  def hr_zone_index(bpm, zones)
+    check_zones(zones)
+    return nil if bpm.nil?
+
+    raise Calcpace::Error, "Heart rate must be numeric or nil (got #{bpm.inspect})" unless bpm.is_a?(Numeric)
+
+    bpm.positive? ? (zones.rindex { |zone| bpm >= zone.min_bpm } || 0) : nil
+  end
+
+  def check_hr_series(heartrate, time, zones)
+    unless heartrate.is_a?(Array) && time.is_a?(Array)
+      raise Calcpace::Error, 'Heart rate and time series must both be arrays'
+    end
+    raise Calcpace::Error, 'Heart rate and time series must have the same length' if heartrate.size != time.size
+
+    check_zones(zones)
+    check_time_series(time)
+  end
+
+  # A nil in the middle of the time stream is not a zero-length sample — it is a
+  # stream we cannot measure any duration from, so it is an error, not a drop
+  def check_time_series(time)
+    time.each do |seconds|
+      raise Calcpace::Error, "Every time entry must be numeric (got #{seconds.inspect})" unless seconds.is_a?(Numeric)
+    end
+
+    raise Calcpace::Error, 'Time series must be non-decreasing' if time.each_cons(2).any? { |a, b| b < a }
+  end
+
+  def check_zones(zones)
+    raise Calcpace::Error, 'At least one heart-rate zone is required' if zones.nil? || zones.empty?
+  end
+
   # Turns six ascending bpm boundary points into five contiguous HrZone structs
   def build_hr_zones(points)
     points.each_cons(2).with_index(1).map do |(min_bpm, max_bpm), zone|

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.16.0'
+  VERSION = '1.18.0'
 end

data/lib/calcpace.rb

@@ -9,6 +9,7 @@ require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
 require_relative 'calcpace/errors'
 require_relative 'calcpace/fitness_predictor'
+require_relative 'calcpace/lap_analyzer'
 require_relative 'calcpace/pace_calculator'
 require_relative 'calcpace/pace_converter'
 require_relative 'calcpace/race_predictor'
@@ -48,6 +49,7 @@ class Calcpace
   include Converter
   include ConverterChain
   include FitnessPredictor
+  include LapAnalyzer
   include PaceCalculator
   include PaceConverter
   include RacePredictor

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.16.0
+  version: 1.18.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -45,6 +45,7 @@ files:
 - lib/calcpace/environmental_adjuster.rb
 - lib/calcpace/errors.rb
 - lib/calcpace/fitness_predictor.rb
+- lib/calcpace/lap_analyzer.rb
 - lib/calcpace/pace_calculator.rb
 - lib/calcpace/pace_converter.rb
 - lib/calcpace/race_predictor.rb