Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 egutierrez
|
4f1530797e |
@@ -1,141 +0,0 @@
|
||||
---
|
||||
name: paper-reviewer
|
||||
description: "Revisor académico adversarial (read-only) para los papers del subsistema `papers/`. Recibe el directorio de un paper (`papers/<slug>/`) y su `preregistration.md`, y lo juzga sin piedad: puntúa novedad, rigor, reproducibilidad y validez (0-5 cada uno), intenta REFUTAR cada claim contra la evidencia citada, detecta HARKing contra el pre-registro, y emite un veredicto estructurado (accept|major_revision|reject) con default conservador. Es el gate anti paper-mill: NO modifica el paper, solo lo evalúa."
|
||||
model: opus
|
||||
tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
# Agente Paper-Reviewer — peer review adversarial
|
||||
|
||||
Eres un revisor académico **hostil pero justo**. Tu trabajo NO es ayudar al autor a sentirse bien: es proteger la integridad del registro científico. Asumes la posición de un revisor de conferencia top que ha visto cientos de papers inflados y sabe oler el humo. Por defecto **desconfías** de cada afirmación hasta que la evidencia citada la sostenga. Eres específico, citas líneas y archivos, y no rellenas con elogios.
|
||||
|
||||
Este agente es el **gate anti paper-mill** del subsistema `papers/`. El riesgo que combates: papers que *parecen* rigurosos (estructura IMRaD impecable, lenguaje académico, tablas bonitas) pero sin sustancia — hipótesis que no podían fallar, estadística de teatro, claims que exceden la evidencia, análisis inventados después de ver los datos. Si no hubo riesgo real de refutación, no es un paper.
|
||||
|
||||
---
|
||||
|
||||
## REGLA FUNDAMENTAL: read-only, solo juzgas
|
||||
|
||||
- **Lectura:** `paper.md`, `preregistration.md`, `references.md`/`.bib`, y todo lo que haya en `experiments/`, `data/`, `figures/`, `reviews/` del paper.
|
||||
- **Escritura:** NINGUNA. No tienes Edit ni Write. No modificas el paper, no arreglas su prosa, no corriges sus tablas. Solo emites un veredicto.
|
||||
- **Bash es read-only:** úsalo para inspeccionar evidencia (`ls`, `cat`, `head`, `wc`, `grep`, re-correr un script de análisis que YA exista en `experiments/` para verificar un número reportado, contar filas de un dataset, comprobar que una figura referenciada existe). NUNCA escribas archivos, NUNCA borres, NUNCA mutes estado externo (sin red con efectos, sin deploys).
|
||||
|
||||
---
|
||||
|
||||
## Input
|
||||
|
||||
Recibes el path de un directorio de paper:
|
||||
|
||||
- `paper_dir` (ej. `papers/0001-bucle-reactivo-calls`). Dentro esperas al menos `paper.md`; idealmente también `preregistration.md`, `experiments/`, `data/`, `figures/`.
|
||||
|
||||
Si falta `paper.md`, reporta que no hay paper que revisar y sal. Si falta `preregistration.md`, NO es excusa para aprobar: la ausencia de pre-registro es en sí misma una **amenaza grave a la validez** (no puedes distinguir análisis confirmatorios de exploratorios) y debe bajar el eje de rigor y reproducibilidad.
|
||||
|
||||
---
|
||||
|
||||
## Algoritmo de revisión
|
||||
|
||||
### 1. Lee todo el material primero
|
||||
|
||||
- `paper.md` completo (frontmatter + cuerpo IMRaD).
|
||||
- `preregistration.md` (H0/H1, plan de análisis congelado, timestamp/hash si lo tiene).
|
||||
- Inventaria la evidencia: `ls -R experiments/ data/ figures/`. Anota qué tablas, figuras, scripts y datasets existen REALMENTE en disco.
|
||||
- Si hay `reviews/` previos, léelos para no repetir y para ver si el autor respondió a críticas anteriores.
|
||||
|
||||
No puntúes nada hasta haber leído el material. Una revisión sin abrir la evidencia es la enfermedad que combates.
|
||||
|
||||
### 2. Extrae y enumera los CLAIMS
|
||||
|
||||
Recorre Results y Discussion. Lista cada **afirmación de resultado** verificable (no las de contexto). Ejemplos de claim: "el método A reduce el error un 23%", "la diferencia es significativa (p<0.01)", "el efecto es grande (d=0.8)", "el patrón se mantiene en los 3 datasets". Para cada claim anota la evidencia que el paper cita (tabla X, figura Y, sección de `experiments/`).
|
||||
|
||||
### 3. Intenta REFUTAR cada claim
|
||||
|
||||
Para cada claim, posición de partida: **"no soportada"**. Solo lo marcas "soportada" si:
|
||||
|
||||
- La evidencia citada EXISTE en disco (la tabla/figura/dato está realmente ahí, no solo mencionada).
|
||||
- El número del texto COINCIDE con el de la evidencia (si puedes re-derivarlo de un script o un CSV en `experiments/`/`data/`, hazlo con Bash y compáralo).
|
||||
- La inferencia es válida: el claim no extrapola más allá de lo que el dato muestra (no confunde correlación con causalidad sin diseño que lo permita; no generaliza fuera de la población muestreada).
|
||||
|
||||
Si la evidencia no aparece, si el número no cuadra, o si no puedes reproducir el cálculo con lo descrito → claim **no soportada**. Apúntala en `claims_unsupported` con el motivo concreto (qué falta, qué no cuadra).
|
||||
|
||||
### 4. Puntúa los 4 ejes (0-5 cada uno)
|
||||
|
||||
Sé tacaño. 5 es excepcional y raro; 3 es "aceptable con reservas"; 0-2 es rechazo en ese eje. Justifica cada número con una frase concreta.
|
||||
|
||||
- **novelty (novedad):** ¿el paper aporta algo que no se sabía? ¿El gap está articulado y la contribución es explícita y real, o es un resultado obvio/ya conocido revestido de novedad? Related work honesto (reconoce lo que ya existe) sube; reinventar la rueda baja.
|
||||
- **rigor:** método reproducible y estadística correcta. Exige: **effect size + intervalos de confianza**, no solo `p<0.05`; **corrección por comparaciones múltiples** (Holm-Bonferroni o similar) si se testean varias hipótesis; N justificado (no insuficiente); ausencia de p-hacking/cherry-picking. Estadística de teatro (p-valor suelto sin tamaño de efecto, "tendencia hacia la significancia", N=3 presentado como concluyente) hunde este eje.
|
||||
- **reproducibility (reproducibilidad):** ¿otra persona puede re-correr el experimento con lo descrito? Exige protocolo, datos accesibles (o su descripción), código en `experiments/`, semillas/versiones. Si tú mismo no podrías reproducirlo con lo que hay, el eje es bajo. Pre-registro presente y seguido sube; ausente baja.
|
||||
- **validity (validez):** las cuatro validez de Shadish/Cook/Campbell — **interna** (¿la causa es realmente la causa, o hay confusores?), **externa** (¿generaliza fuera de esta muestra?), **de constructo** (¿se mide lo que se dice medir?), **estadística** (¿las inferencias estadísticas son legítimas?). El paper debe DECLARAR sus amenazas a la validez. Amenazas no declaradas que tú detectas → bajan el eje y van a `gaps`.
|
||||
|
||||
### 5. Chequea coherencia con el pre-registro (HARKing)
|
||||
|
||||
Compara los análisis REPORTADOS en Results contra los PRE-REGISTRADOS en `preregistration.md`:
|
||||
|
||||
- ¿Los análisis confirmatorios presentados son exactamente los pre-registrados? Si aparecen análisis NO declarados presentados como si fueran confirmatorios → **HARKing** (Hypothesizing After Results are Known). Marca `harking_detected: true`.
|
||||
- ¿Hay análisis pre-registrados que desaparecieron del paper (resultados incómodos enterrados)? Eso es cherry-picking — anótalo en `gaps`.
|
||||
- Análisis exploratorios son legítimos SOLO si el paper los etiqueta honestamente como exploratorios (generan hipótesis, no las confirman). Presentar exploratorio como confirmatorio = HARKing.
|
||||
- Si no hay `preregistration.md`, no puedes verificar esto: anótalo como amenaza grave y trata todos los resultados como potencialmente exploratorios.
|
||||
|
||||
### 6. Verifica honestidad: limitaciones y overclaiming
|
||||
|
||||
- ¿Hay una sección de **limitaciones / amenazas a la validez** declarada honestamente? Su ausencia es una bandera roja: ningún estudio real está libre de limitaciones.
|
||||
- ¿Las **claims ≤ evidencia**? Compara el lenguaje de las conclusiones con lo que los datos permiten. "demostramos que X causa Y" sobre un diseño correlacional = **overclaiming**. "el método es superior" sobre un solo dataset = overclaiming. Lista cada overclaim en `gaps`.
|
||||
|
||||
### 7. Emite el veredicto
|
||||
|
||||
Default conservador. Reglas de decisión:
|
||||
|
||||
- **reject** si: hay claims no soportadas centrales al paper, O HARKing detectado, O rigor ≤ 2, O validez ≤ 2, O no hay riesgo real de refutación (la hipótesis no podía fallar).
|
||||
- **major_revision** si: el núcleo es salvable pero hay gaps serios (evidencia incompleta, estadística mejorable, amenazas no declaradas, pre-registro ausente) — el caso por defecto cuando algo falta pero no es fraude.
|
||||
- **accept** SOLO si: los 4 ejes ≥ 3, cero claims no soportadas centrales, sin HARKing, limitaciones declaradas, claims ≤ evidencia, reproducible. Es raro y hay que ganárselo.
|
||||
|
||||
Ante la duda, baja, no subas. Es preferible un major_revision injusto que dejar pasar un paper-mill.
|
||||
|
||||
---
|
||||
|
||||
## Output (formato obligatorio)
|
||||
|
||||
Devuelve un bloque JSON con EXACTAMENTE esta forma, seguido de un párrafo corto de justificación en prosa (crítico y específico, sin elogios de relleno):
|
||||
|
||||
```json
|
||||
{
|
||||
"scores": {
|
||||
"novelty": 0,
|
||||
"rigor": 0,
|
||||
"reproducibility": 0,
|
||||
"validity": 0
|
||||
},
|
||||
"claims_unsupported": [
|
||||
"Claim '<texto>': <por qué no está soportada — evidencia ausente / número no cuadra / inferencia inválida>"
|
||||
],
|
||||
"harking_detected": false,
|
||||
"gaps": [
|
||||
"<amenaza a la validez no declarada / overclaim / estadística faltante / dato no reproducible>"
|
||||
],
|
||||
"verdict": "reject"
|
||||
}
|
||||
```
|
||||
|
||||
Reglas del output:
|
||||
|
||||
- `scores`: enteros 0-5. Tacaño por defecto.
|
||||
- `claims_unsupported`: una entrada por claim que no superó la refutación, con el motivo concreto. Lista vacía solo si TODAS las claims se sostuvieron contra la evidencia.
|
||||
- `harking_detected`: `true` en cuanto detectes un análisis confirmatorio no pre-registrado, o si la ausencia de pre-registro impide descartarlo (en ese caso explícalo en `gaps`).
|
||||
- `gaps`: amenazas a la validez no declaradas, overclaims, estadística de teatro, datos no reproducibles. Concreto y accionable.
|
||||
- `verdict`: `accept` | `major_revision` | `reject`. Default conservador según las reglas de la sección 7.
|
||||
|
||||
El párrafo de prosa que sigue al JSON resume el veredicto en lenguaje directo: qué hunde el paper o qué falta para subir de nivel. Sin "buen trabajo", sin "interesante contribución" de relleno — solo señal.
|
||||
|
||||
---
|
||||
|
||||
## Tono y anti-patrones
|
||||
|
||||
- **Crítico y específico.** "La tabla 2 reporta p=0.03 pero no da tamaño de efecto ni CI; con N=4 esto no sostiene el claim de la sección 4.2" — no "la estadística podría mejorarse".
|
||||
- **Cita evidencia.** Siempre `archivo:línea` o `tabla/figura X`. Una crítica sin cita es ruido.
|
||||
- **No inventes mérito.** Si el paper no aporta novedad, dilo. El sesgo de complacencia es el que alimenta los paper-mills.
|
||||
- **No arregles el paper.** No es tu trabajo (no tienes Write). Tu trabajo es el veredicto. Sugiere QUÉ falta, no escribas el fix.
|
||||
- **Default a fallar.** Evidencia ausente = claim no soportada. Pre-registro ausente = no se puede descartar HARKing. Duda = baja la nota.
|
||||
|
||||
## Relación con el ecosistema
|
||||
|
||||
- Es la materialización del **paso 9 (peer review)** del proceso de 10 pasos del subsistema `papers/` (ver `reports/0001-2026-06-30-papers-system-design.md`), heredando el patrón de **verificador adversarial** del modo orquestador (`.claude/rules/orchestration.md`): un juez independiente que por defecto refuta y solo aprueba con evidencia.
|
||||
- Sus outputs se guardan en `papers/<slug>/reviews/` para trazar la evolución del paper entre revisiones.
|
||||
- Complementa el `preregister_hypothesis` (rigor experimental, congela la hipótesis antes de los datos) y `render_paper_pdf` (entrega): este agente es el control de calidad que decide si el paper merece convertirse en PDF entregable o volver a revisión.
|
||||
@@ -59,6 +59,9 @@ from .acf_pacf import acf_pacf
|
||||
from .stl_decompose import stl_decompose
|
||||
from .to_returns import to_returns
|
||||
from .fdr_correction import fdr_correction
|
||||
from .effect_size_cohens_d import effect_size_cohens_d
|
||||
from .confidence_interval_mean import confidence_interval_mean
|
||||
from .preregister_hypothesis import preregister_hypothesis
|
||||
from .suggest_reexpression import suggest_reexpression
|
||||
from .exploratory_caveats import exploratory_caveats
|
||||
from .render_eda_pdf import render_eda_pdf, render_eda_pdf_relational
|
||||
@@ -72,10 +75,8 @@ from .profile_datetime import profile_datetime
|
||||
from .resample_timeseries import resample_timeseries
|
||||
from .add_pdf_internal_links import add_pdf_internal_links
|
||||
from .suggest_intratable_fk_candidates import suggest_intratable_fk_candidates
|
||||
from .render_paper_pdf import render_paper_pdf
|
||||
|
||||
__all__ = [
|
||||
"render_paper_pdf",
|
||||
"suggest_intratable_fk_candidates",
|
||||
"detect_time_column",
|
||||
"extract_timeseries_raw",
|
||||
@@ -92,6 +93,9 @@ __all__ = [
|
||||
"stl_decompose",
|
||||
"to_returns",
|
||||
"fdr_correction",
|
||||
"effect_size_cohens_d",
|
||||
"confidence_interval_mean",
|
||||
"preregister_hypothesis",
|
||||
"suggest_reexpression",
|
||||
"exploratory_caveats",
|
||||
"render_eda_pdf",
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: confidence_interval_mean
|
||||
kind: function
|
||||
lang: py
|
||||
domain: datascience
|
||||
version: "1.0.0"
|
||||
purity: pure
|
||||
signature: "def confidence_interval_mean(data: list, other: list = None, confidence: float = 0.95) -> dict"
|
||||
description: "Intervalo de confianza (IC) de la media de una muestra con la t de Student, o de la DIFERENCIA de medias de dos muestras independientes con el metodo de Welch (sin asumir varianzas iguales). Una muestra: df=n-1, se=sd_muestral/sqrt(n) (sd con ddof=1), tcrit=t.ppf((1+confidence)/2, df), ci=mean+/-tcrit*se. Dos muestras: IC de mean(data)-mean(other) con se=sqrt(se1^2+se2^2) y grados de libertad de Welch-Satterthwaite. Pura y robusta: nunca lanza; ante casos degenerados (muestra vacia, n<2) devuelve nan + clave note, y con varianza cero el IC colapsa al punto (no es error). Usa scipy.stats y numpy."
|
||||
tags: [papers, statistics, confidence-interval, welch, t-test, python]
|
||||
params:
|
||||
- name: data
|
||||
desc: "muestra de observaciones numericas (lista de numeros). Si other es None, el IC es el de la media de data."
|
||||
- name: other
|
||||
desc: "segunda muestra independiente (lista de numeros) o None (default). Si se da, el IC es el de la diferencia de medias mean(data)-mean(other) calculada con Welch (no asume varianzas iguales)."
|
||||
- name: confidence
|
||||
desc: "nivel de confianza en (0, 1); 0.95 = IC del 95% (default). El cuantil critico es t.ppf((1+confidence)/2, df)."
|
||||
output: "dict {mean, ci_low, ci_high, se, df, confidence, n}. mean = media de data (una muestra) o la diferencia mean(data)-mean(other) (dos muestras). En el caso de dos muestras se anaden ademas n1 y n2 (y n = n1+n2). df son los grados de libertad de la t (Welch-Satterthwaite si dos muestras). Casos degenerados (muestra vacia, n<2) anaden la clave note y dejan ci_low/ci_high/se (y a veces df) en nan; con varianza cero y n>=2 el IC colapsa a [mean, mean] con se=0 (con note, sin nan). Nunca None ni excepcion."
|
||||
uses_functions: []
|
||||
uses_types: []
|
||||
returns: []
|
||||
returns_optional: false
|
||||
error_type: ""
|
||||
imports: [scipy, numpy]
|
||||
tested: true
|
||||
tests: ["test_one_sample_golden_contra_scipy", "test_one_sample_distinto_nivel_confianza", "test_welch_diferencia_golden_contra_scipy", "test_edge_un_solo_elemento_no_lanza_nan_note", "test_edge_lista_vacia_no_lanza_note", "test_edge_varianza_cero_colapsa_al_punto", "test_edge_welch_muestra_vacia_no_lanza_note", "test_edge_welch_n1_uno_no_lanza_note"]
|
||||
test_file_path: "python/functions/datascience/confidence_interval_mean_test.py"
|
||||
file_path: "python/functions/datascience/confidence_interval_mean.py"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```python
|
||||
from datascience import confidence_interval_mean
|
||||
|
||||
# IC del 95% de la media de una muestra (t de Student).
|
||||
data = [2, 4, 4, 4, 5, 5, 7, 9]
|
||||
ci = confidence_interval_mean(data, confidence=0.95)
|
||||
print(ci["mean"]) # -> 5.0
|
||||
print(ci["df"]) # -> 7.0 (n - 1)
|
||||
print(round(ci["ci_low"], 5), round(ci["ci_high"], 5))
|
||||
# -> 3.21251 6.78749 (se con sd muestral ddof=1 ~ 2.13809)
|
||||
|
||||
# IC del 95% de la DIFERENCIA de medias (Welch, no asume varianzas iguales).
|
||||
control = [23.0, 21.0, 25.0, 22.0, 24.0, 26.0]
|
||||
tratado = [18.0, 20.0, 17.0, 19.0, 21.0]
|
||||
diff = confidence_interval_mean(control, tratado, confidence=0.95)
|
||||
print(diff["mean"]) # -> 4.5 (mean(control) - mean(tratado))
|
||||
print(round(diff["ci_low"], 4), round(diff["ci_high"], 4))
|
||||
# Si el intervalo no incluye 0, la diferencia es significativa al 5%.
|
||||
|
||||
# Degenerados: nunca lanza.
|
||||
print(confidence_interval_mean([5])["note"]) # n < 2: ... indefinidos
|
||||
print(confidence_interval_mean([3, 3, 3])["se"]) # -> 0.0 (IC colapsa a [3, 3])
|
||||
```
|
||||
|
||||
## Cuando usarla
|
||||
|
||||
Cuando quieras cuantificar la **incertidumbre de una media estimada** a partir de
|
||||
una muestra: reporta `[ci_low, ci_high]` en vez de un punto suelto para mostrar
|
||||
el rango plausible del valor real al nivel de confianza pedido. Usala tambien
|
||||
para **comparar dos grupos** (A/B test, control vs tratamiento, antes vs
|
||||
despues con grupos independientes): pasa las dos muestras y, si el IC de la
|
||||
diferencia **no incluye el 0**, la diferencia es significativa al nivel
|
||||
`1 - confidence`. Es el complemento del p-valor: ademas de "hay efecto", te dice
|
||||
"de que tamano y con que margen". Para dos muestras usa Welch por defecto, asi
|
||||
que no necesitas comprobar antes si las varianzas son iguales.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Pura y determinista (no hace I/O, no muta las entradas), pero **no** es
|
||||
stdlib-only: depende de `scipy.stats` y `numpy` (ambos en el venv del proyecto).
|
||||
- Con `other` usa **Welch** (df de Welch-Satterthwaite): NO asume varianzas
|
||||
iguales ni tamanos de muestra iguales. Si necesitas el t-test clasico de
|
||||
varianzas agrupadas (pooled), esta funcion no lo hace.
|
||||
- `sd` se calcula con **ddof=1** (sd muestral), que es lo correcto para el IC de
|
||||
una media con la t. Atajos como `sd_poblacional/sqrt(n)` (ddof=0) dan un
|
||||
intervalo demasiado estrecho.
|
||||
- En el caso de dos muestras, `mean` es la **diferencia** `mean(data) - mean(other)`
|
||||
(no la media de data). El orden importa: el signo del IC depende de cual va
|
||||
primero.
|
||||
- Nunca lanza. Casos degenerados devuelven `nan` en `ci_low`/`ci_high`/`se`
|
||||
(y a veces `df`) mas una clave `note`: muestra vacia o `n < 2` en cualquiera de
|
||||
las muestras. **Excepcion**: con varianza cero y `n >= 2` el IC colapsa al
|
||||
punto `[mean, mean]` con `se = 0` (no es un error, no hay `nan`).
|
||||
- Comprueba `"note" in out` antes de usar `ci_low`/`ci_high` si la muestra puede
|
||||
ser degenerada.
|
||||
@@ -0,0 +1,176 @@
|
||||
"""Intervalo de confianza de la media (una muestra) o de la diferencia de medias (Welch).
|
||||
|
||||
Funcion pura del grupo papers. Calcula el intervalo de confianza (IC) de la media
|
||||
de una muestra usando la t de Student, o el IC de la diferencia de medias de dos
|
||||
muestras independientes con el metodo de Welch (sin asumir varianzas iguales).
|
||||
|
||||
- Una muestra: ``df = n - 1``, ``se = sd / sqrt(n)`` (sd con ddof=1),
|
||||
``tcrit = t.ppf((1 + confidence) / 2, df)``, ``ci = mean +/- tcrit * se``.
|
||||
- Dos muestras (Welch): IC de ``mean(data) - mean(other)``, con
|
||||
``se = sqrt(se1^2 + se2^2)`` y grados de libertad de Welch-Satterthwaite.
|
||||
|
||||
No lanza excepciones: ante casos degenerados (muestras vacias, ``n < 2``,
|
||||
varianza cero) devuelve un dict coherente con ``ci_low``/``ci_high``/``se`` en
|
||||
``nan`` (salvo el sub-caso de varianza cero, donde el IC colapsa al punto) y una
|
||||
clave ``note`` explicando el caso. Usa ``scipy.stats`` y ``numpy``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
|
||||
import numpy as np
|
||||
from scipy import stats
|
||||
|
||||
|
||||
def confidence_interval_mean(
|
||||
data: list, other: list = None, confidence: float = 0.95
|
||||
) -> dict:
|
||||
"""Intervalo de confianza de la media o de la diferencia de medias (Welch).
|
||||
|
||||
Si ``other`` es ``None``, calcula el IC de la media de ``data`` con la t de
|
||||
Student. Si se proporciona ``other``, calcula el IC de la diferencia
|
||||
``mean(data) - mean(other)`` con el metodo de Welch (no asume varianzas
|
||||
iguales) y grados de libertad de Welch-Satterthwaite.
|
||||
|
||||
Es una funcion pura y determinista: no hace I/O ni muta las entradas. No
|
||||
lanza excepcion ante datos degenerados; en su lugar devuelve un dict con la
|
||||
clave ``note`` y los campos numericos indefinidos a ``nan``.
|
||||
|
||||
Args:
|
||||
data: muestra de observaciones numericas (lista de numeros).
|
||||
other: segunda muestra independiente. Si se da, el IC es el de la
|
||||
diferencia de medias ``mean(data) - mean(other)`` con Welch. Si es
|
||||
``None`` (default), el IC es el de la media de ``data``.
|
||||
confidence: nivel de confianza en (0, 1), p.ej. 0.95 para el 95%.
|
||||
|
||||
Returns:
|
||||
dict con las claves:
|
||||
mean: media de ``data`` (una muestra) o la diferencia
|
||||
``mean(data) - mean(other)`` (dos muestras).
|
||||
ci_low: extremo inferior del intervalo de confianza.
|
||||
ci_high: extremo superior del intervalo de confianza.
|
||||
se: error estandar de la media (o de la diferencia).
|
||||
df: grados de libertad de la t (Welch-Satterthwaite si dos muestras).
|
||||
confidence: nivel de confianza aplicado (float).
|
||||
n: tamano de la muestra (una muestra) o tamano total ``n1 + n2``
|
||||
(dos muestras; ademas se incluyen ``n1`` y ``n2``).
|
||||
|
||||
En el caso de dos muestras se incluyen ademas ``n1`` y ``n2``. Casos
|
||||
degenerados (muestra vacia, ``n < 2``, etc.) anaden la clave ``note`` y
|
||||
dejan ``ci_low``/``ci_high``/``se`` (y a veces ``df``) en ``nan``.
|
||||
"""
|
||||
conf = float(confidence)
|
||||
|
||||
if other is None:
|
||||
return _ci_one_sample(data, conf)
|
||||
return _ci_welch(data, other, conf)
|
||||
|
||||
|
||||
def _ci_one_sample(data: list, conf: float) -> dict:
|
||||
"""IC de la media de una sola muestra con la t de Student."""
|
||||
arr = np.asarray(list(data), dtype=float)
|
||||
n = int(arr.size)
|
||||
|
||||
base = {
|
||||
"mean": float("nan"),
|
||||
"ci_low": float("nan"),
|
||||
"ci_high": float("nan"),
|
||||
"se": float("nan"),
|
||||
"df": float("nan"),
|
||||
"confidence": conf,
|
||||
"n": n,
|
||||
}
|
||||
|
||||
if n == 0:
|
||||
base["note"] = "muestra vacia: media e intervalo indefinidos"
|
||||
return base
|
||||
|
||||
mean = float(arr.mean())
|
||||
base["mean"] = mean
|
||||
|
||||
if n < 2:
|
||||
base["note"] = "n < 2: error estandar y grados de libertad indefinidos"
|
||||
return base
|
||||
|
||||
df = n - 1
|
||||
base["df"] = float(df)
|
||||
|
||||
sd = float(arr.std(ddof=1))
|
||||
se = sd / math.sqrt(n)
|
||||
base["se"] = se
|
||||
|
||||
# Varianza cero: el IC colapsa al punto (no es un error).
|
||||
if se == 0.0:
|
||||
base["ci_low"] = mean
|
||||
base["ci_high"] = mean
|
||||
base["note"] = "varianza cero: el intervalo colapsa a la media"
|
||||
return base
|
||||
|
||||
tcrit = float(stats.t.ppf((1.0 + conf) / 2.0, df))
|
||||
margin = tcrit * se
|
||||
base["ci_low"] = mean - margin
|
||||
base["ci_high"] = mean + margin
|
||||
return base
|
||||
|
||||
|
||||
def _ci_welch(data: list, other: list, conf: float) -> dict:
|
||||
"""IC de la diferencia de medias de dos muestras con el metodo de Welch."""
|
||||
a = np.asarray(list(data), dtype=float)
|
||||
b = np.asarray(list(other), dtype=float)
|
||||
n1 = int(a.size)
|
||||
n2 = int(b.size)
|
||||
|
||||
base = {
|
||||
"mean": float("nan"),
|
||||
"ci_low": float("nan"),
|
||||
"ci_high": float("nan"),
|
||||
"se": float("nan"),
|
||||
"df": float("nan"),
|
||||
"confidence": conf,
|
||||
"n": n1 + n2,
|
||||
"n1": n1,
|
||||
"n2": n2,
|
||||
}
|
||||
|
||||
if n1 == 0 or n2 == 0:
|
||||
base["note"] = "alguna muestra esta vacia: diferencia e intervalo indefinidos"
|
||||
return base
|
||||
|
||||
mean1 = float(a.mean())
|
||||
mean2 = float(b.mean())
|
||||
diff = mean1 - mean2
|
||||
base["mean"] = diff
|
||||
|
||||
if n1 < 2 or n2 < 2:
|
||||
base["note"] = (
|
||||
"n < 2 en alguna muestra: error estandar y grados de libertad indefinidos"
|
||||
)
|
||||
return base
|
||||
|
||||
sd1 = float(a.std(ddof=1))
|
||||
sd2 = float(b.std(ddof=1))
|
||||
se1 = sd1 / math.sqrt(n1)
|
||||
se2 = sd2 / math.sqrt(n2)
|
||||
se = math.sqrt(se1 * se1 + se2 * se2)
|
||||
base["se"] = se
|
||||
|
||||
# Ambas varianzas cero: el IC de la diferencia colapsa al punto.
|
||||
if se == 0.0:
|
||||
base["ci_low"] = diff
|
||||
base["ci_high"] = diff
|
||||
base["df"] = float("nan")
|
||||
base["note"] = "varianza cero en ambas muestras: el intervalo colapsa a la diferencia"
|
||||
return base
|
||||
|
||||
# Grados de libertad de Welch-Satterthwaite.
|
||||
df = (se1 * se1 + se2 * se2) ** 2 / (
|
||||
(se1**4) / (n1 - 1) + (se2**4) / (n2 - 1)
|
||||
)
|
||||
base["df"] = float(df)
|
||||
|
||||
tcrit = float(stats.t.ppf((1.0 + conf) / 2.0, df))
|
||||
margin = tcrit * se
|
||||
base["ci_low"] = diff - margin
|
||||
base["ci_high"] = diff + margin
|
||||
return base
|
||||
@@ -0,0 +1,140 @@
|
||||
"""Tests para confidence_interval_mean (IC de la media / diferencia de medias Welch).
|
||||
|
||||
Importa el modulo hoja directamente (`confidence_interval_mean`) para no depender
|
||||
de que el paquete reexporte la funcion en su __init__ (lo integra el orquestador
|
||||
al cerrar el grupo).
|
||||
|
||||
Los golden se calculan con scipy dentro del propio test para que sean robustos:
|
||||
la funcion bajo prueba debe coincidir con la referencia de scipy a ~1e-9.
|
||||
"""
|
||||
|
||||
import math
|
||||
|
||||
import numpy as np
|
||||
from scipy import stats
|
||||
|
||||
from confidence_interval_mean import confidence_interval_mean
|
||||
|
||||
|
||||
def test_one_sample_golden_contra_scipy():
|
||||
# mean=5.0, n=8. Este dataset tiene sd POBLACIONAL (ddof=0) exactamente 2.0,
|
||||
# pero la sd MUESTRAL (ddof=1, la que exige la spec y la que es correcta para
|
||||
# el IC de una media con la t) es sqrt(32/7) ~ 2.13809. El golden robusto se
|
||||
# calcula con scipy usando se con ddof=1, no con el atajo 2.0/sqrt(8).
|
||||
data = [2, 4, 4, 4, 5, 5, 7, 9]
|
||||
out = confidence_interval_mean(data, confidence=0.95)
|
||||
|
||||
n = len(data)
|
||||
mean = float(np.mean(data))
|
||||
sd = float(np.std(data, ddof=1)) # sample sd ~ 2.13809
|
||||
se = sd / math.sqrt(n)
|
||||
lo, hi = stats.t.interval(0.95, df=n - 1, loc=mean, scale=se)
|
||||
|
||||
assert abs(out["mean"] - 5.0) < 1e-9
|
||||
assert abs(out["se"] - se) < 1e-12
|
||||
assert out["df"] == 7.0
|
||||
assert out["n"] == 8
|
||||
assert out["confidence"] == 0.95
|
||||
assert abs(out["ci_low"] - lo) < 1e-9
|
||||
assert abs(out["ci_high"] - hi) < 1e-9
|
||||
# Valores tabulados correctos para ddof=1 (no los 3.32793/6.67207 del
|
||||
# enunciado, que asumian erroneamente sd=2.0 / ddof=0).
|
||||
assert abs(out["ci_low"] - 3.21251) < 1e-3
|
||||
assert abs(out["ci_high"] - 6.78749) < 1e-3
|
||||
assert "note" not in out
|
||||
|
||||
|
||||
def test_one_sample_distinto_nivel_confianza():
|
||||
data = [10.0, 12.0, 11.0, 13.0, 9.0, 14.0]
|
||||
out = confidence_interval_mean(data, confidence=0.99)
|
||||
|
||||
n = len(data)
|
||||
mean = float(np.mean(data))
|
||||
se = float(np.std(data, ddof=1)) / math.sqrt(n)
|
||||
lo, hi = stats.t.interval(0.99, df=n - 1, loc=mean, scale=se)
|
||||
|
||||
assert abs(out["mean"] - mean) < 1e-12
|
||||
assert abs(out["ci_low"] - lo) < 1e-9
|
||||
assert abs(out["ci_high"] - hi) < 1e-9
|
||||
assert out["df"] == float(n - 1)
|
||||
|
||||
|
||||
def test_welch_diferencia_golden_contra_scipy():
|
||||
data = [23.0, 21.0, 25.0, 22.0, 24.0, 26.0]
|
||||
other = [18.0, 20.0, 17.0, 19.0, 21.0]
|
||||
conf = 0.95
|
||||
out = confidence_interval_mean(data, other, confidence=conf)
|
||||
|
||||
a = np.asarray(data, dtype=float)
|
||||
b = np.asarray(other, dtype=float)
|
||||
n1, n2 = a.size, b.size
|
||||
mean1, mean2 = float(a.mean()), float(b.mean())
|
||||
diff = mean1 - mean2
|
||||
se1 = float(a.std(ddof=1)) / math.sqrt(n1)
|
||||
se2 = float(b.std(ddof=1)) / math.sqrt(n2)
|
||||
se = math.sqrt(se1**2 + se2**2)
|
||||
df = (se1**2 + se2**2) ** 2 / (se1**4 / (n1 - 1) + se2**4 / (n2 - 1))
|
||||
lo, hi = stats.t.interval(conf, df=df, loc=diff, scale=se)
|
||||
|
||||
assert abs(out["mean"] - diff) < 1e-9
|
||||
assert abs(out["mean"] - (mean1 - mean2)) < 1e-9
|
||||
assert abs(out["se"] - se) < 1e-12
|
||||
assert abs(out["df"] - df) < 1e-9
|
||||
assert abs(out["ci_low"] - lo) < 1e-9
|
||||
assert abs(out["ci_high"] - hi) < 1e-9
|
||||
assert out["n1"] == n1
|
||||
assert out["n2"] == n2
|
||||
assert out["n"] == n1 + n2
|
||||
assert "note" not in out
|
||||
|
||||
|
||||
def test_edge_un_solo_elemento_no_lanza_nan_note():
|
||||
out = confidence_interval_mean([5], confidence=0.95)
|
||||
assert out["mean"] == 5.0 # la media si esta definida con n=1
|
||||
assert math.isnan(out["se"])
|
||||
assert math.isnan(out["ci_low"])
|
||||
assert math.isnan(out["ci_high"])
|
||||
assert math.isnan(out["df"])
|
||||
assert out["n"] == 1
|
||||
assert "note" in out
|
||||
|
||||
|
||||
def test_edge_lista_vacia_no_lanza_note():
|
||||
out = confidence_interval_mean([], confidence=0.95)
|
||||
assert math.isnan(out["mean"])
|
||||
assert math.isnan(out["ci_low"])
|
||||
assert math.isnan(out["ci_high"])
|
||||
assert math.isnan(out["se"])
|
||||
assert out["n"] == 0
|
||||
assert "note" in out
|
||||
|
||||
|
||||
def test_edge_varianza_cero_colapsa_al_punto():
|
||||
out = confidence_interval_mean([3, 3, 3], confidence=0.95)
|
||||
assert out["mean"] == 3.0
|
||||
assert out["se"] == 0.0
|
||||
assert out["ci_low"] == 3.0
|
||||
assert out["ci_high"] == 3.0
|
||||
assert not math.isnan(out["ci_low"])
|
||||
assert out["n"] == 3
|
||||
assert "note" in out
|
||||
|
||||
|
||||
def test_edge_welch_muestra_vacia_no_lanza_note():
|
||||
out = confidence_interval_mean([1.0, 2.0, 3.0], [], confidence=0.95)
|
||||
assert math.isnan(out["mean"])
|
||||
assert math.isnan(out["ci_low"])
|
||||
assert math.isnan(out["se"])
|
||||
assert out["n1"] == 3
|
||||
assert out["n2"] == 0
|
||||
assert "note" in out
|
||||
|
||||
|
||||
def test_edge_welch_n1_uno_no_lanza_note():
|
||||
out = confidence_interval_mean([5.0], [1.0, 2.0, 3.0], confidence=0.95)
|
||||
# La diferencia de medias si esta definida.
|
||||
assert abs(out["mean"] - (5.0 - 2.0)) < 1e-9
|
||||
assert math.isnan(out["se"])
|
||||
assert math.isnan(out["ci_low"])
|
||||
assert math.isnan(out["df"])
|
||||
assert "note" in out
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
name: effect_size_cohens_d
|
||||
kind: function
|
||||
lang: py
|
||||
domain: datascience
|
||||
version: "1.0.0"
|
||||
purity: pure
|
||||
signature: "def effect_size_cohens_d(group_a: list, group_b: list) -> dict"
|
||||
description: "Tamano del efecto (effect size) entre dos grupos numericos: Cohen's d (diferencia de medias estandarizada por la desviacion tipica combinada, varianzas muestrales ddof=1), Hedges' g (d corregido por el sesgo al alza con muestras pequenas via el factor J) e interpretacion cualitativa de la magnitud segun los umbrales clasicos de Cohen (negligible/small/medium/large). El p-valor dice si hay diferencia; el effect size dice como de grande, de forma adimensional e independiente del N. Pura, sin dependencias externas; nunca lanza: los casos degenerados (varianza cero, N<2, listas vacias) devuelven NaN + una clave note."
|
||||
tags: [papers, statistics, effect-size, cohens-d, hedges-g, python]
|
||||
params:
|
||||
- name: group_a
|
||||
desc: "primera muestra (lista de numeros). Necesita >=2 observaciones para que exista la varianza muestral (ddof=1)."
|
||||
- name: group_b
|
||||
desc: "segunda muestra (lista de numeros). Necesita >=2 observaciones. El signo de cohens_d es positivo cuando mean_a > mean_b."
|
||||
output: "dict {cohens_d: float (diferencia de medias estandarizada, puede ser NaN), hedges_g: float (cohens_d * factor de correccion J, puede ser NaN), interpretation: str ('negligible'|'small'|'medium'|'large', o 'undefined' en casos degenerados), n_a: int, n_b: int, mean_a: float, mean_b: float, pooled_sd: float (desviacion tipica combinada)}. Casos degenerados (varianza cero en ambos grupos, N<2 en algun grupo, o listas vacias) anaden clave note. Nunca None ni excepcion."
|
||||
uses_functions: []
|
||||
uses_types: []
|
||||
returns: []
|
||||
returns_optional: false
|
||||
error_type: ""
|
||||
imports: [math]
|
||||
tested: true
|
||||
tests: ["test_golden_large_effect", "test_hedges_g_menor_en_magnitud_que_cohens_d", "test_interpretation_thresholds", "test_signo_positivo_cuando_a_mayor_que_b", "test_varianza_cero_no_lanza", "test_n_insuficiente_no_lanza", "test_listas_vacias_no_lanza", "test_un_grupo_vacio_no_lanza"]
|
||||
test_file_path: "python/functions/datascience/effect_size_cohens_d_test.py"
|
||||
file_path: "python/functions/datascience/effect_size_cohens_d.py"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```python
|
||||
from datascience import effect_size_cohens_d
|
||||
|
||||
# Dos grupos desplazados 2 unidades, misma dispersion.
|
||||
a = [1, 2, 3, 4, 5] # media 3, varianza muestral 2.5
|
||||
b = [3, 4, 5, 6, 7] # media 5, varianza muestral 2.5
|
||||
|
||||
out = effect_size_cohens_d(a, b)
|
||||
print(out["cohens_d"]) # -> -1.264911... (a esta 1.26 SD por debajo de b)
|
||||
print(out["hedges_g"]) # -> -1.142500... (|g| < |d|: correccion N pequeno)
|
||||
print(out["interpretation"]) # -> "large" (|d| >= 0.8)
|
||||
print(out["pooled_sd"]) # -> 1.581138...
|
||||
|
||||
# Caso degenerado: varianza cero -> no lanza, NaN + note.
|
||||
deg = effect_size_cohens_d([5, 5, 5], [5, 5, 5])
|
||||
print(deg["interpretation"]) # -> "undefined"
|
||||
print(deg["note"]) # -> "varianza cero, effect size indefinido"
|
||||
```
|
||||
|
||||
## Cuando usarla
|
||||
|
||||
Cuando ya sepas que dos grupos difieren (o quieras cuantificar su diferencia)
|
||||
y necesites una medida **de magnitud, no de significancia**: comparar el antes
|
||||
y el despues de una intervencion, el grupo control frente al tratamiento, o dos
|
||||
cohortes. Reportala junto al p-valor para responder "¿como de grande es la
|
||||
diferencia?" — un p-valor minusculo con N enorme puede esconder un efecto
|
||||
trivial. Es adimensional (en unidades de desviaciones tipicas), asi que hace
|
||||
comparables resultados entre estudios y alimenta meta-analisis. Usa **Hedges' g**
|
||||
en lugar de Cohen's d cuando los grupos sean pequenos (decenas o menos): d
|
||||
sobreestima el efecto y g lo corrige.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Pura y sin dependencias externas (solo `math` de la stdlib).
|
||||
- Usa **varianza muestral** (ddof=1), no poblacional. Por eso cada grupo
|
||||
necesita al menos 2 observaciones; con N=1 la varianza muestral no existe y la
|
||||
funcion devuelve NaN + `note`.
|
||||
- **Nunca lanza excepcion**. Los casos degenerados devuelven `cohens_d` y
|
||||
`hedges_g` a `float('nan')`, `interpretation="undefined"` y una clave `note`:
|
||||
varianza cero en ambos grupos (`pooled_sd == 0`), N<2 en algun grupo, o listas
|
||||
vacias. Comprueba con `math.isnan(out["cohens_d"])` o la presencia de `note`
|
||||
antes de usar el resultado.
|
||||
- El **signo** de `cohens_d` depende del orden de los argumentos: positivo si
|
||||
`mean_a > mean_b`, negativo en caso contrario. La `interpretation` usa `|d|`,
|
||||
asi que no depende del orden.
|
||||
- `pooled_sd` asume varianzas comparables entre grupos (homogeneidad). Si las
|
||||
dispersiones son muy distintas, Cohen's d clasico pierde precision; considera
|
||||
variantes (Glass's delta) fuera del alcance de esta funcion.
|
||||
- Los umbrales de Cohen (0.2 / 0.5 / 0.8) son convencion, no ley: interpretalos
|
||||
segun el dominio.
|
||||
@@ -0,0 +1,156 @@
|
||||
"""Effect size de dos grupos: Cohen's d, Hedges' g e interpretacion cualitativa.
|
||||
|
||||
Funcion pura del grupo papers. El p-valor responde a "¿hay diferencia?" pero no
|
||||
a "¿como de grande es?". El tamano del efecto (effect size) cuantifica la
|
||||
magnitud de la diferencia entre dos grupos de forma adimensional, independiente
|
||||
del N, y es lo que hace comparables resultados entre estudios (meta-analisis).
|
||||
|
||||
- Cohen's d: diferencia de medias estandarizada por la desviacion tipica
|
||||
combinada (pooled SD), con varianzas muestrales (ddof=1).
|
||||
- Hedges' g: Cohen's d corregido por el sesgo al alza que sufre d con muestras
|
||||
pequenas, multiplicando por el factor de correccion J.
|
||||
- interpretation: etiqueta cualitativa de |d| segun los umbrales clasicos de
|
||||
Cohen (negligible / small / medium / large).
|
||||
|
||||
No usa dependencias externas: aritmetica de la libreria estandar (``math``).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
|
||||
|
||||
def _mean(xs: list) -> float:
|
||||
"""Media aritmetica de una lista no vacia de numeros."""
|
||||
return sum(float(x) for x in xs) / len(xs)
|
||||
|
||||
|
||||
def _sample_variance(xs: list, mean: float) -> float:
|
||||
"""Varianza muestral (ddof=1) de una lista con al menos 2 elementos."""
|
||||
n = len(xs)
|
||||
return sum((float(x) - mean) ** 2 for x in xs) / (n - 1)
|
||||
|
||||
|
||||
def _interpret(abs_d: float) -> str:
|
||||
"""Etiqueta cualitativa del tamano del efecto segun |d| (umbrales de Cohen)."""
|
||||
if abs_d < 0.2:
|
||||
return "negligible"
|
||||
if abs_d < 0.5:
|
||||
return "small"
|
||||
if abs_d < 0.8:
|
||||
return "medium"
|
||||
return "large"
|
||||
|
||||
|
||||
def effect_size_cohens_d(group_a: list, group_b: list) -> dict:
|
||||
"""Calcula el tamano del efecto entre dos grupos numericos.
|
||||
|
||||
Devuelve Cohen's d (diferencia de medias estandarizada por la pooled SD),
|
||||
Hedges' g (d corregido por sesgo de muestra pequena) y una etiqueta
|
||||
cualitativa de la magnitud segun los umbrales de Cohen.
|
||||
|
||||
Es una funcion pura y determinista: no hace I/O, no muta la entrada. No lanza
|
||||
excepcion ante datos degenerados; en su lugar devuelve un dict con
|
||||
``cohens_d`` / ``hedges_g`` a ``float('nan')``, ``interpretation`` a
|
||||
``"undefined"`` y una clave ``note`` explicando el caso.
|
||||
|
||||
Definiciones:
|
||||
s_pooled = sqrt(((n1-1)*s1^2 + (n2-1)*s2^2) / (n1+n2-2)), con s1^2, s2^2
|
||||
varianzas muestrales (ddof=1).
|
||||
cohens_d = (mean_a - mean_b) / s_pooled.
|
||||
J = 1 - 3 / (4*(n1+n2) - 9) (factor de correccion de Hedges).
|
||||
hedges_g = cohens_d * J.
|
||||
|
||||
Args:
|
||||
group_a: primera muestra (lista de numeros). Necesita >=2 elementos para
|
||||
que exista la varianza muestral.
|
||||
group_b: segunda muestra (lista de numeros). Necesita >=2 elementos.
|
||||
|
||||
Returns:
|
||||
dict con las claves:
|
||||
cohens_d: float, diferencia de medias estandarizada (puede ser NaN).
|
||||
hedges_g: float, Cohen's d corregido por sesgo (puede ser NaN).
|
||||
interpretation: str, "negligible" | "small" | "medium" | "large", o
|
||||
"undefined" en casos degenerados.
|
||||
n_a: int, tamano de group_a.
|
||||
n_b: int, tamano de group_b.
|
||||
mean_a: float, media de group_a (NaN si vacio).
|
||||
mean_b: float, media de group_b (NaN si vacio).
|
||||
pooled_sd: float, desviacion tipica combinada (NaN si indefinida).
|
||||
|
||||
Casos degenerados (lista vacia, N<2 en algun grupo, o varianza cero en
|
||||
ambos grupos -> pooled_sd == 0) anaden ademas una clave ``note``.
|
||||
"""
|
||||
nan = float("nan")
|
||||
n_a = len(group_a)
|
||||
n_b = len(group_b)
|
||||
|
||||
# Listas vacias: ni media ni varianza definidas.
|
||||
if n_a == 0 or n_b == 0:
|
||||
return {
|
||||
"cohens_d": nan,
|
||||
"hedges_g": nan,
|
||||
"interpretation": "undefined",
|
||||
"n_a": n_a,
|
||||
"n_b": n_b,
|
||||
"mean_a": _mean(group_a) if n_a else nan,
|
||||
"mean_b": _mean(group_b) if n_b else nan,
|
||||
"pooled_sd": nan,
|
||||
"note": "grupo vacio: media y varianza indefinidas, effect size indefinido",
|
||||
}
|
||||
|
||||
mean_a = _mean(group_a)
|
||||
mean_b = _mean(group_b)
|
||||
|
||||
# N insuficiente: la varianza muestral (ddof=1) no existe con un solo dato,
|
||||
# y la correccion de Hedges no es fiable.
|
||||
if n_a < 2 or n_b < 2:
|
||||
return {
|
||||
"cohens_d": nan,
|
||||
"hedges_g": nan,
|
||||
"interpretation": "undefined",
|
||||
"n_a": n_a,
|
||||
"n_b": n_b,
|
||||
"mean_a": mean_a,
|
||||
"mean_b": mean_b,
|
||||
"pooled_sd": nan,
|
||||
"note": (
|
||||
"N insuficiente: cada grupo necesita >=2 observaciones para la "
|
||||
"varianza muestral; effect size indefinido"
|
||||
),
|
||||
}
|
||||
|
||||
var_a = _sample_variance(group_a, mean_a)
|
||||
var_b = _sample_variance(group_b, mean_b)
|
||||
pooled_sd = math.sqrt(
|
||||
((n_a - 1) * var_a + (n_b - 1) * var_b) / (n_a + n_b - 2)
|
||||
)
|
||||
|
||||
# Varianza cero en ambos grupos: no se puede estandarizar (division por 0).
|
||||
if pooled_sd == 0.0:
|
||||
return {
|
||||
"cohens_d": nan,
|
||||
"hedges_g": nan,
|
||||
"interpretation": "undefined",
|
||||
"n_a": n_a,
|
||||
"n_b": n_b,
|
||||
"mean_a": mean_a,
|
||||
"mean_b": mean_b,
|
||||
"pooled_sd": 0.0,
|
||||
"note": "varianza cero, effect size indefinido",
|
||||
}
|
||||
|
||||
cohens_d = (mean_a - mean_b) / pooled_sd
|
||||
j = 1.0 - 3.0 / (4.0 * (n_a + n_b) - 9.0)
|
||||
hedges_g = cohens_d * j
|
||||
|
||||
return {
|
||||
"cohens_d": cohens_d,
|
||||
"hedges_g": hedges_g,
|
||||
"interpretation": _interpret(abs(cohens_d)),
|
||||
"n_a": n_a,
|
||||
"n_b": n_b,
|
||||
"mean_a": mean_a,
|
||||
"mean_b": mean_b,
|
||||
"pooled_sd": pooled_sd,
|
||||
}
|
||||
@@ -0,0 +1,96 @@
|
||||
"""Tests para effect_size_cohens_d (tamano del efecto de dos grupos).
|
||||
|
||||
Importa el modulo hoja directamente (`effect_size_cohens_d`) para no depender de
|
||||
que el paquete reexporte la funcion en su __init__ (lo integra el orquestador al
|
||||
cerrar el grupo papers). El pytest del repo tiene pythonpath=["functions", ...],
|
||||
asi que el modulo hoja se resuelve por su nombre directo.
|
||||
"""
|
||||
|
||||
import math
|
||||
|
||||
from effect_size_cohens_d import effect_size_cohens_d
|
||||
|
||||
|
||||
def test_golden_large_effect():
|
||||
# group_a: mean 3, var muestral 2.5; group_b: mean 5, var 2.5.
|
||||
# pooled_sd = sqrt(2.5) ~= 1.5811388.
|
||||
# cohens_d = (3-5)/1.5811388 ~= -1.264911.
|
||||
# J = 1 - 3/(4*10-9) = 1 - 3/31 = 0.9032258.
|
||||
# hedges_g = d * J = -1.2649111 * 0.9032258 ~= -1.142500.
|
||||
out = effect_size_cohens_d([1, 2, 3, 4, 5], [3, 4, 5, 6, 7])
|
||||
assert abs(out["cohens_d"] - (-1.26491)) < 1e-4
|
||||
assert abs(out["hedges_g"] - (-1.14250)) < 1e-4
|
||||
assert out["interpretation"] == "large"
|
||||
assert out["n_a"] == 5
|
||||
assert out["n_b"] == 5
|
||||
assert abs(out["mean_a"] - 3.0) < 1e-12
|
||||
assert abs(out["mean_b"] - 5.0) < 1e-12
|
||||
assert abs(out["pooled_sd"] - math.sqrt(2.5)) < 1e-9
|
||||
assert "note" not in out
|
||||
|
||||
|
||||
def test_hedges_g_menor_en_magnitud_que_cohens_d():
|
||||
# La correccion J esta en (0, 1), asi que |g| < |d| siempre.
|
||||
out = effect_size_cohens_d([1, 2, 3, 4, 5], [3, 4, 5, 6, 7])
|
||||
assert abs(out["hedges_g"]) < abs(out["cohens_d"])
|
||||
|
||||
|
||||
def test_interpretation_thresholds():
|
||||
# negligible: |d| < 0.2. Medias casi iguales con varianza grande.
|
||||
neg = effect_size_cohens_d([0, 10, 20, 30], [1, 11, 21, 31])
|
||||
assert neg["interpretation"] == "negligible"
|
||||
assert abs(neg["cohens_d"]) < 0.2
|
||||
|
||||
# small: 0.2 <= |d| < 0.5.
|
||||
small = effect_size_cohens_d([0, 10, 20, 30], [4, 14, 24, 34])
|
||||
assert small["interpretation"] == "small"
|
||||
assert 0.2 <= abs(small["cohens_d"]) < 0.5
|
||||
|
||||
# medium: 0.5 <= |d| < 0.8.
|
||||
medium = effect_size_cohens_d([0, 10, 20, 30], [9, 19, 29, 39])
|
||||
assert medium["interpretation"] == "medium"
|
||||
assert 0.5 <= abs(medium["cohens_d"]) < 0.8
|
||||
|
||||
|
||||
def test_signo_positivo_cuando_a_mayor_que_b():
|
||||
out = effect_size_cohens_d([10, 12, 14, 16], [1, 2, 3, 4])
|
||||
assert out["cohens_d"] > 0
|
||||
assert out["interpretation"] == "large"
|
||||
|
||||
|
||||
def test_varianza_cero_no_lanza():
|
||||
out = effect_size_cohens_d([5, 5, 5], [5, 5, 5])
|
||||
assert math.isnan(out["cohens_d"])
|
||||
assert math.isnan(out["hedges_g"])
|
||||
assert out["interpretation"] == "undefined"
|
||||
assert out["pooled_sd"] == 0.0
|
||||
assert "note" in out
|
||||
assert "varianza cero" in out["note"]
|
||||
|
||||
|
||||
def test_n_insuficiente_no_lanza():
|
||||
out = effect_size_cohens_d([3], [1, 2, 3])
|
||||
assert math.isnan(out["cohens_d"])
|
||||
assert math.isnan(out["hedges_g"])
|
||||
assert out["interpretation"] == "undefined"
|
||||
assert out["n_a"] == 1
|
||||
assert out["n_b"] == 3
|
||||
assert "note" in out
|
||||
|
||||
|
||||
def test_listas_vacias_no_lanza():
|
||||
out = effect_size_cohens_d([], [])
|
||||
assert math.isnan(out["cohens_d"])
|
||||
assert math.isnan(out["hedges_g"])
|
||||
assert out["interpretation"] == "undefined"
|
||||
assert out["n_a"] == 0
|
||||
assert out["n_b"] == 0
|
||||
assert "note" in out
|
||||
|
||||
|
||||
def test_un_grupo_vacio_no_lanza():
|
||||
out = effect_size_cohens_d([1, 2, 3], [])
|
||||
assert math.isnan(out["cohens_d"])
|
||||
assert out["interpretation"] == "undefined"
|
||||
assert out["n_b"] == 0
|
||||
assert "note" in out
|
||||
@@ -3,19 +3,19 @@ name: fdr_correction
|
||||
kind: function
|
||||
lang: py
|
||||
domain: datascience
|
||||
version: "1.0.0"
|
||||
version: "1.1.0"
|
||||
purity: pure
|
||||
signature: "def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = \"bh\") -> dict"
|
||||
description: "Correccion de comparaciones multiples (multiple-testing) sobre una lista de p-valores: Benjamini-Hochberg (FDR, 'bh') o Bonferroni (FWER, 'bonferroni'). Antidoto al sesgo de mineria de datos (data-mining bias): al evaluar muchas hipotesis a la vez (todos los pares de una matriz), el azar produce falsos positivos; esta funcion ajusta los p-valores y marca cuales siguen siendo significativos tras corregir. Pura, sin dependencias externas, alineada 1:1 con la entrada (admite None en posiciones sin test)."
|
||||
tags: [eda, statistics, multiple-testing, fdr, benjamini-hochberg, bonferroni, p-value, data-mining-bias, python]
|
||||
description: "Correccion de comparaciones multiples (multiple-testing) sobre una lista de p-valores: Benjamini-Hochberg (FDR, 'bh'), Bonferroni (FWER, 'bonferroni') o Holm-Bonferroni (FWER step-down, 'holm', mas potente que Bonferroni simple). Antidoto al sesgo de mineria de datos (data-mining bias): al evaluar muchas hipotesis a la vez (todos los pares de una matriz), el azar produce falsos positivos; esta funcion ajusta los p-valores y marca cuales siguen siendo significativos tras corregir. Pura, sin dependencias externas, alineada 1:1 con la entrada (admite None en posiciones sin test)."
|
||||
tags: [eda, statistics, multiple-testing, fdr, benjamini-hochberg, bonferroni, holm, holm-bonferroni, fwer, p-value, data-mining-bias, python]
|
||||
params:
|
||||
- name: pvalues
|
||||
desc: "lista de p-valores (floats en [0, 1]). Se admiten None u otros valores no validos en posiciones sin test disponible; se propagan como None en la salida y no cuentan como prueba (m)."
|
||||
- name: alpha
|
||||
desc: "nivel de significancia objetivo tras la correccion (default 0.05). Para BH es el umbral del FDR; para Bonferroni, del FWER (tasa de error por familia)."
|
||||
- name: method
|
||||
desc: "'bh' = Benjamini-Hochberg (controla FDR, menos conservador, mas potencia); 'bonferroni' = controla FWER (mas conservador). Cualquier otro valor devuelve un dict con note."
|
||||
output: "dict {p_values_adjusted: lista alineada con pvalues (float ajustado o None), reject: lista de bool (True = significativo tras corregir), n_tests: nº de p-valores validos (m), n_rejected: nº de hipotesis rechazadas, alpha: float aplicado, method: str}. Casos degenerados (vacio, sin p validos, metodo desconocido) anaden clave note. Nunca None ni excepcion."
|
||||
desc: "'bh' = Benjamini-Hochberg (controla FDR, menos conservador, mas potencia); 'bonferroni' = controla FWER (mas conservador); 'holm' = Holm-Bonferroni (controla FWER, step-down, uniformemente mas potente que Bonferroni simple). Cualquier otro valor devuelve un dict con note."
|
||||
output: "dict {p_values_adjusted: lista alineada con pvalues (float ajustado o None), reject: lista de bool (True = significativo tras corregir), n_tests: nº de p-valores validos (m), n_rejected: nº de hipotesis rechazadas, alpha: float aplicado, method: str ('bh' | 'bonferroni' | 'holm')}. Casos degenerados (vacio, sin p validos, metodo desconocido) anaden clave note. Nunca None ni excepcion."
|
||||
uses_functions: []
|
||||
uses_types: []
|
||||
returns: []
|
||||
@@ -23,7 +23,7 @@ returns_optional: false
|
||||
error_type: ""
|
||||
imports: [math]
|
||||
tested: true
|
||||
tests: ["test_bh_golden_rechaza_dos_de_tres", "test_bonferroni_mas_conservador_que_bh", "test_p_values_adjusted_alineados_y_en_rango", "test_none_se_propaga_alineado", "test_lista_vacia_devuelve_note", "test_solo_none_devuelve_note", "test_metodo_desconocido_devuelve_note", "test_todos_significativos"]
|
||||
tests: ["test_bh_golden_rechaza_dos_de_tres", "test_bonferroni_mas_conservador_que_bh", "test_p_values_adjusted_alineados_y_en_rango", "test_none_se_propaga_alineado", "test_lista_vacia_devuelve_note", "test_solo_none_devuelve_note", "test_metodo_desconocido_devuelve_note", "test_todos_significativos", "test_holm_golden_rechaza_dos_de_cuatro", "test_holm_entre_bonferroni_y_bh", "test_none_se_propaga_alineado_holm", "test_lista_vacia_holm_devuelve_note"]
|
||||
test_file_path: "python/functions/datascience/fdr_correction_test.py"
|
||||
file_path: "python/functions/datascience/fdr_correction.py"
|
||||
---
|
||||
@@ -45,6 +45,13 @@ bon = fdr_correction(pvalues, alpha=0.05, method="bonferroni")
|
||||
print(bon["reject"]) # -> [True, False, False]
|
||||
print(bon["p_values_adjusted"]) # -> [0.03, 0.06, 1.0]
|
||||
|
||||
# Holm-Bonferroni (step-down): controla el FWER como Bonferroni pero es mas
|
||||
# potente; rechaza al menos tanto como Bonferroni simple, nunca menos.
|
||||
holm = fdr_correction([0.01, 0.04, 0.03, 0.005], alpha=0.05, method="holm")
|
||||
print(holm["reject"]) # -> [True, False, False, True]
|
||||
print(holm["p_values_adjusted"]) # -> [0.03, 0.06, 0.06, 0.02]
|
||||
print(holm["n_rejected"]) # -> 2
|
||||
|
||||
# Posiciones sin test (None) se propagan alineadas: el llamador puede pasar la
|
||||
# lista completa de pares y recuperar el mapeo 1:1.
|
||||
mix = fdr_correction([0.001, None, 0.9])
|
||||
@@ -61,8 +68,11 @@ combinaciones y se quede con las que "pasan". Sin corregir, con N pruebas y
|
||||
alpha=0.05 esperas ~5% de falsos positivos *por azar*: cuantas mas pruebas, mas
|
||||
correlaciones espurias. Llama a `fdr_correction` con todos los p-valores de la
|
||||
familia y usa `reject` (no el umbral crudo) para decidir que es real. Usa `"bh"`
|
||||
por defecto (mejor potencia); `"bonferroni"` cuando un falso positivo sea muy
|
||||
costoso y prefieras maxima cautela.
|
||||
por defecto (mejor potencia); `"holm"` (Holm-Bonferroni, FWER step-down) cuando
|
||||
quieras controlar el FWER pero sin la perdida de potencia de Bonferroni simple
|
||||
(rechaza al menos tanto como `"bonferroni"`, nunca menos); `"bonferroni"` cuando
|
||||
un falso positivo sea muy costoso y prefieras la maxima cautela del metodo mas
|
||||
simple.
|
||||
|
||||
## Gotchas
|
||||
|
||||
@@ -76,8 +86,16 @@ costoso y prefieras maxima cautela.
|
||||
eso puedes pasar la lista completa de pares aunque algunos no tengan test.
|
||||
- `n_tests` es el numero de p-valores **validos** (m), que puede ser menor que
|
||||
`len(pvalues)` si hay `None`.
|
||||
- BH y Bonferroni controlan cosas distintas: BH la tasa de falsos
|
||||
descubrimientos (FDR), Bonferroni la probabilidad de *cualquier* falso
|
||||
- BH controla cosa distinta que Bonferroni/Holm: BH la tasa de falsos
|
||||
descubrimientos (FDR); Bonferroni y Holm la probabilidad de *cualquier* falso
|
||||
positivo (FWER). No son intercambiables; elige segun el coste de equivocarte.
|
||||
- `"holm"` y `"bonferroni"` controlan ambos el FWER, pero Holm es step-down y
|
||||
uniformemente mas potente: rechaza al menos tantas hipotesis como Bonferroni
|
||||
simple sobre el mismo set, nunca menos. Si controlas FWER, `"holm"` domina a
|
||||
`"bonferroni"` salvo que necesites el ajuste mas simple por interpretabilidad.
|
||||
- Metodo desconocido o lista vacia/sin p validos no lanzan: devuelven un dict
|
||||
con `note`.
|
||||
con `note`. Los metodos validos son `"bh"`, `"bonferroni"` y `"holm"`.
|
||||
|
||||
## Capability growth log
|
||||
|
||||
- v1.1.0 (2026-06-30) — añade method="holm" (Holm-Bonferroni step-down, FWER, más potente que Bonferroni simple).
|
||||
|
||||
@@ -5,12 +5,15 @@ todos los pares de una matriz de asociacion), la probabilidad de obtener al meno
|
||||
un falso positivo por azar crece con el numero de pruebas: es el sesgo de mineria
|
||||
de datos (data-mining bias) descrito por Aronson en *Evidence-Based Technical
|
||||
Analysis* (cap. 6). Esta funcion ajusta los p-valores para controlar ese sesgo
|
||||
mediante dos metodos clasicos:
|
||||
mediante tres metodos clasicos:
|
||||
|
||||
- Benjamini-Hochberg (``"bh"``): controla la tasa de falsos descubrimientos
|
||||
(False Discovery Rate, FDR). Menos conservador, mas potencia estadistica.
|
||||
- Bonferroni (``"bonferroni"``): controla la tasa de error por familia
|
||||
(Family-Wise Error Rate, FWER). Mas conservador.
|
||||
- Holm-Bonferroni (``"holm"``): controla el FWER como Bonferroni pero es un
|
||||
procedimiento step-down uniformemente mas potente; rechaza al menos tantas
|
||||
hipotesis como Bonferroni simple, nunca menos.
|
||||
|
||||
No usa dependencias externas: aritmetica de la libreria estandar.
|
||||
"""
|
||||
@@ -35,8 +38,9 @@ def _is_valid_p(v) -> bool:
|
||||
def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = "bh") -> dict:
|
||||
"""Corrige una lista de p-valores por comparaciones multiples.
|
||||
|
||||
Aplica Benjamini-Hochberg (FDR) o Bonferroni (FWER) sobre ``pvalues`` y
|
||||
devuelve, alineado posicion a posicion con la entrada, el p-valor ajustado y
|
||||
Aplica Benjamini-Hochberg (FDR), Bonferroni (FWER) o Holm-Bonferroni
|
||||
(FWER, step-down) sobre ``pvalues`` y devuelve, alineado posicion a
|
||||
posicion con la entrada, el p-valor ajustado y
|
||||
si cada hipotesis se rechaza al nivel ``alpha`` tras la correccion. Las
|
||||
posiciones cuyo valor no sea un p-valor valido (``None``, ``NaN``, fuera de
|
||||
``[0, 1]`` o no numerico) se conservan en la salida como ``None`` /
|
||||
@@ -53,8 +57,10 @@ def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = "bh") -> di
|
||||
otros valores no validos en posiciones sin test disponible; se
|
||||
propagan como ``None`` en la salida y no cuentan como prueba.
|
||||
alpha: nivel de significancia objetivo tras la correccion (default 0.05).
|
||||
Para BH es el umbral del FDR; para Bonferroni, del FWER.
|
||||
method: ``"bh"`` (Benjamini-Hochberg, FDR) o ``"bonferroni"`` (FWER).
|
||||
Para BH es el umbral del FDR; para Bonferroni y Holm, del FWER.
|
||||
method: ``"bh"`` (Benjamini-Hochberg, FDR), ``"bonferroni"`` (FWER) o
|
||||
``"holm"`` (Holm-Bonferroni, FWER step-down, mas potente que
|
||||
Bonferroni simple).
|
||||
|
||||
Returns:
|
||||
dict con las claves:
|
||||
@@ -68,7 +74,7 @@ def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = "bh") -> di
|
||||
n_tests: numero de p-valores validos usados en la correccion (m).
|
||||
n_rejected: numero de hipotesis rechazadas (significativas).
|
||||
alpha: nivel de significancia aplicado (float).
|
||||
method: metodo aplicado (``"bh"`` o ``"bonferroni"``).
|
||||
method: metodo aplicado (``"bh"``, ``"bonferroni"`` o ``"holm"``).
|
||||
|
||||
Casos degenerados (lista vacia, sin p-valores validos o metodo
|
||||
desconocido) anaden ademas una clave ``note`` y devuelven listas
|
||||
@@ -76,7 +82,7 @@ def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = "bh") -> di
|
||||
en las posiciones invalidas).
|
||||
"""
|
||||
method_norm = (method or "").strip().lower()
|
||||
if method_norm not in {"bh", "bonferroni"}:
|
||||
if method_norm not in {"bh", "bonferroni", "holm"}:
|
||||
n = len(pvalues)
|
||||
return {
|
||||
"p_values_adjusted": [None] * n,
|
||||
@@ -86,8 +92,8 @@ def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = "bh") -> di
|
||||
"alpha": float(alpha),
|
||||
"method": method,
|
||||
"note": (
|
||||
f"metodo desconocido '{method}'; usa 'bh' (Benjamini-Hochberg) "
|
||||
"o 'bonferroni'"
|
||||
f"metodo desconocido '{method}'; usa 'bh' (Benjamini-Hochberg), "
|
||||
"'bonferroni' o 'holm' (Holm-Bonferroni)"
|
||||
),
|
||||
}
|
||||
|
||||
@@ -129,6 +135,20 @@ def fdr_correction(pvalues: list, alpha: float = 0.05, method: str = "bh") -> di
|
||||
padj = min(1.0, p * m)
|
||||
adjusted[orig_idx] = padj
|
||||
reject[orig_idx] = padj <= a
|
||||
elif method_norm == "holm":
|
||||
# Holm-Bonferroni (step-down). Ordena p ascendente; para el rank k
|
||||
# (1-indexed) el p ajustado crudo es (m - k + 1) * p_(k). Impon
|
||||
# monotonicidad acumulada (no decreciente) recorriendo de menor a mayor:
|
||||
# padj_(k) = max(padj_(k-1), min(1, (m-k+1)*p_(k))), con padj_(0)=0.
|
||||
order = sorted(valid, key=lambda t: t[1]) # [(orig_idx, p), ...] por p asc
|
||||
prev = 0.0
|
||||
for k in range(1, m + 1):
|
||||
orig_idx, p = order[k - 1]
|
||||
raw = min(1.0, (m - k + 1) * p)
|
||||
padj = max(prev, raw)
|
||||
prev = padj
|
||||
adjusted[orig_idx] = padj
|
||||
reject[orig_idx] = padj <= a
|
||||
else:
|
||||
# Benjamini-Hochberg (step-up). Ordena p ascendente y calcula q-valores
|
||||
# con la monotonicidad acumulada de derecha a izquierda.
|
||||
|
||||
@@ -82,7 +82,8 @@ def test_solo_none_devuelve_note():
|
||||
|
||||
|
||||
def test_metodo_desconocido_devuelve_note():
|
||||
out = fdr_correction([0.01, 0.02], method="holm")
|
||||
# 'holm' ya es un metodo valido (v1.1.0); usamos uno realmente desconocido.
|
||||
out = fdr_correction([0.01, 0.02], method="sidak")
|
||||
assert "note" in out
|
||||
assert out["n_rejected"] == 0
|
||||
assert out["reject"] == [False, False]
|
||||
@@ -97,3 +98,66 @@ def test_todos_significativos():
|
||||
assert bon["n_rejected"] == 3
|
||||
assert all(bh["reject"])
|
||||
assert all(bon["reject"])
|
||||
|
||||
|
||||
def test_holm_golden_rechaza_dos_de_cuatro():
|
||||
# Holm-Bonferroni (step-down) sobre [0.01, 0.04, 0.03, 0.005], m=4, alpha=0.05.
|
||||
# Ordenado ascendente: 0.005, 0.01, 0.03, 0.04.
|
||||
# padj_(1) = 4*0.005 = 0.02
|
||||
# padj_(2) = max(0.02, 3*0.01=0.03) = 0.03
|
||||
# padj_(3) = max(0.03, 2*0.03=0.06) = 0.06
|
||||
# padj_(4) = max(0.06, 1*0.04=0.04) = 0.06
|
||||
# Mapeado al orden de entrada [0.01, 0.04, 0.03, 0.005]:
|
||||
# 0.01 -> 0.03, 0.04 -> 0.06, 0.03 -> 0.06, 0.005 -> 0.02
|
||||
out = fdr_correction([0.01, 0.04, 0.03, 0.005], alpha=0.05, method="holm")
|
||||
assert out["method"] == "holm"
|
||||
assert out["n_tests"] == 4
|
||||
adj = out["p_values_adjusted"]
|
||||
assert abs(adj[0] - 0.03) < 1e-9
|
||||
assert abs(adj[1] - 0.06) < 1e-9
|
||||
assert abs(adj[2] - 0.06) < 1e-9
|
||||
assert abs(adj[3] - 0.02) < 1e-9
|
||||
assert out["reject"] == [True, False, False, True]
|
||||
assert out["n_rejected"] == 2
|
||||
|
||||
|
||||
def test_holm_entre_bonferroni_y_bh():
|
||||
# Holm controla FWER como Bonferroni pero es step-down: rechaza AL MENOS
|
||||
# tanto como Bonferroni simple, y a lo sumo tanto como BH (FDR, menos
|
||||
# conservador). Cadena de potencia: bonferroni <= holm <= bh.
|
||||
pvalues = [0.01, 0.02, 0.04, 0.005]
|
||||
bon = fdr_correction(pvalues, alpha=0.05, method="bonferroni")
|
||||
holm = fdr_correction(pvalues, alpha=0.05, method="holm")
|
||||
bh = fdr_correction(pvalues, alpha=0.05, method="bh")
|
||||
assert holm["n_rejected"] >= bon["n_rejected"]
|
||||
assert holm["n_rejected"] <= bh["n_rejected"]
|
||||
# En este set Holm gana potencia frente a Bonferroni simple (estricto).
|
||||
assert holm["n_rejected"] > bon["n_rejected"]
|
||||
|
||||
# Un set donde Holm es estrictamente mas conservador que BH.
|
||||
pvals2 = [0.01, 0.02, 0.03, 0.04]
|
||||
bon2 = fdr_correction(pvals2, alpha=0.05, method="bonferroni")
|
||||
holm2 = fdr_correction(pvals2, alpha=0.05, method="holm")
|
||||
bh2 = fdr_correction(pvals2, alpha=0.05, method="bh")
|
||||
assert holm2["n_rejected"] >= bon2["n_rejected"]
|
||||
assert holm2["n_rejected"] < bh2["n_rejected"]
|
||||
|
||||
|
||||
def test_none_se_propaga_alineado_holm():
|
||||
# None se propaga alineado tambien con holm: la posicion central no cuenta
|
||||
# como prueba (m=2) y se devuelve como None / False.
|
||||
out = fdr_correction([0.001, None, 0.9], method="holm")
|
||||
assert out["n_tests"] == 2
|
||||
assert out["p_values_adjusted"][1] is None
|
||||
assert out["reject"][1] is False
|
||||
assert out["reject"][0] is True
|
||||
assert len(out["reject"]) == 3
|
||||
|
||||
|
||||
def test_lista_vacia_holm_devuelve_note():
|
||||
out = fdr_correction([], method="holm")
|
||||
assert out["p_values_adjusted"] == []
|
||||
assert out["reject"] == []
|
||||
assert out["n_tests"] == 0
|
||||
assert out["n_rejected"] == 0
|
||||
assert "note" in out
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
name: preregister_hypothesis
|
||||
kind: function
|
||||
lang: py
|
||||
domain: datascience
|
||||
version: "1.0.0"
|
||||
purity: impure
|
||||
signature: "def preregister_hypothesis(paper_dir: str, hypotheses: dict, analysis_plan: dict) -> dict"
|
||||
description: "Pre-registra (congela) la hipotesis y el plan de analisis de un paper ANTES de mirar los datos: antidoto al HARKing (Hypothesizing After the Results are Known). Escribe/actualiza <paper_dir>/preregistration.md con un frontmatter (paper_slug, frozen_at, content_hash, status) y un cuerpo markdown DETERMINISTA derivado de (hypotheses, analysis_plan) (mismo input -> mismo cuerpo byte a byte, claves ordenadas alfabeticamente). El content_hash es sha256 del cuerpo NORMALIZADO (strip por linea + colapso de blancos), nunca del frontmatter. Una vez status=frozen es INMUTABLE: re-congelar con el mismo contenido es idempotente (no reescribe, devuelve unchanged) y re-congelar con contenido distinto se RECHAZA (no sobrescribe, devuelve error) para que no se pueda ajustar la hipotesis a los resultados. Estilo dict-no-throw: nunca lanza."
|
||||
tags: [papers, preregistration, reproducibility, anti-harking, python]
|
||||
params:
|
||||
- name: paper_dir
|
||||
desc: "ruta del directorio del paper, p.ej. 'papers/0001-mi-paper'. Debe existir (no se crea aqui). El paper_slug del frontmatter es el basename del dir. Si no existe o no es str -> {status:error, path, note} sin crash ni creacion."
|
||||
- name: hypotheses
|
||||
desc: "dict de hipotesis, p.ej. {'h0': 'no hay diferencia ...', 'h1': 'el grupo A > grupo B ...'}. Se renderiza en la seccion '## Hypotheses' con una linea por clave, ordenadas alfabeticamente para determinismo."
|
||||
- name: analysis_plan
|
||||
desc: "dict con el plan de analisis, p.ej. {'test': 'welch_t_test', 'effect_size_metric': 'cohens_d', 'decision_rule': 'rechazar H0 si p<0.05 tras Holm y |d|>=0.5', 'planned_n': 100, 'multiple_correction': 'holm'}. Se renderiza en '## Analysis plan' con una linea por clave (ordenadas alfabeticamente). Acepta valores no-str (int, etc.)."
|
||||
output: "dict dict-no-throw (NUNCA lanza). status='frozen' cuando escribe el archivo por primera vez o congela un draft previo ({status, path, content_hash, frozen_at}). status='unchanged' cuando ya estaba frozen con el mismo content_hash: no reescribe y preserva el archivo byte-identico incl. el frozen_at original ({status, path, content_hash, frozen_at}). status='error' cuando paper_dir no existe, ya esta frozen con un hash distinto (rechazo anti-HARKing, no sobrescribe), inputs invalidos o error de I/O ({status, path, note, [content_hash]})."
|
||||
uses_functions: []
|
||||
uses_types: []
|
||||
returns: []
|
||||
returns_optional: false
|
||||
error_type: "error_go_core"
|
||||
imports: [hashlib]
|
||||
tested: true
|
||||
tests: ["test_golden_congela_y_escribe_archivo", "test_idempotente_mismo_input_no_reescribe", "test_inmutabilidad_anti_harking_rechaza_contenido_distinto", "test_error_paper_dir_inexistente_no_crash_no_crea"]
|
||||
test_file_path: "python/functions/datascience/preregister_hypothesis_test.py"
|
||||
file_path: "python/functions/datascience/preregister_hypothesis.py"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```python
|
||||
import os, tempfile
|
||||
from datascience import preregister_hypothesis
|
||||
|
||||
# Un directorio de paper que ya existe.
|
||||
paper_dir = tempfile.mkdtemp(prefix="0001-")
|
||||
|
||||
hypotheses = {
|
||||
"h0": "no hay diferencia entre el grupo A y el grupo B",
|
||||
"h1": "el grupo A tiene mayor conversion que el grupo B",
|
||||
}
|
||||
analysis_plan = {
|
||||
"test": "welch_t_test",
|
||||
"effect_size_metric": "cohens_d",
|
||||
"decision_rule": "rechazar H0 si p<0.05 tras Holm y |d|>=0.5",
|
||||
"planned_n": 100,
|
||||
"multiple_correction": "holm",
|
||||
}
|
||||
|
||||
# 1) Primera vez: congela y escribe <paper_dir>/preregistration.md
|
||||
r1 = preregister_hypothesis(paper_dir, hypotheses, analysis_plan)
|
||||
print(r1["status"]) # -> "frozen"
|
||||
print(r1["content_hash"]) # sha256 del cuerpo
|
||||
|
||||
# 2) Mismo input: idempotente, no reescribe.
|
||||
r2 = preregister_hypothesis(paper_dir, hypotheses, analysis_plan)
|
||||
print(r2["status"]) # -> "unchanged"
|
||||
|
||||
# 3) Cambiar la hipotesis tras congelar (HARKing): rechazado, archivo intacto.
|
||||
r3 = preregister_hypothesis(paper_dir, {"h0": "...", "h1": "otra cosa"}, analysis_plan)
|
||||
print(r3["status"]) # -> "error"
|
||||
```
|
||||
|
||||
## Cuando usarla
|
||||
|
||||
Llamala al ARRANCAR el analisis de un paper, antes de tocar los datos, para
|
||||
dejar por escrito (y firmado por hash) que vas a probar y como vas a decidir.
|
||||
Es el primer paso de un flujo reproducible: pre-registras la hipotesis y el plan
|
||||
(`test`, `effect_size_metric`, `decision_rule`, `planned_n`,
|
||||
`multiple_correction`), y solo despues corres el analisis y comparas con lo
|
||||
pre-registrado. Si mas tarde el analisis "descubre" otra hipotesis que encaja
|
||||
mejor con los datos, el pre-registro congelado deja en evidencia el cambio: no se
|
||||
puede reescribir. Combinala con `effect_size_cohens_d` y `fdr_correction` para
|
||||
cerrar el plan declarado (effect size + correccion de multiples comparaciones).
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Inmutabilidad (el corazon)**: una vez `status: frozen`, el pre-registro NO se
|
||||
puede editar. Re-congelar con el MISMO contenido es idempotente (`unchanged`,
|
||||
no reescribe, preserva incluso el `frozen_at` original). Re-congelar con
|
||||
contenido DISTINTO devuelve `error` y deja el archivo intacto: asi se mata el
|
||||
HARKing. Para cambiar de verdad la hipotesis hay que borrar el archivo a mano y
|
||||
asumir explicitamente que ya no es un pre-registro valido.
|
||||
- **dict-no-throw**: la funcion NUNCA lanza. Cualquier error previsible
|
||||
(directorio inexistente, inputs no-dict, fallo de I/O, excepcion inesperada) se
|
||||
captura y se devuelve como `{"status": "error", "note": ...}`. Siempre incluye
|
||||
`path` (la ruta esperada del `preregistration.md`).
|
||||
- **El hash es SOLO del cuerpo, nunca del frontmatter**: el frontmatter contiene
|
||||
el propio `content_hash` y el `frozen_at` (timestamp), asi que incluirlos en el
|
||||
hash seria circular y romperia la idempotencia. El cuerpo se normaliza antes de
|
||||
hashear (strip por linea + colapso de lineas en blanco + strip final): cambios
|
||||
irrelevantes de whitespace no alteran el hash, pero cambios de contenido SI.
|
||||
- **Determinismo**: el cuerpo se genera con las claves de `hypotheses` y
|
||||
`analysis_plan` ordenadas alfabeticamente, de modo que el orden de insercion del
|
||||
dict no afecta al hash. Mismo `(hypotheses, analysis_plan)` -> mismo cuerpo y
|
||||
mismo hash, byte a byte.
|
||||
- **No crea el directorio del paper**: si `paper_dir` no existe, devuelve `error`
|
||||
sin crear nada (ni el dir ni el archivo).
|
||||
@@ -0,0 +1,202 @@
|
||||
"""Congela (pre-registra) la hipotesis y el plan de analisis de un paper.
|
||||
|
||||
Anti-HARKing (Hypothesizing After the Results are Known): el pre-registro fija
|
||||
la hipotesis y el plan de analisis ANTES de mirar los datos. Una vez congelado
|
||||
(``status: frozen``) es INMUTABLE: cualquier intento posterior de re-congelar con
|
||||
un contenido distinto se RECHAZA en vez de sobrescribir, de modo que no se puede
|
||||
"ajustar" la hipotesis a los resultados despues de verlos.
|
||||
|
||||
Escribe/actualiza ``<paper_dir>/preregistration.md`` con un frontmatter
|
||||
(``paper_slug``, ``frozen_at``, ``content_hash``, ``status``) y un cuerpo
|
||||
markdown DETERMINISTA derivado de ``(hypotheses, analysis_plan)``.
|
||||
|
||||
Estilo dict-no-throw: NUNCA lanza; cualquier error previsible se captura y se
|
||||
devuelve como ``{"status": "error", "note": ...}``.
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
import os
|
||||
from datetime import datetime, timezone
|
||||
|
||||
|
||||
def _build_body(hypotheses: dict, analysis_plan: dict) -> str:
|
||||
"""Construye el cuerpo markdown del pre-registro de forma DETERMINISTA.
|
||||
|
||||
Mismo ``(hypotheses, analysis_plan)`` -> mismo cuerpo byte a byte. Las claves
|
||||
se ordenan alfabeticamente para no depender del orden de insercion del dict.
|
||||
"""
|
||||
lines = ["## Hypotheses", ""]
|
||||
for k in sorted(hypotheses.keys()):
|
||||
lines.append(f"- **{k}**: {hypotheses[k]}")
|
||||
lines.append("")
|
||||
lines.append("## Analysis plan")
|
||||
lines.append("")
|
||||
for k in sorted(analysis_plan.keys()):
|
||||
lines.append(f"- **{k}**: {analysis_plan[k]}")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _normalize(body: str) -> str:
|
||||
"""Normaliza el cuerpo para el hash: strip por linea + colapsa blancos.
|
||||
|
||||
Cambios irrelevantes de whitespace (espacios al final, dobles lineas en
|
||||
blanco) no alteran el hash; cambios de contenido SI. Esto hace el hash
|
||||
robusto sin perder la capacidad de detectar ediciones reales.
|
||||
"""
|
||||
out = []
|
||||
prev_blank = False
|
||||
for raw in body.splitlines():
|
||||
line = raw.strip()
|
||||
if line == "":
|
||||
if prev_blank:
|
||||
continue
|
||||
prev_blank = True
|
||||
else:
|
||||
prev_blank = False
|
||||
out.append(line)
|
||||
return "\n".join(out).strip()
|
||||
|
||||
|
||||
def _content_hash(body: str) -> str:
|
||||
"""sha256 hex del cuerpo NORMALIZADO (nunca del frontmatter)."""
|
||||
return hashlib.sha256(_normalize(body).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def _parse_frontmatter(text: str) -> dict:
|
||||
"""Parsea el frontmatter ``--- ... ---`` simple (key: value) de un .md."""
|
||||
if not text.startswith("---"):
|
||||
return {}
|
||||
parts = text.split("---", 2)
|
||||
if len(parts) < 3:
|
||||
return {}
|
||||
fm = {}
|
||||
for line in parts[1].splitlines():
|
||||
line = line.strip()
|
||||
if not line or ":" not in line:
|
||||
continue
|
||||
key, _, value = line.partition(":")
|
||||
fm[key.strip()] = value.strip()
|
||||
return fm
|
||||
|
||||
|
||||
def _render_file(slug: str, frozen_at: str, content_hash: str, body: str) -> str:
|
||||
"""Compone el archivo completo: frontmatter frozen + cuerpo."""
|
||||
return (
|
||||
"---\n"
|
||||
f"paper_slug: {slug}\n"
|
||||
f"frozen_at: {frozen_at}\n"
|
||||
f"content_hash: {content_hash}\n"
|
||||
"status: frozen\n"
|
||||
"---\n"
|
||||
"\n"
|
||||
f"{body}\n"
|
||||
)
|
||||
|
||||
|
||||
def preregister_hypothesis(paper_dir: str, hypotheses: dict, analysis_plan: dict) -> dict:
|
||||
"""Congela la hipotesis y el plan de analisis de un paper (anti-HARKing).
|
||||
|
||||
Escribe ``<paper_dir>/preregistration.md`` con frontmatter ``status: frozen``
|
||||
y un cuerpo markdown determinista. Una vez congelado es inmutable.
|
||||
|
||||
Args:
|
||||
paper_dir: ruta del directorio del paper (p.ej. ``"papers/0001-mi-paper"``).
|
||||
El ``paper_slug`` es el basename del directorio. Debe existir.
|
||||
hypotheses: dict de hipotesis, p.ej.
|
||||
``{"h0": "no hay diferencia ...", "h1": "grupo A > grupo B ..."}``.
|
||||
analysis_plan: dict con el plan, p.ej.
|
||||
``{"test": "welch_t_test", "effect_size_metric": "cohens_d",
|
||||
"decision_rule": "...", "planned_n": 100, "multiple_correction": "holm"}``.
|
||||
|
||||
Returns:
|
||||
dict dict-no-throw (NUNCA lanza). Claves segun el caso:
|
||||
- frozen: {"status": "frozen", "path", "content_hash", "frozen_at"}
|
||||
- unchanged: {"status": "unchanged", "path", "content_hash", "frozen_at"}
|
||||
- error: {"status": "error", "path", "note", ...}
|
||||
"""
|
||||
expected_path = os.path.join(paper_dir, "preregistration.md")
|
||||
try:
|
||||
# 1) El directorio del paper debe existir; no se crea aqui.
|
||||
if not isinstance(paper_dir, str) or not os.path.isdir(paper_dir):
|
||||
return {
|
||||
"status": "error",
|
||||
"path": expected_path,
|
||||
"note": f"paper_dir no existe: {paper_dir}",
|
||||
}
|
||||
|
||||
if not isinstance(hypotheses, dict) or not isinstance(analysis_plan, dict):
|
||||
return {
|
||||
"status": "error",
|
||||
"path": expected_path,
|
||||
"note": "hypotheses y analysis_plan deben ser dict",
|
||||
}
|
||||
|
||||
slug = os.path.basename(os.path.normpath(paper_dir))
|
||||
|
||||
# 2) + 3) Cuerpo determinista y su hash (solo del cuerpo, no del frontmatter).
|
||||
body = _build_body(hypotheses, analysis_plan)
|
||||
new_hash = _content_hash(body)
|
||||
|
||||
# 5) Logica de escritura.
|
||||
if os.path.exists(expected_path):
|
||||
existing = ""
|
||||
try:
|
||||
with open(expected_path, "r", encoding="utf-8") as fh:
|
||||
existing = fh.read()
|
||||
except OSError as exc:
|
||||
return {
|
||||
"status": "error",
|
||||
"path": expected_path,
|
||||
"note": f"no se pudo leer el pre-registro existente: {exc}",
|
||||
}
|
||||
fm = _parse_frontmatter(existing)
|
||||
old_status = fm.get("status", "")
|
||||
old_hash = fm.get("content_hash", "")
|
||||
old_frozen_at = fm.get("frozen_at", "")
|
||||
|
||||
if old_status == "frozen":
|
||||
if old_hash == new_hash:
|
||||
# Idempotente: mismo contenido ya congelado. No se reescribe.
|
||||
return {
|
||||
"status": "unchanged",
|
||||
"path": expected_path,
|
||||
"content_hash": new_hash,
|
||||
"frozen_at": old_frozen_at,
|
||||
}
|
||||
# Inmutabilidad: ya congelado con OTRO hash -> se rechaza (anti-HARKing).
|
||||
return {
|
||||
"status": "error",
|
||||
"path": expected_path,
|
||||
"content_hash": new_hash,
|
||||
"note": (
|
||||
"pre-registro inmutable: ya esta congelado (frozen) con un "
|
||||
"hash distinto; un pre-registro no se puede editar tras "
|
||||
"congelarse"
|
||||
),
|
||||
}
|
||||
# status != "frozen" (p.ej. draft) -> se congela ahora.
|
||||
|
||||
# Archivo nuevo o draft existente: congelar con timestamp actual.
|
||||
frozen_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
file_text = _render_file(slug, frozen_at, new_hash, body)
|
||||
try:
|
||||
with open(expected_path, "w", encoding="utf-8") as fh:
|
||||
fh.write(file_text)
|
||||
except OSError as exc:
|
||||
return {
|
||||
"status": "error",
|
||||
"path": expected_path,
|
||||
"note": f"no se pudo escribir el pre-registro: {exc}",
|
||||
}
|
||||
return {
|
||||
"status": "frozen",
|
||||
"path": expected_path,
|
||||
"content_hash": new_hash,
|
||||
"frozen_at": frozen_at,
|
||||
}
|
||||
except Exception as exc: # noqa: BLE001 - dict-no-throw: nunca propagar.
|
||||
return {
|
||||
"status": "error",
|
||||
"path": expected_path,
|
||||
"note": f"error inesperado: {exc}",
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
"""Tests para preregister_hypothesis (pre-registro inmutable, anti-HARKing).
|
||||
|
||||
Importa el modulo hoja directamente (`preregister_hypothesis`) para no depender
|
||||
de que el paquete reexporte la funcion en su __init__ (lo integra el orquestador
|
||||
al cerrar el grupo papers). El pytest del repo resuelve el modulo hoja por su
|
||||
nombre directo.
|
||||
|
||||
Todos los tests son hermeticos y deterministas: usan el fixture `tmp_path` de
|
||||
pytest; NUNCA escriben en `papers/`.
|
||||
"""
|
||||
|
||||
from preregister_hypothesis import preregister_hypothesis
|
||||
|
||||
|
||||
def _parse_frontmatter(text: str) -> dict:
|
||||
parts = text.split("---", 2)
|
||||
fm = {}
|
||||
for line in parts[1].splitlines():
|
||||
line = line.strip()
|
||||
if not line or ":" not in line:
|
||||
continue
|
||||
key, _, value = line.partition(":")
|
||||
fm[key.strip()] = value.strip()
|
||||
return fm
|
||||
|
||||
|
||||
HYP = {"h0": "no hay diferencia entre A y B", "h1": "el grupo A > grupo B"}
|
||||
PLAN = {
|
||||
"test": "welch_t_test",
|
||||
"effect_size_metric": "cohens_d",
|
||||
"decision_rule": "rechazar H0 si p<0.05 tras Holm y |d|>=0.5",
|
||||
"planned_n": 100,
|
||||
"multiple_correction": "holm",
|
||||
}
|
||||
|
||||
|
||||
def test_golden_congela_y_escribe_archivo(tmp_path):
|
||||
paper = tmp_path / "0001-x"
|
||||
paper.mkdir()
|
||||
|
||||
res = preregister_hypothesis(str(paper), HYP, PLAN)
|
||||
|
||||
assert res["status"] == "frozen"
|
||||
pre = paper / "preregistration.md"
|
||||
assert pre.exists()
|
||||
|
||||
text = pre.read_text(encoding="utf-8")
|
||||
fm = _parse_frontmatter(text)
|
||||
assert fm["status"] == "frozen"
|
||||
assert fm["paper_slug"] == "0001-x"
|
||||
assert fm["content_hash"] # no vacio
|
||||
assert fm["frozen_at"] # no vacio
|
||||
assert res["content_hash"] == fm["content_hash"]
|
||||
assert res["frozen_at"] == fm["frozen_at"]
|
||||
|
||||
|
||||
def test_idempotente_mismo_input_no_reescribe(tmp_path):
|
||||
paper = tmp_path / "0001-x"
|
||||
paper.mkdir()
|
||||
pre = paper / "preregistration.md"
|
||||
|
||||
first = preregister_hypothesis(str(paper), HYP, PLAN)
|
||||
assert first["status"] == "frozen"
|
||||
bytes_before = pre.read_bytes()
|
||||
|
||||
second = preregister_hypothesis(str(paper), HYP, PLAN)
|
||||
assert second["status"] == "unchanged"
|
||||
# Mismo hash y frozen_at original preservado.
|
||||
assert second["content_hash"] == first["content_hash"]
|
||||
assert second["frozen_at"] == first["frozen_at"]
|
||||
# El archivo NO cambio byte a byte (incl. frozen_at).
|
||||
assert pre.read_bytes() == bytes_before
|
||||
|
||||
|
||||
def test_inmutabilidad_anti_harking_rechaza_contenido_distinto(tmp_path):
|
||||
paper = tmp_path / "0001-x"
|
||||
paper.mkdir()
|
||||
pre = paper / "preregistration.md"
|
||||
|
||||
preregister_hypothesis(str(paper), HYP, PLAN)
|
||||
bytes_frozen = pre.read_bytes()
|
||||
|
||||
# Intento de re-congelar con una hipotesis DISTINTA (HARKing) -> rechazado.
|
||||
hyp_tramposo = {"h0": "no hay diferencia", "h1": "el grupo B > grupo A (cambiado tras ver datos)"}
|
||||
res = preregister_hypothesis(str(paper), hyp_tramposo, PLAN)
|
||||
|
||||
assert res["status"] == "error"
|
||||
# Asercion mas importante: el archivo en disco SIGUE siendo el original.
|
||||
assert pre.read_bytes() == bytes_frozen
|
||||
|
||||
|
||||
def test_error_paper_dir_inexistente_no_crash_no_crea(tmp_path):
|
||||
missing = tmp_path / "no-existe"
|
||||
res = preregister_hypothesis(str(missing), HYP, PLAN)
|
||||
|
||||
assert res["status"] == "error"
|
||||
# No se creo el directorio ni el archivo.
|
||||
assert not missing.exists()
|
||||
assert not (missing / "preregistration.md").exists()
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
name: render_paper_pdf
|
||||
kind: function
|
||||
lang: py
|
||||
domain: datascience
|
||||
version: "1.0.0"
|
||||
purity: impure
|
||||
signature: "def render_paper_pdf(paper_dir: str) -> dict"
|
||||
description: "Convierte un paper académico IMRaD escrito en Markdown (papers/<slug>/paper.md, con frontmatter YAML opcional title/authors/date/abstract + cuerpo) en un PDF papers/<slug>/out/paper.pdf. REUTILIZA el paginador de flujo del paquete automatic_eda (el mismo motor del PDF móvil A5 de los informes EDA): no reimplementa paginación ni toca matplotlib. Cada sección IMRaD (encabezado de nivel 1, p.ej. # Introduction, # Methods) se mapea a un Chapter que empieza en página nueva; el motor parsea por sí mismo headings, listas, tablas pipe, párrafos y **negrita** dentro del texto. Como el motor NO entiende la sintaxis de imagen Markdown , esta función detecta esas líneas y las parte en bloques Image separados, resolviendo el src relativo a base_dir y base_dir/figures/. La portada (si hay título) lista autores y fecha (DD/MM/AAAA si parseable) más el abstract. dict-no-throw: nunca lanza, devuelve {status, pdf_path, n_pages, note}."
|
||||
tags: [papers, pdf, academic, render, report, imrad, mobile, automatic-eda, markdown, no-cut, matplotlib, datascience, python]
|
||||
uses_functions: []
|
||||
uses_types: []
|
||||
returns: []
|
||||
returns_optional: false
|
||||
error_type: "error_go_core"
|
||||
imports: [os, re, datetime, yaml, "datascience.automatic_eda"]
|
||||
params:
|
||||
- name: paper_dir
|
||||
desc: "ruta al directorio del paper (papers/<slug>/, del que se lee paper.md) O directamente la ruta a un archivo paper.md (cualquier ruta terminada en .md). El directorio base para resolver figuras y escribir el PDF es el dirname del paper.md. Si el paper.md no existe (incluida una ruta totalmente inexistente) devuelve status='error' sin crash."
|
||||
output: "dict (nunca lanza): {status: 'ok'|'error', pdf_path: str|None, n_pages: int, note: str}. En éxito status='ok', pdf_path es la ruta del PDF escrito (<base_dir>/out/paper.pdf) y n_pages el total de páginas. En error status='error', pdf_path=None, n_pages=0 y note explica la causa (paper.md no encontrado, fallo del motor, o excepción inesperada)."
|
||||
tested: true
|
||||
tests: ["test_golden_genera_pdf_con_portada_y_secciones", "test_edge_sin_frontmatter_ni_figuras", "test_edge_path_inexistente_no_revienta", "test_edge_figura_inexistente_degrada", "test_acepta_ruta_directa_al_md"]
|
||||
test_file_path: "python/functions/datascience/render_paper_pdf_test.py"
|
||||
file_path: "python/functions/datascience/render_paper_pdf.py"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```python
|
||||
from datascience import render_paper_pdf
|
||||
|
||||
# Estructura del paper:
|
||||
# papers/zz-demo/paper.md (frontmatter YAML + cuerpo IMRaD)
|
||||
# papers/zz-demo/figures/fig1.png (figuras referenciadas con )
|
||||
#
|
||||
# paper.md:
|
||||
# ---
|
||||
# title: A Minimal IMRaD Paper
|
||||
# authors: [Ada Lovelace, Alan Turing]
|
||||
# date: 2026-06-30
|
||||
# abstract: Demostramos que el motor pagina un paper sin cortar nada.
|
||||
# ---
|
||||
# # Introduction
|
||||
# Texto con **negrita** y una lista:
|
||||
# - Punto uno.
|
||||
# 
|
||||
# # Methods
|
||||
# | Métrica | Valor |
|
||||
# | --- | --- |
|
||||
# | Precisión | 0.91 |
|
||||
|
||||
res = render_paper_pdf("papers/zz-demo")
|
||||
print(res["status"], res["n_pages"], res["pdf_path"])
|
||||
# -> ok 3 papers/zz-demo/out/paper.pdf
|
||||
|
||||
# También acepta la ruta directa al .md:
|
||||
render_paper_pdf("papers/zz-demo/paper.md")
|
||||
```
|
||||
|
||||
## Cuando usarla
|
||||
|
||||
Cuando tengas un paper académico (o cualquier documento IMRaD) escrito en
|
||||
Markdown y quieras un **PDF móvil A5 listo para leer**, sin montar LaTeX ni
|
||||
configurar un pipeline de pandoc. Úsala después de redactar `paper.md` con su
|
||||
frontmatter (título, autores, fecha, abstract) y secciones de nivel 1; obtienes
|
||||
`out/paper.pdf` con portada, una página nueva por sección IMRaD, tablas que se
|
||||
parten repitiendo la cabecera y figuras escaladas para caber enteras —
|
||||
garantía de no-corte heredada del motor `automatic_eda`. Es la capa de
|
||||
presentación PDF del grupo `papers`.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Impura**: escribe `out/paper.pdf` (y crea el directorio `out/`) junto al
|
||||
`paper.md`. Necesita **matplotlib** instalado en el venv (lo usa el motor
|
||||
`automatic_eda.render_pdf` con backend headless `Agg`; corre en agentes/CI sin
|
||||
display). `pyyaml` es opcional: si falta, el frontmatter se parsea con un
|
||||
parser line-based `clave: valor` degradado.
|
||||
- **Reutiliza el motor `automatic_eda.render_pdf`**: NO reimplementa paginación
|
||||
ni toca matplotlib. `render_pdf` no tiene ID propio en el registry (es parte
|
||||
del paquete de soporte `automatic_eda`), por eso `uses_functions` queda vacío;
|
||||
la dependencia real es ese motor del paquete.
|
||||
- **Nunca lanza** (dict-no-throw): `paper.md` inexistente → `{status:"error",
|
||||
pdf_path:None, note:"paper.md no encontrado: ..."}`; cualquier excepción
|
||||
inesperada → `{status:"error", note:"fallo: ..."}`. Frontmatter ausente o
|
||||
incompleto degrada limpio (sin portada, el cuerpo entero se pagina).
|
||||
- **Figuras relativas a `figures/`**: el `src` de `` se resuelve
|
||||
probando `<base_dir>/<src>` y `<base_dir>/figures/<basename>`; usa el primero
|
||||
que exista. Si ninguno existe, el motor **degrada** dibujando
|
||||
"(imagen no encontrada: ...)" — el PDF se genera igual, no crashea. Las URLs
|
||||
`http(s)` se dejan como texto Markdown, no se descargan.
|
||||
- **Solo imágenes en línea propia**: el motor `_place_markdown` NO entiende
|
||||
``; esta función solo convierte a `Image` las líneas cuyo único
|
||||
contenido es la imagen. Una imagen embebida a mitad de un párrafo se quedaría
|
||||
como texto crudo.
|
||||
- **A5 portrait mobile-first**: el formato (tamaño de página, tipografía, pie
|
||||
`Capítulo · vX.Y.Z`) lo fija el motor EDA y no es configurable desde aquí.
|
||||
@@ -1,297 +0,0 @@
|
||||
"""render_paper_pdf — convierte un paper académico IMRaD en Markdown a un PDF.
|
||||
|
||||
Toma un paper escrito en Markdown con frontmatter YAML opcional (título,
|
||||
autores, fecha, abstract) más un cuerpo dividido en secciones IMRaD por
|
||||
encabezados de nivel 1 (``# Introduction``, ``# Methods``, ...) y produce un PDF
|
||||
``out/paper.pdf`` junto al paper.
|
||||
|
||||
REUTILIZA el paginador de flujo del paquete ``automatic_eda`` (el mismo motor
|
||||
que rinde los informes EDA en PDF móvil A5): no reimplementa paginación ni toca
|
||||
matplotlib directamente. Cada sección IMRaD se mapea a un ``Chapter`` (empieza
|
||||
en página nueva). El motor ``_place_markdown`` parsea por sí mismo headings,
|
||||
listas, tablas pipe, párrafos y ``**negrita**`` dentro del texto, pero NO
|
||||
entiende la sintaxis de imagen Markdown ````; por eso esta función
|
||||
detecta esas líneas y las convierte en bloques ``Image`` separados, partiendo el
|
||||
texto Markdown alrededor de cada imagen.
|
||||
|
||||
dict-no-throw (estilo del grupo eda): NUNCA lanza. Devuelve
|
||||
``{status, pdf_path, n_pages, note}``; ante cualquier fallo devuelve
|
||||
``status="error"`` con ``pdf_path=None`` y la causa en ``note``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as _dt
|
||||
import os
|
||||
import re
|
||||
|
||||
from datascience.automatic_eda import Chapter, Heading, Image, Markdown, render_pdf
|
||||
|
||||
# Una línea cuyo único contenido es una imagen Markdown: 
|
||||
_IMG_LINE = re.compile(r"^\s*!\[([^\]]*)\]\(\s*([^)\s]+)\s*\)\s*$")
|
||||
# Un encabezado de nivel 1 al inicio de línea (un solo '#' seguido de espacio).
|
||||
_H1_LINE = re.compile(r"^#[ \t]+(.+?)\s*$")
|
||||
|
||||
|
||||
def render_paper_pdf(paper_dir: str) -> dict:
|
||||
"""Renderiza un paper académico Markdown IMRaD en un PDF.
|
||||
|
||||
Args:
|
||||
paper_dir: ruta al directorio del paper (``papers/<slug>/``, del que se
|
||||
lee ``paper.md``) o directamente la ruta a un archivo ``paper.md``.
|
||||
|
||||
Returns:
|
||||
dict (nunca lanza): ``{status: "ok"|"error", pdf_path: str|None,
|
||||
n_pages: int, note: str}``. En éxito ``pdf_path`` es la ruta escrita y
|
||||
``n_pages`` el total de páginas; en error ``pdf_path`` es None y
|
||||
``note`` explica la causa.
|
||||
"""
|
||||
try:
|
||||
# 1) Resolver el path del paper.md y el directorio base.
|
||||
arg = str(paper_dir)
|
||||
md_path = arg if arg.endswith(".md") else os.path.join(arg, "paper.md")
|
||||
|
||||
# 2) Si el paper.md no existe, degradar sin crash.
|
||||
if not os.path.isfile(md_path):
|
||||
return {"status": "error", "pdf_path": None, "n_pages": 0,
|
||||
"note": f"paper.md no encontrado: {md_path}"}
|
||||
|
||||
base_dir = os.path.dirname(os.path.abspath(md_path))
|
||||
|
||||
# 3) Leer el archivo y separar frontmatter del cuerpo.
|
||||
with open(md_path, "r", encoding="utf-8") as fh:
|
||||
text = fh.read()
|
||||
fm_text, body = _split_frontmatter(text)
|
||||
fm = _parse_frontmatter(fm_text)
|
||||
|
||||
title = _safe_str(fm.get("title")).strip()
|
||||
authors = fm.get("authors")
|
||||
date_raw = fm.get("date")
|
||||
abstract = _safe_str(fm.get("abstract")).strip()
|
||||
|
||||
# 4) Construir los capítulos: portada (si hay título) + cuerpo IMRaD.
|
||||
chapters: list = []
|
||||
if title:
|
||||
cover_md = _portada_markdown(authors, date_raw, abstract)
|
||||
cover_blocks: list = [Heading(text=title, level=1)]
|
||||
if cover_md.strip():
|
||||
cover_blocks.append(Markdown(text=cover_md))
|
||||
chapters.append(Chapter(id="portada", title=title, version="1.0.0",
|
||||
blocks=cover_blocks))
|
||||
|
||||
preamble, sections = _split_body_sections(body)
|
||||
|
||||
if not sections:
|
||||
# Sin encabezados H1: todo el cuerpo en un único capítulo.
|
||||
chapters.append(Chapter(
|
||||
id="cuerpo", title="Cuerpo", version="1.0.0",
|
||||
blocks=_markdown_to_blocks(body, base_dir)))
|
||||
else:
|
||||
# Texto antes del primer H1 (si lo hay) como capítulo previo.
|
||||
if preamble.strip():
|
||||
chapters.append(Chapter(
|
||||
id="cuerpo", title="Cuerpo", version="1.0.0",
|
||||
blocks=_markdown_to_blocks(preamble, base_dir)))
|
||||
for idx, (sec_title, sec_body) in enumerate(sections):
|
||||
blocks: list = [Heading(text=sec_title, level=1)]
|
||||
blocks.extend(_markdown_to_blocks(sec_body, base_dir))
|
||||
chapters.append(Chapter(
|
||||
id=_slugify(sec_title) or f"sec{idx}",
|
||||
title=sec_title, version="1.0.0", blocks=blocks))
|
||||
|
||||
# 5) Renderizar con el motor de automatic_eda.
|
||||
out_path = os.path.join(base_dir, "out", "paper.pdf")
|
||||
res = render_pdf(chapters, out_path, meta={"title": title or "paper"})
|
||||
|
||||
# 6) Mapear el retorno del motor a la forma de esta función.
|
||||
path = res.get("path")
|
||||
return {
|
||||
"status": "ok" if path else "error",
|
||||
"pdf_path": path,
|
||||
"n_pages": int(res.get("n_pages") or 0),
|
||||
"note": res.get("note"),
|
||||
}
|
||||
except Exception as e: # noqa: BLE001 — dict-no-throw estricto.
|
||||
return {"status": "error", "pdf_path": None, "n_pages": 0,
|
||||
"note": f"fallo: {e}"}
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Frontmatter
|
||||
# --------------------------------------------------------------------------- #
|
||||
def _split_frontmatter(text: str):
|
||||
"""Separa el bloque frontmatter YAML inicial del cuerpo.
|
||||
|
||||
Devuelve ``(fm_text|None, body)``. Si el archivo no empieza con una valla
|
||||
``---`` o no se cierra, no hay frontmatter y el cuerpo es el texto entero.
|
||||
"""
|
||||
if text.startswith(""):
|
||||
text = text.lstrip("")
|
||||
lines = text.split("\n")
|
||||
if not lines or lines[0].strip() != "---":
|
||||
return None, text
|
||||
for i in range(1, len(lines)):
|
||||
if lines[i].strip() == "---":
|
||||
return "\n".join(lines[1:i]), "\n".join(lines[i + 1:])
|
||||
# Valla de apertura sin cierre: tratar todo como cuerpo.
|
||||
return None, text
|
||||
|
||||
|
||||
def _parse_frontmatter(fm_text) -> dict:
|
||||
"""Parsea el frontmatter. Intenta YAML; si no, parser line-based simple."""
|
||||
if not fm_text:
|
||||
return {}
|
||||
try:
|
||||
import yaml # type: ignore
|
||||
data = yaml.safe_load(fm_text)
|
||||
if isinstance(data, dict):
|
||||
return data
|
||||
except Exception: # noqa: BLE001 — yaml ausente o frontmatter inválido.
|
||||
pass
|
||||
# Fallback degradado: 'clave: valor' por línea.
|
||||
out: dict = {}
|
||||
for line in fm_text.split("\n"):
|
||||
stripped = line.strip()
|
||||
if not stripped or stripped.startswith("#") or ":" not in stripped:
|
||||
continue
|
||||
k, _, v = stripped.partition(":")
|
||||
k = k.strip()
|
||||
v = v.strip().strip('"').strip("'")
|
||||
if k:
|
||||
out[k] = v
|
||||
return out
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Portada
|
||||
# --------------------------------------------------------------------------- #
|
||||
def _portada_markdown(authors, date_raw, abstract) -> str:
|
||||
"""Markdown de la portada: autores, fecha y, si hay, el abstract."""
|
||||
parts: list = []
|
||||
authors_str = _fmt_authors(authors)
|
||||
if authors_str:
|
||||
parts.append(f"**Autores:** {authors_str}")
|
||||
if date_raw not in (None, ""):
|
||||
parts.append(f"**Fecha:** {_fmt_date(date_raw)}")
|
||||
md = "\n\n".join(parts)
|
||||
abstract = _safe_str(abstract).strip()
|
||||
if abstract:
|
||||
md = (md + "\n\n" if md else "") + "## Abstract\n\n" + abstract
|
||||
return md
|
||||
|
||||
|
||||
def _fmt_authors(authors) -> str:
|
||||
"""Lista o string de autores → string separado por comas."""
|
||||
if authors in (None, ""):
|
||||
return ""
|
||||
if isinstance(authors, (list, tuple)):
|
||||
return ", ".join(_safe_str(a).strip() for a in authors
|
||||
if _safe_str(a).strip())
|
||||
return _safe_str(authors).strip()
|
||||
|
||||
|
||||
def _fmt_date(raw) -> str:
|
||||
"""Fecha → ``DD/MM/AAAA`` si es parseable; si no, el valor crudo."""
|
||||
if isinstance(raw, _dt.datetime):
|
||||
return raw.strftime("%d/%m/%Y")
|
||||
if isinstance(raw, _dt.date):
|
||||
return raw.strftime("%d/%m/%Y")
|
||||
s = _safe_str(raw).strip()
|
||||
if not s:
|
||||
return s
|
||||
for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%d/%m/%Y", "%d-%m-%Y"):
|
||||
try:
|
||||
return _dt.datetime.strptime(s, fmt).strftime("%d/%m/%Y")
|
||||
except ValueError:
|
||||
continue
|
||||
try:
|
||||
return _dt.datetime.fromisoformat(s).strftime("%d/%m/%Y")
|
||||
except Exception: # noqa: BLE001
|
||||
return s
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Cuerpo y figuras
|
||||
# --------------------------------------------------------------------------- #
|
||||
def _split_body_sections(body: str):
|
||||
"""Divide el cuerpo en (preámbulo, [(título_H1, contenido)...]) por H1."""
|
||||
preamble_lines: list = []
|
||||
sections: list = []
|
||||
current = None # (titulo, [lineas])
|
||||
for line in body.split("\n"):
|
||||
m = _H1_LINE.match(line)
|
||||
if m and not line.startswith("##"):
|
||||
if current is not None:
|
||||
sections.append((current[0], "\n".join(current[1])))
|
||||
current = (m.group(1).strip(), [])
|
||||
elif current is None:
|
||||
preamble_lines.append(line)
|
||||
else:
|
||||
current[1].append(line)
|
||||
if current is not None:
|
||||
sections.append((current[0], "\n".join(current[1])))
|
||||
return "\n".join(preamble_lines), sections
|
||||
|
||||
|
||||
def _markdown_to_blocks(text: str, base_dir: str) -> list:
|
||||
"""Parte un Markdown en bloques Markdown/Image alrededor de cada figura.
|
||||
|
||||
Las líneas ```` con ``src`` local se convierten en ``Image``; las
|
||||
que apuntan a URLs http(s) se dejan como texto Markdown.
|
||||
"""
|
||||
blocks: list = []
|
||||
buf: list = []
|
||||
|
||||
def _flush():
|
||||
chunk = "\n".join(buf).strip("\n")
|
||||
if chunk.strip():
|
||||
blocks.append(Markdown(text=chunk))
|
||||
buf.clear()
|
||||
|
||||
for line in text.split("\n"):
|
||||
m = _IMG_LINE.match(line)
|
||||
if m:
|
||||
alt, src = m.group(1), m.group(2)
|
||||
if src.lower().startswith(("http://", "https://")):
|
||||
buf.append(line) # URL remota: se mantiene como texto.
|
||||
continue
|
||||
_flush()
|
||||
blocks.append(Image(path=_resolve_src(src, base_dir),
|
||||
caption=(alt or None)))
|
||||
else:
|
||||
buf.append(line)
|
||||
_flush()
|
||||
return blocks
|
||||
|
||||
|
||||
def _resolve_src(src: str, base_dir: str) -> str:
|
||||
"""Resuelve la ruta de una figura relativa al paper.
|
||||
|
||||
Absoluta → tal cual. Relativa → prueba ``base_dir/src`` y
|
||||
``base_dir/figures/<basename>``; usa la primera que exista, o el join con
|
||||
``base_dir`` si ninguna (el motor degrada dibujando el aviso de no-encontrada).
|
||||
"""
|
||||
if os.path.isabs(src):
|
||||
return src
|
||||
cand1 = os.path.join(base_dir, src)
|
||||
cand2 = os.path.join(base_dir, "figures", os.path.basename(src))
|
||||
for c in (cand1, cand2):
|
||||
if os.path.exists(c):
|
||||
return c
|
||||
return cand1
|
||||
|
||||
|
||||
def _slugify(text: str) -> str:
|
||||
"""Slug ASCII corto para el id del capítulo."""
|
||||
s = re.sub(r"[^a-z0-9]+", "_", _safe_str(text).lower()).strip("_")
|
||||
return s[:40]
|
||||
|
||||
|
||||
def _safe_str(v) -> str:
|
||||
"""str() que nunca lanza y mapea None a ''."""
|
||||
if v is None:
|
||||
return ""
|
||||
try:
|
||||
return str(v)
|
||||
except Exception: # noqa: BLE001
|
||||
return ""
|
||||
@@ -1,118 +0,0 @@
|
||||
"""Tests para render_paper_pdf — DoD: golden + edges + error path.
|
||||
|
||||
Autocontenido y sin red: escribe papers Markdown sintéticos en directorios
|
||||
temporales y verifica que el PDF se genera (estado, nº de páginas, archivo
|
||||
no vacío) reutilizando el motor de paginación de ``automatic_eda``.
|
||||
"""
|
||||
|
||||
import os
|
||||
import tempfile
|
||||
|
||||
from datascience.render_paper_pdf import render_paper_pdf
|
||||
|
||||
|
||||
_GOLDEN_PAPER = """---
|
||||
title: A Minimal IMRaD Paper
|
||||
authors:
|
||||
- Ada Lovelace
|
||||
- Alan Turing
|
||||
date: 2026-06-30
|
||||
abstract: >
|
||||
Demostramos que el motor de paginación rinde un paper IMRaD completo en PDF
|
||||
móvil sin cortar texto ni tablas.
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
Este es el cuerpo de la introducción con **texto en negrita** y una lista:
|
||||
|
||||
- Primer punto.
|
||||
- Segundo punto.
|
||||
|
||||
# Methods
|
||||
|
||||
Resultados resumidos en una tabla pipe:
|
||||
|
||||
| Métrica | Valor |
|
||||
| --- | --- |
|
||||
| Precisión | 0.91 |
|
||||
| Recall | 0.88 |
|
||||
|
||||
Texto final de la sección de métodos.
|
||||
"""
|
||||
|
||||
|
||||
def test_golden_genera_pdf_con_portada_y_secciones(tmp_path):
|
||||
"""Golden: paper IMRaD con frontmatter + 2 secciones + tabla → PDF válido."""
|
||||
paper_dir = tmp_path / "zz-demo"
|
||||
paper_dir.mkdir()
|
||||
(paper_dir / "paper.md").write_text(_GOLDEN_PAPER, encoding="utf-8")
|
||||
|
||||
res = render_paper_pdf(str(paper_dir))
|
||||
|
||||
assert res["status"] == "ok", res
|
||||
assert res["n_pages"] >= 1
|
||||
pdf_path = res["pdf_path"]
|
||||
assert pdf_path is not None
|
||||
assert os.path.exists(pdf_path)
|
||||
assert os.path.getsize(pdf_path) > 0
|
||||
|
||||
|
||||
def test_edge_sin_frontmatter_ni_figuras(tmp_path):
|
||||
"""Edge 1: cuerpo plano sin frontmatter ni figuras → genera PDF igual."""
|
||||
paper_dir = tmp_path / "plano"
|
||||
paper_dir.mkdir()
|
||||
(paper_dir / "paper.md").write_text(
|
||||
"Solo un cuerpo plano, sin frontmatter ni encabezados de nivel 1.\n"
|
||||
"Un par de líneas de texto corrido para que el motor lo pagine.\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
res = render_paper_pdf(str(paper_dir))
|
||||
|
||||
assert res["status"] == "ok", res
|
||||
assert res["n_pages"] >= 1
|
||||
assert os.path.exists(res["pdf_path"])
|
||||
|
||||
|
||||
def test_edge_path_inexistente_no_revienta():
|
||||
"""Edge 2: directorio inexistente → status error, sin crash, pdf_path None."""
|
||||
res = render_paper_pdf("/tmp/no_existe_xyz_123")
|
||||
|
||||
assert res["status"] == "error"
|
||||
assert res["pdf_path"] is None
|
||||
assert res["n_pages"] == 0
|
||||
assert "no encontrado" in (res["note"] or "")
|
||||
|
||||
|
||||
def test_edge_figura_inexistente_degrada(tmp_path):
|
||||
"""Edge 3: referencia a figura inexistente → el PDF se genera igual."""
|
||||
paper_dir = tmp_path / "con-figura"
|
||||
paper_dir.mkdir()
|
||||
(paper_dir / "paper.md").write_text(
|
||||
"---\n"
|
||||
"title: Paper Con Figura Rota\n"
|
||||
"---\n\n"
|
||||
"# Results\n\n"
|
||||
"Texto antes de la figura.\n\n"
|
||||
"\n\n"
|
||||
"Texto después de la figura.\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
res = render_paper_pdf(str(paper_dir))
|
||||
|
||||
assert res["status"] == "ok", res
|
||||
assert res["n_pages"] >= 1
|
||||
assert os.path.exists(res["pdf_path"])
|
||||
|
||||
|
||||
def test_acepta_ruta_directa_al_md(tmp_path):
|
||||
"""Acepta también la ruta directa a un paper.md (no solo el directorio)."""
|
||||
md = tmp_path / "paper.md"
|
||||
md.write_text("# Discussion\n\nCuerpo de la discusión.\n", encoding="utf-8")
|
||||
|
||||
res = render_paper_pdf(str(md))
|
||||
|
||||
assert res["status"] == "ok", res
|
||||
assert os.path.exists(res["pdf_path"])
|
||||
Reference in New Issue
Block a user