Saltar a contenido

doekit

Diseño de Experimentos (DoE) en Python con un enfoque híbrido — personas (laboratorio) y agentes LLM que lo consumen vía MCP — sobre un mismo motor determinista. doekit no solo construye diseños: los interpreta y los evalúa, con rigor.

Una capa semántica (interpret/Interpretation) convierte cifras en significado — qué significa, por qué, qué hacer, con qué salvedades — sin inventar nada: los hechos vienen de doekit; el juicio, del usuario. Misma verdad, dos superficies: summary() / reportes HTML para personas, to_dict() / for_llm() para agentes. Cubre screening, superficie de respuesta, diseño óptimo, mezcla/split-plot y DoE secuencial (aprender u optimizar), con el flujo de razonamiento brief → recommend → evaluate → [lab: ingest] → analyze → interpret → decide (stop/augment/refine/redesign) → next.

stateDiagram-v2
    direction LR
    [*] --> Design: User / Agent
    Design --> Recommend
    Recommend --> Learn: if learn
    Recommend --> Optimize: if optimize
    Learn --> Semantic
    Optimize --> Semantic

    state best <<choice>>
    Semantic --> best
    best --> [*]: if stop
    best --> Design: if continue

Depende de numpy, pandas, scipy y statsmodels. matplotlib es opcional (gráficas y reportes HTML); doekit[mcp] sirve las tools para agentes y doekit[bo] añade el surrogate GP.

pip install doekit            # núcleo
pip install "doekit[plot]"    # con gráficas (matplotlib)
pip install "doekit[report]"  # con reportes HTML

El embudo del DoE

El DoE clásico es un embudo: screening (¿qué factores importan?) → superficie de respuesta (¿dónde está el óptimo?), con el diseño óptimo como vía alternativa cuando las plantillas estándar no encajan.

import doekit as ed

# 1) Screening — Plackett-Burman para 6 factores en 8 corridas
pb = ed.plackett_burman(6)

# 2) Superficie de respuesta — Box-Behnken en unidades naturales
bb = ed.box_behnken({"temp": (20, 80), "ph": (3, 9), "conc": (0.1, 0.5)})

# 3) Diseño óptimo — subconjunto D-óptimo desde un candidate set
cand = ed.random_design([ed.ContinuousFactor("x1", -1, 1),
                         ed.ContinuousFactor("x2", -1, 1)], n=200, seed=0)
cand.model = ed.Model.parse("0 ~ x1 + x2 + x1:x2")
opt = ed.optimal_design(cand, n_runs=12, criterion="D", n_starts=5, seed=1)

Lo que distingue a doekit: interpretar y evaluar, no solo construir

La mayoría de las librerías de DoE en Python solo generan diseños. doekit añade los otros dos tercios del trabajo que hacen las herramientas comerciales (JMP, Design-Expert) — y lo hace una sola vez para ambos públicos:

  1. Interpretar — la capa semántica lee cualquier resultado (recomendación, evaluación, ajuste, propuesta, comparación) como qué significa / por qué / salvedades, misma verdad para una persona o un agente.
  2. Evaluar — un boletín de calidad reproducible: "¿qué tan lejos está mi diseño del óptimo teórico?"
  3. Construir — el catálogo completo de generadores.
  4. Decidir — tras learn u optimize, decide_next mapea señales a stop | augment | refine | redesign (continuar vuelve a Design).
  5. Optimizar — intent="optimize" ajusta un surrogate (OLS o GP) y puntúa candidatos con EI/PI/UCB/EHVI; el DoE clásico sigue en intent="learn".
ev = ed.evaluate(bb, effect_size=1.0, sigma=1.0)
#   D/A/G-eficiencia, distribución de la SPV (FDS), potencia por término, VIF, alias

print(ed.interpret(ev).for_llm())   # capa semántica: cifras -> significado (sin inventar)
ed.report(bb, response=y)           # carpeta HTML para personas (requiere doekit[report])
# Bucle agregado: ed.experiment(goal=..., factors=..., budget=...)
# Agentes: pip install "doekit[mcp]" → recommend / evaluate / propose_and_decide

Por dónde seguir

  • Teoría — una página por metodología, cada una con motivación → teoría (con matemática) → un ejemplo con doekit. Empieza por Factores y codificación.
  • Referencia de API — autogenerada desde los docstrings del código.
  • Guía — los notebooks recorren casos reales por dominio (química, ML, ML cuántico) con el patrón construir → evaluar → benchmarkear.
  • Agentes y MCP — el skill portable del diseñador de experimentos y el servidor MCP que expone doekit como tools para agentes (recommend / evaluate / propose_and_decide).
  • DoE secuencial — learn vs optimize en DoE secuencial.