pfun-cma-model

Links (Demos, Homepage)

• PFun Homepage
• Terminal Demo Video — performance benchmarks + 3D waveform animation

Overview

API Description

The pfun-cma-model API provides a comprehensive framework for analyzing and modeling the interplay between circadian rhythm, glucose metabolism, and hormonal dynamics. It enables researchers and practitioners to understand how physiological processes influence glucose levels over time.

In simple terms, what exactly does it do?!?

A few pithy one-liners:

• Phase-based dimensionality reduction: "Included is a well-validated (on ~30million rows of CGM data) phase portrait analysis technique that can compress weeks', months', or even many-years'-worth of glucose time-series data into a minimum-length phase vector (>= 1024b in memory)."
• Interpretable, Quantifiable: It provides a way to quickly translate between qualitative ("mood", e.g.) & biophysical neuroendocrine dynamics ("cortisol levels", e.g.).
• It provides a high-speed interface for understanding how the circadian rhythm maps to glucose values.

Background

• About the project: PFun CMA Model Documentation
• Preliminary research summary (includes citations): Chronometabolic Analysis (Markdown) · PDF

About this repository

Generated Cortisol-Melatonin-Adiponectin decomposition (from Glucose time series)

Project Goals

For detailed development information, check the TODO.md:

• TODO.md

CMA Model Description

Model Parameters

Example Fitted Parameters

Development notes

• Using uv for super fast dependency management, intuitive CLI, and ezpz publishing to pypi.

Usage notes

nix, devenv

# https://devenv.sh/guides/using-with-flakes/#entering-the-shell
nix develop --no-pure-eval

(dashlane) Inject secrets to create .env

# NOTE: only works if you have dcli (the dashlane CLI) installed locally
$ ./scripts/inject-secrets-env.sh

Convert docker-compose.yml to Helm Chart

# convert docker-compose.yml to a Helm Chart (for kubernetes)
\# kompose convert -c -o pfun-cma-model-chart
...

# build a binary helm chart package (ready for deployment)
\# helm package pfun-cma-model-chart --destination dist/pfun-cma-model-chart
...

# install the helm chart
\# helm install pfun-cma-model-chart -f dist/pfun-cma-model-chart-<VERSION>.tgz
...

(containerized) docker-compose environment

Complete rebuild & launch

docker compose up -d \
	--build \
	--renew-anon-volumes \
	--remove-orphans

# ...or with the convenience script:
./scripts/full-rebuild.sh

(Nix) devenv shell

# Enter the devenv shell environment (see flake.nix)
devenv shell
...

(local) uv Python Dev environment

Debugging the app locally (run as a local FastAPI server)

# Run using fastapi development server
$ uv run fastapi dev pfun_cma_model/app.py --port 8001

# Alternatively, use the convenience script
$ scripts/serve-dev.sh

Interact with the app via CLI

$ pfun-cma-model generate-scenario --query 'a healthy individual with a tendency to sleep in.'
{
	"qualitative_description": "This individual is a healthy young adult who is a natural 'night owl'. They have a delayed sleep phase, meaning they tend to go to bed late, around 2:00 AM, and wake up late in the morning, typically after 10:00 AM. Their meal schedule is shifted accordingly, with 'breakfast' often being eaten closer to noon. They are otherwise healthy, with a stable diet and regular activity levels, but their entire daily rhythm, including their natural cortisol cycle, is pushed back by several hours compared to someone with a more conventional sleep schedule.",
"parameters": {
    "toff": 2.5,
    "d": 0,
    "taup": 1,
    "taug": 1,
    "B": 0.05,
    "Cm": 0
	}
}

# fit the CMA model using partial least squares, plot the results
$ uv run pfun-cma-model run-fit-model --plot