MeasureMe (Core Library)

The MeasureMe project is an open source Python library for storing health data in a vendor agnostic way. It utilizes SQLAlchemy to provide a privacy-first, local database (SQLite/MariaDB) to store your metrics safely without requiring cloud servers.

Integrations are required to fetch data from proprietary sources and write them to the database.

Installation

Requires Python 3.9+.

Use pip to install:

pip install measureme

For local development, clone the repository and install the development requirements:

pip install -r requirements-dev.txt

Example

How to use MeasureMe:

FitBit Ingestion

An example script has been provided that ingests FitBit data, exported using Google Takeout.

The script relies on FitOut, which is installed via pypi:

pip install fitout

Export FitBit Data using Google TakeOut

Export your FitBit data, using Google Takeout.

Once the export is complete, download the zip file. I use C:/Dev/Fitbit/Google/. This directory is the takeout_dir.

Ingest the Data

The ingest_fitout is available as a callable script, and can be used directly:

ingest_fitout "C:/Dev/Fitbit/Google/takeout-20260320T162823Z-3-001.zip" --start 2024-01-01 --end 2026-03-20

By default, this will create and populate a local SQLite database named measureme_dev.db in the current directory. Once the data has been ingested, it can be queried using the MeasureMe library.

See the tool README for full details.

Trivial Example

For the full, runnable script, see examples/basic_query.py.

from measureme.database import get_engine, get_session_maker
from measureme.models import HealthMetric, HealthSession

engine = get_engine("sqlite:///measureme_dev.db")
Session = get_session_maker(engine)

with Session() as session:
    # Query the 5 most recent sleep sessions
    recent_sleep = session.query(HealthSession)\
        .filter(HealthSession.session_type == 'sleep')\
        .order_by(HealthSession.start_time.desc())\
        .limit(5).all()
        
    for sleep in recent_sleep:
        duration_hrs = sleep.duration_seconds / 3600.0 if sleep.duration_seconds else 0
        print(f"Date: {sleep.start_time.date()}, Duration: {duration_hrs:.2f} hours")

Plotting Example with Numpy and Matplotlib

Note: To run this example, you will need to install the dependencies:

pip install matplotlib numpy PyQt6

For the full, runnable script, see examples/plot_calmness.py.

import numpy as np
import fitout as fo
from measureme.database import get_engine, get_session_maker
from measureme.models import HealthMetric

# 1. Fetch raw data from MeasureMe
# ... (Querying logic omitted for brevity) ...

# 2. Extract database rows into lists aligned to continuous dates
breathing_raw = extract_aligned_data(metrics, dates, 'breathing_rate')
hrv_raw = extract_aligned_data(metrics, dates, 'hrv_rmssd')
rhr_raw = extract_aligned_data(metrics, dates, 'resting_heart_rate')

# 3. Apply cleaning algorithms (Clean-On-Read feature via FitOut helpers)
breathing_data = fo.fill_missing_with_neighbours(breathing_raw)
hrv_data = fo.fill_missing_with_neighbours(hrv_raw)

breathing_data = fo.fix_invalid_data_points(breathing_data, 10, 20)
hrv_data = fo.fix_invalid_data_points(hrv_data, 20, 50)

# 4. Create the Derived Calmness Metric and plot!
breathing_arr = np.array(breathing_data).astype(float)
hrv_arr = np.array(hrv_data).astype(float)
rhr_arr = np.array(rhr_data).astype(float)

# Equation: 100 - (RHR/2 + breathing rate*2 - HRV)
calmness_index = 100 - (rhr_arr / 2. + breathing_arr * 2. - hrv_arr)

More Examples

For more examples, see the examples directory.

Contributing

If you'd like to contribute to MeasureMe, follow the guidelines outlined in the Contributing Guide.

License

See LICENSE.txt for more information.

Contact

For inquiries and discussion, use MeasureMe Discussions.

Issues

For issues related to this Python implementation, visit the Issues page.