3.1 Visualization Tools

Opciones para mostrar gráficas en tu GitHub Wiki

1) Mermaid (nativo en GitHub)

Perfecto para diagramas y algunos gráficos simples.

• Pastel (útil para composiciones pequeñas):

pie showData
title Distribución de categorías
"Clase A" : 34
"Clase B" : 21
"Clase C" : 45

Loading

• Timeline / Gantt (pseudo-series temporales):

gantt
dateFormat  YYYY-MM-DD
title Evolución del proyecto
section Ingesta de datos
Parser CSV           :done,    a1, 2025-09-01, 2025-09-05
Validador            :active,  a2, 2025-09-06, 2025-09-12
section Visualización
Prototipo dashboard  :         a3, 2025-09-10, 2025-09-20

Loading

Nota: Mermaid es ideal para diagramas (flowchart, class, state, ER, mindmap, journey, timeline, gantt, pie). Para gráficas de datos continuos (series, scatter, histogramas), mejor generar imágenes (opción 3) o usar GitHub Pages + Vega-Lite (opción 4).

---

2) MathJax (nativo en GitHub)

Para fórmulas, unidades, anotaciones en tus notas/gráficos.

• Inline: $\sigma^2 = \frac{1}{n}\sum (x_i - \mu)^2$
• Bloque:

$$
z = \frac{x - \mu}{\sigma}
$$

---

3) Gráficas como imágenes (SVG/PNG) generadas por código

La vía robusta: generas las gráficas con Python/R y las insertas en la wiki.

3.1. Flujo recomendado

1. Clona la Wiki (es un repo aparte):

git clone https://github.com/<usuario>/<repo>.wiki.git
cd <repo>.wiki
mkdir -p img

2. Genera gráficos a img/ (mejor SVG para nitidez).
3. Referéncialos en tus páginas wiki:

![Ventas por mes](img/ventas_por_mes.svg)

4. git add . && git commit -m "Añadir gráficas" && git push

3.2. Script Python mínimo (SVG)

Guarda esto en el repo de la wiki (p. ej., scripts/graficas.py) o ejecútalo local y copia los SVG a img/.

# scripts/graficas.py
# Intención: generar gráficos reproducibles en SVG para la wiki.
def GenerarGraficas():
    import os
    import pathlib
    import matplotlib.pyplot as plt

    outdir = pathlib.Path("img")
    outdir.mkdir(parents=True, exist_ok=True)

    # Ejemplo 1: series temporales simples
    meses = ["E", "F", "M", "A", "M", "J", "J", "A", "S", "O", "N", "D"]
    ventas = [12, 14, 18, 17, 20, 21, 25, 24, 23, 27, 28, 30]

    plt.figure()
    plt.plot(meses, ventas, marker="o")
    plt.title("Ventas por mes")
    plt.xlabel("Mes")
    plt.ylabel("Unidades")
    plt.tight_layout()
    plt.savefig(outdir / "ventas_por_mes.svg")
    plt.close()

    # Ejemplo 2: barras categóricas
    categorias = ["A", "B", "C", "D"]
    valores = [34, 21, 45, 12]

    plt.figure()
    plt.bar(categorias, valores)
    plt.title("Distribución por categoría")
    plt.xlabel("Categoría")
    plt.ylabel("Valor")
    plt.tight_layout()
    plt.savefig(outdir / "dist_categoria.svg")
    plt.close()

if __name__ == "__main__":
    GenerarGraficas()

Repite el patrón para histogramas, scatter, boxplots, etc. SVG queda perfecto en GitHub y es liviano.

Tip DRY: guarda tus datos en /data/*.csv y escribe un Makefile o scripts/build.py que regenere todo en un paso.

---

4) Interactividad con GitHub Pages + Vega-Lite

Las wikis sanitizan HTML/JS, así que lo interactivo real va mejor en Pages. Crea /docs/chart.html en el repo principal y en Settings → Pages activa la rama que sirva /docs/.

4.1. HTML mínimo (Vega-Lite)

Guarda como docs/chart.html en el repo principal:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Demo Vega-Lite</title>
    <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
  </head>
  <body>
    <div id="vis"></div>
    <script>
      const spec = {
        "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
        "description": "Ventas por mes",
        "data": {
          "values": [
            {"mes":"E","ventas":12},{"mes":"F","ventas":14},
            {"mes":"M","ventas":18},{"mes":"A","ventas":17},
            {"mes":"M","ventas":20},{"mes":"J","ventas":21},
            {"mes":"J","ventas":25},{"mes":"A","ventas":24},
            {"mes":"S","ventas":23},{"mes":"O","ventas":27},
            {"mes":"N","ventas":28},{"mes":"D","ventas":30}
          ]
        },
        "mark": "line",
        "encoding": {
          "x": {"field": "mes", "type": "ordinal", "title": "Mes"},
          "y": {"field": "ventas", "type": "quantitative", "title": "Unidades"},
          "tooltip": [{"field":"mes"},{"field":"ventas"}]
        }
      };
      vegaEmbed('#vis', spec, {actions: false});
    </script>
  </body>
</html>

Luego, desde la wiki, enlaza:

👉 [Ver gráfico interactivo (Vega-Lite)](https://<usuario>.github.io/<repo>/chart.html)

---

5) Jupyter Notebooks (estáticos en GitHub)

Si usas notebooks (.ipynb) con Matplotlib/Plotly:

• Sube el .ipynb al repo.
• GitHub lo renderiza estáticamente (las imágenes ya generadas se ven).
• En la wiki, enlaza el notebook:

[Exploración de ventas (Notebook)](../blob/main/notebooks/exploracion_ventas.ipynb)

---

6) Automatizar (opcional) — Regenerar imágenes en cada push

Si quieres regenerar imágenes estáticas automáticamente:

1. Pon tus scripts en el repo de la wiki o en el principal (si alojas imágenes allí).
2. Crea un workflow mínimo .github/workflows/build-plots.yml (en el repo que guarda las imágenes):

name: build-plots
on:
  push:
    paths:
      - 'data/**'
      - 'scripts/**'
      - '.github/workflows/build-plots.yml'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: python -m pip install --upgrade pip matplotlib
      - run: python scripts/graficas.py
      - name: Commit updated images
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add img/*.svg || true
          git commit -m "Update plots" || echo "No changes"
          git push

Para actuar sobre el repo de la wiki, lo más limpio es mantener las imágenes en el repo principal (carpeta /docs/img o /assets/img) y usarlas desde la wiki con rutas absolutas al GitHub Pages (cuando tengas Pages activo), o clonar manualmente la wiki para subir imágenes.

---

7) Resumen táctico (elige según objetivo)

• Notas/diagramas rápidos → Mermaid + MathJax en la wiki (nativo).
• Gráficos de datos estáticos → genera SVG con Python y embébelo en la wiki.
• Interactividad real → GitHub Pages + Vega-Lite y enlaza desde la wiki.
• Prototipo de análisis → Notebook .ipynb con imágenes incluidas y enlace desde wiki.

Si quieres, te preparo una plantilla mínima de repo + wiki:

• /data/ (CSV de ejemplo)
• /scripts/graficas.py (genera SVG)
• /docs/chart.html (Vega-Lite)
• Wiki con Home.md enlazando a img/*.svg, a chart.html, y con secciones Mermaid/MathJax.