# Manual de uso — GrafiEstadistik

Manual práctico para usar `grafiestadistik-motorv2.js` junto con `grafiestadistik-autov3.js` en páginas web o Moodle.

El sistema funciona en dos capas:

1. **Motor**: define las funciones que dibujan los gráficos SVG.
2. **Auto**: busca elementos HTML con clases específicas y lee sus atributos `data-*` para dibujar automáticamente.

---

## 1. Archivos necesarios

Carga siempre primero el motor y después el autoinicializador:

```html
<script src="grafiestadistik-motorv2.js"></script>
<script src="grafiestadistik-autov3.js"></script>
```

En Moodle puedes dejarlos en `additionalhtmlhead` o cargarlos desde CDN, por ejemplo:

```html
<script src="https://cdn.jsdelivr.net/gh/USUARIO/REPOSITORIO/ruta/grafiestadistik-motorv2.js"></script>
<script src="https://cdn.jsdelivr.net/gh/USUARIO/REPOSITORIO/ruta/grafiestadistik-autov3.js"></script>
```

El archivo `grafiestadistik-autov3.js` se ejecuta automáticamente cuando el documento está listo. También puedes reinicializar manualmente con:

```js
window.GrafiEstadistikAuto.inicializar(document);
```

O sobre una sección específica:

```js
const bloque = document.querySelector("#mi-bloque");
window.GrafiEstadistikAuto.inicializar(bloque);
```

---

## 2. Reglas generales de escritura HTML

Cada gráfico necesita:

- Un `id` único.
- Una clase específica, por ejemplo `grafico-lineas-auto`.
- Atributos `data-*` con datos en formato JSON válido.

Ejemplo mínimo:

```html
<div id="poligono-1" class="grafico-lineas-auto"
  data-etiquetas-x='["4,5","14,5","24,5","34,5","44,5"]'
  data-valores-y='[2,5,8,4,1]'></div>
```

En Moodle, si el editor convierte comillas, puedes usar `&quot;`:

```html
<div id="poligono-1" class="grafico-lineas-auto"
  data-etiquetas-x="[&quot;4,5&quot;,&quot;14,5&quot;,&quot;24,5&quot;,&quot;34,5&quot;,&quot;44,5&quot;]"
  data-valores-y="[2,5,8,4,1]"></div>
```

### Conversión de nombres `data-*`

JavaScript convierte automáticamente nombres con guion a formato camelCase:

| En HTML | En JS |
|---|---|
| `data-etiquetas-x` | `dataset.etiquetasX` |
| `data-valores-y` | `dataset.valoresY` |
| `data-etiquetas-ejes` | `dataset.etiquetasEjes` |
| `data-min-y` | `dataset.minY` |
| `data-max-y` | `dataset.maxY` |
| `data-ticks-y` | `dataset.ticksY` |
| `data-range-x` | `dataset.rangeX` |
| `data-step-x` | `dataset.stepX` |
| `data-radio-punto` | `dataset.radioPunto` |

---

## 3. Gráfico de líneas / polígono de frecuencias

Clase:

```html
class="grafico-lineas-auto"
```

Uso recomendado para polígonos de frecuencia.

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único del contenedor. |
| `data-etiquetas-x` | Sí | Lista de etiquetas del eje X. |
| `data-valores-y` | Sí | Lista de valores del eje Y. Debe tener la misma cantidad de elementos que `data-etiquetas-x`. |
| `data-etiquetas-ejes` | No | Objeto JSON con etiquetas y configuración del eje Y. |
| `data-color` | No | Color de la línea y los puntos. Por defecto `#3e95cd`. |

### Opciones de `data-etiquetas-ejes`

```json
{
  "x": "Marca de clase",
  "y": "Frecuencia",
  "minY": 0,
  "maxY": 10,
  "ticksY": 5
}
```

Si todas las etiquetas X son numéricas, incluso escritas con coma decimal como `"4,5"`, el motor las trata como escala numérica. Si no son numéricas, las distribuye de forma ordinal.

### Ejemplo mínimo

```html
<div id="poligono-1" class="grafico-lineas-auto"
  data-etiquetas-x='["4,5","14,5","24,5","34,5","44,5"]'
  data-valores-y='[2,5,8,4,1]'></div>
```

### Ejemplo completo

```html
<div id="poligono-2" class="grafico-lineas-auto"
  data-etiquetas-x='["4,5","14,5","24,5","34,5","44,5"]'
  data-valores-y='[2,5,8,4,1]'
  data-etiquetas-ejes='{
    "x":"Marca de clase",
    "y":"Frecuencia",
    "minY":0,
    "maxY":10,
    "ticksY":5
  }'
  data-color="#ff6200"></div>
```

### Ejemplo compatible con Moodle usando `&quot;`

```html
<div id="poligono-2" class="grafico-lineas-auto"
  data-etiquetas-x="[&quot;4,5&quot;,&quot;14,5&quot;,&quot;24,5&quot;,&quot;34,5&quot;,&quot;44,5&quot;]"
  data-valores-y="[2,5,8,4,1]"
  data-etiquetas-ejes="{
    &quot;x&quot;:&quot;Marca de clase&quot;,
    &quot;y&quot;:&quot;Frecuencia&quot;,
    &quot;minY&quot;:0,
    &quot;maxY&quot;:10,
    &quot;ticksY&quot;:5
  }"
  data-color="#ff6200"></div>
```

---

## 4. Gráfico de barras

Clase:

```html
class="grafico-barra-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-frecuencias` | Sí | Lista numérica de frecuencias. |
| `data-etiquetas` | Sí | Lista de etiquetas. Debe tener la misma cantidad de elementos que `data-frecuencias`. |
| `data-color` | No | Color de las barras. Por defecto `#ccc`. |
| `data-min-y` | No | Mínimo manual del eje Y. |
| `data-max-y` | No | Máximo manual del eje Y. |
| `data-ticks-y` | No | Cantidad de divisiones del eje Y. |
| `data-posicion-etiquetas` | No | `1` para etiquetas horizontales, `0` para etiquetas rotadas verticalmente. |

### Ejemplo

```html
<div id="barras-1" class="grafico-barra-auto"
  data-etiquetas='["A","B","C","D"]'
  data-frecuencias='[4,7,3,6]'
  data-color="#4caf50"
  data-min-y="0"
  data-max-y="10"
  data-ticks-y="5"
  data-posicion-etiquetas="1"></div>
```

### Ejemplo con etiquetas largas

```html
<div id="barras-2" class="grafico-barra-auto"
  data-etiquetas='["Muy bajo","Bajo","Medio","Alto","Muy alto"]'
  data-frecuencias='[2,5,8,6,3]'
  data-color="#ff6200"
  data-posicion-etiquetas="0"></div>
```

---

## 5. Histograma

Clase:

```html
class="histograma-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-frecuencias` | Sí | Lista de frecuencias. |
| `data-limites` | Sí | Lista de límites de clase. Debe tener una posición más que las frecuencias. |
| `data-color` | No | Color de las barras. |
| `data-min-y` | No | Mínimo del eje Y. |
| `data-max-y` | No | Máximo del eje Y. |
| `data-ticks-y` | No | Cantidad de divisiones del eje Y. |

### Ejemplo

```html
<div id="histograma-1" class="histograma-auto"
  data-limites='[0,10,20,30,40,50]'
  data-frecuencias='[2,5,8,4,1]'
  data-color="#4caf50"
  data-min-y="0"
  data-max-y="10"
  data-ticks-y="5"></div>
```

---

## 6. Ojiva

Clase:

```html
class="ojiva-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-limites` | Sí | Lista de límites. Puede tener la misma longitud que las frecuencias acumuladas o una posición más. |
| `data-frecuencias-acumuladas` | Sí | Lista de frecuencias acumuladas. |
| `data-color` | No | Color de la línea. Por defecto `#4bc0c0`. |
| `data-min-y` | No | Mínimo del eje Y. |
| `data-max-y` | No | Máximo del eje Y. |
| `data-ticks-y` | No | Cantidad de divisiones del eje Y. |
| `data-etiquetas-ejes` | No | Objeto con `x` e `y`. |
| `data-etiqueta-x` | No | Alternativa simple para nombrar el eje X. |
| `data-etiqueta-y` | No | Alternativa simple para nombrar el eje Y. |

Cuando `data-limites` tiene una posición más que `data-frecuencias-acumuladas`, el motor agrega automáticamente un punto inicial con frecuencia acumulada `0`.

### Ejemplo

```html
<div id="ojiva-1" class="ojiva-auto"
  data-limites='[0,10,20,30,40,50]'
  data-frecuencias-acumuladas='[2,7,15,19,20]'
  data-etiquetas-ejes='{"x":"Límite superior","y":"Frecuencia acumulada"}'
  data-color="#ff6200"
  data-min-y="0"
  data-max-y="20"
  data-ticks-y="4"></div>
```

---

## 7. Gráfico de dispersión

Clase:

```html
class="grafico-dispersion-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-puntos` | Sí | Lista de objetos `{ "x": número, "y": número }`. |
| `data-etiquetas` | No | Objeto con configuración avanzada. |
| `data-etiquetas-ejes` | No | Objeto con nombres de ejes `{ "x":"...", "y":"..." }`. |
| `data-etiqueta-x` | No | Nombre simple del eje X. |
| `data-etiqueta-y` | No | Nombre simple del eje Y. |
| `data-range-x` | No | Rango manual X como texto: `"0,100"`. |
| `data-range-y` | No | Rango manual Y como texto: `"0,50"`. |
| `data-step-x` | No | Salto entre marcas del eje X. |
| `data-step-y` | No | Salto entre marcas del eje Y. |
| `data-ticks-x` | No | Cantidad de divisiones en X si no se usa `stepX`. |
| `data-ticks-y` | No | Cantidad de divisiones en Y si no se usa `stepY`. |
| `data-width` | No | Ancho del SVG. Por defecto `640`. |
| `data-height` | No | Alto del SVG. Por defecto `420`. |
| `data-radio-punto` | No | Radio de cada punto. |
| `data-color` | No | Color de los puntos. |

### Ejemplo básico

```html
<div id="dispersion-1" class="grafico-dispersion-auto"
  data-puntos='[
    {"x":1,"y":2},
    {"x":2,"y":4},
    {"x":3,"y":5},
    {"x":4,"y":7}
  ]'
  data-etiquetas-ejes='{"x":"Horas de estudio","y":"Puntaje"}'
  data-color="#4caf50"></div>
```

### Ejemplo con rangos y saltos

```html
<div id="dispersion-2" class="grafico-dispersion-auto"
  data-puntos='[
    {"x":10,"y":35},
    {"x":20,"y":42},
    {"x":30,"y":50},
    {"x":40,"y":63}
  ]'
  data-etiqueta-x="Tiempo"
  data-etiqueta-y="Resultado"
  data-range-x="0,50"
  data-range-y="0,70"
  data-step-x="10"
  data-step-y="10"
  data-width="640"
  data-height="420"
  data-radio-punto="5"
  data-color="#ff6200"></div>
```

### Configuración avanzada en `data-etiquetas`

También puedes pasar configuración dentro de `data-etiquetas`:

```html
<div id="dispersion-3" class="grafico-dispersion-auto"
  data-puntos='[{"x":1,"y":3},{"x":2,"y":5},{"x":3,"y":8}]'
  data-etiquetas='{
    "x":"Variable X",
    "y":"Variable Y",
    "minX":0,
    "maxX":4,
    "minY":0,
    "maxY":10,
    "ticksX":4,
    "ticksY":5,
    "anchoSVG":640,
    "altoSVG":420,
    "radioPunto":5
  }'
  data-color="#1976d2"></div>
```

---

## 8. Gráfico circular

Clase:

```html
class="grafico-circular-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-datos` | Sí | Lista de objetos con `label`, `valor` y opcionalmente `color`. |

### Ejemplo

```html
<div id="circular-1" class="grafico-circular-auto"
  data-datos='[
    {"label":"A","valor":12,"color":"#4caf50"},
    {"label":"B","valor":8,"color":"#ff6200"},
    {"label":"C","valor":5,"color":"#2196f3"}
  ]'></div>
```

Si no se define `color` en cada sector, el motor asigna colores por defecto.

---

## 9. Pictograma

Clase:

```html
class="pictograma-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-datos` | Sí | Lista de objetos `{ "label":"...", "valor": número }`. |
| `data-icono` | Sí | Ruta SVG tipo `path d`. |
| `data-valor-por-icono` | Sí | Valor que representa cada ícono. |
| `data-color` | No | Color del ícono. |

El motor permite íconos fraccionarios cuando el valor no es múltiplo exacto de `data-valor-por-icono`.

### Ejemplo

```html
<div id="pictograma-1" class="pictograma-auto"
  data-datos='[
    {"label":"Lunes","valor":10},
    {"label":"Martes","valor":15},
    {"label":"Miércoles","valor":7}
  ]'
  data-icono="M12 2 L15 9 L22 9 L17 14 L19 21 L12 17 L5 21 L7 14 L2 9 L9 9 Z"
  data-valor-por-icono="5"
  data-color="#ff6200"></div>
```

---

## 10. Gráfico de caja y bigotes

Clase:

```html
class="caja-auto"
```

### Atributos

| Atributo | Obligatorio | Descripción |
|---|---:|---|
| `id` | Sí | Identificador único. |
| `data-valores` | Sí | Objeto con resumen de cinco números. |
| `data-color` | No | Color de la caja. |

### Estructura de `data-valores`

```json
{
  "min": 2,
  "q1": 5,
  "mediana": 8,
  "q3": 12,
  "max": 16,
  "limiteMin": 0,
  "limiteMax": 20,
  "salto": 5
}
```

Los campos obligatorios son:

- `min`
- `q1`
- `mediana`
- `q3`
- `max`

Los campos opcionales son:

- `limiteMin`
- `limiteMax`
- `salto`

Debe cumplirse:

```text
min <= q1 <= mediana <= q3 <= max
```

### Ejemplo

```html
<div id="caja-1" class="caja-auto"
  data-valores='{
    "min":2,
    "q1":5,
    "mediana":8,
    "q3":12,
    "max":16,
    "limiteMin":0,
    "limiteMax":20,
    "salto":5
  }'
  data-color="rgba(255, 159, 64, 0.5)"></div>
```

---

## 11. Uso manual con JavaScript

Además del modo automático por HTML, el motor exporta funciones en:

```js
window.GrafiEstadistik
```

También mantiene compatibilidad legacy, por lo que las funciones pueden existir directamente en `window`.

### Funciones disponibles

```js
window.GrafiEstadistik.dibujarGraficoBarra(
  contenedorId,
  frecuencias,
  etiquetasX,
  color,
  minY,
  maxY,
  ticksY,
  posicionEtiquetas
);

window.GrafiEstadistik.dibujarPictograma(
  contenedorId,
  datos,
  icono,
  valorPorIcono,
  color
);

window.GrafiEstadistik.dibujarHistograma(
  contenedorId,
  frecuencias,
  limites,
  color,
  minY,
  maxY,
  ticksY
);

window.GrafiEstadistik.dibujarGraficoCircular(
  contenedorId,
  datos
);

window.GrafiEstadistik.dibujarGraficoCaja(
  contenedorId,
  valores,
  color
);

window.GrafiEstadistik.dibujarOjiva(
  contenedorId,
  limites,
  frecuenciasAcumuladas,
  color,
  minY,
  maxY,
  ticksY,
  etiquetasEjes
);

window.GrafiEstadistik.dibujarGraficoDispersion(
  contenedorId,
  puntos,
  etiquetas,
  color
);

window.GrafiEstadistik.dibujarGraficoLineas(
  contenedorId,
  etiquetasX,
  valoresY,
  etiquetasEjes,
  color
);
```

### Ejemplo manual

```html
<div id="manual-lineas"></div>

<script>
window.GrafiEstadistik.dibujarGraficoLineas(
  "manual-lineas",
  ["4,5", "14,5", "24,5", "34,5", "44,5"],
  [2, 5, 8, 4, 1],
  {
    x: "Marca de clase",
    y: "Frecuencia",
    minY: 0,
    maxY: 10,
    ticksY: 5
  },
  "#ff6200"
);
</script>
```

---

## 12. Plantilla general para Moodle

```html
<section class="ejemplo">
  <h3>Polígono de frecuencias</h3>

  <div id="poligono-ejemplo" class="grafico-lineas-auto"
    data-etiquetas-x="[&quot;4,5&quot;,&quot;14,5&quot;,&quot;24,5&quot;,&quot;34,5&quot;,&quot;44,5&quot;]"
    data-valores-y="[2,5,8,4,1]"
    data-etiquetas-ejes="{
      &quot;x&quot;:&quot;Marca de clase&quot;,
      &quot;y&quot;:&quot;Frecuencia&quot;,
      &quot;minY&quot;:0,
      &quot;maxY&quot;:10,
      &quot;ticksY&quot;:5
    }"
    data-color="#ff6200"></div>

  <p>El gráfico anterior representa un polígono de frecuencias usando marcas de clase.</p>
</section>
```

---

## 13. Colores recomendados para Profe Arauco

```text
Naranjo principal: #ff6200
Verde principal:   #4caf50
Azul apoyo:        #1976d2
Calipso apoyo:     #4bc0c0
Gris neutro:       #666666
```

Ejemplo:

```html
<div id="barras-arauco" class="grafico-barra-auto"
  data-etiquetas='["Inicio","Proceso","Logrado"]'
  data-frecuencias='[3,9,6]'
  data-color="#ff6200"></div>
```

---

## 14. Errores frecuentes

### 1. El gráfico no aparece

Revisa:

- Que el `id` exista y sea único.
- Que el motor se cargue antes que el auto.
- Que la clase sea correcta.
- Que el JSON sea válido.
- Que las listas tengan longitudes compatibles.

### 2. Error al parsear `data-*`

Probablemente hay comillas mal escritas. Usa una de estas dos formas:

```html
data-valores-y='[2,5,8,4,1]'
```

O en Moodle:

```html
data-etiquetas-x="[&quot;A&quot;,&quot;B&quot;,&quot;C&quot;]"
```

### 3. Barras o líneas se ven aplastadas

Define manualmente el eje Y:

```html
data-min-y="0"
data-max-y="20"
data-ticks-y="5"
```

En gráfico de líneas, esto va dentro de `data-etiquetas-ejes`:

```html
data-etiquetas-ejes='{"minY":0,"maxY":20,"ticksY":5}'
```

### 4. Dispersión muestra rangos extraños

Fija los rangos manualmente:

```html
data-range-x="0,100"
data-range-y="0,50"
data-step-x="10"
data-step-y="5"
```

### 5. Histograma no aparece

Revisa que:

```text
cantidad de límites = cantidad de frecuencias + 1
```

Ejemplo correcto:

```text
frecuencias: [2,5,8,4,1]       → 5 clases
límites:     [0,10,20,30,40,50] → 6 límites
```

---

## 15. Resumen rápido de clases

| Tipo de gráfico | Clase HTML |
|---|---|
| Barras | `grafico-barra-auto` |
| Pictograma | `pictograma-auto` |
| Histograma | `histograma-auto` |
| Circular | `grafico-circular-auto` |
| Caja y bigotes | `caja-auto` |
| Ojiva | `ojiva-auto` |
| Dispersión | `grafico-dispersion-auto` |
| Líneas / polígono | `grafico-lineas-auto` |

---

## 16. Ejemplo completo integrado

```html
<h3>Ejemplos GrafiEstadistik</h3>

<p>Gráfico de barras</p>
<div id="barras-demo" class="grafico-barra-auto"
  data-etiquetas='["A","B","C","D"]'
  data-frecuencias='[4,7,3,6]'
  data-color="#4caf50"></div>

<p>Histograma</p>
<div id="histograma-demo" class="histograma-auto"
  data-limites='[0,10,20,30,40,50]'
  data-frecuencias='[2,5,8,4,1]'
  data-color="#ff6200"></div>

<p>Polígono de frecuencias</p>
<div id="poligono-demo" class="grafico-lineas-auto"
  data-etiquetas-x='["4,5","14,5","24,5","34,5","44,5"]'
  data-valores-y='[2,5,8,4,1]'
  data-etiquetas-ejes='{"x":"Marca de clase","y":"Frecuencia","minY":0,"maxY":10,"ticksY":5}'
  data-color="#1976d2"></div>

<p>Ojiva</p>
<div id="ojiva-demo" class="ojiva-auto"
  data-limites='[0,10,20,30,40,50]'
  data-frecuencias-acumuladas='[2,7,15,19,20]'
  data-color="#4bc0c0"
  data-etiqueta-x="Límite superior"
  data-etiqueta-y="Frecuencia acumulada"></div>

<p>Dispersión</p>
<div id="dispersion-demo" class="grafico-dispersion-auto"
  data-puntos='[{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":5},{"x":4,"y":7}]'
  data-etiqueta-x="Horas"
  data-etiqueta-y="Puntaje"
  data-range-x="0,5"
  data-range-y="0,10"
  data-step-x="1"
  data-step-y="2"
  data-color="#ff6200"></div>

<p>Circular</p>
<div id="circular-demo" class="grafico-circular-auto"
  data-datos='[
    {"label":"A","valor":12,"color":"#4caf50"},
    {"label":"B","valor":8,"color":"#ff6200"},
    {"label":"C","valor":5,"color":"#2196f3"}
  ]'></div>

<p>Caja y bigotes</p>
<div id="caja-demo" class="caja-auto"
  data-valores='{"min":2,"q1":5,"mediana":8,"q3":12,"max":16,"limiteMin":0,"limiteMax":20,"salto":5}'
  data-color="rgba(255, 159, 64, 0.5)"></div>
```