Privacy-Period-Tracker/docs/architecture/SCIENCE.md

# The science — which constants are claims about bodies, and on what evidence

```
Status: Current
Owner: _null
Last reviewed: 2026-08-20
Governs: docs/architecture/SCIENCE.md — the constants in domain/prediction that
         encode a claim about menstrual physiology, and the evidence for each
Review trigger: Any change to DEFAULT_LUTEAL_PHASE_DAYS, FERTILE_DAYS_BEFORE_OVULATION,
                FERTILE_DAYS_AFTER_OVULATION, MAX_USEFUL_UNCERTAINTY_DAYS,
                POPULATION_DEFAULT_DAYS, MINIMUM_PLAUSIBLE_DAYS, or the shape of the
                distribution the engine fits
```

> A reader who opens `PersonalPredictionEngine.kt` finds thirty constants and no
> way to tell which are physiology and which are engineering. Both kinds are
> argued for in comments, in the same voice, which makes the difference
> invisible: `MAD_TO_SCALE` was tuned against fixtures and can be retuned by
> anyone with a measurement, while `FERTILE_DAYS_BEFORE_OVULATION` is a claim
> about how long sperm survive and cannot.
>
> This file is the line between them.

## Why this is not in `architecture/README.md`

That document's subject is the module graph and the shapes data takes — it fires
its review trigger on a new Gradle module or a changed Room entity. The evidence
for a luteal phase changes when somebody publishes, which has nothing to do with
either. Two subjects with unrelated review cycles in one document means the one
nobody is looking at goes stale behind the one they are.

## What "supported" means here

**Supported** — the value matches the published measurement, and the citation
says which.

**Needs a caveat** — the value is defensible but the literature says something
the code does not: usually that a population mean hides a distribution the app
cannot see for an individual user. The caveat belongs in the code comment, not
only here.

**Contradicted** — the measurement disagrees, and the constant should move or
the disagreement should be recorded as a deliberate choice with its reason.

**Not a scientific claim** — an engineering parameter. Listed so nobody demands a
citation for one, and so nobody mistakes one for physiology and refuses to tune
it.

## The constants

| Constant | Where | Value | Verdict |
| --- | --- | --- | --- |
| `DEFAULT_LUTEAL_PHASE_DAYS` | `FertilityEstimate.kt` | 14 | Needs a caveat |
| `FERTILE_DAYS_BEFORE_OVULATION` | `FertilityEstimate.kt` | 5 | Supported |
| `FERTILE_DAYS_AFTER_OVULATION` | `FertilityEstimate.kt` | 1 | Supported, deliberately conservative |
| `MAX_USEFUL_UNCERTAINTY_DAYS` | `FertilityEstimate.kt` | 3 | Product judgment, not biology |
| `POPULATION_DEFAULT_DAYS` | `PersonalPredictionEngine.kt` | 29.0 | Was 28.0 — contradicted, changed |
| Laplace tails | `PersonalPredictionEngine.kt` | — | Supported, with a caveat about skew |
| `MINIMUM_PLAUSIBLE_DAYS` | `IntervalAnalysis.kt` | 10 | Supported |
| `MULTIPLE_TOLERANCE`, `UNUSUAL_TOLERANCE` | `IntervalAnalysis.kt` | 0.18, 0.35 | Not scientific claims |
| Everything in the engine's spread and confidence blocks | `PersonalPredictionEngine.kt` | — | Not scientific claims |

### `DEFAULT_LUTEAL_PHASE_DAYS` = 14 — needs a caveat

Fourteen days is the textbook convention, and the app anchors every ovulation
estimate to it: ovulation is estimated as the predicted period minus this.
Anchoring backwards from the *next* period rather than forwards from the last is
the defensible half, and the reason is real — the luteal phase is the more stable
part of the cycle, so the follicular phase absorbs most of the variation.

The caveat is that "more stable" is not "fixed", and 14 is above the measured
mean. Large studies of app-recorded cycles put the luteal phase closer to 12–13
days on average, with a normal range of roughly 11–17. A woman with an 11-day
luteal phase has her ovulation estimated three days late by this constant.

Kept for now, and filed rather than changed — moving it shifts what the fertility
screen shows every user, which is a product decision with its own evidence and
its own QA, not a line inside a prediction-calibration change. The constant is
already named and overridable rather than buried in arithmetic, so the day this
app can measure a user's own luteal phase, one value changes.

What protects the user meanwhile is not this constant but the two rules around
it: the estimate is a *window*, never a day presented as fact, and
`MAX_USEFUL_UNCERTAINTY_DAYS` makes the app decline entirely when the forecast is
too vague to hang one on.

**Sources.** Bull et al., *Real-world menstrual cycle characteristics of more
than 600,000 menstrual cycles* (npj Digital Medicine, 2019). Lenton et al., *The
normal variation of the length of the luteal phase of the menstrual cycle*
(BJOG, 1984).

### `FERTILE_DAYS_BEFORE_OVULATION` = 5 — supported

The fertile window opens before ovulation, not on it, because sperm survive in
the reproductive tract for several days. The classic prospective study of
conception timing found essentially all conceptions occurred within a six-day
window ending on the day of ovulation itself.

Five days before, plus the day of ovulation, is that window. No change.

**Source.** Wilcox, Weinberg & Baird, *Timing of sexual intercourse in relation
to ovulation* (New England Journal of Medicine 333:1517, 1995).

### `FERTILE_DAYS_AFTER_OVULATION` = 1 — supported, and conservative on purpose

The egg is viable for roughly 12–24 hours, and the same study found conception
probability falling to essentially zero the day after ovulation. One day is
therefore at or slightly beyond the measured edge.

That direction is deliberate. Every rounding decision in the fertility estimate
widens the window rather than narrowing it, because a window that is too wide
tells a user the app is unsure, and one that is too narrow tells her something
false about a day. §18 has already promised this is not contraception; the
arithmetic should not quietly imply otherwise.

**Source.** Wilcox, Weinberg & Baird (1995), as above.

### `MAX_USEFUL_UNCERTAINTY_DAYS` = 3 — a product judgment, and it should stay one

Past this much forecast uncertainty the app offers no fertility estimate at all.
This is not a biological threshold and should never be cited as one: the fertile
window is inherently seven days wide before any forecast uncertainty is added, so
a forecast carrying ±5 produces a seventeen-day "fertile window" — over half a
cycle, honest arithmetic, and useless information. It was on screen before
anybody noticed.

The literature supports the *shape* of the decision rather than the number:
calendar-based ovulation estimates carry several days of irreducible uncertainty
even for women who describe their cycles as regular, so there is no threshold at
which a calendar app should present a precise ovulation day. Even at uncertainty
zero this app shows a range.

**Source.** Wilcox, Dunson & Baird, *The timing of the "fertile window" in the
menstrual cycle: day specific estimates from a prospective study* (BMJ 321:1259,
2000).

### `POPULATION_DEFAULT_DAYS` = 29.0 — was 28.0, and 28.0 was wrong

This is the only cycle length the engine ever assumes: the forecast for a user
with exactly one confirmed period and therefore no interval to measure. It is
replaced by her own data the moment she has any.

Twenty-eight is the number everyone knows, and the large app-data studies agree
it is not the average. Mean cycle length across hundreds of thousands of users
sits near 29 days, and only a minority of women average 28 — cycle length also
shortens with age, which no single constant can express.

Changed to 29.0. The honest gain is small and worth having anyway: the app's one
unavoidable guess is now the population's actual centre rather than the
folklore's.

**`BaselinePredictionEngine.DEFAULT_CYCLE_DAYS` stays 28.0 and must not be
changed.** That engine is the frozen control `EngineComparisonTest` measures
against; moving it would silently move the yardstick.

**Sources.** Bull et al. (2019), as above. Grieger & Norman, *Menstrual cycle
length and patterns in a global cohort of women using a mobile phone app* (JMIR,
2020).

### The Laplace distribution — supported, with a caveat the engine handles elsewhere

The engine fits a Laplace rather than a normal distribution over candidate start
dates. The justification in the code is that cycle lengths have heavier tails
than a bell curve, and that is what the distributional data shows: cycle-length
distributions are leptokurtic, and under a normal fit a period arriving four days
late reads as nearly impossible, so the model refuses to widen and stays
confidently wrong.

The caveat is that the real distribution is also **right-skewed** — long cycles
are further from the centre than short ones — and a symmetric Laplace does not
express that. What compensates is not a distributional trick but the censoring in
§13: as each day passes without a period, the mass on that day is removed and the
remainder renormalised, so the surviving distribution leans late exactly when the
evidence says it should. `OVERDUE_WIDENING` extends the same idea past the end of
the window.

Worth knowing if anybody replaces the distribution: a skewed family would let the
engine express this before the user has to answer "Not yet" three times.

**Sources.** Chiazze et al., *The length and variability of the human menstrual
cycle* (JAMA 203:377, 1968). Bull et al. (2019), distribution figures.

### `MINIMUM_PLAUSIBLE_DAYS` = 10 — supported

A gap shorter than this between two confirmed *starts* is discarded as an
interval. The clinical description of a normal cycle runs roughly 24–38 days, and
nothing at 9 days is a menstrual cycle: it is a re-entry, a correction, or two
records of one period.

Bleeding genuinely occurring between periods is a real thing and this app records
it — as spotting, which by design cannot start or reset a cycle.

**Source.** Munro et al., *The FIGO classification of causes of abnormal uterine
bleeding* — FIGO AUB System 1 (2018).

### The engineering constants — no citation exists, and none is needed

`MULTIPLE_TOLERANCE` and `UNUSUAL_TOLERANCE` decide when an interval is
questionable, and they are expressed as fractions of *this user's own* centre
rather than as day counts. That relative framing is the part with evidence behind
it — within-woman variation is what the cycle literature describes, and a global
day-count threshold gets the unusual user wrong, which is precisely the user this
product exists for. The fractions themselves were tuned against fixtures.

The same applies to everything in the engine's spread and confidence blocks —
`MAD_TO_SCALE`, `AGREEMENT_SENSITIVITY`, `WINDOW_MASS`, the thresholds, the
recency decay. They are calibration, they were measured, and they are recorded in
`LearningCurveTest` rather than in the literature. Two of them carry an identity
rather than a tuning — `EXPECTED_ERROR_PER_SCALE` is 1.0 because the mean
absolute deviation of a Laplace distribution equals its scale, and the
estimation-uncertainty term is √(1 + 1/n) for the same textbook reason — and
those are mathematics, not physiology, so they are not in the table above either.

## What this file does not claim

That the engine is clinically validated. It is not, and nothing here should be
read as a medical claim about an individual user. These citations justify the
*defaults and shapes* the app assumes in the absence of her data, which is a much
smaller claim: that where the app has to guess, it guesses what the population
data says rather than what folklore says, and that it declines rather than
inventing precision when her own data cannot support an answer.