Life Wheel¶

Purpose¶

The Life Wheel summarizes the recent quality of signals that were actually recorded for each axis. Missing values are not interpreted as zero or as a bad day. A small number of entries or old entries do, however, produce lower momentum and therefore a more cautious visible score.

The visible score follows the fixed invariant:

\[ \boxed{S=100\,Q\,M} \]

Here, \(Q\) is time- and importance-weighted quality and \(M\) is momentum derived from the recent evidence base.

From field to axis¶

Normal tracking fields belong to a section through field.section. Each active section can be connected to at most one Life Wheel axis through radarAxis.

flowchart LR
    F[Field or event] --> B[Section]
    B --> T[Daily section quality]
    T --> A[Daily axis quality]
    A --> Q[time-weighted quality]
    A --> M[momentum]
    Q --> S[visible score]
    M --> S

The following rules apply:

A section can be assigned to no axis or exactly one axis.
Several sections may point to the same axis.
Each section is calculated independently first.
When several sections point to the same axis, their available daily qualities are averaged equally. A section with many fields therefore does not automatically overpower a smaller section.
Inactive sections and sections without a valid axis assignment do not contribute.
Fields inherit their section's axis; fields cannot be assigned directly to an axis.

Window, recency and momentum¶

Parameter	Value
Evaluation window	28 days
Half-life	7 days
Momentum scale	4
Base supportive-action bonus limit	25% of the remaining quality gap
Visible score	0–100

The recency weight of a signal aged \(a\) days is:

\[ r(a)=2^{-a/7} \]

An entry from today has weight 1, a seven-day-old entry has weight 1/2, and a 14-day-old entry has weight 1/4.

Each day with at least one valid signal contributes exactly one evidence unit to the axis. Several fields or events on the same day therefore do not create multiple momentum units.

Effective evidence \(E\) is:

\[ E=\sum_d e_d\,r(a_d) \]

Here, \(e_d=1\) when day \(d\) contains at least one valid signal for the axis. Momentum is:

\[ M=1-\exp\!\left(-\frac{E}{4}\right) \]

Important: Field and catalog-item weighting never changes \(E\) or \(M\). Weighting can make quality count more or less strongly, but it cannot create an artificial evidence base.

Goal direction and initial quality¶

Numeric fields use their configured goal direction:

high: higher values are more favorable,
low: lower values are more favorable,
target: values inside the target range are optimal; outside it, quality falls toward the scale boundaries,
neutral: no Life Wheel signal.

qualityAtMin and qualityAtMax can set scale-boundary qualities to values other than zero.

Status values are interpreted as follows:

Value	Initial quality
`yes` / `true`	1.00
`partial`	0.65
`no` / `false`	0.00
`na`, empty, missing	no signal

For goal direction low, status quality is inverted.

Weighting levels¶

Fields and supported catalog items use only these levels:

Level	Weight \(w\)
less important	0.7
standard	1.0
more important	1.5
very important	2.0

Invalid or old intermediate values are normalized to standard 1.0.

Weighting acts in three places:

State values inside a section use a weighted mean.
Actions are combined with weighted saturation and their bonus limit is adjusted.
Daily qualities with greater mean importance count more strongly toward overall quality \(Q\) inside the 28-day window.

It explicitly does not affect momentum.

States and supportive actions¶

Every signal has a role:

State: describes the current condition, such as mood, stress or sleep quality.
Supportive action: describes something helpful that was done, such as a routine, exercise or self-care.

Automatic classification:

Boolean and status → action,
scale → state,
duration and number with goal high → action,
target ranges touching a scale boundary → action,
other numeric target ranges → state.

radarRole can override the automatic result with state or action.

State quality inside a section¶

For states with quality \(q_i\) and weight \(w_i\):

\[ q_Z=\frac{\sum_i w_iq_i}{\sum_i w_i} \]

Action quality inside a section¶

Several actions are combined with saturation:

\[ q_A=1-\prod_i(1-q_i)^{w_i} \]

Let \(\bar{w}_A\) be the mean action weight. The bonus limit is:

\[ b=\min\!\left(1,\;0.25\,\bar{w}_A\right) \]

The limit is therefore normally 25% at weight 1.0 and can reach 50% of the remaining quality gap at weight 2.0.

Daily section quality is:

\[ q_{\mathrm{section}}= \begin{cases} q_A, & \text{when no state is available},\\[4pt] q_Z+(1-q_Z)\,q_A\,b, & \text{when at least one state is available}. \end{cases} \]

A positive action can improve an existing state, but it can never lower it or fully replace it.

Several sections on one axis¶

When results from \(n\) assigned sections are available on a day, they are averaged equally:

\[ q_d=\frac{1}{n}\sum_{s=1}^{n}q_{d,s} \]

Daily importance \(w_d\) is the mean importance of those available section results. Missing sections are not inserted as zero values.

Time-weighted quality¶

For each available day \(d\), let:

\(q_d\): daily axis quality,
\(w_d\): mean daily importance,
\(a_d\): age of the day.

Then:

\[ Q=\frac{\sum_d q_d\,w_d\,r(a_d)}{\sum_d w_d\,r(a_d)} \]

Recent and more important daily qualities influence \(Q\) more strongly. Momentum, in contrast, is calculated only from time-weighted evidence \(E\).

Visible axis score¶

The final formula, protected by regression tests, is:

\[ \boxed{S=100\,Q\,M} \]

In percentage form:

\[ S=\frac{\text{quality in %}\times\text{momentum in %}}{100} \]

One perfect entry from today has \(Q=1\), but only:

\[ M=1-\exp(-1/4)\approx0.2212 \]

Therefore:

\[ S=100\times1\times0.2212\approx22.12 \]

A single perfect day produces about 22 points, not 100 points. Repeated recent evidence is required to build momentum.

quality, momentum, effectiveEvidence, coverage and hasData remain available separately. When hasData: false, the interface shows a dash or “No data” rather than an evaluative zero.

Dynamic events¶

Social contacts are states derived from connection on a 1–5 scale.
Exercise is an action; feeling afterward and exertion determine quality. Exertion 4/5 is optimal, while 5/5 is rated lower.
Self-care is an action; feeling, relaxation and clarity determine quality.
Meals are states derived from amount, balance and feeling afterward.
A relapse sets that day's recovery signal to zero.
An explicit no-urge check-in creates a positive recovery signal.
For urge events, the highest intensity of the day is used.
Triggers create their own recovery signal, which decreases with the weighted count.

Weighted or hidden catalog items – such as people, exercise types or triggers – are respected by these event signals.

Field versions and hidden content¶

Historical field versions remain analyzable. Their stored definition continues to determine type, goal direction and section. The current field version with the same logicalId determines whether the field is active and which current weight is used.

When the current version is hidden, its historical versions are also excluded from the Life Wheel. Hidden catalog items do not contribute either.