HealthKit

Reference
1

Apple HealthKit is a powerful framework that allows researchers to access a comprehensive range of health and fitness data collected by participants’ iPhones and paired Apple Watch devices. It acts as a central repository for metrics on physical activity, vital signs, sleep, nutrition, mobility, and more, offering researchers valuable insights into participants’ health behaviors and outcomes.

Supported HealthKit Metrics in Avicenna

Below is a comprehensive list of HealthKit metrics that Avicenna supports. We’ll first cover the common fields that appear across all HealthKit data types, followed by the specific fields for each individual metric.

Common Fields Across All HealthKit Data Sources

All metrics include the common data fields and the following additional fields:

  • Start Date: Start time of the measurement period. Internally stored as start_date.
  • End Date: End time of the measurement period. Internally stored as end_date.
  • Device: HealthKit device information serialized as a string. Internally stored as device. It contains the following fields:
    • Model: Device model type. Internally stored as device.model. It can be one of:
      • UNKNOWN (0)
      • IPHONE (1)
      • WATCH (2)
      • IPAD (3)
      • OTHER (4)
    • Name: Device name. Internally stored as name.
    • UDI: Unique Device Identifier (UDI). Internally stored as udi.
    • Firmware Version: Firmware version of the device. Internally stored as firmware_version.
    • Hardware Version: Hardware version of the device. Internally stored as hardware_version.
    • Local Identifier: Local identifier of the device. Internally stored as local_identifier.
    • Manufacturer: Device manufacturer. Internally stored as manufacturer.
    • Software Version: Software version of the device. Internally stored as software_version.
  • Source Revision: HealthKit source revision information serialized as a string. Internally stored as source_revision. It contains the following fields:
    • Source: Source app information. Internally stored as source. It contains the following fields:
      • Name: Source app name. Internally stored as name.
      • Bundle Identifier: Source app bundle identifier. Internally stored as bundle_identifier.
    • Version: Source app version. Internally stored as version.
    • Product Type: Product type of the device (e.g., “iPhone13,4”, “Watch6,2”). Internally stored as product_type.
    • Operating System Version: Operating system version (e.g., “17.0.0”, “18.1.2”). Internally stored as operating_system_version.
  • Product Type: Product type of the device that recorded the data (e.g., “iPhone13,4”, “Watch6,2”). Internally stored as product_type.
  • Operating System Version: Operating system version of the device that recorded the data (e.g., “17.0.0”, “18.1.2”). Internally stored as operating_system_version.

HealthKit Activity

Captures participant activity, including movement, energy expenditure, and workout data. Internally stored as healthkit_activity and includes:

  • Step Count: Number of steps taken. Internally stored as step_count.
  • Distance Walking Running: Distance walked or run in meters. Internally stored as distance_walking_running.
  • Distance Cycling: Distance cycled in meters. Internally stored as distance_cycling.
  • Push Count: Number of wheelchair pushes. Internally stored as push_count.
  • Distance Wheelchair: Distance traveled in wheelchair in meters. Internally stored as distance_wheelchair.
  • Swimming Stroke Count: Number of swimming strokes. Internally stored as swimming_stroke_count.
  • Distance Swimming: Distance swum in meters. Internally stored as distance_swimming.
  • Distance Downhill Snow Sports: Distance traveled in downhill snow sports in meters. Internally stored as distance_downhill_snow_sports.
  • Basal Energy Burned: Basal energy burned in kilocalories. Internally stored as basal_energy_burned.
  • Active Energy Burned: Active energy burned in kilocalories. Internally stored as active_energy_burned.
  • Flights Climbed: Flights of stairs climbed. Internally stored as flights_climbed.
  • Nike Fuel: Nike Fuel points. Internally stored as nike_fuel.
  • Apple Exercise Time: Exercise time in minutes. Internally stored as apple_exercise_time.
  • Apple Stand Time: Stand time in minutes. Internally stored as apple_stand_time.
  • VO2 Max: Maximum oxygen consumption during exercise. Internally stored as vo2_max.
  • Apple Move Time: Move time in minutes. Internally stored as apple_move_time.
  • Running Speed: Running speed in meters per second. Internally stored as running_speed.
  • Running Stride Length: Running stride length in meters. Internally stored as running_stride_length.
  • Running Power: Running power in watts. Internally stored as running_power.
  • Running Ground Contact Time: Ground contact time during running in seconds. Internally stored as running_ground_contact_time.
  • Running Vertical Oscillation: Vertical oscillation during running in meters. Internally stored as running_vertical_oscillation.
  • Apple Stand Hour: Stand hour indicator. Internally stored as apple_stand_hour.
  • Low Cardio Fitness Event: Low cardio fitness event indicator. Internally stored as low_cardio_fitness_event.

HealthKit Vital Signs

Provides insight into cardiovascular and respiratory health. Internally stored as healthkit_vital_signs and includes:

  • Heart Rate: Heart rate in beats per minute (BPM). Internally stored as heart_rate.
  • Heart Rate Event: Event associated with heart rate. Internally stored as heart_rate_event. It can be one of the following values:
    • LOW_HEART_RATE_EVENT (0)
    • HIGH_HEART_RATE_EVENT (1)
    • IRREGULAR_HEART_RHYTHM_EVENT (2)
  • Resting Heart Rate: Baseline resting heart rate in beats per minute (BPM). Internally stored as resting_heart_rate.
  • Walking Heart Rate Average: Average heart rate while walking, in beats per minute (BPM). Internally stored as walking_heart_rate_average.
  • Heart Rate Variability (SDNN): Standard deviation of heartbeat intervals (SDNN), measured in milliseconds. Internally stored as heart_rate_variability_sdnn.
  • Systolic Blood Pressure: Systolic blood pressure in millimeters of mercury (mmHg). Internally stored as blood_pressure_systolic.
  • Diastolic Blood Pressure: Diastolic blood pressure in millimeters of mercury (mmHg). Internally stored as blood_pressure_diastolic.
  • Atrial Fibrillation Burden: An estimate of the percentage of time a person’s heart shows signs of atrial fibrillation (AFib) while wearing Apple Watch. Internally stored as atrial_fibrillation_burden.
  • Oxygen Saturation: Blood oxygen saturation measured as a decimal value ranging from 0.0 to 1.0. Internally stored as oxygen_saturation.
  • Respiratory Rate: Breaths per minute. Internally stored as respiratory_rate.
  • Body Temperature: Body temperature in degrees Celsius. Internally stored as body_temperature.
  • Heart Rate Recovery (1 Minute): The reduction in heart rate from the peak exercise rate to the rate one minute after exercising ended, measured in beats per minute (BPM). Internally stored as heart_rate_recovery_one_minute.

HealthKit Sleep

Records the sleep analysis of a user. Internally stored as apple_health_kit_sleep and includes:

  • Sleep Analysis: Type of sleep recorded. Internally stored as sleep_analysis. It can be one of the following:
    • IN_BED (0)
    • ASLEEP (1)
    • AWAKE (2)
    • CORE (3)
    • DEEP (4)
    • REM (5)
  • Sleep Wrist Temperature: Wrist temperature in degrees Celsius. Internally stored as sleep_wrist_temperature.

HealthKit State of Mind

iOS 18+

Provides insight into a user’s emotional state and mood. Internally stored as apple_health_kit_state_of_mind and includes:

  • Kind: Type of mood captured. Internally stored as state_of_mind_kind. Possible values include:
    • MOMENTARY_EMOTION (0)
    • DAILY_MOOD (1)
  • Valence: A continuous score that captures the emotional tone of a user’s mood ranging from -1 to 1. Internally stored as valence.
  • Valence Classification: A categorical classification of the emotional tone of a user’s mood. Internally stored as valence_classification. It can be one of the following:
    • VERY_UNPLEASANT(0)
    • UNPLEASANT (1)
    • SLIGHTLY_UNPLEASANT (2)
    • NEUTRAL (3)
    • SLIGHTLY_PLEASANT (4)
    • PLEASANT (5)
    • VERY_PLEASANT (6)
  • Labels: A list of participant-selected descriptors of mood. Internally stored as labels. It can contain one or more of the following:
    • AMAZED (0)
    • AMUSED (1)
    • ANGRY (2)
    • ANXIOUS (3)
    • ASHAMED (4)
    • BRAVE (5)
    • CALM (6)
    • CONTENT (7)
    • DISAPPOINTED (8)
    • DISCOURAGED (9)
    • DISGUSTED (10)
    • EMBARRASSED (11)
    • EXCITED (12)
    • FRUSTRATED (13)
    • GRATEFUL (14)
    • GUILTY (15)
    • HAPPY (16)
    • HOPELESS (17)
    • IRRITATED (18)
    • JEALOUS (19)
    • JOYFUL (20)
    • LONELY (21)
    • PASSIONATE (22)
    • PEACEFUL (23)
    • PROUD (24)
    • RELIEVED (25)
    • SAD (26)
    • SCARED (27)
    • STRESSED (28)
    • SURPRISED (29)
    • WORRIED (30)
    • ANNOYED (31)
    • CONFIDENT (32)
    • DRAINED (33)
    • HOPEFUL (34)
    • INDIFFERENT (35)
    • OVERWHELMED (36)
    • SATISFIED (37)
  • Associations: A list of contexts associated with the mood. Internally stored as associations. It can contain one or more of the following:
    • COMMUNITY (0)
    • CURRENT_EVENTS (1)
    • DATING (2)
    • EDUCATION (3)
    • FAMILY (4)
    • FITNESS (5)
    • FRIENDS (6)
    • HEALTH (7)
    • HOBBIES (8)
    • IDENTITY (9)
    • MONEY (10)
    • PARTNER (11)
    • SELF_CARE (12)
    • SPIRITUALITY (13)
    • TASKS (14)
    • TRAVEL (15)
    • WORK (16)
    • WEATHER (17)

Adding HealthKit As a Data Source

See Adding Data Sources.

Data Collection Behavior

HealthKit data is collected within Avicenna’s standard 5-minute collection cycle. The app queries the HealthKit store for new data since the last fetch. This process avoids duplicates and prioritizes the most accurate source, such as an Apple Watch over an iPhone. New data is available for collection almost immediately after a device syncs with Apple Watch.

Monitoring and Exporting HealthKit Data

You can export and download the collected HealthKit data using the Data Export page.