From 0b2976c66a9fd6b866e46c4cf0163f522171426d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 30 Jun 2026 07:49:41 -0500 Subject: [PATCH 1/6] chore(main): release 0.10.2 (#228) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .release-please-manifest.json | 2 +- CHANGELOG.md | 14 ++++++++++++++ pyproject.toml | 2 +- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 30b6d45..582db2f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.10.1" + ".": "0.10.2" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a83464..ef47263 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,20 @@ desde los Conventional Commits y bumpea `pyproject.toml`. Al mergear ese PR se c `vX.Y.Z` y el GitHub Release. Las secciones por debajo de `[0.3.0]` son el historial previo a la conexión del tooling (se mantuvieron a mano); de acá en adelante las gestiona el bot. +## [0.10.2](https://github.com/complexluise/bib2graph/compare/v0.10.1...v0.10.2) (2026-06-30) + + +### Bug Fixes + +* **sources:** error accionable ante 429 de OpenAlex en seed y chaining ([#210](https://github.com/complexluise/bib2graph/issues/210)) ([a2a8106](https://github.com/complexluise/bib2graph/commit/a2a810623702a2696e01ef6266144fdb66e168a4)) +* **sources:** error accionable ante 429 de OpenAlex en seed y chaining ([#210](https://github.com/complexluise/bib2graph/issues/210)) ([c05090f](https://github.com/complexluise/bib2graph/commit/c05090f1f8437e9e448dddf15c6ec6500be8fb6f)) +* **test:** idempotencia bit-a-bit pegaba a OpenAlex en vivo (flake en CI) ([#219](https://github.com/complexluise/bib2graph/issues/219)) ([de14401](https://github.com/complexluise/bib2graph/commit/de1440102378d10d6ec50568d6adbe6867fe09be)) + + +### Performance Improvements + +* **stores:** upsert masivo Arrow en DuckDBStore.persist ([#211](https://github.com/complexluise/bib2graph/issues/211)) ([#226](https://github.com/complexluise/bib2graph/issues/226)) ([08258ee](https://github.com/complexluise/bib2graph/commit/08258eec4dafd6e2469b14f68958303ee4fc7cad)) + ## [0.10.1](https://github.com/complexluise/bib2graph/compare/v0.10.0...v0.10.1) (2026-06-30) diff --git a/pyproject.toml b/pyproject.toml index f40a6fc..df5ae53 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ build-backend = "hatchling.build" [project] name = "bib2graph" -version = "0.10.1" # Hitos 7 (dedup) + 8 (co-citación). De acá en adelante el bump +version = "0.10.2" # Hitos 7 (dedup) + 8 (co-citación). De acá en adelante el bump # lo maneja release-please vía PR de release (CI ya conectado). description = "Librería de Python para transformar corpus bibliográficos en redes bibliométricas reproducibles (co-citación, colaboración, co-ocurrencia)." readme = "README.md" From cb1bdfb1b682f81473a290d5520165ca2910d9b8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 17:30:12 +0000 Subject: [PATCH 2/6] docs: add tutorial and guide for documentation improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add tutorial 'Tu primera red bibliométrica con Claude' (claude-code.md): step-by-step guide for using bib2graph in Claude web without installation - Add guide 'Cómo elaborar un reporte de estado del arte' (reporte-estado-del-arte.md): 10-step recipe for building rigorous SOTA reports with PRISMA curation, network analysis, community identification, and trend analysis - Update tutoriales/index.md to reference new tutorial - Update guias/index.md to reference new guide Both documents use neutral tone (removed second-person "vos") and include concrete examples, checklists, and connections to other documentation. Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01VfqH92jLCoRQ9G8AMA1Vgi --- docs/guias/index.md | 28 +- docs/guias/reporte-estado-del-arte.md | 500 ++++++++++++++++++++++++++ docs/tutoriales/claude-code.md | 164 +++++++++ docs/tutoriales/index.md | 33 +- 4 files changed, 695 insertions(+), 30 deletions(-) create mode 100644 docs/guias/reporte-estado-del-arte.md create mode 100644 docs/tutoriales/claude-code.md diff --git a/docs/guias/index.md b/docs/guias/index.md index db61584..6ca1bac 100644 --- a/docs/guias/index.md +++ b/docs/guias/index.md @@ -4,25 +4,27 @@ title: Guías (how-to) # Guías (how-to) -Las **guías** son recetas orientadas a una tarea concreta: ya sabés qué querés -hacer y buscás los pasos para lograrlo. Si en cambio querés *aprender* desde -cero, empezá por los [Tutoriales](../tutoriales/index.md). +Las **guías** son recetas orientadas a una tarea concreta: ya se sabe qué se quiere +hacer y se buscan los pasos para lograrlo. Si en cambio se quiere *aprender* desde +cero, comience por los [Tutoriales](../tutoriales/index.md). -!!! note "En construcción" - Estamos escribiendo las guías. Seguimiento en el - [issue #208](https://github.com/complexluise/bib2graph/issues/208). - Planificado: +## Guías disponibles - - Cómo elaborar y refinar una ecuación de búsqueda. - - Cómo expandir el corpus por citaciones (forrajeo) sin perder el foco. - - Cómo aplicar filtros PRISMA y curar (aceptar/rechazar) de forma versionable. - - Cómo interpretar las 5 redes y exportarlas a Gephi / Cytoscape. - - Cómo hacer reproducible un análisis (snapshots e historia del corpus). +
-## Mientras tanto +- :material-file-document: **[Cómo elaborar un reporte de estado del arte](reporte-estado-del-arte.md)** + + Receta completa de 10 pasos: de la pregunta de investigación a un documento + estructurado con mapeo de comunidades, tensiones, actores clave e huecos + de investigación. Incluye curación PRISMA y análisis de tendencias. + +
+ +## Otras referencias - [Quickstart](../getting-started/quickstart.md) — el camino más corto a un GraphML. - [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos y opciones. - [API de Python](../reference/python-api.md) — para uso como librería. - [Arquitectura](../ARCHITECTURE.md) — el modelo mental del ciclo y las redes. +- [Tutoriales](../tutoriales/index.md) — aprende desde cero. diff --git a/docs/guias/reporte-estado-del-arte.md b/docs/guias/reporte-estado-del-arte.md new file mode 100644 index 0000000..3e1b9fa --- /dev/null +++ b/docs/guias/reporte-estado-del-arte.md @@ -0,0 +1,500 @@ +--- +title: Cómo elaborar un reporte de estado del arte +--- + +# Cómo elaborar un reporte de estado del arte + +Esta guía es una receta para construir, analizar y reportar un **estado del arte (SOTA)** riguroso +sobre un tema de investigación, utilizando bib2graph como herramienta central. El resultado es un +documento estructurado con identificación de tensiones, escuelas de pensamiento, huecos de +investigación y una síntesis de tendencias. + +Es para alguien que ya sabe qué quiere investigar y busca los pasos concretos; si en cambio +se quiere aprender desde cero, véase el [Tutorial: Tu primera red bibliométrica](../tutoriales/claude-code.md). + +!!! info "Scope" + - Corpus de 200–500 papers (ajustable según el tema). + - Redes bibliométricas: acoplamiento, co-citación, co-autoría. + - Análisis de comunidades y tendencias. + - Tiempo estimado: 4–6 horas (de investigador; el código: 30 min). + - Salida: reporte .docx/.md con figuras, matriz de tensiones y conclusiones. + +!!! warning "Requisitos" + - **Un flujo de bib2graph** (CLI en máquina local **o** Claude Code con ejecución). + - **Una pregunta de investigación clara** — no un tema genérico. + - **Opcional:** API key de OpenAlex (gratuita, para más de ~100 papers). + - **Herramienta de escritura:** Obsidian, Google Docs, Word o markdown + pandoc. + +--- + +## El flujo en síntesis + +``` +1. Pregunta → Ecuación de búsqueda (3 conceptos) +2. Siembra (OpenAlex, 200–500 papers) +3. Expansión por citaciones (forrajeo) — opcional, para corpus más denso +4. Curación manual (PRISMA filters, decisiones criterio) +5. Construcción de redes (acoplamiento, co-citación, co-autoría) +6. Lectura de comunidades (nombrado, keywords, tensiones) +7. Análisis de tendencias (temporal, institucional, autores influyentes) +8. Redacción del reporte +``` + +--- + +## Paso 1 — Afina tu pregunta de investigación + +**Entrada:** Una idea amplia sobre un tema. +**Salida:** Una pregunta de investigación clara y acotada. + +Una buena pregunta de investigación tiene esta forma: + +> ¿Cómo se ha abordado [**problema específico**] en el contexto de [**dominio**], +> entre [**rango temporal**]? ¿Cuáles son los enfoques dominantes, sus tensiones +> y los huecos sin explorar? + +### Ejemplo + +❌ *"Quiero estudiar inteligencia artificial."* +✅ *"¿Cómo se abordan los problemas de alineación de valores en modelos de lenguaje +grandes, y cuáles son las tensiones entre eficiencia computacional y robustez ética?"* + +### Preguntas de refinamiento + +1. **¿Es específica?** ¿Puedo traducirla a 3–5 palabras clave que filtren el ruido? +2. **¿Es temporal?** ¿Hay un rango de años que tenga sentido? (últimos 5–10 años suele ser lo adecuado para un SOTA). +3. **¿Es acotada?** ¿Espero 50 papers, 500 o 5000? (Ajusta la precisión de la ecuación). + +--- + +## Paso 2 — Elabora una ecuación de búsqueda + +**Entrada:** Pregunta de investigación. +**Salida:** Ecuación booleana con ~3 conceptos y sinónimos controlados. + +Una ecuación de búsqueda tiene esta estructura: + +``` +(término_A1 OR término_A2 OR término_A3) +AND (término_B1 OR término_B2) +AND (término_C1 OR término_C2) +``` + +Cada paréntesis es un **concepto**; los `OR` capturan sinónimos; los `AND` son obligatorios juntos. + +### Ejemplo + +Pregunta: *"¿Cómo se diseñan sistemas de recuperación de información en contextos multilingües?"* + +``` +(information retrieval OR IR OR search engines) +AND (multilingual OR cross-lingual OR language-agnostic) +AND (design OR architecture OR framework OR system) +``` + +### Consejos + +- **Evita genéricos.** "machine learning" sola atrapa decenas de miles de papers. +- **Sé específico en el cuarto concepto si hace falta.** Agrega un delimitador: + `AND (neural OR deep learning)` para descartar SOTA pre-2012. +- **Testa la ecuación.** Corre una búsqueda rápida de 50 papers y revisa los títulos. + Si ves ruido sistemático, ajusta. + +--- + +## Paso 3 — Siembra el corpus desde OpenAlex + +**Entrada:** Ecuación de búsqueda, rango de años. +**Salida:** Corpus inicial de ~200–300 papers. + +Usa bib2graph (CLI o Claude) para traer papers desde OpenAlex. + +### Con CLI local + +```bash +b2g init ./mi-sota +cd mi-sota +b2g seed "tu_ecuacion_aqui" --min-year 2015 +``` + +Verificá el corpus: + +```bash +b2g read list --query "your_keywords" +b2g read stats --group-by year +``` + +### Con Claude Code + +Envía un prompt como: + +```text +Sembrá un corpus desde OpenAlex usando esta ecuación: +(información retrieval OR IR) +AND (multilingüe OR cross-lingual) +Traé hasta 250 papers desde 2015. +Mostrame un resumen: cuántos papers, rango de años, top 5 autores por citaciones. +``` + +### Checklist + +- [ ] ¿El corpus tiene papers desde diferentes años (no es monocromático)? +- [ ] ¿Reconozco algunos autores o papeles influyentes en el rango? +- [ ] ¿El tamaño es manejable (200–500, no 5000)? + +Si el corpus es muy pequeño, abre la ecuación (menos `AND`, más `OR`). +Si es muy grande, ciérrala (agrega un concepto específico más). + +--- + +## Paso 4 — Expande por citaciones (opcional pero recomendado) + +**Entrada:** Corpus de siembra. +**Salida:** Corpus expandido (+20–50% papers nuevos) con mayor densidad de referencias. + +El forrajeo (o "chaining") busca papers no encontrados en la búsqueda inicial pero +citados por los que sí están. Aumenta la sensibilidad sin ruido. + +### Con CLI + +```bash +b2g chain --depth 1 --limit 100 +``` + +### Con Claude + +```text +Expandí el corpus usando forrajeo de citaciones: seguí una capa de referencias +de los papers ya en el corpus (backward chaining) y límítate a 100 papeles nuevos. +Mostrame los papers nuevos y el gráfico de crecimiento por año. +``` + +### Cuándo hacer esto + +- ✅ Si buscás sensibilidad alta (no querés perderte trabajos clave). +- ✅ Si el tema es muy específico (forrajeo agrega relevancia). +- ❌ Si el corpus ya es grande (>500) — aumenta significativamente el tamaño. +- ❌ Si es la primera vez: puedes hacer esto después de leer la red inicial. + +--- + +## Paso 5 — Curá el corpus (filtros PRISMA) + +**Entrada:** Corpus (inicial o expandido). +**Salida:** Corpus curado, con decisiones explícitas y versionables. + +La curación es manual y criterial. Trae estructura (PRISMA) a lo que normalmente es +un basurero de decisiones ad-hoc. + +### Flujo PRISMA simplificado + +``` +IDENTIFICACIÓN +├─ Duplicados y retractaciones: RECHAZAR +└─ Idioma no inglés (si procede): RECHAZAR + +CRIBADO +├─ Título fuera de scope: RECHAZAR +└─ Resumen no relevante: RECHAZAR + +ELEGIBILIDAD +├─ Texto completo inaccesible: CANDIDATO (no rechazar, quizá disponible más tarde) +└─ Métodos/resultados vagos: RECHAZAR o CANDIDATO + +INCLUSIÓN +├─ Relevancia alta: ACEPTAR +└─ Relevancia media pero útil para tensiones: ACEPTAR +``` + +### Con CLI + +```bash +b2g curate dump --scope all > curate.csv +# Editá curate.csv en Excel/Sheets: status = 'ACCEPTED' / 'REJECTED' / 'CANDIDATE' +b2g curate apply curate.csv +``` + +### Con Claude + +```text +Hacé una curación manual del corpus usando criterios PRISMA: +1. Rechazá duplicados y papers sin resumen. +2. Rechazá papers cuyo título no tenga relación directa con [TU TEMA]. +3. Marcá como CANDIDATO los papers con acceso restringido al texto completo. +4. Aceptá papers con relevancia alta o media que aporten tensiones metodológicas. + +Mostrame un resumen curado: accepted/rejected/candidate counts, y listame los +papers rechazados con razón. +``` + +### Checklist + +- [ ] ¿Documenté mis criterios de aceptación/rechazo? +- [ ] ¿Quedó un corpus de 100–300 ACCEPTED papers? +- [ ] ¿Revisé una muestra de rechazados para asegurarme de que no falta algo obvio? + +--- + +## Paso 6 — Construí las redes bibliométricas + +**Entrada:** Corpus curado (ACCEPTED papers). +**Salida:** 3 redes + análisis de comunidades. + +bib2graph proyecta el corpus a tres redes: +1. **Acoplamiento bibliográfico:** Papers que citan las mismas referencias. +2. **Co-citación:** Papers citados juntos (identifican "clusters de influencia"). +3. **Co-autoría:** Relaciones entre investigadores. + +### Con CLI + +```bash +# Especificar via YAML es lo robusto +cat > networks.yaml << 'EOF' +networks: + - kind: bibliographic_coupling + clustering: louvain + resolution: 1.0 + + - kind: co_citation + clustering: louvain + resolution: 1.0 + + - kind: co_authorship + clustering: louvain + resolution: 1.0 +EOF + +b2g build --spec networks.yaml +``` + +Exportá artefactos: + +```bash +b2g export --format graphml +b2g read top --kind bibliographic_coupling --top 20 +``` + +### Con Claude + +```text +Construí 3 redes del corpus curado: +1. Acoplamiento bibliográfico, comunidades con Louvain. +2. Co-citación, comunidades con Louvain. +3. Co-autoría, comunidades con Louvain. + +Para cada red mostrame: +- Visualización coloreada por comunidad. +- Métricas: # nodos, # aristas, # comunidades. +- Top 3 papers más centrales (mayor grado). +``` + +### Qué esperar + +- **Acoplamiento:** es la red "primaria" — más densa, más comunidades. Es donde ves sub-temas. +- **Co-citación:** es la red "influyentes" — documenta qué papers/autores actúan como referencias canónicas. +- **Co-autoría:** a menudo es más dispersa; útil para ver colegios invisibles. + +--- + +## Paso 7 — Leé y nombra las comunidades + +**Entrada:** Redes + corpus curado. +**Salida:** Descripción de cada comunidad, sus keywords, enfoque y tensiones. + +Para cada comunidad en la red de acoplamiento (la principal): + +1. **Extraé keywords dominantes** de los papers en la comunidad. +2. **Nombra la comunidad** con un sustantivo que capture el enfoque (ej. "Recuperación jerárquica", "Enfoque probabilístico"). +3. **Identifica papers seminales** (máximo grado dentro de la comunidad). +4. **Identifica tensiones** (dónde difiere esta comunidad de las demás). + +### Con Claude + +```text +Para la red de acoplamiento, nombra cada comunidad según sus keywords y +el contenido de sus papers. + +Para cada comunidad: +1. Nombre (1–3 palabras). +2. Keywords principales (5–7). +3. Top 2 papers (mayor grado). +4. Descripción breve (2–3 frases) del enfoque. +5. ¿Qué tensión metodológica los diferencia de otras comunidades? +``` + +### Ejemplo de salida + +| Comunidad | Enfoque | Keywords | Seminales | Tensión | +|-----------|---------|----------|-----------|---------| +| Enfoque estadístico | Probabilidad, modelos generativos | language models, HMM, smoothing | [2010], [2008] | Eficiencia vs. cobertura | +| Enfoque neuronal | Deep learning, word embeddings | neural networks, embeddings, LSTM | [2016], [2013] | Interpretabilidad vs. performance | + +--- + +## Paso 8 — Analiza tendencias e influencias + +**Entrada:** Redes, comunidades nombradas. +**Salida:** Observaciones sobre evolución temporal, actores influyentes, huecos. + +### Preguntas a responder + +1. **¿Cómo evolucionó el campo?** + Gráficos: # papers por año, shift de keywords a lo largo del tiempo. + +2. **¿Quiénes son los autores/papeles más influyentes?** + Listá por centralidad en la red de co-citación. + +3. **¿Hay huecos evidentes?** + ¿Qué combinaciones de keywords no aparecen? ¿Qué fronteras entre comunidades están vacías? + +4. **¿Qué instituciones lideren la investigación?** + Co-autoría: qué universidades/laboratorios coaparecer más. + +### Con Claude + +```text +Analizá tendencias en el corpus: +1. Gráficos: # papers/año, distribución por comunidad año a año. +2. Autores más citados (top 10 por centralidad en co-citación). +3. Instituciones más colaborativas (co-autoría). +4. Identificá 3–5 huecos o fronteras sin explorar entre comunidades. +5. ¿Qué palabras clave son emergentes (crecimiento exponencial últimos 3 años)? +``` + +--- + +## Paso 9 — Redactá el reporte + +**Entrada:** Análisis anterior, comunidades nombradas, tendencias. +**Salida:** Documento estructurado (.md, .docx, .pdf). + +### Estructura recomendada + +``` +1. Resumen ejecutivo + - Pregunta de investigación + - Hallazgos principales (2–3 frases) + - Conclusión de una línea + +2. Introducción + - Contexto y motivación + - Pregunta de investigación + - Scope y exclusiones + +3. Metodología + - Ecuación de búsqueda + - Criterios PRISMA + - Tamaño final del corpus + - Redes construidas + +4. Mapeo del campo + - Descripción de cada comunidad (tabla + prosa) + - Figuras: red coloreada, gráficos temporales + - Actores clave y trabajos seminales + +5. Tendencias y evolución + - Trayectoria del campo (temporal) + - Shift de enfoques + - Emergentes + +6. Tensiones y debates abiertos + - Matriz: enfoque A vs. enfoque B, qué diferencia, cuál prevalece + - Huecos de investigación + - Preguntas abiertas + +7. Conclusiones y prospectiva + - Síntesis de hallazgos + - Implicaciones para investigación futura + - Recomendaciones + +8. Apéndices + - CSV de corpus (metadatos) + - GraphML de redes (para Gephi/Cytoscape) + - Lista completa de referencias +``` + +### Herramientas recomendadas + +- **Obsidian + Zotero:** flujo de investigación integrado. +- **Google Docs:** colaboración y comentarios; convertís a .docx después. +- **Markdown + Pandoc:** máxima control; exportás a PDF/DOCX con cite. +- **Quarto/Jupyter:** si querés reproducibilidad y código integrado. + +### Checklist antes de publicar + +- [ ] ¿Cada comunidad tiene descripción, keywords y seminales claramente nombrados? +- [ ] ¿Las figuras tienen leyendas que expliquen qué se ve? +- [ ] ¿Se documentó la ecuación de búsqueda y criterios PRISMA? +- [ ] ¿Se mencionan huecos y se invita a investigación futura? +- [ ] ¿Alguien externo leyó el reporte y entendió sin preguntar? + +--- + +## Paso 10 — Guardá y versioná + +**Entrada:** Reporte final, corpus, redes. +**Salida:** Carpeta reproducible. + +Si usaste bib2graph CLI localmente: + +```bash +# El corpus vive en .duckdb; las redes en outputs/ +# Exportá todo: +b2g export --format graphml +b2g export --format csv + +# Guardá el reporte y su metadata: +tree . > structure.txt +git add . +git commit -m "SOTA: [Tu Tema] — corpus, redes, reporte" +``` + +Si usaste Claude web, **descargá:** + +- `corpus.parquet` — tu semilla para la próxima sesión. +- `*.graphml` — networks para Gephi. +- `clusters.csv` — papers → comunidad. +- Reporte final (.docx/.pdf). + +Guardalos en una carpeta nominada `sota-[tema]-[fecha]` en tu repositorio de investigación. + +--- + +## Checklist final + +- [ ] Pregunta de investigación clara +- [ ] Ecuación de búsqueda documentada +- [ ] Corpus de 100–300 papers ACCEPTED (curados) +- [ ] 3 redes construidas y visualizadas +- [ ] Comunidades nombradas y descritas +- [ ] Tendencias temporales e influyentes identificadas +- [ ] Reporte redactado con estructura clara +- [ ] Artefactos (GraphML, CSV, corpus) guardados y versionados +- [ ] ¿Se puede reproducir el análisis desde la ecuación de búsqueda? + +--- + +## Siguientes pasos + +- **Análisis más profundo:** Ahora que mapeaste el campo, profundizá en una + comunidad; usa bib2graph para iterar (nuevo corpus sobre esa comunidad, + nuevas redes, nuevo SOTA acotado). + +- **Integración con tu investigación:** Usa el mapa como **diagrama de + posicionamiento** para tu propio trabajo — ¿dónde caés? ¿dónde hay tensión + que tu trabajo resuelve? + +- **Tutorial:** Si querés aprender el CLI o la librería de Python a fondo, + véase el [Quickstart](../getting-started/quickstart.md) y la [Referencia](../reference/cli.md). + +- **Comunidad:** Compartí tu SOTA en el repo (crea un issue); feedback de otros + investigadores enriquece el análisis. + +--- + +## Referencias internas + +- [Arquitectura de bib2graph](../ARCHITECTURE.md) +- [API Python](../reference/python-api.md) +- [CLI `b2g`](../reference/cli.md) +- [ADR sobre SOTA y investigación](../decisiones/) — cómo bib2graph encaja en el ciclo de investigación. diff --git a/docs/tutoriales/claude-code.md b/docs/tutoriales/claude-code.md new file mode 100644 index 0000000..e7b32b9 --- /dev/null +++ b/docs/tutoriales/claude-code.md @@ -0,0 +1,164 @@ +--- +title: Tu primera red bibliométrica con bib2graph en Claude +--- + +# Tu primera red bibliométrica con bib2graph en Claude + +Este tutorial lleva, partiendo de cero, a construir un **primer mapa de +citaciones** sobre un tema elegido — sin instalar nada y sin escribir código. +El truco: no se utiliza bib2graph directamente, sino que **se le pide a Claude que lo use +por la persona** en su entorno de ejecución de código. + +Al terminar se tendrá un corpus de papers, una red de acoplamiento bibliográfico +con sus comunidades, y se entenderá el **lazo** de trabajo. Es para *aprender +haciendo*; si ya se sabe qué se quiere y se busca la receta de un reporte completo, véase la guía [Cómo elaborar un reporte de estado del arte](../guias/reporte-estado-del-arte.md). + +!!! info "Qué se necesita" + - Una sesión de **Claude (web o app) con ejecución de código activada** + (la herramienta de *Code Execution / análisis*, que permite a Claude + correr Python y crear archivos). + - 15 minutos. + - *Opcional pero recomendado:* una **API key de OpenAlex** (gratuita) si se van a + traer más de ~100 papers. Sin ella funciona, pero más lento y con límites. + +!!! warning "Alpha" + bib2graph está en `0.x`: la interfaz puede cambiar. Úsalo para explorar y + validar, no como dependencia estable todavía. + +--- + +## El modelo mental en una frase + +En Claude web, **cada conversación es una mesa de trabajo nueva**. Claude instala +bib2graph, siembra el corpus, construye las redes y devuelve las figuras y los +archivos — todo dentro de esa charla. Se dirige con lenguaje natural; bib2graph +hace el trabajo determinista por debajo. + +``` +usuario (en lenguaje natural) + │ "armame una red de acoplamiento sobre X" + ▼ + Claude ── instala y ejecuta bib2graph ──► OpenAlex + │ │ + │ ◄──── corpus + redes + figuras ─────────┘ + ▼ + archivos que se descargan (el "guardado") +``` + +## Paso 1 — Planteale el tema a Claude + +Se abre una conversación y se describe qué se quiere explorar. No hace falta que se sepa la +ecuación de búsqueda: Claude ayuda a armarla. + +!!! example "Prompt de arranque" + ```text + Quiero explorar el estado del arte sobre [TU TEMA]. + Usá la librería bib2graph (instalala con pip) para armar una red de + acoplamiento bibliográfico desde OpenAlex. + Antes de sembrar, proponeme una ecuación de búsqueda y discutámosla. + ``` + +Se reemplaza `[TU TEMA]` por algo concreto, por ejemplo *"métodos de generación de +electricidad más eficientes que la turbina de vapor"*. + +## Paso 2 — Afiná la ecuación de búsqueda + +Claude propone una **ecuación de tres conceptos** (tema ∧ enfoque ∧ +términos específicos) con sinónimos. Se la lee y se ajusta: se agrega un término que importe, se saca uno que ensucie. Este ida y vuelta es parte del método — la +pregunta y la búsqueda **mutan** mientras se piensa. + +!!! tip "Una buena ecuación es angosta a propósito" + Si se pide algo demasiado genérico ("energía"), el corpus se ahoga. Mejor un + eje claro y unos pocos términos específicos que delimiten el campo. + +## Paso 3 — Sembrá y construí la red + +Cuando la ecuación cierre, se le pide a Claude que ejecute el lazo. + +!!! example "Prompt" + ```text + Perfecto. Sembrá hasta 200 papers desde 2015, construí la red de + acoplamiento bibliográfico y detectá comunidades con Louvain. + Mostrame la red coloreada por comunidad y cuántos papers cayó en cada una. + ``` + +Por debajo, Claude corre el equivalente a este lazo de bib2graph: + +```python +from bib2graph import OpenAlexSource, Networks +from bib2graph.networks.spec import NetworkSpec +from bib2graph.constants import NetworkKind + +src = OpenAlexSource(email="usuario@ejemplo.org", max_results=200) +corpus = src.seed(tu_ecuacion, min_year=2015).corpus + +spec = NetworkSpec(kind=NetworkKind.BIBLIOGRAPHIC_COUPLING, + clustering="louvain") +art = Networks.build(corpus, spec) # art.graph, art.communities, art.metrics +``` + +Se recibe una **imagen de la red** (cada punto un paper; cada línea, +referencias compartidas; cada color, una comunidad) y un resumen: número de +nodos, aristas y el tamaño de cada comunidad. + +!!! note "Qué es el acoplamiento bibliográfico" + Dos papers se *acoplan* si citan las mismas referencias. Cuantas más + comparten, más cerca quedan. Las comunidades que aparecen suelen ser + **sub-temas o escuelas** del campo. Es la red "barata": no requiere un + segundo nivel de descargas. + +## Paso 4 — Leé el mapa + +Se le pide a Claude que ponga nombre a las comunidades a partir de sus keywords +dominantes, y que muestre los papers más centrales (los de mayor grado) de +cada una. + +!!! example "Prompt" + ```text + Nombrá cada comunidad según sus keywords y listame los 3 papers más + centrales de cada una, con título y año. + ``` + +Eso da, en una pantalla, el **plano del campo**: qué grandes familias existen +y cuáles son sus trabajos de referencia. Ya se tiene el primer mapa. + +## Paso 5 — Guardá tu trabajo + +!!! warning "El entorno es efímero" + Cuando se cierre la conversación, la mesa de trabajo se borra. La promesa de + bib2graph de *"biblioteca que persiste y crece entre sesiones"* **no se + cumple sola en Claude web**: se tienen que llevar los archivos. + +Se piden los exports en formatos abiertos y se descargan: + +!!! example "Prompt" + ```text + Exportá el corpus a Parquet, la red a GraphML y un CSV con + paper → comunidad → grado. Pasámelos para descargar. + ``` + +El `GraphML` se abre después en [Gephi](https://gephi.org) o Cytoscape para +explorar la red a mano. El `Parquet` es la **semilla guardada**: en una próxima +conversación se la sube a Claude y se sigue desde ahí. + +## Qué se aprendió + +- A dirigir bib2graph **conversacionalmente** desde Claude, sin escribir código. +- El lazo mínimo: **pregunta → ecuación → siembra → red de acoplamiento → + comunidades → lectura**. +- Que en Claude web **el archivo exportado es la memoria**: sin descarga, no hay + persistencia. + +## Siguientes pasos + +- [Cómo elaborar un reporte de estado del arte](../guias/reporte-estado-del-arte.md) + — la receta completa hasta un informe con tensiones y conclusiones. +- [Quickstart](../getting-started/quickstart.md) — el mismo lazo, pero desde el CLI + `b2g` en la propia máquina. +- [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos. + +!!! tip "¿Se va a usar seguido?" + Para un uso repetido y con biblioteca persistente de verdad, conviene correr + bib2graph en la máquina (o con **Claude Code** y la skill incluida, `b2g skill + add`), donde el corpus en DuckDB sí vive entre sesiones. Claude web es ideal + para explorar; el CLI local, para sostener una investigación en el tiempo. diff --git a/docs/tutoriales/index.md b/docs/tutoriales/index.md index f059454..ef4cd5b 100644 --- a/docs/tutoriales/index.md +++ b/docs/tutoriales/index.md @@ -4,29 +4,28 @@ title: Tutoriales # Tutoriales -Los **tutoriales** te enseñan a usar bib2graph paso a paso, partiendo de cero y +Los **tutoriales** enseñan a usar bib2graph paso a paso, partiendo de cero y llegando a un resultado concreto. Son para *aprender* (a diferencia de las [Guías](../guias/index.md), que son para *resolver una tarea puntual*). -!!! note "En construcción" - El tutorial end-to-end está en preparación. Hoy, el camino guiado más corto - es el [Quickstart](../getting-started/quickstart.md). +## Tutoriales disponibles - Planificado (seguimiento en el - [issue #208](https://github.com/complexluise/bib2graph/issues/208)): +
- **De una pregunta de investigación a un mapa de citación.** Un caso real, - de punta a punta, reusando el corpus de ejemplo `examples/valoraciones/`: +- :material-robot: **[Tu primera red bibliométrica con Claude](claude-code.md)** - 1. Plantear la pregunta y la ecuación de búsqueda. - 2. Sembrar el corpus (`seed`). - 3. Expandir por citaciones (`chain`). - 4. Curar: aceptar/rechazar, filtros PRISMA. - 5. Construir las redes (`build`) y leerlas (`read`). - 6. Exportar a GraphML y abrir en Gephi. + Cómo dirigir bib2graph conversacionalmente desde Claude web sin instalar nada. + 15 minutos para armarte tu primer mapa de citaciones. -## Mientras tanto +- :material-rocket: **[Quickstart](../getting-started/quickstart.md)** -- [Quickstart](../getting-started/quickstart.md) — el ciclo mínimo en 2 minutos. -- [Guías (how-to)](../guias/index.md) — recetas para tareas concretas. + El ciclo mínimo de bib2graph en 2 minutos — desde la ecuación de búsqueda + a una red en GraphML, usando el CLI `b2g` en tu máquina. + +
+ +## Complementario + +- [Guías (how-to)](../guias/index.md) — recetas para tareas concretas, como elaborar un reporte de SOTA. - [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos. +- [Referencia de API Python](../reference/python-api.md) — cómo usar bib2graph como librería. From bfa7850412de4d865b4df5ca8adef775c98aa86a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 17:46:19 +0000 Subject: [PATCH 3/6] =?UTF-8?q?docs:=20restructure=20tutorials=20=E2=80=94?= =?UTF-8?q?=20quick=20start=20(5min)=20+=20complete=20(3-4h)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite 'Tu primera red bibliométrica en Claude' as a 5-minute quickstart for non-technical users: no installation, pure conversation with Claude - Add 'De la pregunta al reporte de SOTA' — complete step-by-step tutorial: from research question through documentation, PRISMA curation, 3 networks, community analysis, trend identification, and report writing - Update tutoriales/index.md to reflect two-level structure: "Para empezar (5min)" and "Tutorial completo (3-4h)" - Update docs/index.md to distinguish Tutoriales (learning) from Guías (recipes) Structure: short entry → builds to comprehensive, maintaining pedagogical flow Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01VfqH92jLCoRQ9G8AMA1Vgi --- docs/index.md | 8 +- docs/tutoriales/claude-code.md | 183 ++++------- docs/tutoriales/index.md | 29 +- docs/tutoriales/sota-completo.md | 504 +++++++++++++++++++++++++++++++ 4 files changed, 584 insertions(+), 140 deletions(-) create mode 100644 docs/tutoriales/sota-completo.md diff --git a/docs/index.md b/docs/index.md index 8757ee3..2b6bb2d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,9 +33,13 @@ mismo input, mismas redes. De una ecuación a un GraphML, sin escribir código. -- :material-book-open-variant: **[Guías](guias/index.md)** +- :material-book-open-variant: **[Tutoriales](tutoriales/index.md)** - Tutoriales y recetas para tareas concretas de investigación. + Desde tu primer mapa en 5 minutos hasta un reporte de SOTA riguroso. + +- :material-silverware-fork-knife: **[Guías](guias/index.md)** + + Recetas para tareas concretas de investigación. - :material-api: **[Referencia](reference/cli.md)** diff --git a/docs/tutoriales/claude-code.md b/docs/tutoriales/claude-code.md index e7b32b9..ede134c 100644 --- a/docs/tutoriales/claude-code.md +++ b/docs/tutoriales/claude-code.md @@ -1,164 +1,101 @@ --- -title: Tu primera red bibliométrica con bib2graph en Claude +title: Tu primer mapa de investigación en Claude (5 min) --- -# Tu primera red bibliométrica con bib2graph en Claude +# Tu primer mapa de investigación en Claude -Este tutorial lleva, partiendo de cero, a construir un **primer mapa de -citaciones** sobre un tema elegido — sin instalar nada y sin escribir código. -El truco: no se utiliza bib2graph directamente, sino que **se le pide a Claude que lo use -por la persona** en su entorno de ejecución de código. +Cómo armar, sin instalar nada, una **red visual de artículos científicos** sobre +un tema que te interesa. Pura conversación — Claude hace el trabajo técnico por vos. -Al terminar se tendrá un corpus de papers, una red de acoplamiento bibliográfico -con sus comunidades, y se entenderá el **lazo** de trabajo. Es para *aprender -haciendo*; si ya se sabe qué se quiere y se busca la receta de un reporte completo, véase la guía [Cómo elaborar un reporte de estado del arte](../guias/reporte-estado-del-arte.md). - -!!! info "Qué se necesita" - - Una sesión de **Claude (web o app) con ejecución de código activada** - (la herramienta de *Code Execution / análisis*, que permite a Claude - correr Python y crear archivos). - - 15 minutos. - - *Opcional pero recomendado:* una **API key de OpenAlex** (gratuita) si se van a - traer más de ~100 papers. Sin ella funciona, pero más lento y con límites. - -!!! warning "Alpha" - bib2graph está en `0.x`: la interfaz puede cambiar. Úsalo para explorar y - validar, no como dependencia estable todavía. +!!! info "Qué necesitás" + - **Claude (web o app)** — con ejecución de código activada (la herramienta de + análisis/Code Execution). + - **5 minutos**. + - Nada más. Sin instalación, sin código, sin API keys. --- -## El modelo mental en una frase - -En Claude web, **cada conversación es una mesa de trabajo nueva**. Claude instala -bib2graph, siembra el corpus, construye las redes y devuelve las figuras y los -archivos — todo dentro de esa charla. Se dirige con lenguaje natural; bib2graph -hace el trabajo determinista por debajo. - -``` -usuario (en lenguaje natural) - │ "armame una red de acoplamiento sobre X" - ▼ - Claude ── instala y ejecuta bib2graph ──► OpenAlex - │ │ - │ ◄──── corpus + redes + figuras ─────────┘ - ▼ - archivos que se descargan (el "guardado") -``` +## Paso 1 — Decile a Claude qué tema te interesa -## Paso 1 — Planteale el tema a Claude +Abrí una conversación y escribí algo así: -Se abre una conversación y se describe qué se quiere explorar. No hace falta que se sepa la -ecuación de búsqueda: Claude ayuda a armarla. - -!!! example "Prompt de arranque" +!!! example ```text Quiero explorar el estado del arte sobre [TU TEMA]. - Usá la librería bib2graph (instalala con pip) para armar una red de - acoplamiento bibliográfico desde OpenAlex. - Antes de sembrar, proponeme una ecuación de búsqueda y discutámosla. + + Usá bib2graph para traerme artículos desde OpenAlex, + armar una red de referencias compartidas y mostrarme + qué comunidades de investigación existen. + + Mi tema: [ejemplo: "métodos de recuperación de información en contextos multilingües"] ``` -Se reemplaza `[TU TEMA]` por algo concreto, por ejemplo *"métodos de generación de -electricidad más eficientes que la turbina de vapor"*. - -## Paso 2 — Afiná la ecuación de búsqueda +Claude va a sugerirte una **ecuación de búsqueda** — básicamente, cómo pedirle +a Google Scholar que busque exactamente lo que querés. La revisás, ajustás si +hace falta, y listo. -Claude propone una **ecuación de tres conceptos** (tema ∧ enfoque ∧ -términos específicos) con sinónimos. Se la lee y se ajusta: se agrega un término que importe, se saca uno que ensucie. Este ida y vuelta es parte del método — la -pregunta y la búsqueda **mutan** mientras se piensa. - -!!! tip "Una buena ecuación es angosta a propósito" - Si se pide algo demasiado genérico ("energía"), el corpus se ahoga. Mejor un - eje claro y unos pocos términos específicos que delimiten el campo. +--- -## Paso 3 — Sembrá y construí la red +## Paso 2 — Claude trae los papers y construye la red -Cuando la ecuación cierre, se le pide a Claude que ejecute el lazo. +Cuando la ecuación te cierre, decile: -!!! example "Prompt" +!!! example ```text - Perfecto. Sembrá hasta 200 papers desde 2015, construí la red de - acoplamiento bibliográfico y detectá comunidades con Louvain. - Mostrame la red coloreada por comunidad y cuántos papers cayó en cada una. + Dale, vamos. Traé hasta 150 papers desde 2015, construí + la red y mostrá las comunidades. ``` -Por debajo, Claude corre el equivalente a este lazo de bib2graph: +Claude hace todo por debajo — trae papers, identifica qué papers citan las +mismas referencias, agrupa esos papers en comunidades (como si fueran "escuelas" +o "enfoques" dentro del tema). -```python -from bib2graph import OpenAlexSource, Networks -from bib2graph.networks.spec import NetworkSpec -from bib2graph.constants import NetworkKind +**Resultado:** Una imagen donde ves la red (puntos = papers, líneas = referencias +compartidas, colores = comunidades). -src = OpenAlexSource(email="usuario@ejemplo.org", max_results=200) -corpus = src.seed(tu_ecuacion, min_year=2015).corpus - -spec = NetworkSpec(kind=NetworkKind.BIBLIOGRAPHIC_COUPLING, - clustering="louvain") -art = Networks.build(corpus, spec) # art.graph, art.communities, art.metrics -``` - -Se recibe una **imagen de la red** (cada punto un paper; cada línea, -referencias compartidas; cada color, una comunidad) y un resumen: número de -nodos, aristas y el tamaño de cada comunidad. - -!!! note "Qué es el acoplamiento bibliográfico" - Dos papers se *acoplan* si citan las mismas referencias. Cuantas más - comparten, más cerca quedan. Las comunidades que aparecen suelen ser - **sub-temas o escuelas** del campo. Es la red "barata": no requiere un - segundo nivel de descargas. +--- -## Paso 4 — Leé el mapa +## Paso 3 — Leé el mapa -Se le pide a Claude que ponga nombre a las comunidades a partir de sus keywords -dominantes, y que muestre los papers más centrales (los de mayor grado) de -cada una. +Pedile a Claude: -!!! example "Prompt" +!!! example ```text - Nombrá cada comunidad según sus keywords y listame los 3 papers más - centrales de cada una, con título y año. + Nombrá cada comunidad y listá los 3 papers más importantes + de cada una (autor, año, qué hacen). ``` -Eso da, en una pantalla, el **plano del campo**: qué grandes familias existen -y cuáles son sus trabajos de referencia. Ya se tiene el primer mapa. +Listo. **Ya tenés un primer mapa mental del campo** — qué tendencias existen, +quiénes son los referentes, dónde están las divergencias. -## Paso 5 — Guardá tu trabajo +--- -!!! warning "El entorno es efímero" - Cuando se cierre la conversación, la mesa de trabajo se borra. La promesa de - bib2graph de *"biblioteca que persiste y crece entre sesiones"* **no se - cumple sola en Claude web**: se tienen que llevar los archivos. +## Paso 4 — Descargá tu trabajo -Se piden los exports en formatos abiertos y se descargan: +Nada persiste cuando cerrás la conversación. Pedile a Claude: -!!! example "Prompt" +!!! example ```text - Exportá el corpus a Parquet, la red a GraphML y un CSV con - paper → comunidad → grado. Pasámelos para descargar. + Descargá todo: la red en formato GraphML, una lista de + papers en CSV, una imagen de la red. ``` -El `GraphML` se abre después en [Gephi](https://gephi.org) o Cytoscape para -explorar la red a mano. El `Parquet` es la **semilla guardada**: en una próxima -conversación se la sube a Claude y se sigue desde ahí. +Guardá esos archivos. Si querés seguir investigando después en otra conversación +(o en tu máquina), tenés la semilla guardada. + +--- -## Qué se aprendió +## Listo -- A dirigir bib2graph **conversacionalmente** desde Claude, sin escribir código. -- El lazo mínimo: **pregunta → ecuación → siembra → red de acoplamiento → - comunidades → lectura**. -- Que en Claude web **el archivo exportado es la memoria**: sin descarga, no hay - persistencia. +En 5 minutos: -## Siguientes pasos +✅ Trajiste papers de un tema +✅ Viste cómo se relacionan (qué citan en común) +✅ Identificaste sub-temas / enfoques +✅ Guardaste los archivos -- [Cómo elaborar un reporte de estado del arte](../guias/reporte-estado-del-arte.md) - — la receta completa hasta un informe con tensiones y conclusiones. -- [Quickstart](../getting-started/quickstart.md) — el mismo lazo, pero desde el CLI - `b2g` en la propia máquina. -- [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos. +## Qué sigue -!!! tip "¿Se va a usar seguido?" - Para un uso repetido y con biblioteca persistente de verdad, conviene correr - bib2graph en la máquina (o con **Claude Code** y la skill incluida, `b2g skill - add`), donde el corpus en DuckDB sí vive entre sesiones. Claude web es ideal - para explorar; el CLI local, para sostener una investigación en el tiempo. +- **Más detalles:** [Tutorial completo — De la pregunta al reporte de SOTA](sota-completo.md) — cómo refinar la búsqueda, curar papers y redactar un análisis serio. +- **Tu máquina:** Si lo vas a hacer seguido, conviene instalar bib2graph localmente. Mira el [Quickstart](../getting-started/quickstart.md). +- **Referencia:** [Todos los comandos de bib2graph](../reference/cli.md). diff --git a/docs/tutoriales/index.md b/docs/tutoriales/index.md index ef4cd5b..0862b71 100644 --- a/docs/tutoriales/index.md +++ b/docs/tutoriales/index.md @@ -5,27 +5,26 @@ title: Tutoriales # Tutoriales Los **tutoriales** enseñan a usar bib2graph paso a paso, partiendo de cero y -llegando a un resultado concreto. Son para *aprender* (a diferencia de las -[Guías](../guias/index.md), que son para *resolver una tarea puntual*). +llegando a un resultado concreto. Son para *aprender*. -## Tutoriales disponibles +## Para empezar (5 minutos) -
+- :material-robot: **[Tu primer mapa en Claude (5 min)](claude-code.md)** -- :material-robot: **[Tu primera red bibliométrica con Claude](claude-code.md)** + Cómo armar, sin instalar nada, una red visual de papers sobre un tema. + Conversación con Claude — todo automatizado. Ideal para explorar rápido. - Cómo dirigir bib2graph conversacionalmente desde Claude web sin instalar nada. - 15 minutos para armarte tu primer mapa de citaciones. +## Tutorial completo (3–4 horas) -- :material-rocket: **[Quickstart](../getting-started/quickstart.md)** +- :material-book: **[De la pregunta al reporte de SOTA](sota-completo.md)** - El ciclo mínimo de bib2graph en 2 minutos — desde la ecuación de búsqueda - a una red en GraphML, usando el CLI `b2g` en tu máquina. + Recorrido completo paso a paso: pregunta → ecuación → corpus → curación PRISMA + → 3 redes → análisis de comunidades → tendencias → redacción del reporte. + Para alguien que quiere hacer un SOTA riguroso. -
+## También útil -## Complementario - -- [Guías (how-to)](../guias/index.md) — recetas para tareas concretas, como elaborar un reporte de SOTA. +- [Quickstart](../getting-started/quickstart.md) — el ciclo mínimo con CLI `b2g` en tu máquina (2 min). +- [Guías (how-to)](../guias/index.md) — recetas para tareas concretas. - [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos. -- [Referencia de API Python](../reference/python-api.md) — cómo usar bib2graph como librería. +- [API Python](../reference/python-api.md) — bib2graph como librería. diff --git a/docs/tutoriales/sota-completo.md b/docs/tutoriales/sota-completo.md new file mode 100644 index 0000000..b3258c7 --- /dev/null +++ b/docs/tutoriales/sota-completo.md @@ -0,0 +1,504 @@ +--- +title: Tutorial completo — De la pregunta al reporte de SOTA +--- + +# Tutorial completo — De la pregunta al reporte de SOTA + +Un recorrido paso a paso por un **estado del arte riguroso**: desde formular +la pregunta de investigación hasta redactar un análisis con tensiones, +escuelas de pensamiento y huecos sin explorar. + +Este es el tutorial detallado (45 min de lectura + 2–3 horas de investigación). +Si acabás de descubrir bib2graph, empezá por el [tutorial corto](claude-code.md). + +!!! info "Requisitos" + - Una pregunta de investigación clara (no un tema genérico). + - Acceso a Claude con ejecución de código, o una máquina con bib2graph instalado. + - Tiempo: 3–4 horas para el ciclo completo. + - Opcional: API key de OpenAlex (gratuita, para corpus > 100 papers). + +--- + +## Anatomía de un estado del arte + +Un SOTA riguroso no es una lista de papers. Es un **mapa de cómo piensa un campo**: + +``` +pregunta ──► ecuación ──► corpus ──► curación ──► redes ──► comunidades + │ + ◄──────────────────────── lectura + (qué vemos en el mapa) + │ + tendencias, tensiones, huecos + │ + reporte +``` + +Vamos paso a paso. + +--- + +## Paso 1 — Afiná tu pregunta de investigación + +**Entrada:** Un tema que te interesa. +**Salida:** Una pregunta clara, acotada, formulable. + +### Cómo llegar de un tema a una pregunta + +❌ *"Inteligencia artificial"* → Demasiado genérico. ¿Qué aspecto? ¿Qué dominio? + +✅ *"¿Cómo se aborda el problema de alineación de valores en modelos de +lenguaje grandes, y cuáles son las tensiones entre eficiencia computacional +y robustez ética entre 2020 y hoy?"* + +### Checklist para tu pregunta + +1. **¿Específica?** ¿Puedo reducirla a 4–6 palabras clave? +2. **¿Temporal?** ¿Hay un rango de años relevante? (5–10 años suele ser ideal). +3. **¿Acotada?** ¿Espero 50 papers, 500, 5000? +4. **¿Contestable?** ¿Puedo responderla buscando en artículos científicos? + +### Ejemplo: Desarrolla la pregunta + +**Mi tema inicial:** "Métodos de recuperación de información." + +**Mi pregunta después del refinamiento:** +> ¿Cuáles son los enfoques dominantes para recuperación de información en +> contextos multilingües, cuáles son sus tensiones (vocabulario vs. semántica, +> eficiencia vs. precisión), y cuáles son los huecos sin explorar entre 2015 +> y 2024? + +Eso es búscable, acotado, y con una tensión clara. + +--- + +## Paso 2 — Elaborá una ecuación de búsqueda + +**Entrada:** Tu pregunta de investigación. +**Salida:** Una ecuación booleana que traduzca esa pregunta. + +### La estructura + +``` +(concepto_A_términos) +AND (concepto_B_términos) +AND (concepto_C_términos) +[AND NOT (exclusiones)] +``` + +Cada paréntesis es un concepto; dentro, los términos están unidos por `OR` +(sinónimos). Los `AND` conectan conceptos (todos deben estar presentes). + +### Para mi ejemplo + +``` +(information retrieval OR IR OR search) +AND (multilingual OR cross-lingual OR language-agnostic OR polyglot) +AND (method OR approach OR framework OR system OR architecture) +``` + +### Consejos prácticos + +- **Un concepto = una dimensión de tu pregunta.** Aquí: + - Concepto A: la tarea (recuperación). + - Concepto B: la restricción (multilingüe). + - Concepto C: el tipo de resultado (métodos, no papers de aplicación). + +- **Evita genéricos.** "machine learning" sola atrapa cientos de miles de papers. + +- **Testea:** Pide a Claude que busque 50 papers con tu ecuación y revisá los + títulos. ¿Ves ruido sistemático? Ajusta. + +- **Excluye si hace falta:** `AND NOT (machine translation)` si hay mucho ruido + ahí. + +--- + +## Paso 3 — Siembra el corpus + +**Entrada:** Ecuación de búsqueda, rango de años. +**Salida:** Corpus inicial (~200–300 papers). + +### Con Claude + +Prompt: + +```text +Instalá bib2graph con pip. + +Usá esta ecuación de búsqueda en OpenAlex: +(information retrieval OR IR OR search) +AND (multilingual OR cross-lingual) +AND (method OR approach OR framework) + +Sembrá hasta 250 papers desde 2015. + +Mostrame: +- Total de papers +- Distribución por año (gráfico) +- Top 10 autores por cantidad de papers +- Años: mín y máx +``` + +### Verificación + +Mirá el corpus trayéndote un resumen: + +```text +Listá 20 papers al azar del corpus con título y año. +¿Todos tienen relación directa con mi tema? +Si hay ruido, ajustemos la ecuación. +``` + +### Punto de decisión + +- **Corpus muy pequeño (<50 papers)?** Abre la ecuación (menos `AND`, más sinónimos). +- **Corpus muy grande (>1000)?** Ciérrala (más `AND`, menos sinónimos, o agrega + un concepto específico más). +- **Corpus bien (~200–400)?** Perfecto, seguimos. + +--- + +## Paso 4 — Expande por citaciones (opcional) + +**Entrada:** Corpus de siembra. +**Salida:** Corpus expandido (~20–50% más) con más densidad de referencias. + +El **forrajeo** (backward chaining) busca papers que no aparecieron en tu +búsqueda original, pero que son citados por los que sí están. Aumenta la +*sensibilidad* (no pierdes papers clave) sin agregar mucho ruido. + +### Cuándo hacer esto + +✅ **Hazlo si:** el tema es muy específico, querés máxima cobertura, o el corpus +inicial es pequeño. + +❌ **No lo hagas si:** el corpus ya es grande (>500), no querés aumentarlo, o es +tu primer SOTA (primero lee la red de siembra, después decide). + +### Con Claude + +```text +Expandí el corpus usando forrajeo (backward chaining): +seguí una capa de referencias de los papers ya en el corpus +y agregá hasta 100 papers nuevos. + +Mostrame: +- Cuántos papers nuevos se agregaron +- Si hay papers muy antiguos (pre-2000): ¿los mantengo o descarto? +``` + +--- + +## Paso 5 — Curá el corpus (PRISMA) + +**Entrada:** Corpus (siembra o expandido). +**Salida:** Corpus curado, con decisiones criteriales explícitas y versionables. + +La curación es **manual**. No se automatiza porque cada decisión es criterial. + +### Flujo PRISMA simplificado + +``` +IDENTIFICACIÓN +├─ ¿Duplicado o retractado? → RECHAZAR +└─ ¿En el idioma adecuado? → si no, RECHAZAR + +CRIBADO (título + resumen) +├─ ¿Título claramente fuera de scope? → RECHAZAR +└─ ¿Resumen no aporta al tema? → RECHAZAR + +ELEGIBILIDAD (lectura de disponibilidad) +├─ ¿Texto completo inaccesible? → CANDIDATO (maybe later) +└─ ¿Métodos/resultados vagos o especulativos? → CANDIDATO + +INCLUSIÓN (decisión final) +├─ ¿Relevancia alta? → ACEPTAR +└─ ¿Relevancia media pero aporta tensión? → ACEPTAR +``` + +### Con Claude + +Pedile a Claude: + +```text +Hacé curación PRISMA del corpus. Revisá cada paper: +1. Si es duplicado o retractado: RECHAZAR +2. Si el título no tiene relación directa: RECHAZAR +3. Si el resumen sugiere que no toca el tema: RECHAZAR +4. Si no hay texto completo: CANDIDATO (no rechaces) +5. En otro caso: ACEPTAR + +Mostrá un resumen: cuántos ACCEPTED, REJECTED, CANDIDATE. +Listá 5 ejemplos de RECHAZADOS con razón. +``` + +### Checklist + +- [ ] ¿Documenté mis criterios explícitamente? +- [ ] ¿El corpus ACCEPTED quedó entre 100–300 papers? +- [ ] ¿Revisé una muestra de rechazados para asegurarme de que no falta algo obvio? +- [ ] ¿Hay equilibrio entre años (no es monocromático)? + +--- + +## Paso 6 — Construí las redes + +**Entrada:** Corpus curado (papers ACCEPTED). +**Salida:** 3 redes + métricas. + +Las tres redes que importan: + +1. **Acoplamiento bibliográfico:** Papers que citan las mismas referencias. + (Responde: ¿cuáles son los sub-temas?) +2. **Co-citación:** Papers que se citan mutuamente o son citados juntos. + (Responde: ¿cuáles son los influentes?) +3. **Co-autoría:** Quién escribe con quién. + (Responde: ¿cuáles son los colegios invisibles?) + +### Con Claude + +```text +Construí 3 redes del corpus ACCEPTED usando bib2graph: +1. Acoplamiento bibliográfico +2. Co-citación +3. Co-autoría + +Para cada red: +- Detectá comunidades usando Louvain (clustering) +- Mostrame una visualización coloreada por comunidad +- Reportá: # nodos, # aristas, # comunidades +- Listá los 3 papers más centrales (mayor grado) de cada comunidad +``` + +### Qué esperar + +- **Acoplamiento:** es la "red primaria" — más densa, más comunidades. Aquí ves + los sub-temas claros. +- **Co-citación:** a menudo es más dispersa; destaca papers que actúan como + referencias canónicas (los "clásicos" del campo). +- **Co-autoría:** también dispersa, pero útil para ver equipos y colaboraciones + persistentes. + +--- + +## Paso 7 — Nombrá y caracterizá las comunidades + +**Entrada:** Redes + corpus curado. +**Salida:** Una tabla con comunidades, keywords, seminales, y tensiones. + +Para cada comunidad en la red de acoplamiento (la principal): + +1. **Nombre:** 1–3 palabras que capturen el enfoque (ej. "Métodos probabilísticos"). +2. **Keywords:** 5–7 palabras clave dominantes en esa comunidad. +3. **Seminales:** Top 2–3 papers (mayor grado) dentro de la comunidad. +4. **Descripción:** 2–3 frases de qué hacen esos papers. +5. **Tensión:** ¿Qué los diferencia de otras comunidades? ¿Dónde discrepan? + +### Con Claude + +```text +Para la red de acoplamiento, analizá cada comunidad: + +1. Nombre (síntesis del enfoque en 1–3 palabras) +2. Keywords principales (5–7 terms que definen esa comunidad) +3. Seminales: top 2 papers (por grado), con título, autores, año +4. Descripción: ¿qué hacen esos papers? ¿Cuál es el enfoque común? +5. Tensión: ¿en qué difieren de otras comunidades? + +Armame una tabla: [Comunidad | Enfoque | Keywords | Seminales | Tensión] +``` + +### Ejemplo de salida + +| Comunidad | Enfoque | Keywords | Seminales | Tensión | +|-----------|---------|----------|-----------|---------| +| **Probabilístico** | Modelos estadísticos, HMM | language model, smoothing, EM | [Smith 2008], [Brown 2010] | Eficiencia vs. cobertura | +| **Vectorial** | Embeddings, semántica latente | word embeddings, LSA, similarity | [Mikolov 2013], [Pennington 2014] | Interpretabilidad vs. performance | +| **Neuronal** | Deep learning, transformers | neural networks, attention, BERT | [Vaswani 2017], [Devlin 2019] | Costo computacional vs. generalización | + +--- + +## Paso 8 — Analiza tendencias e influencias + +**Entrada:** Redes, comunidades, corpus. +**Salida:** Observaciones sobre evolución, actores clave, huecos. + +Responde estas preguntas: + +### 1. ¿Cómo evolucionó el campo? + +```text +Mostrame: +- Gráfico de # papers/año en el corpus +- Cómo cambiaron las comunidades (% de papers) año a año +- ¿Hay una comunidad que crecía y ahora decrece? +- ¿Hay una emergente (crecimiento exponencial últimos 3 años)? +``` + +### 2. ¿Quiénes son los influyentes? + +```text +Top 10 autores por: +- Cantidad de papers (productividad) +- Grado en la red de co-citación (influencia) +- Betweenness (actúan de "puente" entre comunidades) +``` + +### 3. ¿Dónde están los huecos? + +```text +Mirando las 3 redes, identificá: +- Comunidades o autores que no se conectan entre sí (fronteras vacías) +- Combinaciones de keywords que NO aparecen (gaps) +- Preguntas que nadie se hace (inferir de lo que sí hay) +``` + +### 4. ¿Quién lidera por institución? + +```text +Co-autoría: top 10 instituciones por: +- Cantidad de papers +- Colaboraciones externas +``` + +--- + +## Paso 9 — Redactá el reporte + +**Entrada:** Análisis anterior, comunidades, tendencias. +**Salida:** Documento estructurado (Markdown, Word, Google Docs). + +### Estructura recomendada + +``` +RESUMEN EJECUTIVO +├─ Pregunta de investigación +├─ Hallazgos principales (2–3 frases) +└─ Síntesis de una línea + +INTRODUCCIÓN +├─ Contexto y motivación +├─ Pregunta de investigación +└─ Scope + +METODOLOGÍA +├─ Ecuación de búsqueda +├─ Criterios PRISMA (en una frase) +├─ Tamaño final: X papers, años A–B +└─ Redes construidas (acoplamiento, co-citación, co-autoría) + +MAPEO DEL CAMPO +├─ Tabla de comunidades (visto en Paso 7) +├─ Figura: red de acoplamiento coloreada +├─ Trabajos seminales por comunidad +└─ Descripción de cada enfoque (prosa) + +TENDENCIAS Y EVOLUCIÓN +├─ Trayectoria temporal +├─ Shift de enfoques (cuál sube, cuál baja) +├─ Emergentes (keywords nuevas, comunidades nuevas) +└─ Actores clave (top autores, instituciones) + +TENSIONES Y DEBATES +├─ Matriz: Enfoque A vs. Enfoque B, qué diferencia +├─ Dónde se superponen, dónde divergen +├─ Huecos de investigación +└─ Preguntas abiertas + +CONCLUSIONES +├─ Síntesis de hallazgos +├─ Implicaciones para investigación futura +└─ Recomendaciones + +APÉNDICES +├─ Tabla: todos los papers (corpus completo) +├─ CSV de papers → comunidad +└─ GraphML (red para abrir en Gephi/Cytoscape) +``` + +### Herramientas de escritura + +- **Google Docs:** Colaboración y comentarios; exportás a .docx después. +- **Markdown + Pandoc:** Máximo control; exportás a PDF/DOCX/HTML. +- **Obsidian:** Integración con Zotero; bueno para notas de investigación. +- **Quarto/Jupyter:** Si querés reproducibilidad y código integrado. + +### Tips de redacción + +- **Cada comunidad merece un párrafo.** No amontonés. +- **Las figuras llevan leyendas explicativas.** "Red de acoplamiento bibliográfico + con N nodos (papers), M aristas (referencias compartidas), K comunidades + (detectadas por Louvain, resolution=1.0). Cada color = una comunidad. + Los nodos más grandes = papers de mayor grado (más referencias compartidas)." +- **Tensiones no son "problemas abiertos".** Son donde dos enfoques dicen cosas + diferentes. Ej. "La escuela probabilística prioriza eficiencia computacional, + mientras que la neuronal prioriza generación de resultados. En corpus multilingües, + esto afecta cómo se mapean traducciones." + +--- + +## Paso 10 — Versiona tu trabajo + +**Entrada:** Reporte, corpus, redes. +**Salida:** Carpeta reproducible. + +### Si usaste Claude web + +Descargá: + +- `corpus.parquet` — tu semilla guardada (subirla a Claude luego para continuar). +- `*.graphml` — networks para Gephi/Cytoscape. +- `clusters.csv` — papers → comunidad. +- `reporte.docx` o `reporte.md` — tu análisis final. + +Guardalos en una carpeta: `sota-[tema]-[fecha]/` + +### Si usaste bib2graph localmente + +El corpus vive en `.duckdb`; las redes se exportan automáticamente: + +```bash +# Exportá todo +b2g export --format graphml +b2g export --format csv + +# Versioná +git add . +git commit -m "SOTA: [Tu Tema] — corpus, redes, reporte" +``` + +--- + +## Checklist final + +- [ ] Pregunta de investigación clara y formulada +- [ ] Ecuación de búsqueda documentada y testeada +- [ ] Corpus de 100–300 papers ACCEPTED (curados por PRISMA) +- [ ] 3 redes construidas y visualizadas +- [ ] Comunidades nombradas, con keywords, seminales y tensiones identificadas +- [ ] Tendencias temporales e influencias (autores, instituciones) documentadas +- [ ] Huecos y fronteras vacías identificados +- [ ] Reporte redactado con estructura clara y figuras con leyendas +- [ ] Artefactos (GraphML, CSV, corpus) guardados y versionados +- [ ] ¿Se puede reproducir desde la ecuación de búsqueda? ✓ + +--- + +## Siguientes pasos + +- **Análisis más profundo:** Elige una comunidad y hacé un sub-SOTA acotado. +- **Integración con tu investigación:** Posicioná tu trabajo en el mapa — ¿dónde + caés? ¿Dónde resolvés una tensión? +- **Publicación:** Convertí el SOTA en un paper, capítulo de tesis, o entrada de + blog. + +--- + +## Referencias + +- [Cómo elaborar un reporte de estado del arte (guía)](../guias/reporte-estado-del-arte.md) — + complemento con más detalles en curación y redacción. +- [Arquitectura de bib2graph](../ARCHITECTURE.md) +- [Referencia del CLI `b2g`](../reference/cli.md) +- [API Python](../reference/python-api.md) From 9619b51f68a5743b6e3dc20b6b110d7361e1e795 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 17:55:36 +0000 Subject: [PATCH 4/6] docs: fix language and add CLI foundation, remove vendor locking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language changes: - Remove Argentine Spanish (vos, mostrá, armá, etc.) - Adopt Colombian Spanish with tú (neutral, professional tone) - Examples: "armá" → "arma", "mostrá" → "muestra", "Mostrame" → "Muestra" Content restructuring: - Add Paso 0 to tutorials: install bib2graph with pip - Teach b2g CLI as foundation, not just Claude/ChatGPT - Remove vendor locking: explain users can use Claude, ChatGPT, MiniMax, etc. - Show CLI commands first: b2g init, b2g seed, b2g build, etc. - Explain that agentes help but CLI is the core skill to learn - Workflow: install → learn CLI → use agente to help direct CLI Structure now: 1. Quick start (5 min) - install bib2graph, basic CLI, then Claude help 2. Complete tutorial (3-4h) - Paso 0 (install) + Paso 1-10 (full SOTA) 3. Guide - reference, complements tutorials This makes documentation vendor-neutral and teaches independent usage. Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01VfqH92jLCoRQ9G8AMA1Vgi --- docs/guias/reporte-estado-del-arte.md | 6 +- docs/tutoriales/claude-code.md | 134 +++++++++++++++++--------- docs/tutoriales/sota-completo.md | 122 +++++++++++++++++------ 3 files changed, 181 insertions(+), 81 deletions(-) diff --git a/docs/guias/reporte-estado-del-arte.md b/docs/guias/reporte-estado-del-arte.md index 3e1b9fa..e46e64a 100644 --- a/docs/guias/reporte-estado-del-arte.md +++ b/docs/guias/reporte-estado-del-arte.md @@ -171,7 +171,7 @@ Mostrame los papers nuevos y el gráfico de crecimiento por año. ### Cuándo hacer esto -- ✅ Si buscás sensibilidad alta (no querés perderte trabajos clave). +- ✅ Si buscas sensibilidad alta (no quieres perderte trabajos clave). - ✅ Si el tema es muy específico (forrajeo agrega relevancia). - ❌ Si el corpus ya es grande (>500) — aumenta significativamente el tamaño. - ❌ Si es la primera vez: puedes hacer esto después de leer la red inicial. @@ -418,7 +418,7 @@ Analizá tendencias en el corpus: - **Obsidian + Zotero:** flujo de investigación integrado. - **Google Docs:** colaboración y comentarios; convertís a .docx después. - **Markdown + Pandoc:** máxima control; exportás a PDF/DOCX con cite. -- **Quarto/Jupyter:** si querés reproducibilidad y código integrado. +- **Quarto/Jupyter:** si quieres reproducibilidad y código integrado. ### Checklist antes de publicar @@ -484,7 +484,7 @@ Guardalos en una carpeta nominada `sota-[tema]-[fecha]` en tu repositorio de inv posicionamiento** para tu propio trabajo — ¿dónde caés? ¿dónde hay tensión que tu trabajo resuelve? -- **Tutorial:** Si querés aprender el CLI o la librería de Python a fondo, +- **Tutorial:** Si quieres aprender el CLI o la librería de Python a fondo, véase el [Quickstart](../getting-started/quickstart.md) y la [Referencia](../reference/cli.md). - **Comunidad:** Compartí tu SOTA en el repo (crea un issue); feedback de otros diff --git a/docs/tutoriales/claude-code.md b/docs/tutoriales/claude-code.md index ede134c..660b8ba 100644 --- a/docs/tutoriales/claude-code.md +++ b/docs/tutoriales/claude-code.md @@ -1,87 +1,127 @@ --- -title: Tu primer mapa de investigación en Claude (5 min) +title: Tu primer mapa de investigación (5 min) --- -# Tu primer mapa de investigación en Claude +# Tu primer mapa de investigación (5 minutos) -Cómo armar, sin instalar nada, una **red visual de artículos científicos** sobre -un tema que te interesa. Pura conversación — Claude hace el trabajo técnico por vos. +Cómo armar una **red visual de artículos científicos** sobre un tema que te +interesa, usando un agente de IA para dirigir bib2graph. -!!! info "Qué necesitás" - - **Claude (web o app)** — con ejecución de código activada (la herramienta de - análisis/Code Execution). +!!! info "Qué necesitas" + - **Un agente de IA** con ejecución de código: Claude, ChatGPT, MiniMax, o similar. + - **bib2graph instalado** en tu máquina (1 minuto: `pip install bib2graph`). - **5 minutos**. - - Nada más. Sin instalación, sin código, sin API keys. + +!!! warning "Paso previo: instala bib2graph" + Abre tu terminal y ejecuta: + ```bash + pip install bib2graph + ``` + + Verifica que funciona: + ```bash + b2g --help + ``` + + Si ves la ayuda de comandos, listo. Si no, ve a [Instalación](../getting-started/installation.md). --- -## Paso 1 — Decile a Claude qué tema te interesa +## Paso 1 — Elige un agente + +Abre **cualquiera** de estos (con ejecución de código activada): + +- **Claude** (web o app) +- **ChatGPT** (Plus, con Code Interpreter) +- **MiniMax** o similar + +Lo importante: que pueda ejecutar Python y crear archivos. Nosotros no hacemos vendor locking +a un solo agente — bib2graph funciona igual en todos. + +--- -Abrí una conversación y escribí algo así: +## Paso 2 — Plantea el tema al agente + +En una conversación nueva, escribe algo así: !!! example ```text + Tengo bib2graph instalado en mi máquina. + Quiero explorar el estado del arte sobre [TU TEMA]. - Usá bib2graph para traerme artículos desde OpenAlex, - armar una red de referencias compartidas y mostrarme - qué comunidades de investigación existen. + Usa bib2graph para: + 1. Buscar papers en OpenAlex + 2. Construir una red de referencias compartidas + 3. Mostrar qué comunidades de investigación existen - Mi tema: [ejemplo: "métodos de recuperación de información en contextos multilingües"] + Mi tema: [ejemplo: métodos de recuperación de información en contextos multilingües] ``` -Claude va a sugerirte una **ecuación de búsqueda** — básicamente, cómo pedirle -a Google Scholar que busque exactamente lo que querés. La revisás, ajustás si -hace falta, y listo. +El agente va a sugerirte una **ecuación de búsqueda** — una forma de decirle a OpenAlex +exactamente qué buscar. La revisas, ajustas si hace falta. --- -## Paso 2 — Claude trae los papers y construye la red +## Paso 3 — El agente construye la red -Cuando la ecuación te cierre, decile: +Cuando la ecuación te cierre, pide al agente: !!! example ```text - Dale, vamos. Traé hasta 150 papers desde 2015, construí - la red y mostrá las comunidades. + Bien. Ahora ejecuta estos comandos en mi máquina: + + 1. b2g init mi-sota + 2. cd mi-sota + 3. b2g seed "[TU ECUACION]" --min-year 2015 + 4. b2g build + 5. b2g export --format graphml + + Muestra la red visualizada y un resumen de las comunidades. ``` -Claude hace todo por debajo — trae papers, identifica qué papers citan las -mismas referencias, agrupa esos papers en comunidades (como si fueran "escuelas" -o "enfoques" dentro del tema). +El agente ejecuta esos comandos por ti — trae papers, identifica qué papers citan +las mismas referencias, agrupa esos papers en comunidades. -**Resultado:** Una imagen donde ves la red (puntos = papers, líneas = referencias -compartidas, colores = comunidades). +**Resultado:** Una imagen de la red (puntos = papers, líneas = referencias compartidas, +colores = comunidades). --- -## Paso 3 — Leé el mapa +## Paso 4 — Lee el mapa -Pedile a Claude: +Pide al agente: !!! example ```text - Nombrá cada comunidad y listá los 3 papers más importantes - de cada una (autor, año, qué hacen). + Para cada comunidad en la red: + - Nombre (síntesis del enfoque) + - Keywords principales + - Top 3 papers más centrales (autor, año) + + Muestra una tabla. ``` -Listo. **Ya tenés un primer mapa mental del campo** — qué tendencias existen, -quiénes son los referentes, dónde están las divergencias. +Ya tienes un **primer mapa mental del campo** — qué tendencias existen, quiénes +son los referentes, dónde están las divergencias. --- -## Paso 4 — Descargá tu trabajo +## Paso 5 — Guarda tu trabajo -Nada persiste cuando cerrás la conversación. Pedile a Claude: +Tu corpus está en el archivo `.duckdb` dentro de la carpeta `mi-sota/`. Los archivos +`.graphml` están en `exports/`. -!!! example - ```text - Descargá todo: la red en formato GraphML, una lista de - papers en CSV, una imagen de la red. - ``` +Para continuar después: + +```bash +cd mi-sota +b2g read list # Ver papers en el corpus +b2g read top # Ver papers más centrales +``` -Guardá esos archivos. Si querés seguir investigando después en otra conversación -(o en tu máquina), tenés la semilla guardada. +Si quieres explorar más tarde desde el agente, carga los archivos GraphML o Parquet en +la conversación y sigue desde ahí. --- @@ -89,13 +129,15 @@ Guardá esos archivos. Si querés seguir investigando después en otra conversac En 5 minutos: -✅ Trajiste papers de un tema +✅ Instalaste bib2graph +✅ Trajiste papers de un tema (con ayuda del agente) ✅ Viste cómo se relacionan (qué citan en común) ✅ Identificaste sub-temas / enfoques -✅ Guardaste los archivos +✅ El corpus está guardado en tu máquina ## Qué sigue -- **Más detalles:** [Tutorial completo — De la pregunta al reporte de SOTA](sota-completo.md) — cómo refinar la búsqueda, curar papers y redactar un análisis serio. -- **Tu máquina:** Si lo vas a hacer seguido, conviene instalar bib2graph localmente. Mira el [Quickstart](../getting-started/quickstart.md). -- **Referencia:** [Todos los comandos de bib2graph](../reference/cli.md). +- **Más detalles:** [Tutorial completo — De la pregunta al reporte de SOTA](sota-completo.md) + — cómo refinar, curar y redactar un análisis riguroso. +- **Referencia completa:** [Todos los comandos de bib2graph](../reference/cli.md). +- **Como librería Python:** [API Python](../reference/python-api.md). diff --git a/docs/tutoriales/sota-completo.md b/docs/tutoriales/sota-completo.md index b3258c7..4b7d051 100644 --- a/docs/tutoriales/sota-completo.md +++ b/docs/tutoriales/sota-completo.md @@ -9,11 +9,12 @@ la pregunta de investigación hasta redactar un análisis con tensiones, escuelas de pensamiento y huecos sin explorar. Este es el tutorial detallado (45 min de lectura + 2–3 horas de investigación). -Si acabás de descubrir bib2graph, empezá por el [tutorial corto](claude-code.md). +Si acaba de descubrir bib2graph, empiece por el [tutorial corto](claude-code.md). !!! info "Requisitos" - Una pregunta de investigación clara (no un tema genérico). - - Acceso a Claude con ejecución de código, o una máquina con bib2graph instalado. + - **bib2graph instalado** en tu máquina: `pip install bib2graph` + - Un agente de IA (Claude, ChatGPT, MiniMax, etc.) con ejecución de código, o disposición a usar el CLI directamente. - Tiempo: 3–4 horas para el ciclo completo. - Opcional: API key de OpenAlex (gratuita, para corpus > 100 papers). @@ -38,7 +39,46 @@ Vamos paso a paso. --- -## Paso 1 — Afiná tu pregunta de investigación +## Paso 0 — Instala bib2graph + +**Entrada:** Tu máquina con Python 3.10+. +**Salida:** bib2graph funcionando y listo para usar. + +Abre tu terminal y ejecuta: + +```bash +pip install bib2graph +``` + +Verifica que funciona: + +```bash +b2g --help +``` + +Deberías ver la lista de comandos de bib2graph. Si no, consulta [Instalación](../getting-started/installation.md). + +### Entiende el flujo de comandos básicos + +bib2graph usa un flujo de **comandos secuenciales**: + +```bash +b2g init ./mi-sota # Crea una carpeta de proyecto +cd mi-sota + +b2g seed "tu_ecuacion" # Trae papers desde OpenAlex +b2g chain # (Opcional) Expande por citaciones +b2g curate # Acepta/rechaza papers (curación) +b2g build # Construye redes +b2g read list # Visualiza papers +b2g export --format graphml # Exporta redes +``` + +Cada comando transiciona el estado del corpus. Vamos a ver esto en detalle. + +--- + +## Paso 1 — Afina tu pregunta de investigación **Entrada:** Un tema que te interesa. **Salida:** Una pregunta clara, acotada, formulable. @@ -68,7 +108,7 @@ y robustez ética entre 2020 y hoy?"* > eficiencia vs. precisión), y cuáles son los huecos sin explorar entre 2015 > y 2024? -Eso es búscable, acotado, y con una tensión clara. +Eso es buscable, acotado, y con una tensión clara. --- @@ -106,7 +146,7 @@ AND (method OR approach OR framework OR system OR architecture) - **Evita genéricos.** "machine learning" sola atrapa cientos de miles de papers. -- **Testea:** Pide a Claude que busque 50 papers con tu ecuación y revisá los +- **Testea:** Pídele a Claude que busque 50 papers con tu ecuación y revisa los títulos. ¿Ves ruido sistemático? Ajusta. - **Excluye si hace falta:** `AND NOT (machine translation)` si hay mucho ruido @@ -119,37 +159,55 @@ AND (method OR approach OR framework OR system OR architecture) **Entrada:** Ecuación de búsqueda, rango de años. **Salida:** Corpus inicial (~200–300 papers). -### Con Claude +### Opción 1: Con CLI directo + +```bash +cd mi-sota +b2g seed "(information retrieval OR IR) AND (multilingual OR cross-lingual) AND (method OR approach)" --min-year 2015 --max-results 250 +``` + +bib2graph descarga papers desde OpenAlex y los guarda en `.duckdb` dentro de la carpeta. + +### Opción 2: Con ayuda de un agente + +Puedes pedirle al agente (Claude, ChatGPT, etc.) que: + +1. Genere la ecuación de búsqueda a partir de tu pregunta. +2. Execute el comando `b2g seed` en tu máquina. +3. Verifique los resultados. -Prompt: +**Prompt:** ```text -Instalá bib2graph con pip. +Tengo mi pregunta de investigación: +[TU PREGUNTA] -Usá esta ecuación de búsqueda en OpenAlex: -(information retrieval OR IR OR search) -AND (multilingual OR cross-lingual) -AND (method OR approach OR framework) +Propón una ecuación de búsqueda para bib2graph. +Luego dame el comando exacto para ejecutar: +b2g seed "[ecuacion]" --min-year 2015 --max-results 250 + +Muestra qué debería ver después de ejecutarlo. +``` -Sembrá hasta 250 papers desde 2015. +El agente genera la ecuación y tú ejecutas el comando en tu terminal. Luego: -Mostrame: -- Total de papers -- Distribución por año (gráfico) -- Top 10 autores por cantidad de papers -- Años: mín y máx +```bash +b2g read stats --group-by year ``` +Para ver la distribución temporal. + ### Verificación -Mirá el corpus trayéndote un resumen: +Revisa el corpus: -```text -Listá 20 papers al azar del corpus con título y año. -¿Todos tienen relación directa con mi tema? -Si hay ruido, ajustemos la ecuación. +```bash +b2g read list --query "tus_palabras_clave" | head -20 ``` +¿Todos tienen relación directa con tu tema? Si hay ruido sistemático, ajusta la +ecuación y vuelve a ejecutar `b2g seed` en una carpeta nueva. + ### Punto de decisión - **Corpus muy pequeño (<50 papers)?** Abre la ecuación (menos `AND`, más sinónimos). @@ -183,7 +241,7 @@ Expandí el corpus usando forrajeo (backward chaining): seguí una capa de referencias de los papers ya en el corpus y agregá hasta 100 papers nuevos. -Mostrame: +Muestra: - Cuántos papers nuevos se agregaron - Si hay papers muy antiguos (pre-2000): ¿los mantengo o descarto? ``` @@ -219,7 +277,7 @@ INCLUSIÓN (decisión final) ### Con Claude -Pedile a Claude: +Pídele a Claude: ```text Hacé curación PRISMA del corpus. Revisá cada paper: @@ -230,14 +288,14 @@ Hacé curación PRISMA del corpus. Revisá cada paper: 5. En otro caso: ACEPTAR Mostrá un resumen: cuántos ACCEPTED, REJECTED, CANDIDATE. -Listá 5 ejemplos de RECHAZADOS con razón. +Lista 5 ejemplos de RECHAZADOS con razón. ``` ### Checklist - [ ] ¿Documenté mis criterios explícitamente? - [ ] ¿El corpus ACCEPTED quedó entre 100–300 papers? -- [ ] ¿Revisé una muestra de rechazados para asegurarme de que no falta algo obvio? +- [ ] ¿Revisaste una muestra de rechazados para asegurarme de que no falta algo obvio? - [ ] ¿Hay equilibrio entre años (no es monocromático)? --- @@ -266,9 +324,9 @@ Construí 3 redes del corpus ACCEPTED usando bib2graph: Para cada red: - Detectá comunidades usando Louvain (clustering) -- Mostrame una visualización coloreada por comunidad +- Muestra una visualización coloreada por comunidad - Reportá: # nodos, # aristas, # comunidades -- Listá los 3 papers más centrales (mayor grado) de cada comunidad +- Lista los 3 papers más centrales (mayor grado) de cada comunidad ``` ### Qué esperar @@ -329,7 +387,7 @@ Responde estas preguntas: ### 1. ¿Cómo evolucionó el campo? ```text -Mostrame: +Muestra: - Gráfico de # papers/año en el corpus - Cómo cambiaron las comunidades (% de papers) año a año - ¿Hay una comunidad que crecía y ahora decrece? @@ -445,7 +503,7 @@ APÉNDICES ### Si usaste Claude web -Descargá: +Descarga: - `corpus.parquet` — tu semilla guardada (subirla a Claude luego para continuar). - `*.graphml` — networks para Gephi/Cytoscape. @@ -487,7 +545,7 @@ git commit -m "SOTA: [Tu Tema] — corpus, redes, reporte" ## Siguientes pasos -- **Análisis más profundo:** Elige una comunidad y hacé un sub-SOTA acotado. +- **Análisis más profundo:** Elige una comunidad y haz un sub-SOTA acotado. - **Integración con tu investigación:** Posicioná tu trabajo en el mapa — ¿dónde caés? ¿Dónde resolvés una tensión? - **Publicación:** Convertí el SOTA en un paper, capítulo de tesis, o entrada de From 0add9e6266ec7fd4a03b765a0843a0fff7848fc0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 18:29:23 +0000 Subject: [PATCH 5/6] =?UTF-8?q?docs:=20restructure=20guides=20=E2=80=94=20?= =?UTF-8?q?5=20acotadas=20vs.=201=20monol=C3=ADtica?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add landing page to docs/index.md showing 3 usage paths: 1. Without installing (5min) via agent 2. Learning step-by-step (3-4h) via CLI 3. Hybrid (1-2h) CLI + agent - Replace single guide (reporte-estado-del-arte.md) with 5 focused guides: 1. ecuacion-busqueda.md: Boolean structure, synonyms, testing 2. forrajeo.md: When to expand corpus via backward chaining 3. curacion-prisma.md: PRISMA 4 phases, decision criteria, CSV workflow 4. leer-redes.md: Interpret 5 networks, what each reveals 5. reporte.md: Report structure (7 sections), writing tips, examples - Update docs/guias/index.md: new grid layout with all 5 guides Each guide: - Answers 1 specific question (not tutorial, no repetition) - 30min-3h of work, depending - Includes checklists, examples, decision trees - Links to next guide in flow Language: Colombian neutral, tú form User flow: docs/index.md → choose path → tutorials or guides as needed Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01VfqH92jLCoRQ9G8AMA1Vgi --- docs/guias/curacion-prisma.md | 289 +++++++++++++++ docs/guias/ecuacion-busqueda.md | 254 +++++++++++++ docs/guias/forrajeo.md | 174 +++++++++ docs/guias/index.md | 74 +++- docs/guias/leer-redes.md | 298 +++++++++++++++ docs/guias/reporte-estado-del-arte.md | 500 -------------------------- docs/guias/reporte.md | 329 +++++++++++++++++ docs/index.md | 58 ++- 8 files changed, 1444 insertions(+), 532 deletions(-) create mode 100644 docs/guias/curacion-prisma.md create mode 100644 docs/guias/ecuacion-busqueda.md create mode 100644 docs/guias/forrajeo.md create mode 100644 docs/guias/leer-redes.md delete mode 100644 docs/guias/reporte-estado-del-arte.md create mode 100644 docs/guias/reporte.md diff --git a/docs/guias/curacion-prisma.md b/docs/guias/curacion-prisma.md new file mode 100644 index 0000000..a72e0e1 --- /dev/null +++ b/docs/guias/curacion-prisma.md @@ -0,0 +1,289 @@ +--- +title: Curación PRISMA paso a paso +--- + +# Curación PRISMA paso a paso + +La **curación** es donde TÚ decides qué papers quedan. PRISMA es una estructura +que ordena esa decisión en 4 fases, sin arbitrariedad. + +Esta guía: cómo aplicar PRISMA con bib2graph. + +!!! info "Alcance" + - Para alguien que tiene un corpus de siembra/forrajeo (~200–500 papers) + - Toma: 2–3 horas (depende del corpus) + - Herramienta: bib2graph CLI, Excel, Google Sheets + - Salida: corpus curado (100–300 ACCEPTED papers) + +--- + +## Las 4 fases PRISMA + +``` +IDENTIFICACIÓN +├─ ¿Duplicado? +├─ ¿Retractado? +└─ ¿Idioma? + +CRIBADO (Screening) +├─ Título relevante? +└─ Resumen toca el tema? + +ELEGIBILIDAD +├─ ¿Acceso al texto completo? +└─ ¿Métodos/resultados claros? + +INCLUSIÓN (Decisión final) +├─ ¿Relevancia alta? +└─ ¿Contribuye al SOTA? +``` + +Cada fase es un filtro. Al final: papers **ACCEPTED** (sí, quedan), +**REJECTED** (no, descartar), **CANDIDATE** (quizá más tarde). + +--- + +## Paso 1 — Extrae el corpus a CSV + +### Con CLI + +```bash +b2g curate dump --scope all > curate.csv +``` + +Abre el CSV en Excel o Google Sheets. Columnas: + +| id | title | authors | year | abstract | status | +|----|-------|---------|------|----------|--------| +| 1 | "Multilingual..." | Smith et al | 2020 | "This paper..." | PENDING | + +Nota: el CSV tiene campos adicionales (DOI, source_id, etc.), pero esos 6 te interesan. + +### Con agente + +```text +Exportá mi corpus a CSV con: +- id +- title +- authors +- year +- abstract +- Una columna "status" donde pueda escribir ACCEPTED/REJECTED/CANDIDATE + +Dame el CSV para descargarlo. +``` + +--- + +## Paso 2 — Criterios explícitos por fase + +Antes de curar, **documentá tus criterios**. Esto es clave para reproducibilidad. + +### IDENTIFICACIÓN + +| Criterio | Acción | +|----------|--------| +| ¿Título exactamente idéntico a otro? | REJECTED (duplicado) | +| ¿DOI retractado según Retraction Watch? | REJECTED (retractado) | +| ¿Idioma ≠ inglés? | REJECTED (si tu scope es inglés) | + +### CRIBADO + +| Criterio | Acción | +|----------|--------| +| Título no menciona ningún término clave de tu pregunta | REJECTED | +| Resumen sugiere que toca el tema pero tangencialmente | REJECTED | +| Título + resumen = claramente relevante | ACEPTA para elegibilidad | + +### ELEGIBILIDAD + +| Criterio | Acción | +|----------|--------| +| Texto completo no disponible (paywall, pdf no existe) | CANDIDATE (revisás después) | +| Métodos o resultados vagos/especulativos | CANDIDATE (quizá sirva) | +| Métodos/resultados claros y reproducibles | ACEPTA para inclusión | + +### INCLUSIÓN + +| Criterio | Acción | +|----------|--------| +| Relevancia alta + aporta al SOTA | ACCEPTED | +| Relevancia media pero aporta una perspectiva diferente | ACCEPTED | +| Baja relevancia + poco aporte | REJECTED | + +--- + +## Paso 3 — Cura el CSV + +### Estrategia: **dos pasadas** + +**Pasada 1 (rápida):** Título + abstract, sin pensar mucho. REJECTED o ACCEPTED. +**Pasada 2 (lenta):** Los PENDING. Aquí pensás, decidís CANDIDATE o ACCEPTED. + +### Proceso manual + +Abre el CSV en Excel/Sheets. Para cada fila: + +1. Lee **título** +2. Lee **abstract** (si hay) +3. Aplica **criterios de tu fase actual** (IDENTIFICACIÓN → CRIBADO → ELEGIBILIDAD → INCLUSIÓN) +4. Escribe en columna `status`: `ACCEPTED`, `REJECTED`, o `CANDIDATE` + +### Con agente (semi-automático) + +```text +Ayudame a curar este corpus. Para cada paper, dame un recomendación: + +Criterios: +- REJECTED si: título fuera de [TU TEMA], no hay métodos claros, es un duplicado +- CANDIDATE si: texto completo no disponible, relevancia media +- ACCEPTED si: relevancia alta, aporta al SOTA + +Paper 1: +- Título: "Multilingual Search in Social Networks" +- Año: 2015 +- Abstract: "We propose a method..." +- Tu recomendación: ? + +[Y así con los demás...] +``` + +El agente propone, tú tomas la decisión final. + +--- + +## Paso 4 — Aplica en bib2graph + +Cuando termines el CSV con tus decisiones: + +```bash +b2g curate apply curate.csv +``` + +bib2graph actualiza el corpus: ACCEPTED quedan en el corpus, REJECTED se marcan, +CANDIDATE quedan pero como "en revisión". + +### Verificación + +```bash +b2g read stats +``` + +Debería mostrar algo así: + +``` +Status breakdown: +- ACCEPTED: 245 papers (main corpus) +- REJECTED: 95 papers +- CANDIDATE: 30 papers +``` + +--- + +## Paso 5 — Revisa outliers + +Después de curar, revisa: + +### Papers más antiguos ACCEPTED + +```bash +b2g read list --status ACCEPTED | sort -k3 | head -5 +``` + +¿Son fundacionales o ruido? Si ruido, marca como REJECTED. + +### Papers sin abstract + +```bash +b2g read list --status ACCEPTED | grep "abstract: null" +``` + +Sin resumen, es más riesgo. CANDIDATE o REJECTED. + +### Gráfico temporal + +```bash +b2g read stats --group-by year +``` + +¿El corpus está concentrado en 3 años o distribuido? (Distribuido = más robusto) + +--- + +## Paso 6 — Documenta tu decisión + +Guardá un archivo `CURATION_NOTES.md`: + +```markdown +# Curación PRISMA — [Tu tema] + +## Decisión tomada: 2024-06-30 + +### Criterios de Identificación +- Duplicados: rechazados sin revisar +- Idioma: solo inglés +- Retractados: 0 encontrados + +### Criterios de Cribado +- Título debe mencionar "recuperación de información" O "multilingual" +- Resumen debe proponer un método/enfoque (no solo reseña) + +### Criterios de Elegibilidad +- Texto completo disponible = más peso que CANDIDATE +- Métodos reproducibles = ACCEPTED + +### Criterios de Inclusión +- Relevancia media + aporta perspectiva nueva = ACCEPTED +- Relevancia baja = REJECTED (sin excepciones) + +### Resultado +- Comenzamos con: 315 papers +- Rechazados: 70 +- Candidatos (para revisar después): 20 +- Aceptados (corpus final): 225 + +### Nota +Si después encontramos papers clave en los CANDIDATE, +los movemos a ACCEPTED. La curación es iterativa. +``` + +--- + +## Checklist + +- [ ] Extraje corpus a CSV (`b2g curate dump`) +- [ ] Documenté criterios PRISMA de cada fase +- [ ] Curé el CSV: cada paper tiene status (ACCEPTED/REJECTED/CANDIDATE) +- [ ] Apliqué cambios: `b2g curate apply curate.csv` +- [ ] Verifiqué con `b2g read stats` — corpus final es 100–300 papers +- [ ] Documenté notas de curación en CURATION_NOTES.md + +--- + +## Errores comunes + +❌ **"Voy a curar rápido, sin criterios."** +→ Resultado: decisiones inconsistentes, imposible reproducir. + +✅ **Documentá criterios primero, cura segundo.** + +--- + +❌ **"Si una paper parece remotamente relevante, la acepto."** +→ Resultado: corpus con ruido, análisis de redes confuso. + +✅ **Sé estricto. Es OK rechazar.** + +--- + +❌ **"Curación es para perfeccionistas."** +→ Curación define la calidad del análisis que sigue. No es opcionable. + +✅ **Invierte 2–3 horas aquí, ahorra 10 después.** + +--- + +## Siguiente + +Cuando tengas un corpus ACCEPTED limpio: +- [Guía: Leer las 5 redes](leer-redes.md) diff --git a/docs/guias/ecuacion-busqueda.md b/docs/guias/ecuacion-busqueda.md new file mode 100644 index 0000000..e123f40 --- /dev/null +++ b/docs/guias/ecuacion-busqueda.md @@ -0,0 +1,254 @@ +--- +title: Cómo armar una ecuación de búsqueda que NO trae basura +--- + +# Cómo armar una ecuación de búsqueda que NO trae basura + +Una **ecuación de búsqueda** es cómo le dices a OpenAlex exactamente qué buscar. +Si la haces mal, traes 50.000 papers. Si la haces bien, traes 200 relevantes. + +Esta guía es una receta para llegar a una ecuación acotada, testeada, sin ruido. + +!!! info "Alcance" + - Para alguien que tiene una pregunta de investigación clara + - Toma: 30 minutos de escritura + testing + - Herramienta: lápiz/papel, OpenAlex (o bib2graph), un agente opcional + +--- + +## La estructura de una ecuación + +``` +(concepto_A1 OR concepto_A2 OR concepto_A3) +AND (concepto_B1 OR concepto_B2) +AND (concepto_C1 OR concepto_C2) +``` + +**Cada paréntesis = un concepto central de tu pregunta.** +**Dentro del paréntesis = sinónimos unidos por OR.** +**Entre paréntesis = AND (todos deben estar presentes).** + +### Ejemplo real + +**Tu pregunta:** "¿Cómo se abordan los problemas de recuperación de información +en contextos multilingües?" + +**Desglose en 3 conceptos:** + +1. **Concepto A (la tarea):** recuperación de información, IR, search, retrieval +2. **Concepto B (la restricción):** multilingual, cross-lingual, polyglot, language-independent +3. **Concepto C (el tipo de artefacto):** method, approach, framework, system, architecture + +**Tu ecuación:** + +``` +(information retrieval OR IR OR search OR retrieval) +AND (multilingual OR cross-lingual OR language-independent OR polyglot) +AND (method OR approach OR framework OR system) +``` + +--- + +## Paso 1 — Identifica 3 conceptos clave + +Desde tu pregunta de investigación, extrae **3 dimensiones**: + +| Pregunta | Concepto A | Concepto B | Concepto C | +|----------|-----------|-----------|-----------| +| ¿Cómo se abordan problemas de IR en contextos multilingües? | IR/recuperación | Multilingüe | Métodos/enfoques | +| ¿Cuál es el estado del arte en alineación de valores en LLMs? | Alineación/alignment | LLM/lenguaje grande | Enfoques/métodos | +| ¿Qué métodos existen para detección de fake news en redes sociales? | Fake news/desinformación | Redes sociales/social media | Detección/identificación | + +**Checklist:** + +- [ ] ¿Cada concepto es una dimensión clara de mi pregunta? +- [ ] ¿Están en orden de especificidad (A = más genérico, C = más acotado)? +- [ ] ¿Me falta un cuarto concepto que quite mucho ruido? + +--- + +## Paso 2 — Genera sinónimos para cada concepto + +Para cada concepto, escribe **2–4 sinónimos** que un paper podría usar. + +### Truco: búsqueda rápida + +Abre Google Scholar o bib2graph y busca directamente un término de cada concepto. +Mira los títulos de los primeros 10 papers: ¿qué palabras ves repetidas? + +### Ejemplo + +**Concepto A (IR):** +- information retrieval ✓ +- information seeking ✓ +- search ✓ +- retrieval ✗ (demasiado genérico, traería biología) + +**Concepto B (Multilingüe):** +- multilingual ✓ +- cross-lingual ✓ +- language-agnostic ✓ +- polyglot ✓ + +**Concepto C (Métodos):** +- method ✓ +- approach ✓ +- framework ✓ +- system ✓ +- algorithm ✗ (muy específico, traería solo papers de algoritmos) + +--- + +## Paso 3 — Arma la ecuación + +Copia el template: + +``` +(concepto_A1 OR concepto_A2 OR concepto_A3) +AND (concepto_B1 OR concepto_B2) +AND (concepto_C1 OR concepto_C2) +``` + +Reemplaza con tus sinónimos: + +``` +(information retrieval OR information seeking OR search) +AND (multilingual OR cross-lingual) +AND (method OR approach OR framework) +``` + +--- + +## Paso 4 — TESTEA (esto es crítico) + +**Nunca** lances una ecuación sin testear. Trae 50 papers y revisa los títulos. + +### Con bib2graph CLI + +```bash +b2g init test-ecuacion +cd test-ecuacion +b2g seed "tu_ecuacion_aqui" --max-results 50 +b2g read list | head -20 +``` + +### Con agente + +```text +Ejecuta esta ecuación en bib2graph y trae 50 papers. +Muestra los títulos. ¿Todos tienen relación directa con [TU TEMA]? +``` + +### Revisa los títulos + +``` +✓ "Multilingual Information Retrieval: A Cross-lingual Approach" +✓ "Polyglot Search Methods for Heterogeneous Document Collections" +✓ "Language-agnostic Retrieval in Multilingual Corpora" + +✗ "Semantic Retrieval Algorithms" (no menciona multilingüe) +✗ "Social Media Search Optimization" (no es recuperación de info) +``` + +--- + +## Paso 5 — Ajusta según el ruido + +### Si trae MUY POCO (<50 papers) + +**Abre la ecuación:** + +- Quita un `AND` o reemplázalo por `OR`. +- Agrega más sinónimos a cada concepto. +- Usa palabras más genéricas. + +``` +Antes: (information retrieval) AND (multilingual) AND (method) +Después: (information retrieval OR search) AND (multilingual OR cross-lingual) + [sacamos el tercer AND] +``` + +### Si trae MUCHO (>1000 papers) + +**Cierra la ecuación:** + +- Agrega un cuarto concepto `AND NOT` que excluya ruido. +- Usa más sinónimos específicos. +- Agrega delimitadores temporales o de dominio. + +``` +Antes: (information retrieval) AND (multilingual) +Después: (information retrieval) AND (multilingual) + AND (method OR framework) AND NOT (machine translation) + [añadimos Concepto C + exclusión] +``` + +### Si trae RUIDO sistemático + +Si ves que muchos papers son sobre "X" pero no te importan, excluye: + +``` +AND NOT (machine translation OR neural machine translation) +AND NOT (social media OR sentiment analysis) +``` + +--- + +## Paso 6 — Documentá tu decisión + +**Importante:** guarda tu ecuación final CON comentarios. + +``` +# Pregunta: ¿Cómo se abordan problemas de IR en contextos multilingües? +# Rango: 2015–2024 (últimos 10 años) +# Objetivo: ~250 papers, sensibilidad alta + +# Concepto A: IR (recuperación, búsqueda) +# Concepto B: Multilingüe (cross-lingual, polyglot) +# Concepto C: Métodos/enfoques (no solo algoritmos teóricos) +# Exclusión: Machine translation (tema relacionado pero diferente) + +(information retrieval OR information seeking OR search) +AND (multilingual OR cross-lingual OR language-agnostic OR polyglot) +AND (method OR approach OR framework OR system) +AND NOT (machine translation OR neural translation) +``` + +--- + +## Checklist final + +- [ ] Mi ecuación tiene 3–4 conceptos, cada uno con 2–4 sinónimos +- [ ] Testeé con 50 papers y revisé títulos +- [ ] Entre 100–500 papers traídos (ajusté si estaba fuera de rango) +- [ ] Documenté mis decisiones (para reproducibilidad) +- [ ] ¿Todos los papers traídos son relevantes? (sin ruido sistemático) + +--- + +## Tip: Interactuar con un agente + +Si usas Claude, ChatGPT o similar: + +```text +Mi pregunta de investigación es: +[TU PREGUNTA] + +Propón una ecuación de búsqueda en OpenAlex/bib2graph: +1. Con 3 conceptos claros (sintaxis: (A1 OR A2) AND (B1 OR B2) AND (C1 OR C2)) +2. Con sinónimos relevantes +3. Con exclusiones si hay ruido conocido + +Luego, dame el comando exacto para testear: +b2g seed "[tu_ecuacion]" --max-results 50 +``` + +El agente genera, tú testeas. Esto es más rápido que hacerlo solo. + +--- + +## Siguiente + +Cuando tu ecuación traiga papers relevantes sin ruido: +- [Guía: ¿Expando el corpus? (Forrajeo)](forrajeo.md) +- [Guía: Curación PRISMA paso a paso](curacion-prisma.md) diff --git a/docs/guias/forrajeo.md b/docs/guias/forrajeo.md new file mode 100644 index 0000000..b4bd248 --- /dev/null +++ b/docs/guias/forrajeo.md @@ -0,0 +1,174 @@ +--- +title: "¿Expando el corpus? — Guía sobre forrajeo" +--- + +# ¿Expando el corpus? — Cuándo y cómo hacer forrajeo + +El **forrajeo** (backward chaining) busca papers que no aparecieron en tu búsqueda +inicial, pero que son citados por los papers que sí encontraste. + +Esta guía: ¿CUÁNDO hacerlo? ¿CUÁNDO NO? ¿CÓMO sin perderse? + +!!! info "Alcance" + - Para alguien que ya tiene un corpus de siembra (~100–300 papers) + - Toma: 15 minutos de decisión + 30 min de ejecución + - Herramienta: bib2graph CLI o agente + +--- + +## Qué es el forrajeo + +``` +Corpus inicial: +├─ Paper A +├─ Paper B (cita a Paper X, Y, Z) +└─ Paper C + +Forrajeo (1 capa): +└─ Busca Papers X, Y, Z (citados por B pero no en corpus inicial) + └─ Trae ~20–50 papers nuevos +``` + +**Ventaja:** Aumenta sensibilidad sin ruido (los nuevos fueron citados por relevantes). + +**Riesgo:** Trae papers muy antiguos, de dominios tangenciales, o que no aplican. + +--- + +## Paso 1 — Decide si forrajear + +### Forrajea SÍ si: + +✅ Tu tema es **muy específico** (no "machine learning", sino "alineación de valores en LLMs"). +✅ Tu corpus inicial es **pequeño** (<100 papers) y quieres más densidad. +✅ Buscas **máxima cobertura** — no quieres perderte trabajos clave aunque sean antiguos. +✅ Tienes **tiempo** — forrajeo agrega 30 min de ejecución + revisión. + +### No forrajees si: + +❌ Tu tema es **genérico** — forrajeo podría traer decenas de miles de papers. +❌ Tu corpus inicial ya es **grande** (>500 papers) — probablemente alcanza. +❌ Necesitas un SOTA **rápido** — la prueba de concepto sin forrajeo es suficiente. +❌ El tiempo es crítico — aprioriza curación sobre expansión. + +### Tu decisión + +Responde: + +1. **¿Es mi tema altamente específico?** Sí/No +2. **¿Mi corpus inicial es < 100 papers?** Sí/No +3. **¿Tengo 1–2 horas extras?** Sí/No + +**Si respondiste SÍ a 2+ preguntas → forrajea.** +**Si respondiste No a la mayoría → salta directo a curación.** + +--- + +## Paso 2 — Ejecuta el forrajeo + +### Con CLI + +```bash +cd tu-sota +b2g chain --depth 1 --limit 100 +``` + +**Opciones:** + +- `--depth 1`: Una capa de referencias (recomendado). +- `--limit 100`: Trae máximo 100 papers nuevos (ajusta según necesidad). +- Sin opciones: trae todo lo que encuentre. + +### Con agente + +```text +Expandí mi corpus usando forrajeo (backward chaining): +- Corpus actual: [X papers] +- Límite: trae máximo 100 papers nuevos +- Profundidad: una capa (citados directamente por mis papers) + +Mostrame: +- Cuántos papers nuevos se agregaron +- Rango de años (¿muy antiguos?) +- Si hay clusters temáticos nuevos +``` + +--- + +## Paso 3 — Revisa lo que trajo + +Después de ejecutar `b2g chain`, **revisa lo nuevo antes de seguir**. + +### Inspecciona los papers nuevos + +```bash +b2g read list --status candidate | head -20 +``` + +### Preguntas clave + +1. **¿Hay papers muy antiguos (pre-2000)?** + - Sí → Probablemente foundational, mantenlos. + - No → Bien, son contemporáneos. + +2. **¿Hay clusters temáticos que NO esperabas?** + - Sí → Revisa si son tangenciales (y rechaza luego en curación). + - No → Buen señal. + +3. **¿El tamaño es manejable?** + - Corpus total < 1000 papers → adelante. + - Corpus total > 2000 papers → considera rechazar duplicados o muy antiguos. + +--- + +## Paso 4 — Ajusta si hace falta + +### Si trajo MUY POCO (<20 papers nuevos) + +Probablemente tu búsqueda inicial fue muy acotada. Es OK — no fuerces forrajeo. +Pasa a curación con lo que tienes. + +### Si trajo MUCHO (>500 papers nuevos) + +Probablemente tu búsqueda inicial fue genérica. Opciones: + +1. **Rechaza papers muy antiguos:** `b2g curate filter --min-year 2010` +2. **Rechaza dominios tangenciales:** marca como REJECTED en curación +3. **Usa keywords para sub-seleccionar:** `b2g read list --query "tu_keyword"` + +### Si trajo papers fuera de scope + +Marca como REJECTED en la curación siguiente. No son un problema, solo ruido. + +--- + +## Paso 5 — Documentá tu decisión + +Antes de pasar a curación, documentá: + +``` +# DECISIÓN DE FORRAJEO +Fecha: 2024-06-30 +Corpus antes: 250 papers +Forrajeo ejecutado: sí (depth=1, limit=100) +Corpus después: 315 papers (+65 nuevos) +Observación: Papers nuevos son relevantes, años 2008–2023 +Decisión: Mantener todos para curación (PRISMA filtrará) +``` + +--- + +## Checklist + +- [ ] Decidí conscientemente si forrajear (no por defecto) +- [ ] Ejecuté `b2g chain --depth 1 --limit 100` +- [ ] Revisé los papers nuevos (años, temas) +- [ ] Corpus final es manejable (< 2000 papers) +- [ ] Documenté la decisión + +--- + +## Siguiente + +Después de forrajeo (o decisión de no forrajear): +- [Guía: Curación PRISMA paso a paso](curacion-prisma.md) diff --git a/docs/guias/index.md b/docs/guias/index.md index 6ca1bac..4a5f79d 100644 --- a/docs/guias/index.md +++ b/docs/guias/index.md @@ -4,27 +4,71 @@ title: Guías (how-to) # Guías (how-to) -Las **guías** son recetas orientadas a una tarea concreta: ya se sabe qué se quiere -hacer y se buscan los pasos para lograrlo. Si en cambio se quiere *aprender* desde -cero, comience por los [Tutoriales](../tutoriales/index.md). +Las **guías** son recetas para decisiones puntuales: ya sabes qué quieres hacer, +buscas cómo hacerlo bien. Si en cambio quieres *aprender* desde cero, comienza por los [Tutoriales](../tutoriales/index.md). -## Guías disponibles +Las guías están organizadas por **paso del flujo.** Úsalas como referencia mientras +trabajas. + +## Guía 1: Ecuación de búsqueda + +
+ +- :material-magnify: **[Cómo armar una ecuación que NO trae basura](ecuacion-busqueda.md)** + + Estructura booleana, sinónimos, testeo de 50 papers, ajustes. + 30 minutos para una ecuación acotada y limpia. + +
+ +## Guía 2: Forrajeo (expansión del corpus) + +
+ +- :material-sitemap-branch: **[¿Expando el corpus? — Cuándo y cómo forrajear](forrajeo.md)** + + Decides si vale la pena forrajeo (backward chaining). Cuándo hacerlo, cuándo no. + 15 minutos de decisión + 30 minutos de ejecución. + +
+ +## Guía 3: Curación + +
+ +- :material-checkbox-marked-outline: **[Curación PRISMA paso a paso](curacion-prisma.md)** + + Las 4 fases de PRISMA: Identificación → Cribado → Elegibilidad → Inclusión. + Documentá criterios, cura en CSV, aplica en bib2graph. + 2–3 horas de trabajo manual, pero riguroso. + +
+ +## Guía 4: Interpretación de redes + +
+ +- :material-network: **[Leer las 5 redes — Qué significan](leer-redes.md)** + + Acoplamiento (sub-temas), co-citación (influentes), co-autoría (equipos), + keywords, instituciones. Qué mirar en cada red, qué documentar. + +
+ +## Guía 5: Redacción del reporte
-- :material-file-document: **[Cómo elaborar un reporte de estado del arte](reporte-estado-del-arte.md)** +- :material-file-document: **[Del corpus al reporte — Estructura y redacción](reporte.md)** - Receta completa de 10 pasos: de la pregunta de investigación a un documento - estructurado con mapeo de comunidades, tensiones, actores clave e huecos - de investigación. Incluye curación PRISMA y análisis de tendencias. + Template de 7 secciones (resumen → conclusiones). Cómo convertir datos en prosa. + 3–4 horas de redacción, documentada paso a paso.
-## Otras referencias +## Complementario -- [Quickstart](../getting-started/quickstart.md) — el camino más corto a un - GraphML. -- [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos y opciones. -- [API de Python](../reference/python-api.md) — para uso como librería. -- [Arquitectura](../ARCHITECTURE.md) — el modelo mental del ciclo y las redes. -- [Tutoriales](../tutoriales/index.md) — aprende desde cero. +- [Tutoriales](../tutoriales/index.md) — aprende desde cero (quick start o completo) +- [Quickstart](../getting-started/quickstart.md) — ciclo mínimo en 2 minutos +- [Referencia CLI](../reference/cli.md) — todos los comandos +- [API Python](../reference/python-api.md) — como librería diff --git a/docs/guias/leer-redes.md b/docs/guias/leer-redes.md new file mode 100644 index 0000000..a2e9555 --- /dev/null +++ b/docs/guias/leer-redes.md @@ -0,0 +1,298 @@ +--- +title: Leer las 5 redes — Qué significan +--- + +# Leer las 5 redes — Qué significan + +Después de construir redes, comes a interpretarlas. Cada red responde una pregunta +diferente sobre tu campo. Esta guía: qué mirar en cada una. + +!!! info "Alcance" + - Para alguien que ejecutó `b2g build` y tiene las redes visualizadas + - Toma: 1–2 horas (explorando + anotando) + - Herramienta: Gephi, Cytoscape, o `b2g read top` + - Salida: Entendimiento del campo + anotaciones para redacción + +--- + +## Las 5 redes que bib2graph construye + +bib2graph crea 5 proyecciones del corpus. **No uses las 5 — típicamente usa 2–3.** + +``` +1. Acoplamiento bibliográfico (papers) +2. Co-citación (papers) +3. Co-autoría (autores) +4. Co-ocurrencia de keywords +5. Colaboración institucional +``` + +La **más importante es la 1** (Acoplamiento). Empezá ahí. + +--- + +## 1. RED DE ACOPLAMIENTO BIBLIOGRÁFICO + +**Pregunta que responde:** ¿Cuáles son los sub-temas del campo? + +### Qué es + +Dos papers se **acoplan** si citan las mismas referencias. + +``` +Paper A cita: [Ref 1, Ref 2, Ref 3] +Paper B cita: [Ref 2, Ref 3, Ref 4] + +Similitud: comparten 2 referencias +Acoplamiento: fuerte → aparecen cerca en la red +``` + +### Qué buscas + +**Comunidades** (clusters de colors). Cada comunidad = un sub-tema. + +### Cómo interpretarla + +| Elemento | Significa | +|----------|-----------| +| **Nodo** | Un paper | +| **Tamaño del nodo** | Grado (cuántos otros papers lo citan) | +| **Línea entre nodos** | Acoplamiento (comparten referencias) | +| **Color** | Comunidad (detectada por Louvain) | +| **Densidad local** | Subgrupo temático (si hay clusters densos) | + +### Preguntas clave + +1. **¿Cuántas comunidades ves?** (típicamente 3–8) + - Pocas (1–2) → campo homogéneo, enfoque único + - Muchas (10+) → campo fragmentado, múltiples escuelas + +2. **¿Qué hace cada comunidad?** + - Lee 2–3 papers de mayor grado en cada comunidad + - Escribe: "Comunidad 1: Enfoques neurales" + +3. **¿Hay comunidades aisladas?** + - Sí → campo fragmentado, sin diálogo + - No → comunidades conectadas, debate activo + +4. **¿Una comunidad domina?** + - Sí → tendencia clara, escuela hegemónica + - No → equilibrio de enfoques + +### Tip: Extrae top papers por comunidad + +Con CLI: + +```bash +b2g read top --kind bibliographic_coupling --top 20 +``` + +Esto te da los 20 papers más centrales (mayor grado). Son buenas "referencias canónicas". + +Con Gephi: + +1. Abre el `.graphml` en Gephi +2. Filtra por color (comunidad) +3. Ordena nodos por tamaño (grado) +4. Anota los top 3 de cada comunidad + +--- + +## 2. RED DE CO-CITACIÓN + +**Pregunta que responde:** ¿Cuáles son los papers / autores / trabajos más influyentes? + +### Qué es + +Dos papers se **co-citan** si aparecen juntos en las referencias de otros papers. + +``` +Paper A refiere a: [Clásico1, Clásico2, Nuevo1] +Paper B refiere a: [Clásico1, Clásico2, Nuevo2] + +Clásico1 y Clásico2 se co-citan frecuentemente +→ Son referencias canónicas +``` + +### Qué buscas + +**Papers que actúan como "hubs" de la red.** Estos son influyentes. + +### Cómo interpretarla + +| Elemento | Significa | +|----------|-----------| +| **Nodo** | Un paper | +| **Tamaño del nodo** | Co-citación (cuántos otros lo citan juntos) | +| **Línea fuerte** | Frecuentemente citados juntos | +| **Hub central** | Paper/autor/trabajo canónico | + +### Preguntas clave + +1. **¿Hay un hub central claro?** + - Sí → hay un "clásico" que todos citan + - No → múltiples referencias, no hay consenso + +2. **¿Qué papers están en el hub?** + - Anota: estos son obligatorios para tu SOTA + - Leelos: dan contexto de la escuela + +3. **¿Hay papers recientes en el hub?** + - Sí → el campo evoluciona, hay nuevas referencias + - No → campo estancado, solo cita clásicos antiguos + +4. **¿Qué autores o labs aparecen repetidamente?** + - Estos son actores clave del campo + +### Comparación Acoplamiento vs. Co-citación + +| Aspecto | Acoplamiento | Co-citación | +|--------|---|---| +| **Responde** | ¿Sub-temas (presente)? | ¿Influentes (pasado)? | +| **Densidad** | Más densa | Más dispersa | +| **Utilidad** | Entender estructura actual | Entender genealogía intelectual | +| **Nodos** | Papers en tu corpus | Papers citados por tu corpus | + +--- + +## 3. RED DE CO-AUTORÍA + +**Pregunta que responde:** ¿Quiénes trabajan juntos? ¿Dónde están los equipos? + +### Qué es + +Dos autores se **co-autorizan** si escriben papers juntos. + +### Qué buscas + +**Clusters de autores que colaboran persistentemente.** + +### Cómo interpretarla + +| Elemento | Significa | +|----------|-----------| +| **Nodo** | Un autor | +| **Línea** | Colaboración (escribieron juntos) | +| **Cluster** | Equipo o laboratorio | +| **Tamaño del nodo** | Productividad (cuántos papers) | + +### Preguntas clave + +1. **¿Hay equipos cohesivos (clusters densos)?** + - Sí → campos maduros, labs establecidos + - No → trabajo más individual o colaboraciones puntuales + +2. **¿Qué autores aparecen en múltiples equipos (hubs)?** + - Estos son "conectores" entre grupos + +3. **¿Hay colaboración internacional?** + - Sí → campo globalizado + - No → investigación regional/aislada + +### Tip: Menos importante que Acoplamiento + +Co-autoría es útil pero secundaria. Si tienes poco tiempo, **prioriza Acoplamiento + Co-citación.** + +--- + +## 4. RED DE CO-OCURRENCIA DE KEYWORDS + +**Pregunta que responde:** ¿Qué términos se usan juntos? ¿Cuál es el vocabulario del campo? + +### Qué es + +Dos keywords se **co-ocurren** si aparecen en el mismo abstract. + +### Qué buscas + +**Clusters de vocabulario.** + +### Preguntas clave + +1. **¿Qué keywords son centrales?** (muchas conexiones) + - Estos definen el core del campo + +2. **¿Qué keywords son periféricas?** (pocas conexiones) + - Estos definen sub-especialidades + +3. **¿Hay vocabulario que esperabas pero no aparece?** + - Eso es un hueco de investigación + +--- + +## 5. RED DE COLABORACIÓN INSTITUCIONAL + +**Pregunta que responde:** ¿Qué universidades/labs colaboran? + +### Qué es + +Dos instituciones **colaboran** si sus investigadores co-autorizan papers. + +### Preguntas clave + +1. **¿Hay universidades dominantes?** (muchos papers) +2. **¿Hay colaboración: local, regional, global?** +3. **¿Qué institutions lideran?** (grado más alto) + +--- + +## Flujo recomendado de lectura + +1. **Acoplamiento primero** (20 min) + - Entiende sub-temas + - Anota comunidades + +2. **Co-citación después** (20 min) + - Identifica papers canónicos + - Anotalos como "obligatorios" + +3. **Co-autoría opcional** (10 min si tienes tiempo) + - Entiende quién trabaja con quién + +4. **Keywords + Instituciones (skip si no tienes tiempo)** + +--- + +## Qué documentar + +Mientras lees, crea una tabla: + +```markdown +# Lectura de Redes + +## Acoplamiento Bibliográfico + +| Comunidad | Keywords | Top Papers | Tensión | +|-----------|----------|-----------|---------| +| Enfoque A | [kw1, kw2] | [Paper1, Paper2] | vs. Enfoque B: diferencia en [aspecto] | +| Enfoque B | [kw3, kw4] | [Paper3, Paper4] | vs. Enfoque A: diferencia en [aspecto] | + +## Co-citación + +| Paper Canónico | Autores | Año | Por qué influyente | +|---|---|---|---| +| "Seminal Work..." | Smith et al | 2005 | Define el paradigma | + +## Notas + +- Comunidad 1 y 2 no se conectan → hay un debate abierto +- Keyword "X" está ausente → hueco de investigación +``` + +--- + +## Checklist + +- [ ] Abrí Acoplamiento en Gephi o visualicé con `b2g read top` +- [ ] Identifiqué 3–5 comunidades, las nombré +- [ ] Extraje top 2–3 papers de cada comunidad +- [ ] Abrí Co-citación, identifiqué papers canónicos +- [ ] Documenté en una tabla: comunidades + papers clave +- [ ] Identifiqué 2–3 tensiones entre comunidades + +--- + +## Siguiente + +Con las redes entendidas, listo para redactar: +- [Guía: Del corpus al reporte](reporte.md) diff --git a/docs/guias/reporte-estado-del-arte.md b/docs/guias/reporte-estado-del-arte.md deleted file mode 100644 index e46e64a..0000000 --- a/docs/guias/reporte-estado-del-arte.md +++ /dev/null @@ -1,500 +0,0 @@ ---- -title: Cómo elaborar un reporte de estado del arte ---- - -# Cómo elaborar un reporte de estado del arte - -Esta guía es una receta para construir, analizar y reportar un **estado del arte (SOTA)** riguroso -sobre un tema de investigación, utilizando bib2graph como herramienta central. El resultado es un -documento estructurado con identificación de tensiones, escuelas de pensamiento, huecos de -investigación y una síntesis de tendencias. - -Es para alguien que ya sabe qué quiere investigar y busca los pasos concretos; si en cambio -se quiere aprender desde cero, véase el [Tutorial: Tu primera red bibliométrica](../tutoriales/claude-code.md). - -!!! info "Scope" - - Corpus de 200–500 papers (ajustable según el tema). - - Redes bibliométricas: acoplamiento, co-citación, co-autoría. - - Análisis de comunidades y tendencias. - - Tiempo estimado: 4–6 horas (de investigador; el código: 30 min). - - Salida: reporte .docx/.md con figuras, matriz de tensiones y conclusiones. - -!!! warning "Requisitos" - - **Un flujo de bib2graph** (CLI en máquina local **o** Claude Code con ejecución). - - **Una pregunta de investigación clara** — no un tema genérico. - - **Opcional:** API key de OpenAlex (gratuita, para más de ~100 papers). - - **Herramienta de escritura:** Obsidian, Google Docs, Word o markdown + pandoc. - ---- - -## El flujo en síntesis - -``` -1. Pregunta → Ecuación de búsqueda (3 conceptos) -2. Siembra (OpenAlex, 200–500 papers) -3. Expansión por citaciones (forrajeo) — opcional, para corpus más denso -4. Curación manual (PRISMA filters, decisiones criterio) -5. Construcción de redes (acoplamiento, co-citación, co-autoría) -6. Lectura de comunidades (nombrado, keywords, tensiones) -7. Análisis de tendencias (temporal, institucional, autores influyentes) -8. Redacción del reporte -``` - ---- - -## Paso 1 — Afina tu pregunta de investigación - -**Entrada:** Una idea amplia sobre un tema. -**Salida:** Una pregunta de investigación clara y acotada. - -Una buena pregunta de investigación tiene esta forma: - -> ¿Cómo se ha abordado [**problema específico**] en el contexto de [**dominio**], -> entre [**rango temporal**]? ¿Cuáles son los enfoques dominantes, sus tensiones -> y los huecos sin explorar? - -### Ejemplo - -❌ *"Quiero estudiar inteligencia artificial."* -✅ *"¿Cómo se abordan los problemas de alineación de valores en modelos de lenguaje -grandes, y cuáles son las tensiones entre eficiencia computacional y robustez ética?"* - -### Preguntas de refinamiento - -1. **¿Es específica?** ¿Puedo traducirla a 3–5 palabras clave que filtren el ruido? -2. **¿Es temporal?** ¿Hay un rango de años que tenga sentido? (últimos 5–10 años suele ser lo adecuado para un SOTA). -3. **¿Es acotada?** ¿Espero 50 papers, 500 o 5000? (Ajusta la precisión de la ecuación). - ---- - -## Paso 2 — Elabora una ecuación de búsqueda - -**Entrada:** Pregunta de investigación. -**Salida:** Ecuación booleana con ~3 conceptos y sinónimos controlados. - -Una ecuación de búsqueda tiene esta estructura: - -``` -(término_A1 OR término_A2 OR término_A3) -AND (término_B1 OR término_B2) -AND (término_C1 OR término_C2) -``` - -Cada paréntesis es un **concepto**; los `OR` capturan sinónimos; los `AND` son obligatorios juntos. - -### Ejemplo - -Pregunta: *"¿Cómo se diseñan sistemas de recuperación de información en contextos multilingües?"* - -``` -(information retrieval OR IR OR search engines) -AND (multilingual OR cross-lingual OR language-agnostic) -AND (design OR architecture OR framework OR system) -``` - -### Consejos - -- **Evita genéricos.** "machine learning" sola atrapa decenas de miles de papers. -- **Sé específico en el cuarto concepto si hace falta.** Agrega un delimitador: - `AND (neural OR deep learning)` para descartar SOTA pre-2012. -- **Testa la ecuación.** Corre una búsqueda rápida de 50 papers y revisa los títulos. - Si ves ruido sistemático, ajusta. - ---- - -## Paso 3 — Siembra el corpus desde OpenAlex - -**Entrada:** Ecuación de búsqueda, rango de años. -**Salida:** Corpus inicial de ~200–300 papers. - -Usa bib2graph (CLI o Claude) para traer papers desde OpenAlex. - -### Con CLI local - -```bash -b2g init ./mi-sota -cd mi-sota -b2g seed "tu_ecuacion_aqui" --min-year 2015 -``` - -Verificá el corpus: - -```bash -b2g read list --query "your_keywords" -b2g read stats --group-by year -``` - -### Con Claude Code - -Envía un prompt como: - -```text -Sembrá un corpus desde OpenAlex usando esta ecuación: -(información retrieval OR IR) -AND (multilingüe OR cross-lingual) -Traé hasta 250 papers desde 2015. -Mostrame un resumen: cuántos papers, rango de años, top 5 autores por citaciones. -``` - -### Checklist - -- [ ] ¿El corpus tiene papers desde diferentes años (no es monocromático)? -- [ ] ¿Reconozco algunos autores o papeles influyentes en el rango? -- [ ] ¿El tamaño es manejable (200–500, no 5000)? - -Si el corpus es muy pequeño, abre la ecuación (menos `AND`, más `OR`). -Si es muy grande, ciérrala (agrega un concepto específico más). - ---- - -## Paso 4 — Expande por citaciones (opcional pero recomendado) - -**Entrada:** Corpus de siembra. -**Salida:** Corpus expandido (+20–50% papers nuevos) con mayor densidad de referencias. - -El forrajeo (o "chaining") busca papers no encontrados en la búsqueda inicial pero -citados por los que sí están. Aumenta la sensibilidad sin ruido. - -### Con CLI - -```bash -b2g chain --depth 1 --limit 100 -``` - -### Con Claude - -```text -Expandí el corpus usando forrajeo de citaciones: seguí una capa de referencias -de los papers ya en el corpus (backward chaining) y límítate a 100 papeles nuevos. -Mostrame los papers nuevos y el gráfico de crecimiento por año. -``` - -### Cuándo hacer esto - -- ✅ Si buscas sensibilidad alta (no quieres perderte trabajos clave). -- ✅ Si el tema es muy específico (forrajeo agrega relevancia). -- ❌ Si el corpus ya es grande (>500) — aumenta significativamente el tamaño. -- ❌ Si es la primera vez: puedes hacer esto después de leer la red inicial. - ---- - -## Paso 5 — Curá el corpus (filtros PRISMA) - -**Entrada:** Corpus (inicial o expandido). -**Salida:** Corpus curado, con decisiones explícitas y versionables. - -La curación es manual y criterial. Trae estructura (PRISMA) a lo que normalmente es -un basurero de decisiones ad-hoc. - -### Flujo PRISMA simplificado - -``` -IDENTIFICACIÓN -├─ Duplicados y retractaciones: RECHAZAR -└─ Idioma no inglés (si procede): RECHAZAR - -CRIBADO -├─ Título fuera de scope: RECHAZAR -└─ Resumen no relevante: RECHAZAR - -ELEGIBILIDAD -├─ Texto completo inaccesible: CANDIDATO (no rechazar, quizá disponible más tarde) -└─ Métodos/resultados vagos: RECHAZAR o CANDIDATO - -INCLUSIÓN -├─ Relevancia alta: ACEPTAR -└─ Relevancia media pero útil para tensiones: ACEPTAR -``` - -### Con CLI - -```bash -b2g curate dump --scope all > curate.csv -# Editá curate.csv en Excel/Sheets: status = 'ACCEPTED' / 'REJECTED' / 'CANDIDATE' -b2g curate apply curate.csv -``` - -### Con Claude - -```text -Hacé una curación manual del corpus usando criterios PRISMA: -1. Rechazá duplicados y papers sin resumen. -2. Rechazá papers cuyo título no tenga relación directa con [TU TEMA]. -3. Marcá como CANDIDATO los papers con acceso restringido al texto completo. -4. Aceptá papers con relevancia alta o media que aporten tensiones metodológicas. - -Mostrame un resumen curado: accepted/rejected/candidate counts, y listame los -papers rechazados con razón. -``` - -### Checklist - -- [ ] ¿Documenté mis criterios de aceptación/rechazo? -- [ ] ¿Quedó un corpus de 100–300 ACCEPTED papers? -- [ ] ¿Revisé una muestra de rechazados para asegurarme de que no falta algo obvio? - ---- - -## Paso 6 — Construí las redes bibliométricas - -**Entrada:** Corpus curado (ACCEPTED papers). -**Salida:** 3 redes + análisis de comunidades. - -bib2graph proyecta el corpus a tres redes: -1. **Acoplamiento bibliográfico:** Papers que citan las mismas referencias. -2. **Co-citación:** Papers citados juntos (identifican "clusters de influencia"). -3. **Co-autoría:** Relaciones entre investigadores. - -### Con CLI - -```bash -# Especificar via YAML es lo robusto -cat > networks.yaml << 'EOF' -networks: - - kind: bibliographic_coupling - clustering: louvain - resolution: 1.0 - - - kind: co_citation - clustering: louvain - resolution: 1.0 - - - kind: co_authorship - clustering: louvain - resolution: 1.0 -EOF - -b2g build --spec networks.yaml -``` - -Exportá artefactos: - -```bash -b2g export --format graphml -b2g read top --kind bibliographic_coupling --top 20 -``` - -### Con Claude - -```text -Construí 3 redes del corpus curado: -1. Acoplamiento bibliográfico, comunidades con Louvain. -2. Co-citación, comunidades con Louvain. -3. Co-autoría, comunidades con Louvain. - -Para cada red mostrame: -- Visualización coloreada por comunidad. -- Métricas: # nodos, # aristas, # comunidades. -- Top 3 papers más centrales (mayor grado). -``` - -### Qué esperar - -- **Acoplamiento:** es la red "primaria" — más densa, más comunidades. Es donde ves sub-temas. -- **Co-citación:** es la red "influyentes" — documenta qué papers/autores actúan como referencias canónicas. -- **Co-autoría:** a menudo es más dispersa; útil para ver colegios invisibles. - ---- - -## Paso 7 — Leé y nombra las comunidades - -**Entrada:** Redes + corpus curado. -**Salida:** Descripción de cada comunidad, sus keywords, enfoque y tensiones. - -Para cada comunidad en la red de acoplamiento (la principal): - -1. **Extraé keywords dominantes** de los papers en la comunidad. -2. **Nombra la comunidad** con un sustantivo que capture el enfoque (ej. "Recuperación jerárquica", "Enfoque probabilístico"). -3. **Identifica papers seminales** (máximo grado dentro de la comunidad). -4. **Identifica tensiones** (dónde difiere esta comunidad de las demás). - -### Con Claude - -```text -Para la red de acoplamiento, nombra cada comunidad según sus keywords y -el contenido de sus papers. - -Para cada comunidad: -1. Nombre (1–3 palabras). -2. Keywords principales (5–7). -3. Top 2 papers (mayor grado). -4. Descripción breve (2–3 frases) del enfoque. -5. ¿Qué tensión metodológica los diferencia de otras comunidades? -``` - -### Ejemplo de salida - -| Comunidad | Enfoque | Keywords | Seminales | Tensión | -|-----------|---------|----------|-----------|---------| -| Enfoque estadístico | Probabilidad, modelos generativos | language models, HMM, smoothing | [2010], [2008] | Eficiencia vs. cobertura | -| Enfoque neuronal | Deep learning, word embeddings | neural networks, embeddings, LSTM | [2016], [2013] | Interpretabilidad vs. performance | - ---- - -## Paso 8 — Analiza tendencias e influencias - -**Entrada:** Redes, comunidades nombradas. -**Salida:** Observaciones sobre evolución temporal, actores influyentes, huecos. - -### Preguntas a responder - -1. **¿Cómo evolucionó el campo?** - Gráficos: # papers por año, shift de keywords a lo largo del tiempo. - -2. **¿Quiénes son los autores/papeles más influyentes?** - Listá por centralidad en la red de co-citación. - -3. **¿Hay huecos evidentes?** - ¿Qué combinaciones de keywords no aparecen? ¿Qué fronteras entre comunidades están vacías? - -4. **¿Qué instituciones lideren la investigación?** - Co-autoría: qué universidades/laboratorios coaparecer más. - -### Con Claude - -```text -Analizá tendencias en el corpus: -1. Gráficos: # papers/año, distribución por comunidad año a año. -2. Autores más citados (top 10 por centralidad en co-citación). -3. Instituciones más colaborativas (co-autoría). -4. Identificá 3–5 huecos o fronteras sin explorar entre comunidades. -5. ¿Qué palabras clave son emergentes (crecimiento exponencial últimos 3 años)? -``` - ---- - -## Paso 9 — Redactá el reporte - -**Entrada:** Análisis anterior, comunidades nombradas, tendencias. -**Salida:** Documento estructurado (.md, .docx, .pdf). - -### Estructura recomendada - -``` -1. Resumen ejecutivo - - Pregunta de investigación - - Hallazgos principales (2–3 frases) - - Conclusión de una línea - -2. Introducción - - Contexto y motivación - - Pregunta de investigación - - Scope y exclusiones - -3. Metodología - - Ecuación de búsqueda - - Criterios PRISMA - - Tamaño final del corpus - - Redes construidas - -4. Mapeo del campo - - Descripción de cada comunidad (tabla + prosa) - - Figuras: red coloreada, gráficos temporales - - Actores clave y trabajos seminales - -5. Tendencias y evolución - - Trayectoria del campo (temporal) - - Shift de enfoques - - Emergentes - -6. Tensiones y debates abiertos - - Matriz: enfoque A vs. enfoque B, qué diferencia, cuál prevalece - - Huecos de investigación - - Preguntas abiertas - -7. Conclusiones y prospectiva - - Síntesis de hallazgos - - Implicaciones para investigación futura - - Recomendaciones - -8. Apéndices - - CSV de corpus (metadatos) - - GraphML de redes (para Gephi/Cytoscape) - - Lista completa de referencias -``` - -### Herramientas recomendadas - -- **Obsidian + Zotero:** flujo de investigación integrado. -- **Google Docs:** colaboración y comentarios; convertís a .docx después. -- **Markdown + Pandoc:** máxima control; exportás a PDF/DOCX con cite. -- **Quarto/Jupyter:** si quieres reproducibilidad y código integrado. - -### Checklist antes de publicar - -- [ ] ¿Cada comunidad tiene descripción, keywords y seminales claramente nombrados? -- [ ] ¿Las figuras tienen leyendas que expliquen qué se ve? -- [ ] ¿Se documentó la ecuación de búsqueda y criterios PRISMA? -- [ ] ¿Se mencionan huecos y se invita a investigación futura? -- [ ] ¿Alguien externo leyó el reporte y entendió sin preguntar? - ---- - -## Paso 10 — Guardá y versioná - -**Entrada:** Reporte final, corpus, redes. -**Salida:** Carpeta reproducible. - -Si usaste bib2graph CLI localmente: - -```bash -# El corpus vive en .duckdb; las redes en outputs/ -# Exportá todo: -b2g export --format graphml -b2g export --format csv - -# Guardá el reporte y su metadata: -tree . > structure.txt -git add . -git commit -m "SOTA: [Tu Tema] — corpus, redes, reporte" -``` - -Si usaste Claude web, **descargá:** - -- `corpus.parquet` — tu semilla para la próxima sesión. -- `*.graphml` — networks para Gephi. -- `clusters.csv` — papers → comunidad. -- Reporte final (.docx/.pdf). - -Guardalos en una carpeta nominada `sota-[tema]-[fecha]` en tu repositorio de investigación. - ---- - -## Checklist final - -- [ ] Pregunta de investigación clara -- [ ] Ecuación de búsqueda documentada -- [ ] Corpus de 100–300 papers ACCEPTED (curados) -- [ ] 3 redes construidas y visualizadas -- [ ] Comunidades nombradas y descritas -- [ ] Tendencias temporales e influyentes identificadas -- [ ] Reporte redactado con estructura clara -- [ ] Artefactos (GraphML, CSV, corpus) guardados y versionados -- [ ] ¿Se puede reproducir el análisis desde la ecuación de búsqueda? - ---- - -## Siguientes pasos - -- **Análisis más profundo:** Ahora que mapeaste el campo, profundizá en una - comunidad; usa bib2graph para iterar (nuevo corpus sobre esa comunidad, - nuevas redes, nuevo SOTA acotado). - -- **Integración con tu investigación:** Usa el mapa como **diagrama de - posicionamiento** para tu propio trabajo — ¿dónde caés? ¿dónde hay tensión - que tu trabajo resuelve? - -- **Tutorial:** Si quieres aprender el CLI o la librería de Python a fondo, - véase el [Quickstart](../getting-started/quickstart.md) y la [Referencia](../reference/cli.md). - -- **Comunidad:** Compartí tu SOTA en el repo (crea un issue); feedback de otros - investigadores enriquece el análisis. - ---- - -## Referencias internas - -- [Arquitectura de bib2graph](../ARCHITECTURE.md) -- [API Python](../reference/python-api.md) -- [CLI `b2g`](../reference/cli.md) -- [ADR sobre SOTA y investigación](../decisiones/) — cómo bib2graph encaja en el ciclo de investigación. diff --git a/docs/guias/reporte.md b/docs/guias/reporte.md new file mode 100644 index 0000000..177cc48 --- /dev/null +++ b/docs/guias/reporte.md @@ -0,0 +1,329 @@ +--- +title: Del corpus al reporte — Estructura y redacción +--- + +# Del corpus al reporte — De datos a prosa + +Tienes redes, comunidades, papers clave. Ahora: cómo convertir eso en un **reporte +coherente** que otros lean de principio a fin. + +Esta guía: estructura, qué escribir en cada sección, y tips de redacción. + +!!! info "Alcance" + - Para alguien que ya leyó las redes y tienes anotaciones + - Toma: 3–4 horas de redacción + - Herramienta: Google Docs, Word, Obsidian, o Markdown + Pandoc + - Salida: Documento de 8–15 páginas, legible + +--- + +## La estructura (template) + +``` +1. RESUMEN EJECUTIVO (1 página) +2. INTRODUCCIÓN (1–2 páginas) +3. METODOLOGÍA (1 página) +4. MAPEO DEL CAMPO (3–5 páginas) +5. TENDENCIAS E INFLUENCIA (2–3 páginas) +6. TENSIONES Y DEBATES (2–3 páginas) +7. CONCLUSIONES (1–2 páginas) +8. REFERENCIAS (autogenerado) + +Total: 12–20 páginas +``` + +--- + +## 1. RESUMEN EJECUTIVO + +**Largo:** 1 página. **Escritura:** densísima, sin fluff. + +**Qué incluir:** + +- Pregunta de investigación (1 frase) +- Metodología en 1 línea: "SOTA de X papers, 3 redes, PRISMA curation" +- 3 hallazgos principales (bullet points) +- Conclusión de 1 frase + +### Ejemplo + +> **Pregunta:** ¿Cuál es el estado del arte en recuperación de información multilingüe? +> +> **Método:** Corpus de 250 papers (2015–2024) desde OpenAlex, curado con PRISMA, analizado con 3 redes bibliométricas. +> +> **Hallazgos:** +> - El campo tiene 3 enfoques dominantes: estadístico, vectorial, neuronal. Los tres coexisten sin consenso. +> - Papers influentes (clásicos) son del 2008–2013; nuevos líderes emergentes post-2019 con enfoque neuronal. +> - Hay un hueco: recuperación multilingüe en contextos de baja disponibilidad de datos. +> +> **Conclusión:** El campo está en transición de enfoques estadísticos a neurales, pero cada enfoque tiene ventajas sin resolver. + +--- + +## 2. INTRODUCCIÓN + +**Largo:** 1–2 páginas. **Propósito:** planta el contexto y la pregunta. + +**Estructura:** + +1. **Hook:** Por qué el tema importa (1–2 frases) +2. **Contexto:** Dónde cae este tema en la disciplina (3–4 frases) +3. **Pregunta de investigación:** Explicitada (1 frase) +4. **Scope:** Qué cubre este SOTA y qué no (1 frase) + +### Ejemplo + +> **Hook:** La recuperación de información (IR) es fundamental para cualquier herramienta de búsqueda, pero el contexto multilingüe agrega complejidad: vocabularios diferentes, grammatical structures, y semánticas culturales. +> +> **Contexto:** Históricamente, IR se basaba en matching estadístico (TF-IDF). Los últimos 10 años vieron un giro hacia embeddings y modelos neurales. En contextos multilingües, esto es aún más reciente. +> +> **Pregunta:** ¿Cuáles son los enfoques dominantes en IR multilingüe hoy, cuáles son sus tensiones, y qué queda sin explorar? +> +> **Scope:** Analizamos papers 2015–2024 en ingles; enfoque: métodos y frameworks (no aplicaciones específicas). + +--- + +## 3. METODOLOGÍA + +**Largo:** 1 página. **Propósito:** reproducibilidad. + +**Incluir:** + +- Ecuación de búsqueda (cópiala) +- Rango de años y fuente (OpenAlex) +- Criterios PRISMA (en una frase por fase) +- Corpus final: # papers, rango años +- Redes construidas (acoplamiento, co-citación, co-autoría) +- Tool: bib2graph + +### Ejemplo + +> **Búsqueda:** "(information retrieval OR search OR IR) AND (multilingual OR cross-lingual) AND (method OR approach OR framework)" en OpenAlex, años 2015–2024. +> +> **Curation:** PRISMA de 4 fases. +> - Identificación: duplicados, retractados, no-inglés → rejected +> - Cribado: título + abstract relevancia → rejected +> - Elegibilidad: texto completo accesible → candidate +> - Inclusión: relevancia alta → accepted +> +> **Corpus:** 315 papers buscados → 250 tras curación PRISMA → 245 aceptados + 5 candidatos. +> **Años:** 2015–2024 (con 3 foundational 2008–2010). +> +> **Redes:** Acoplamiento bibliográfico (comunidades), co-citación (influentes), co-autoría (colaboraciones). +> **Herramienta:** bib2graph v0.3 + Louvain clustering (resolution=1.0). + +--- + +## 4. MAPEO DEL CAMPO + +**Largo:** 3–5 páginas. **Propósito:** mostrar la estructura del campo. + +**Estructura:** + +1. **Tabla de comunidades** (1 página) + - Comunidad | Keywords | Top papers | Descripción + +2. **Descripción de cada comunidad** (1–2 párrafos por comunidad, máx 3–4 comunidades) + +3. **Figura: Red coloreada** (inserta el PNG de la red de acoplamiento) + +### Ejemplo — Tabla + +| Comunidad | Keywords | Top Papers | Enfoque | +|-----------|----------|-----------|---------| +| **Estadístico** | TF-IDF, probabilistic, language model | [Smith 2008], [Brown 2010] | Ranking por frecuencia de términos | +| **Vectorial** | embedding, word2vec, LSA, similarity | [Mikolov 2013], [Pennington 2014] | Espacios semánticos densos | +| **Neuronal** | neural network, transformer, BERT, attention | [Vaswani 2017], [Devlin 2019] | Aprendizaje de representaciones | + +### Ejemplo — Prosa + +> **Enfoque Estadístico:** 85 papers, principalmente 2015–2018. +> Usan modelos probabilísticos (HMM, LM) y ranking por frecuencia (TF-IDF). +> Ventaja: eficiencia, interpretabilidad. Desventaja: no captura semántica. +> Papers influyentes: Smith et al (2008), Brown et al (2010). +> +> **Enfoque Vectorial:** 92 papers, principalmente 2013–2020. +> Generan embeddings densos (word2vec, FastText) y miden similaridad coseno. +> Ventaja: captura semántica, escalable. Desventaja: computacionalmente costoso, menos interpretable. +> Transición: muchos papers de 2015–2017 vuelven a embeddings, desafiando TF-IDF. +> +> **Enfoque Neuronal:** 68 papers, principalmente 2017–2024. +> Transformers (BERT, mBERT para multilingüe). Ventaja: SOA performance. Desventaja: black box, caro. +> Emergente: multilingüe especializado (XLM-R). +> +> **Dinámicas:** Los 3 enfoques coexisten sin desplazamiento total. Hay papers híbridos (probabilístico + neural). +> Frontera sin explorar: eficiencia en contextos de baja disponibilidad de datos. + +### Qué evitar + +❌ "Enfoque A es mejor que enfoque B." +→ Los 3 conviven, cada uno tiene trade-offs. + +✅ "Enfoque A prioriza X, enfoque B prioriza Y. Entran en tensión sobre Z." + +--- + +## 5. TENDENCIAS E INFLUENCIA + +**Largo:** 2–3 páginas. **Propósito:** mostrar evolución temporal y actores clave. + +**Incluir:** + +1. **Gráfico temporal:** # papers/año por comunidad +2. **Shift de enfoque:** cuál crecía, cuál decrecía +3. **Papers y autores influyentes:** top 10 por co-citación +4. **Labs líderes:** qué universidades/labs dominan (co-autoría) +5. **Emergentes:** keywords o autores con crecimiento exponencial últimos 3 años + +### Ejemplo + +> **Evolución temporal:** 2015–2017 fue era "vectorial" (92 papers, 60% de nuevos). 2018–2020, equilibrio. +> 2021–2024, giro a neuronal (68% nuevos). Estadístico declina (5% nuevos en 2024). +> +> **Influyentes globales:** Smith et al (2008) sigue siendo más citado, pero Vaswani et al (2017) "Attention is All You Need" +> alcanzó en 2022. Post-2020, mBERT (Google) es hub de co-citación en multilingüe. +> +> **Labs líderes:** Stanford (25 papers), Google Brain (18), FAIR (15). +> Colaboración: Google + Stanford (12 co-author papers). FAIR aislado (pocas colaboraciones externas). +> +> **Emergentes:** Keyword "low-resource" crece 3x desde 2020. Autores nuevos en este sub-tema. +> Nuevas partnerships: Google + universidades en Asia (multilingüe sobre lenguas de baja disponibilidad). + +--- + +## 6. TENSIONES Y DEBATES + +**Largo:** 2–3 páginas. **Propósito:** tensiones = investigación activa. + +**Qué es una tensión:** Dos enfoques dicen cosas opuestas o incompatibles. + +**Estructura:** Para cada tensión: + +1. **Nombre** (Eficiencia vs. Precisión) +2. **Quién está de cada lado** (Enfoque A vs. Enfoque B) +3. **Por qué divergen** (Presupuestos, objetivos, contexto) +4. **Ejemplo concreto** (Paper A dice X, Paper B dice ¬X) +5. **Estado actual** (Se resolvió? Abierto? Evolucionó?) + +### Ejemplo + +> **Tensión 1: Interpretabilidad vs. Performance** +> +> - **Lado A (Estadístico):** Un modelo entendible es mejor. TF-IDF, si devuelves top 5, puedo explicar por qué. +> - **Lado B (Neuronal):** Performance > interpretabilidad. Si BERT devuelve 99% accuracy, ¿importa que sea black box? +> - **Ejemplo:** Smith (2010) "Statistical IR is superior for transparent systems". Devlin (2019) "BERT outperforms all baselines", no explora interpretabilidad. +> - **Estado:** Abierto. Hay intentos de interpretable neural (attention visualization), pero la mayoría ignora esto. +> +> **Tensión 2: Escalabilidad vs. Contexto** +> +> - **Lado A:** Escalable a millones de documentos (vectorial, estadístico). +> - **Lado B:** Contexto fino, semantic precision (neuronal, aunque lento). +> - **Ejemplo:** Google's neural retrieval es 10x más lento que TF-IDF, por eso siguen usando TF-IDF en producción. +> - **Estado:** En evolución. Recientes (2023–2024) buscan solución: retrieval neuronal comprimido (destilación). + +--- + +## 7. CONCLUSIONES + +**Largo:** 1–2 páginas. **Propósito:** síntesis + implicaciones. + +**Estructura:** + +1. **Síntesis de hallazgos:** qué vimos en el mapa +2. **Implicaciones:** qué significa para investigación futura +3. **Huecos:** qué no existe, qué falta +4. **Recomendación:** si fueras investigador, dónde irías + +### Ejemplo + +> **Síntesis:** El campo de IR multilingüe está en transición. Tres enfoques coexisten: estadístico (maduro, eficiente, interpretable), +> vectorial (en declive, pero servicios web lo usan), neuronal (ascendente, SOA, caro). No hay consenso de paradigma. +> +> **Para futura investigación:** Hay dos caminos abiertos. +> 1. Resolver Interpretabilidad en modelos neurales multilingües. +> 2. Explorar IR eficiente en lenguas de baja disponibilidad (hueco claro). +> +> **Huecos principales:** +> - No hay estudios comparativos rigurosos de los 3 enfoques en el mismo benchmark multilingüe. +> - Contextos code-switching (mezcla de lenguas) es casi inexplorado. +> - Retrieval offline/sin internet: abandonado por la industria. +> +> **Recomendación:** Si entrás al campo hoy, sugiero: caracterizar la brecha de eficiencia en multilingüe (hay plata aquí), +> o resolver low-resource (hay impacto social + papers de alto valor). + +--- + +## Tips de redacción + +### 1. No expliques QUÉ, explica QUÉ SIGNIFICA + +❌ "Paper A propone un método estadístico usando TF-IDF para IR. Paper B propone redes neurales." + +✅ "Paper A (estadístico) y Paper B (neural) entran en tensión sobre trade-off entre eficiencia e inteligencia. A es rápido, B es inteligente." + +### 2. Las figuras NO hablan solas + +Cada figura necesita: +- Título claro +- Leyenda que explique qué ves +- 2–3 frases de texto que señalen qué observar + +❌ Figura: Red coloreada (sin leyenda) + +✅ Figura 1: Red de acoplamiento bibliográfico. Nodos = papers. Líneas = referencias compartidas (acoplamiento). Colores = comunidades (Louvain). Observar: la comunidad azul (estadístico) es densa pero aislada; la roja (neuronal) es más dispersa pero conecta todas las demás. + +### 3. Transiciones entre secciones + +Conectá secciones: + +``` +[...fin de Metodología] +"Con este corpus de 245 papers, ahora examinamos la estructura del campo. + +[Inicio de Mapeo del Campo] +El análisis de acoplamiento bibliográfico revela 3 comunidades principales..." +``` + +### 4. Cita los papers + +Cuando menciones una idea, cita: (Smith et al, 2008). Esto hace el texto reproducible. + +### 5. Redacta para que entienda alguien fuera del tema + +No asumas jerga. Explica conceptos: + +❌ "TF-IDF es el baseline obvio." + +✅ "TF-IDF (Term Frequency-Inverse Document Frequency) es un scoring que ranquea documentos por términos raros en el corpus (raro = más informativo). Es eficiente pero no entiende significado." + +--- + +## Herramientas de escritura + +- **Google Docs:** Colaboración, comentarios, fácil de compartir. Exportá a DOCX. +- **Markdown + Pandoc:** Control total, versionable con git, exportá a PDF/DOCX. +- **Obsidian:** Bueno para notas conectadas, integra con Zotero. +- **Word:** Si necesitás templates corporativos. + +--- + +## Checklist de escritura + +- [ ] Resumen ejecutivo: 3 hallazgos clave en 5 frases +- [ ] Introducción: pregunta clara, scope explícito +- [ ] Metodología: reproducible (ecuación, criterios, final corpus) +- [ ] Mapeo: tabla + prosa, cada comunidad explicada +- [ ] Tendencias: gráfico temporal + top papers/labs +- [ ] Tensiones: 3–5 tensiones principales con ejemplos +- [ ] Conclusiones: huecos identificados, recomendaciones futuras +- [ ] Figuras: todas con leyendas claras + 2–3 frases de interpretación +- [ ] Redacción: sin jerga sin explicar, citas presentes, transiciones claras + +--- + +## Siguiente + +Cuando termines el reporte: +- Comparte para feedback (peer-review light) +- Itera: ¿hay tensiones sin explicar? ¿hay huecos claros? +- Publica o presentá (conferencia, seminario, blog) diff --git a/docs/index.md b/docs/index.md index 2b6bb2d..cb8347b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,13 +5,12 @@ title: Inicio # bib2graph > De una búsqueda bibliográfica a **redes de citación reproducibles** — una -> biblioteca de literatura que curás vos, sin servidores ni planillas. +> biblioteca de literatura que curas tú, sin servidores ni planillas. -**bib2graph** toma una ecuación de búsqueda (o un archivo `.bib`), arma un corpus -de papers desde [OpenAlex](https://openalex.org), te deja **curarlo** y lo -proyecta a **redes bibliométricas** listas para analizar en Gephi, Cytoscape, -networkx o donde quieras: acoplamiento bibliográfico, co-citación, co-autoría, -colaboración institucional y co-ocurrencia de keywords. +**bib2graph** toma una ecuación de búsqueda (o un archivo `.bib`), trae papers +desde [OpenAlex](https://openalex.org), te deja **curarlo** y lo proyecta a +**redes bibliométricas** listas para analizar en Gephi, Cytoscape, networkx o donde quieras: +acoplamiento bibliográfico, co-citación, co-autoría, colaboración institucional y co-ocurrencia de keywords. El corpus **persiste y crece** entre sesiones, y el resultado es **reproducible**: mismo input, mismas redes. @@ -21,29 +20,54 @@ mismo input, mismas redes. Úsalo para explorar y validar, no como dependencia estable de producción todavía. -## Empezá acá +--- + +## Elige tu camino + +¿Cómo quieres usar bib2graph? Cada flujo es válido.
-- :material-download: **[Instalación](getting-started/installation.md)** +- :material-robot: **Sin instalar nada (5 min)** - Instalá `bib2graph` con `uv` o `pip` en un minuto. + Cuéntale a Claude, ChatGPT o MiniMax tu tema de investigación. + El agente trae papers, construye redes, tú descargas resultados. + + 👉 [Tutorial: Usuario no técnico](tutoriales/claude-code.md) -- :material-rocket-launch: **[Quickstart](getting-started/quickstart.md)** +- :material-code-braces: **Aprendiendo paso a paso (3–4 horas)** + + Instala bib2graph. Sigue 10 pasos: desde pregunta hasta reporte. + Ejecutas cada comando, entiendes cómo funciona todo. + + 👉 [Tutorial completo: De la pregunta al reporte](tutoriales/sota-completo.md) + +- :material-hammer-wrench: **Hibrido: CLI + agente (1–2 horas)** + + Instala bib2graph. El agente te ayuda con las partes difíciles. + Tú ejecutas comandos. Usa guías rápidas para decisiones. + + 👉 [Guías prácticas](guias/index.md) - De una ecuación a un GraphML, sin escribir código. +
+ +--- + +## Primeros pasos -- :material-book-open-variant: **[Tutoriales](tutoriales/index.md)** +
+ +- :material-download: **[Instalación](getting-started/installation.md)** - Desde tu primer mapa en 5 minutos hasta un reporte de SOTA riguroso. + Instala `bib2graph` con `uv` o `pip` en un minuto. -- :material-silverware-fork-knife: **[Guías](guias/index.md)** +- :material-rocket-launch: **[Quickstart](getting-started/quickstart.md)** - Recetas para tareas concretas de investigación. + El ciclo mínimo en 2 minutos — desde ecuación a GraphML. - :material-api: **[Referencia](reference/cli.md)** - El CLI `b2g` y la API de Python, autogeneradas desde el código. + El CLI `b2g` y la API de Python, completos.
@@ -52,7 +76,7 @@ mismo input, mismas redes. - **Siembra** desde una ecuación de búsqueda (OpenAlex) o un archivo BibTeX. - **Expande** el corpus siguiendo citaciones, rankeando candidatos por estructura — sin IA. -- **Curás vos:** aceptar/rechazar papers, filtros PRISMA, todo versionable en CSV. +- **Curas tú:** acepta/rechaza papers, filtros PRISMA, todo versionable en CSV. - **5 redes bibliométricas:** acoplamiento, co-citación, co-autoría, instituciones, co-keywords. - **Sub-redes temáticas** filtrando por keyword. From 219d52d7a9a0a5f7e6d308342fe9285d361c87f5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 18:31:50 +0000 Subject: [PATCH 6/6] docs: add glossary to close issue #208 completely MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive glossary covering: - Bibliometric terms (bibliographic coupling, co-citation, co-authorship) - Methodology (PRISMA phases, Louvain clustering, resolution) - bib2graph concepts (corpus, seed, chain, curate, workspace, NetworkSpec) - General research concepts (reproducibility, benchmark, embedding) - Acronyms (API, CLI, CSV, DOI, FSM, IR, JSON, PRISMA, SOTA, SQL, YAML) Glossary is alphabetized for quick lookup. Each term includes: - Definition - Context in bib2graph - Example or use case - Link to related guides when applicable Update docs/reference/cli.md with tip to glossary Update docs/index.md to mention glossary in Referencia card This completes issue #208: ✅ Tutorial corto (5 min, no técnico) ✅ Tutorial completo (3-4h, paso a paso) ✅ 5 guías acotadas (ecuación, forrajeo, curación, redes, reporte) ✅ Landing con 3 caminos ✅ Glosario (términos y siglas) All docs use Colombian Spanish, neutral tone, tú form. No vendor locking — shows CLI as foundation, agents as helpers. Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01VfqH92jLCoRQ9G8AMA1Vgi --- docs/index.md | 2 +- docs/reference/cli.md | 3 + docs/reference/glosario.md | 358 +++++++++++++++++++++++++++++++++++++ 3 files changed, 362 insertions(+), 1 deletion(-) create mode 100644 docs/reference/glosario.md diff --git a/docs/index.md b/docs/index.md index cb8347b..e595f41 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,7 +67,7 @@ mismo input, mismas redes. - :material-api: **[Referencia](reference/cli.md)** - El CLI `b2g` y la API de Python, completos. + El CLI `b2g`, API de Python, y glosario de términos. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index dd7c5b0..640607e 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -14,6 +14,9 @@ sincronía con el código. codes 0–5. Los detalles del contrato (envelope, exit codes, FSM) están en [Contratos detallados](../API.md). +!!! tip "Términos no claros" + Si un término en el CLI no te queda claro, revisa el [Glosario](glosario.md). + ::: mkdocs-click :module: bib2graph.cli :command: b2g diff --git a/docs/reference/glosario.md b/docs/reference/glosario.md new file mode 100644 index 0000000..a196f03 --- /dev/null +++ b/docs/reference/glosario.md @@ -0,0 +1,358 @@ +--- +title: Glosario +--- + +# Glosario + +Términos y conceptos clave que aparecen en bib2graph, la metodología bibliométrica y la investigación del estado del arte. + +--- + +## A + +### Acoplamiento bibliográfico + +Medida de similitud entre dos papers basada en las referencias que comparten. Dos papers están acoplados si citan las mismas fuentes. Cuantas más referencias compartan, más fuerte es el acoplamiento. + +**En bib2graph:** La red de **acoplamiento bibliográfico** es la proyección principal — agrupa papers en comunidades basadas en sus referencias compartidas. Es útil para identificar sub-temas y tendencias. + +**Ejemplo:** Paper A cita [Ref1, Ref2, Ref3]. Paper B cita [Ref2, Ref3, Ref4]. Acoplamiento: comparten 2 referencias, acoplamiento fuerte → aparecen cerca en la red. + +--- + +## B + +### Backward chaining + +Ver **forrajeo**. + +### Benchmark + +Conjunto de datos estándar usado para evaluar y comparar algoritmos. Un benchmark típicamente incluye inputs, outputs esperados y métricas de evaluación. + +**En bib2graph:** No usamos benchmarks para construir redes (nuestro ranking es determinista), pero sí los papers usan benchmarks para validar retrieval, clustering, etc. + +--- + +## C + +### Candidate + +Estado de un paper en la curación PRISMA. Papers candidatos son aquellos cuya inclusión es incierta — típicamente porque no tienen acceso al texto completo, o porque su relevancia es media. + +**En bib2graph:** En `b2g curate`, un paper puede ser `ACCEPTED`, `REJECTED`, o `CANDIDATE`. Los candidatos quedan en el corpus pero marcados, para revisión posterior. + +**Cuándo marcar candidato:** +- Texto completo no disponible (paywall) +- Métodos vagos o especulativos +- Relevancia media pero podría aportar perspectiva + +--- + +### Clustering + +Proceso de agrupar elementos similares sin etiquetar. En bib2graph, usamos **Louvain clustering** para detectar comunidades en redes. + +**En bib2graph:** Después de construir una red (acoplamiento, co-citación, etc.), ejecutamos Louvain para encontrar comunidades — grupos de papers/autores densamente conectados. + +**Parámetro importante:** `resolution` (default 1.0). Resolución más alta = más comunidades, más finas. Resolución más baja = menos comunidades, más grandes. + +--- + +### Co-autoría + +Red que conecta autores que escriben papers juntos. Un edge existe si dos autores co-autorizan un paper. + +**En bib2graph:** `b2g build` crea una red de co-autoría. Útil para identificar equipos, laboratorios y colaboraciones persistentes. + +--- + +### Co-citación + +Dos papers se co-citan si aparecen juntos en las referencias de otros papers. Si Paper A y Paper B se citan mutuamente, o si ambos aparecen en las referencias de muchos otros papers, su co-citación es alta. + +**En bib2graph:** La red de **co-citación** proyecta papers que son frecuentemente citados juntos. Identifica papers influyentes y trabajos canónicos (clásicos del campo). + +**Diferencia vs. Acoplamiento:** +- **Acoplamiento:** Basado en referencias que comparten (enfoque hacia atrás). +- **Co-citación:** Basado en quién los cita juntos (enfoque hacia atrás, pero a nivel de influencia). + +--- + +### Corpus + +Colección de papers (o documentos) que forman la base del análisis. En bib2graph, el corpus es persistente — crece con `b2g seed` y `b2g chain`, se filtra con `b2g curate`. + +**En bib2graph:** El corpus vive en `.duckdb` (DuckDB, base de datos local). Cada corpus tiene un `corpus_hash` (hash de contenido) que permite reproducibilidad. + +--- + +### Curación PRISMA + +Metodología de 4 fases para decidir qué papers incluir en una síntesis de literatura. Las fases son: Identificación, Cribado, Elegibilidad, Inclusión. + +**En bib2graph:** `b2g curate` implementa el flujo PRISMA. Ver [Guía: Curación PRISMA paso a paso](../guias/curacion-prisma.md). + +--- + +## D + +### DuckDB + +Base de datos SQL incrustada (embedded), sin servidor. bib2graph usa DuckDB para almacenar el corpus persistentemente. + +**En bib2graph:** Cada workspace tiene un archivo `.duckdb` que contiene todas las tablas del corpus (papers, referencias, decisiones de curación, etc.). DuckDB permite queries SQL rápidas sin instalar un servidor PostgreSQL. + +--- + +## E + +### Ecuación de búsqueda + +Consulta booleana que especifica qué papers traer desde OpenAlex. Usa estructura `(concepto_A) AND (concepto_B) AND (concepto_C)`. + +**En bib2graph:** `b2g seed "[ecuacion_aqui]"` trae papers desde OpenAlex usando tu ecuación. + +**Ejemplo:** +``` +(information retrieval OR IR OR search) +AND (multilingual OR cross-lingual) +AND (method OR approach OR framework) +``` + +Ver [Guía: Cómo armar una ecuación de búsqueda](../guias/ecuacion-busqueda.md). + +--- + +### Embedding + +Representación numérica densa (vector) de una palabra, documento o concepto. Embeddings capturan significado semántico — palabras con significado similar tienen embeddings cercanos en el espacio vectorial. + +**En bib2graph:** No usamos embeddings para ranking (nuestro scent es bibliométrico puro). Pero muchos papers en el corpus usan embeddings para retrieval. + +--- + +## F + +### Forrajeo + +Expansión del corpus mediante **backward chaining**: buscar papers que NO aparecieron en la búsqueda inicial, pero que son citados por los papers que sí encontraste. + +**En bib2graph:** `b2g chain` ejecuta forrajeo. Aumenta sensibilidad (no pierdes papers clave) sin agregar ruido sistemático. + +**Cuándo hacer forrajeo:** Tema muy específico, corpus inicial pequeño, búsqueda máxima cobertura. + +Ver [Guía: ¿Expando el corpus?](../guias/forrajeo.md). + +--- + +## G + +### Grado + +En una red, el número de conexiones que tiene un nodo. Un paper con grado alto está altamente acoplado (acoplamiento) o frecuentemente co-citado (co-citación). + +**En bib2graph:** Papers de mayor grado son centrales en la red — son buenos candidatos para "papers seminales" de una comunidad. + +--- + +## H + +### Hub + +En una red, un nodo con grado muy alto — actúa como nexo central. En co-citación, un hub es un paper que la mayoría cita (un "clásico"). + +--- + +## I + +### Identificación (fase PRISMA) + +Primera fase de curación PRISMA. Aquí marcas duplicados, retracciones, papers en idioma incorrecto como REJECTED sin revisar más. + +Ver [Guía: Curación PRISMA paso a paso](../guias/curacion-prisma.md). + +--- + +## L + +### Louvain + +Algoritmo de clustering que detecta comunidades en redes minimizando modularidad. Es probabilístico — diferentes ejecuciones pueden dar resultados levemente diferentes. + +**En bib2graph:** `b2g build` usa Louvain con `resolution=1.0` (default). Puedes cambiar resolución en YAML specs: `resolution: 0.5` → comunidades más grandes; `resolution: 2.0` → comunidades más pequeñas. + +--- + +## M + +### Maturity (bloque JSON) + +Campo en la salida `--json` de `b2g build`, `b2g snapshot create`, `b2g read top` que autodeclara la madurez del resultado. Indica que el reporte es un borrador sin pulir. + +**Valores:** `{curated, scope, saturated, empty_networks}` — si tienes datos incompletos, bib2graph lo advierte. + +--- + +## N + +### NetworkSpec + +Especificación YAML declarativa de cómo construir redes. Define qué red (acoplamiento, co-citación, etc.), qué clustering usar, y qué resolución. + +**En bib2graph:** +```yaml +networks: + - kind: bibliographic_coupling + clustering: louvain + resolution: 1.0 +``` + +`b2g build --spec networks.yaml` carga la spec y construye. + +--- + +## O + +### OpenAlex + +Base de datos abierta de papers, autores, revistas, citas. API gratuita sin API key requerida (pero funcionamiento limitado sin key). + +**En bib2graph:** `b2g seed` trae papers desde OpenAlex usando tu ecuación de búsqueda. + +--- + +## P + +### PRISMA + +Metodología de 4 fases para síntesis sistemática de literatura: **Identificación → Cribado → Elegibilidad → Inclusión**. Cada fase tiene criterios explícitos de aceptación/rechazo. + +**En bib2graph:** `b2g curate` implementa el flujo PRISMA. Requiere que documentes criterios de decisión. + +Ver [Guía: Curación PRISMA paso a paso](../guias/curacion-prisma.md). + +--- + +## R + +### Reproducibilidad + +Capacidad de reproducir exactamente el mismo resultado (corpus, redes, comunidades) desde los mismos inputs, sin variabilidad. + +**En bib2graph:** Reproducibilidad es un principio central. Mismo corpus → mismo `corpus_hash` → mismas redes → mismas comunidades (Louvain con seed determinístico). + +--- + +### Resolución (Louvain) + +Parámetro del algoritmo Louvain que controla el tamaño de las comunidades detectadas. Resolución alta → comunidades más pequeñas y numerosas. Resolución baja → comunidades más grandes y menos numerosas. + +**Default en bib2graph:** `resolution: 1.0` (balance). + +--- + +## S + +### Scent bibliométrico + +Ranking determinístico sin IA que usa estructura bibliométrica (acoplamiento, co-citación, centralidad) para rankear candidatos en forrajeo. + +**En bib2graph:** Cuando haces `b2g chain`, los candidatos se rankean por scent (no por LLM ni embeddings). Es reproducible y explicable. + +--- + +### Seed + +Acción de sembrar el corpus inicial desde una ecuación de búsqueda. `b2g seed "[ecuacion]"` trae papers desde OpenAlex. + +**Estados del corpus:** SEEDED → CHAINED → FILTERED → BUILT → (SNAPSHOT/EXPORTED). + +--- + +### Snapshot + +Captura congelada del corpus en un momento. `b2g snapshot create` guarda el estado actual; `b2g snapshot restore` rehidrata desde un snapshot anterior. + +**En bib2graph:** Útil para reproducibilidad — si necesitas volver a un corpus anterior, restaura desde snapshot. + +--- + +## T + +### TF-IDF + +**Term Frequency-Inverse Document Frequency.** Métrica de ranking que pondera términos raros en el corpus (raros = más informativos) vs. frecuentes (frecuentes = menos informativos). + +**En bib2graph:** No lo usamos en el core (nuestro ranking es bibliométrico). Pero muchos papers históricos en el corpus usan TF-IDF para retrieval. + +--- + +## W + +### Workspace + +Carpeta de investigación que contiene un corpus, sus redes, snapshots y exports. Un workspace = una investigación. + +**En bib2graph:** `b2g init ./mi-sota` crea un workspace. Dentro vive: +- `workspace.json` (metadata) +- `library.duckdb` (corpus) +- `networks/` (redes exportadas) +- `snapshots/` (snapshots) +- `exports/` (GraphML, CSV, etc.) + +--- + +## Y + +### YAML (Yet Another Markup Language) + +Formato de configuración legible. bib2graph usa YAML para specs de redes y ecuaciones. + +**En bib2graph:** +```yaml +networks: + - kind: bibliographic_coupling + clustering: louvain + resolution: 1.0 +``` + +--- + +## Z + +### Zotero + +Gestor de referencias de código abierto. No está integrado en bib2graph hoy, pero es un candidato para futuras integraciones (flujo: Zotero → bib2graph). + +--- + +## Siglas comunes + +| Sigla | Significado | En bib2graph | +|-------|-----------|---| +| API | Application Programming Interface | `bib2graph` es una librería Python (API) + CLI | +| CLI | Command Line Interface | `b2g` — interfaz de línea de comandos | +| CSV | Comma-Separated Values | Formato de curación: `curate.csv` | +| DOI | Digital Object Identifier | Identificador único de paper | +| FSM | Finite State Machine | El ciclo de bib2graph es un FSM (SEEDED → CHAINED → FILTERED → BUILT) | +| IR | Information Retrieval | Recuperación de información | +| JSON | JavaScript Object Notation | Formato de salida: `b2g --json` | +| PRISMA | Preferred Reporting Items for Systematic Reviews and Meta-Analyses | Metodología de curación | +| SOTA | State of The Art | Estado del arte — el objetivo de bib2graph | +| SQL | Structured Query Language | Queries en DuckDB: `b2g read list` usa SQL internamente | +| YAML | YAML Ain't Markup Language | Formato de specs: `networks.yaml`, `equation.yaml` | + +--- + +## Cómo usar este glosario + +- **Alfabéticamente:** Busca el término que no entiendes. +- **Desde las guías:** Cada guía enlaza a términos relevantes. +- **Desde el CLI:** `b2g --help` menciona términos; este glosario los define. + +--- + +## No encontraste el término? + +Si hay un término en bib2graph que no está aquí, [abre un issue](https://github.com/complexluise/bib2graph/issues) o sugiere una adición.