HealthKit - Menstrual cycle start date / how cycles are split?

Hey!

TLDR: How Health app knows the new menstruation cycle started?

The API

Adding .menstrualFlow (HKCategoryValueMenstrualFlow) samples require HKMetadataKeyMenstrualCycleStart: Bool parameter. It's fairly simple for the consecutive days - the first sample includes true, the rest false.

The problem

What about more complex scenarios like: 3 days of unspecified samples, then 2 days of none samples, and unspecified sample again. Should it be marked as the new cycle start? I don't want to prompt the user to confirm the new menstruation cycle.

Observations

I noticed Health app performs some logic under the hood.

For instance, when I marked 5 days in a row unspecified, then left 6 days in a row empty, then selected unspecified again, I got 2 menstruation cycles (11 days ago and today).

But when I changed the number of the days I marked as unspecified before the gap, or the length of the gap, or edited the cycles further in the past, I ended up having just 1 menstruation cycle.

I guess Health app takes into consideration: previous menstruation length, gap length, average cycle length. But what is the exact math here? I don't want to ruin the user's statistics 💚

I found in the user guide this info about the fertility:

The fertile window will be the six days you're most likely to be fertile, based on data that you’ve logged about your period or a positive ovulation test result. The fertile window prediction is based on a traditional calendar method. The fertile window is calculated by subtracting 13 days (the luteal phase) from the estimated next cycle start date.

So I think something similar might be going on here.

Thanks in advance!

HealthKit - Menstrual cycle start date / how cycles are split?
 
 
Q