PKoffee - Coffee Productivity Analysis

A Conda package implemented in python for analyzing the relationship between coffee consumption and productivity through statistical modeling and visualization.

Project inspired by Le Café - Oldelaf for the S3 School 2026.

Features

• Data Analysis: Load and analyze coffee consumption vs productivity datasets
• Multiple Models: Fit various mathematical models (quadratic, Michaelis-Menten, logistic, peak functions)
• Visualization: Beautiful violin plots with model overlays using Seaborn
• Model Comparison: Automatic R² scoring and ranking of models
• Type-Safe: Full type hints for better IDE support and code quality

Installation

pixi install

Quick Start

from pathlib import Path
from pkoffee.data import load_csv
from pkoffee.productivity_analysis import fit_all_models
from pkoffee.visualization import plot_models

# Load your data
data = load_csv(Path("coffee_productivity.csv"))

# Fit models
fitted_models = fit_all_models(data)

# Create visualization
plot_models(data, fitted_models, output_path=Path("results.png"))

Command Line Interface

# Analyze
cd analysis && pixi shell
# fit models and save to toml
pkoffee analyze --data-file coffee_productivity.csv --output fitted_models.toml --show-rankings
# plot models predictions
pkoffee plot --data-file coffee_productivity.csv --models fitted_models.toml --output analysis.png --y-max 7

Project Structure

pkoffee-sol/
├── src/pkoffee/
│   ├── __init__.py               # Python package
│   ├── cli.py                    # Command line interface
│   ├── data.py                   # Data loading utilities
│   ├── fit_model.py              # Model definition and fitting
│   ├── fit_model_io.py           # Model writing/reading to file
│   ├── log.py                    # Logging utilities
│   ├── metrics.py                # Model evaluation metrics
│   ├── parametric_function.py    # Mathematical models as parametric functions
│   ├── productivity_analysis.py  # Coffee analysis
│   └── visualization.py          # Plotting functions
├── tests/
│   ├── test_data.py
│   ├── test_fit_model.py
│   ├── test_fit_model_io.py
│   ├── test_metrics.py
│   └── test_parametric_function.py
├── README.md
├── pixi.toml
├── pixi.lock
└── pyproject.toml

Models Implemented

1. Quadratic: f(x) = a₀ + a₁x + a₂x²
2. Michaelis-Menten (Saturating): f(x) = y₀ + Vₘₐₓ·x/(K + x)
3. Logistic: f(x) = y₀ + L/(1 + e^(-k(x - x₀)))
4. Peak: f(x) = a·x·e^(-x/b)
5. Peak2: f(x) = a·x²·e^(-x/b)

Development

# Activate the environment
pixi shell
# use development dependencies like jupyter notebooks/ipython
jupyterlab

Tests

# Run tests
pixi run test

Linting

# Linting
pixi run lint
pixi run format

License

MIT License