diagrama-mecanismo-bio-vía
Una figura de vía es una declaración de mecanismo que los lectores impugnarán una flecha a la vez. Contrato de esta habilidad: cada entidad y cada arista en el lienzo se remonta a una cita textual con una localización; la semántica de interacción (activación / inhibición / unión / modificación / transporte) es visualmente distinta y nunca se mezcla; cualquier cosa que la fuente no indique (dirección, localización, números) se marca visiblemente como no declarada, no adivinada. Los entregables son un SVG editable, por capas y direccionable por ID, más exportaciones PNG/PDF y un result.json completo del contrato.
Cuándo usar / cuándo no
Usar para: figuras de mecanismos, diagramas de vías de señalización, cascadas receptor-núcleo, diafonía de vías, tareas de "dibujar la Figura N de este artículo" y ediciones de una figura de vía existente (agregar/eliminar entidad o arista, volver a etiquetar). No para: gráficos estadísticos (barras/caja/volcán), esquemas experimentales o retoques solo estéticos; esos pertenecen a habilidades adyacentes.
Contrato de ejecución (entorno de ejecución de la plataforma)
- Entrada:
/input/case.json(+ task.md). Trabajar bajo/app/work; entregables bajo/app/output. - Primera acción de toda la ejecución (antes de leer el caso en profundidad):
python scripts/scaffold_result.py --input /input/case.json --outdir /app/outputEsto escribe un result.json con cada campo del contrato de salida presente, los no producidos con null + motivo. Manténgalo actualizado paso a paso; nunca elimine un campo del contrato. - Todos los scripts siguientes toman rutas de estilo
--model/--svgy son Python 3 puro (solo stdlib) a menos que se indique.references/es leído por los scripts; lea los archivos.mdusted mismo antes del Paso 1.
Paso 0 - Leer el contrato y preparar el andamio (1 solicitud)
Ejecute el andamio. Hojeé task.md + case.json: identifique el objetivo de la figura (qué mecanismo, qué figura si se reproduce una, escenario de generar vs editar), los formatos de exportación requeridos y el alcance de la evidencia. Registre la lista de campos del contrato que debe completar. Conciencia de presupuesto: apunte a terminar en 5-8 pasos del modelo; los scripts hacen el trabajo pesado, usted hace la ciencia.
Paso 1 - Extraer el modelo del mecanismo (el núcleo científico - hágalo usted mismo)
Lea el material real (analice el PDF de verdad; lea archivos, nunca asuma contenido a partir de etiquetas). Construya /app/work/model.json según references/layout-conventions.md por su PROPIO criterio:
- Entidades — gen / proteína / receptor / ARN / complejo / molécula / célula / familia. Aplique
references/naming-rules.md: símbolos de genes en cursiva y nodos de genes distintos de sus proteínas (MYC vs MYC); símbolos preferidos con ortografías de la fuente en sinónimos; familias vs miembros; un nodo por complejo indicado. Cada entidad llevasource: {loc, quote}— una cita TEXTUAL y una localización suficientemente precisa para reencontrarla (sección/párrafo/página/leyenda de figura). - Aristas — tipo del conjunto cerrado en
references/edge-types.json(activación, inhibición, unión, fosforilación, ubiquitinación, regulación transcripcional, translocación, formación de complejo, ...).directeddebe establecerse explícitamente. Nunca adivine la dirección: si la cita no tiene señal direccional, establezcadirected: falsey registre una incertidumbre (references/uncertainty-policy.md). La unión/reclutamiento no tiene dirección. La regulación transcripcional tiene como objetivo un nodo de gen y necesita un signo. - Compartimentos — extracelular / membrana / citoplasma / núcleo (+ RE, Golgi, subregiones de orgánulos si el mecanismo los necesita). Las entidades cuya localización no está indicada van a la banda
unspecified— nunca silenciosamente al citoplasma. Los receptores se anclan en la banda de membrana. - Orden — establezca
ordersegún la posición en la vía (orden topológico, no orden de texto); los bucles de retroalimentación surgen naturalmente como aristas hacia atrás. - Números en el lienzo (expresión, significancia) solo si existen textualmente en la fuente; de lo contrario, deje los mapeos de datos como nulos explícitos.
Orden práctico de extracción: lea una vez para el flujo general; segunda pasada oración por oración para entidades + citas; tercera pasada para aristas, incluidos inhibidores, retroalimentación y diafonía (se esconden en oraciones con "sin embargo/mientras que").
Paso 2 - Validar el modelo (script)
python scripts/validate_model.py --model /app/work/model.json \
--report /app/work/validation-report.json
Corrija cada error E-*. E-DIR-01 (arista dirigida sin señal direccional) es la protección científica central: o cite una oración que indique dirección o reduzca a no dirigida + incertidumbre. Las advertencias requieren una decisión consciente: nodos de familia, ubicación del receptor, desajustes signo-vs-cita. Vuelva a ejecutar hasta que sea válido. Si el material no puede respaldar un elemento requerido del contrato, anótelo ahora (se convierte en un null + motivo en el Paso 5).
Paso 3 - Renderizar SVG y exportar (scripts)
python scripts/render_svg.py --model /app/work/model.json \
--out /app/output/pathway.svg --report /app/work/render-report.json
python scripts/export_assets.py --svg /app/output/pathway.svg \
--outdir /app/output --model /app/work/model.json \
--png-width 2400 --report /app/work/export-report.json
Lea las advertencias del informe de renderizado (límites del lienzo, compartimentos desconocidos). Mire el PNG usted mismo; si el diseño oscurece el mecanismo (cruce de aristas que oculta una bifurcación, retroalimentación sobre la cascada), ajuste order/posiciones de anclaje en el modelo y vuelva a renderizar. El SVG es determinista: modelo idéntico → SVG idéntico.
Paso 4 - Escenarios de edición (si el caso solicita ediciones de una figura existente)
Reconstruya primero el modelo de la figura objetivo (Paso 1 sobre el texto fuente de la figura original), luego use ediciones que preserven la fuente — el modelo/SVG original se respalda, cada edición se registra en el change_log del modelo:
python scripts/apply_edit.py --model /app/work/model.json --op add-edge \
--id e-new --src A --tgt B --type inhibition --directed true \
--sign negative --loc "..." --quote "..."
Operaciones: agregar/renombrar/eliminar entidad (eliminar se niega cuando hay aristas adjuntas a menos que --cascade, y las eliminaciones en cascada se registran como incertidumbres), agregar/eliminar arista, agregar compartimento. Cada entidad/arista agregada REQUIERE --loc + --quote textual. Después de las ediciones, revalide (automático) y vuelva a renderizar (Paso 3).
Paso 5 - Verificar y finalizar result.json (script + usted)
python scripts/verify_outputs.py --model /app/work/model.json \
--svg /app/output/pathway.svg --result /app/output/result.json \
--exports /app/output/pathway.png /app/output/pathway.pdf \
--report /app/output/verification-report.json
Esto relee el SVG y verifica la relectura de nodos/aristas, la consistencia leyenda↔uso en ambas direcciones, el desbordamiento de etiquetas, los límites del lienzo, la existencia de exportaciones y que cada nulo en result.json tenga un motivo. Luego finalice usted mismo result.json: complete los campos del contrato (rutas de editable_source, exportaciones con backend/parámetros, entity_table/edge_table con citas, legend_basis, fuentes con versiones, incertidumbres, resumen de verificación, estado honesto). Mantenga _unanswered_reasons para cualquier cosa nula. La entrega parcial debe indicar sus límites en palabras claras.
Manejo de excepciones (rutas reales, no decoración)
| Falla | Detección | Acción |
|---|---|---|
| PDF ilegible / sin capa de texto | el análisis falla o texto vacío | pdf-render-tool / ocr-tool para el renderizado, marcar "capa de texto ausente" en result.json |
| Nombre de entidad ambiguo (dos lecturas) | su extracción | elegir según contexto, registrar alternativa + incertidumbre; si no se puede decidir, null + motivo |
| Dirección no indicada | E-DIR-01 | degradar a arista no dirigida (sin punta de flecha) + incertidumbre. NUNCA adivinar |
| Compartimento desconocido | E-CMP-01 / advertencia de diseño | banda unspecified + nota |
| Faltan datos numéricos para visuales codificadas por datos | el modelo no tiene números textuales | dibujar topología, marcar mapeo null + "datos ausentes de la fuente" |
| Desbordamiento de etiqueta | verificar label_overflow | acortar etiqueta / dividir en label+sub / reordenar |
| Lienzo excede límites | advertencia de renderizado | dividir en paneles o reducir ramas; anotarlo |
| Falta backend de exportación | estado del informe de exportación fallido | cadena de respaldo ya intentada; entregar SVG, registrar falla + guía en result.json |
| PNG en blanco/degenerado | blank_check | investigar informe de renderizado; volver a renderizar; registrar |
| Persisten errores de validación | código de salida 2 | corregir modelo; si no se puede corregir a partir del material, entregar el subconjunto válido + límites explícitos |
Barra de calidad (autoverificación antes de finalizar)
- ¿Podría un revisor señalar cualquier flecha y obtener su justificación textual de la tabla/modelo incrustados? (trazabilidad)
- ¿Son visualmente distintas activación/inhibición/unión/modificación, y coincide la leyenda con lo dibujado — sin entradas faltantes ni fantasma?
- ¿Está todo lo no indicado visiblemente no indicado (no dirigido, banda unspecified, null + motivo)?
- ¿Puede alguien abrir el SVG, cambiar una etiqueta y reexportar? (por capas, direccionable por ID, pila de fuentes estándar)
- ¿Cubre result.json cada campo del contrato con estado honesto?
Archivos
scripts/scaffold_result.py- result.json completo del contrato con null+motivoscripts/validate_model.py- esquema + verificación de evidencia de dirección + nomenclaturascripts/render_svg.py- SVG determinista por capas a partir de model.jsonscripts/export_assets.py- PNG/PDF con cadena de respaldo + verificación de blancoscripts/apply_edit.py- ediciones registradas que preservan la fuentescripts/verify_outputs.py- verificación de relectura del paquetereferences/edge-types.json- semántica de símbolos legible por máquinareferences/symbol-semantics.md- gramática visual y su razonamientoreferences/naming-rules.md- convenciones para genes/proteínas/familias/complejosreferences/uncertainty-policy.md- reglas de degradación; política de nunca adivinarreferences/layout-conventions.md- esquema model.json + algoritmo de diseñoexamples/ras-mapk-case/- un ejemplo práctico con material real (Brown & Ried 2022)README.md- documentación de uso independiente