loopy-basic 0.1.0

Type 1 Diabetes Data Analysis from DIY Loop system

Loopy Basic - Type 1 Diabetes Data Analysis

A Python proof of concept project for accessing and analyzing Type 1 diabetes data from a DIY Loop system stored in MongoDB Atlas. Focuses on CGM pattern analysis for diabetes management optimization.

Project Status

Stages 1-3 Complete ✅ - Database connection, CGM data access, and time-range queries implemented

Project Structure

src/loopy/
├── connection/    # Database connectivity
│   └── mongodb.py
├── data/          # Data access modules
│   └── cgm.py
└── utils/         # Utilities and debugging
    └── debug.py
docs/              # Analysis documentation
dev/               # Development and analysis scripts
├── exploratory/   # Exploratory analysis notebooks
├── reports/       # Analysis reports  
└── usage_example.py # Complete usage demonstration
tests/             # Test modules

Installation & Setup

1. Clone and Install

# Clone the repository
git clone <repository-url>
cd loopy-basic

# Install dependencies
uv sync

# Install package in editable mode for development
uv pip install -e .

2. Package Usage

Once installed, you can import and use the package from anywhere:

from loopy.data.cgm import CGMDataAccess
from loopy.connection.mongodb import MongoDBConnection

# Initialize and use
cgm = CGMDataAccess()
cgm.connect()
df = cgm.get_dataframe_for_period('last_week')

3. MongoDB Atlas Connection Setup

Create Environment File

Copy the example environment file:

cp .env.example .env

Configure MongoDB Credentials

Edit .env with your MongoDB Atlas credentials:

MONGODB_USERNAME=your_actual_username
MONGODB_PW=your_actual_password
MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.yourcluster.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0
MONGODB_DATABASE=myCGMitc

Important Notes:

• Keep the <username> and <password> placeholders in the URI exactly as shown - the code automatically replaces them
• Only change the cluster URL part (after the @ symbol) to match your MongoDB Atlas cluster
• Provide your actual username and password in the separate MONGODB_USERNAME and MONGODB_PW variables
• Ensure the database user has read access to the myCGMitc database

Test Connection

uv run python -m src.loopy.connection.mongodb

You should see output like:

✓ Connected to MongoDB database: myCGMitc
Available databases: ['myCGMitc', 'test', 'admin', 'local']
Collections in myCGMitc: ['entries', 'treatments', 'food', 'settings', 'devicestatus', 'auth_roles', 'auth_subjects', 'activity', 'profile']
✓ Disconnected from MongoDB

Database Schema

The myCGMitc database contains the following collections:

• entries - CGM/blood glucose readings (primary data for analysis)
• treatments - Insulin doses and medical treatments
• food - Food intake and carbohydrate data
• settings - Loop system configuration
• devicestatus - Device status and connectivity info
• profile - User profile and basal rate settings
• activity - Activity and exercise logs
• auth_roles, auth_subjects - Authentication data

entries Collection Schema (CGM Data)

Collection Stats:

• Total documents: 243,047 CGM readings
• Date range: March 2023 to July 2025 (~2 years of data)
• Device: Dexcom CGM ("share2")
• Data actively updated (real-time)

Document Structure:

{
  "_id": "ObjectId",
  "sgv": 163,                           // Blood glucose value (mg/dL)
  "date": 1678724324000.0,             // Unix timestamp (milliseconds)
  "dateString": "2023-03-13T16:18:44.000Z",  // ISO formatted date
  "trend": 4,                          // Glucose trend indicator (1-7)
  "direction": "Flat",                 // Trend direction text
  "device": "share2",                  // CGM device identifier
  "type": "sgv",                       // Sensor glucose value type
  "utcOffset": 0,                      // UTC offset
  "sysTime": "2023-03-13T16:18:44.000Z"  // System timestamp
}

Key Fields:

• sgv - Primary glucose reading in mg/dL
• date - Unix timestamp for sorting and time-based queries
• direction - Trend indicators: "Flat", "FortyFiveUp", "FortyFiveDown", "SingleUp", "SingleDown", "DoubleUp", "DoubleDown"
• trend - Numeric trend value (1-7 scale)

Database Indexes:

• Optimized indexes on date, sgv, dateString, type for efficient queries

Development Stages

✅ Stage 1: Database Connection

• MongoDB Atlas connection with environment variables
• Basic authentication and connection testing
• Database and collection discovery

✅ Stage 2: CGM Data Access

• Connect to entries collection for glucose readings
• Explore document structure and schema
• Implement basic data retrieval queries
• Verify data format and field analysis

✅ Stage 3: Time-Range Queries

• Implement date/time filtering for CGM data
• Add functions to query specific time periods (24h, week, month, custom ranges)
• Test with various time ranges and validate results
• Summary statistics and data validation

✅ Stage 4: Data Processing & DataFrame Integration

• Convert MongoDB documents to pandas DataFrames with PyArrow backend
• Implement efficient data cleaning and validation
• Handle timestamp conversions and timezone management
• Prepare data for time-series analysis

🔄 Stage 5: Pattern Analysis & Temporal Insights (Next)

• Time-of-day pattern analysis (hourly glucose trends)
• Day-of-week pattern identification
• Weekly and monthly trend analysis
• Statistical summaries for specific time periods
• Data preparation for marimo notebook exploration

📋 Upcoming Stages

• Stage 6: Treatment correlation analysis (future goal)

Key Files & Commands

Core Modules:

• src/loopy/connection/mongodb.py - Main MongoDB connection module
• src/loopy/data/cgm.py - CGM data access and time-range queries
• src/loopy/utils/debug.py - Connection debugging utilities
• docs/analysis_patterns.md - Analysis methodology documentation
• .env.example - Environment variable template
• CLAUDE.md - Development guidance for AI assistants

Testing Commands:

# Test database connection
uv run python -m src.loopy.connection.mongodb

# Test CGM data access and time-range queries  
uv run python -m src.loopy.data.cgm

# Debug connection issues
uv run python -m src.loopy.utils.debug

# Start marimo notebook for exploration
uv run marimo edit dev/exploratory/analysis.py

# Run usage example (3 months of CGM data)
uv run python dev/usage_example.py

Troubleshooting

If you encounter authentication errors:

1. Verify credentials in MongoDB Atlas dashboard
2. Ensure database user has appropriate permissions
3. Check for extra spaces in .env file
4. Test connection with MongoDB Compass first
5. Run uv run python -m src.loopy.utils.debug for detailed diagnostics

Development Standards

This project follows Python best practices for professional coding:

• Code Quality: Type hints, comprehensive docstrings, error handling
• Reproducibility: Pinned dependencies, environment configuration, deterministic workflows
• Documentation: Detailed docstrings, inline comments, complete setup instructions
• Testing: Input validation, data quality checks, comprehensive testing

Quick Start Example

from loopy.data.cgm import CGMDataAccess
from datetime import datetime, timedelta

# Initialize CGM data access
cgm = CGMDataAccess()
cgm.connect()

# Get last week's data as a cleaned DataFrame
df = cgm.get_dataframe_for_period('last_week')

# Basic analysis
analysis = cgm.analyze_dataframe(df)
print(f"Average glucose: {analysis['basic_stats']['avg_glucose']:.1f} mg/dL")
print(f"Time in range: {analysis['time_in_range']['normal_percent']:.1f}%")

cgm.disconnect()

Security Notes

• Never commit the .env file to version control
• Use read-only database connections when possible
• Store connection credentials securely