[Feature] Expand environmental context with air quality, heat, UV, pollen, and smoke exposure

[lutzkind]

Summary

Expand HealthLog’s existing opt-in Environment module beyond historical weather and daylight to include health-relevant ambient exposure context such as air pollution, heat stress, UV, pollen, dust, and wildfire smoke.

The current module already has a strong architecture: coarse city-level location, effective dates, travel overrides, historical backfill, nightly refresh, external-provider attribution, and lagged environmental correlation channels. This feature should extend that foundation while preserving privacy, provenance, uncertainty, and the distinction between ambient modeled conditions and a person’s actual exposure.

Current foundation

HealthLog currently supports coarse home location and dated travel overrides, then stores daily environmental observations including temperature, apparent temperature, sunshine, daylight, precipitation, pressure, humidity, cloud cover, and weather code.

A subset of these values can already participate in personal correlation discovery against later sleep, mood, and vital outcomes.

This proposal is therefore an extension of the existing module rather than a new location system.

Problem

Location can provide useful health context beyond ordinary weather:

• Fine-particle and ozone exposure can coincide with respiratory and cardiovascular changes.
• Hot days and hot nights can affect sleep, resting pulse, activity, hydration needs, and medication safety.
• Pollen can help contextualize allergy and respiratory symptoms.
• Wildfire smoke and dust can produce large short-term exposure changes.
• UV can support prevention-oriented guidance.
• Travel can introduce altitude, heat, air-quality, pollen, and timezone changes simultaneously.

At present, HealthLog cannot store or surface most of these contextual exposures. This limits both retrospective analysis and proactive Coach guidance.

Proposed exposure channels

1. Air pollution

Initial health-relevant pollutants:

• PM2.5.
• PM10.
• Ozone (O₃).
• Nitrogen dioxide (NO₂).
• Sulfur dioxide (SO₂).
• Carbon monoxide (CO).
• Provider-supplied regional and/or national AQI values where available.

Store raw pollutant concentration where possible rather than only an AQI category. AQI can be derived or stored alongside it, but national AQI systems differ and should retain the standard/provider used.

Potential analytics outcomes include:

• Resting heart rate and nocturnal heart rate.
• HRV and recovery/readiness.
• Respiratory rate.
• Oxygen saturation.
• Breathing disturbances.
• Activity and outdoor workouts.
• Illness/symptom logs, particularly respiratory symptoms and headache.
• Sleep duration and fragmentation.

2. Heat and thermal stress

Derive and store useful daily or hourly summaries such as:

• Apparent temperature and heat index.
• Maximum heat stress.
• Hours above configurable heat thresholds.
• Hot-night exposure, such as overnight minimum temperature or hours above a nighttime threshold.
• Consecutive hot days.
• Cold exposure equivalents where useful.
• Humidity-adjusted thermal context.

Heat should be contextualized rather than presented as a diagnosis or direct cause.

3. UV

• Daily maximum UV index.
• Optional cumulative UV estimate.
• High-UV duration where provider resolution permits.
• Prevention-oriented alerts based on current or forecast conditions, subject to separate real-time provider support.

Location-only UV remains ambient potential exposure. It should not imply the person was outdoors.

4. Pollen and allergens

Where provider coverage is available:

• Grass pollen.
• Tree pollen categories/species where reliable.
• Weed pollen.
• Mold or fungal-spore context if a suitable source is available.

Pollen coverage and model quality vary significantly by region. Missing or low-confidence regional coverage should be represented honestly rather than filled with fabricated values.

5. Smoke, dust, and aerosols

• Wildfire-smoke indicators where available.
• Dust or aerosol concentration.
• Smoke-event flags derived from provider data only when methodology is documented.
• Link smoke/dust context to PM2.5/PM10 without double-counting the same signal as independent exposures.

6. Additional travel context

Potential later extensions:

• Altitude/elevation and significant altitude changes.
• Timezone changes and jet-lag context.
• Workout-route exposure when route sharing is explicitly enabled.
• Device-supplied coarse per-day location using the reserved DEVICE location precedence slot.

These should remain optional and should not require continuous GPS history.

Provenance and exposure semantics

Every environmental record should distinguish:

• Modeled ambient data.
• Nearby monitoring-station observation.
• Local sensor data.
• Device-measured exposure.
• User-reported indoor context.

Recommended metadata:

• Provider and dataset/model.
• Fetch time and observation time.
• Spatial and temporal resolution where known.
• Location source: home, travel override, device, workout route, or local sensor.
• Confidence/coverage indicator.
• Raw unit and canonical unit.
• Whether the value is measured, modeled, derived, or inferred.

HealthLog should never imply that city-level PM2.5 or temperature equals the person’s exact inhaled or indoor exposure. Indoor time, ventilation, air-conditioning, filtration, commuting, and personal activity all affect actual exposure.

Provider architecture

The existing provider abstraction and self-host-friendly design should be preserved.

Requirements:

• Provider configuration controlled by the operator where appropriate.
• Clear attribution and license compliance.
• Safe bounded egress and timeouts.
• Retry/backfill behavior consistent with the existing Environment module.
• Ability to omit unavailable fields rather than fail the entire day.
• No hard dependency on a paid API for core self-hosted operation where a reasonable open provider exists.
• Schema should not be tied irreversibly to one provider’s AQI nomenclature.

UI proposal

Add an Environment Insights surface showing:

• Current coverage range and latest stored date.
• Location source used for each period.
• Daily air-quality and thermal context.
• Exposure categories with raw values and provider standard.
• High-exposure days and trends.
• Missing-data/low-confidence indicators.
• Personal associations that have passed the separate statistical discovery gates.
• Provider attribution.

Settings should allow users to:

• Enable or disable individual environmental categories.
• Set or update home location and effective date.
• Add travel overrides.
• Backfill supported history.
• Choose whether environmental data may be used by Coach and correlations.
• Delete stored environmental history without deleting health measurements.

Coach and notification behavior

The environment module may provide context such as:

PM2.5 was elevated on three days when respiratory symptoms were logged.

It should not state:

Pollution caused your symptoms.

Proactive guidance should be confidence-gated and distinguish:

• General public-health guidance based on the environmental condition.
• A personal association discovered from the user’s own data.
• A profile-based priority, such as asthma or migraine context supplied by the user.

Any real-time or forecast alerting should remain separate from retrospective historical analysis and should identify the forecast provider and uncertainty.

Relationship to Health Score

Environmental conditions should remain explanatory exposure context and should not directly lower a person’s Personal Health Score merely because they live in a hot or polluted region.

A clean separation is:

• Personal Health Score: physiological/clinical and behavioral outcome pillars.
• Readiness/recovery: short-term physiological state.
• Environmental context/exposure: external conditions and modeled exposure load.
• Coverage/confidence: completeness and reliability.

Environment may help explain changes and prioritize guidance, but should not become an opaque score penalty.

Privacy requirements

• Environment module remains opt-in.
• City-level coordinates remain the default privacy floor.
• No continuous location tracking is required.
• Device location, workout routes, and local sensors require separate explicit consent.
• Raw coordinates should not be injected into Coach prompts when summarized exposure values are sufficient.
• Location and exposure records must be exportable and deletable.
• Logs and telemetry must not contain precise location or sensitive health/profile content.
• Historical home assignment must remain conservative: do not apply the current home to dates before its effective date.

Acceptance criteria

• HealthLog can store daily PM2.5, PM10, O₃, NO₂, SO₂, CO, and AQI context when available.
• Heat-stress and hot-night summaries are supported using documented derivations.
• UV, pollen, smoke, and dust fields can be stored with explicit provider coverage and confidence.
• Records retain provider, units, location source, and modeled/measured provenance.
• Missing individual fields do not invalidate an otherwise usable environmental day.
• The Environment Insights UI exposes coverage, values, location source, confidence, and attribution.
• Users can independently control storage/use of environmental categories.
• Historical backfill and travel overrides continue to work.
• Environmental channels can be supplied to the separate personal-pattern discovery engine without automatically affecting the Personal Health Score.
• Tests cover location precedence, effective dates, travel, provider partial data, unit normalization, provenance, privacy redaction, backfill idempotency, and deletion/export.

Related work

• Structured contextual and lifestyle events: [Feature] Add a unified contextual-factor timeline and structured lifestyle-event logging #613.
• Structured long-term health/lifestyle profile: [Feature] Expand the encrypted health profile with a structured health and lifestyle questionnaire #614.
• Personal multi-factor pattern discovery and Coach explanations should consume this exposure data through a separate feature request.

[MBombeck]

Thank you for this, @lutzkind, and for the care you put into writing it up. Richer environmental context (air quality, heat, UV, pollen, smoke) is a natural extension of what's already there.

I want to be straight about timing: the near-term focus is on making the foundation rock solid, reliability, sync, and the quality issues you and others have surfaced, rather than new features. So I am capturing this as a roadmap item rather than starting on it right away. It is noted and valued, and I would rather build it well later than rush it now. Please keep the ideas coming.