 DataCentral - Librería para Análisis Estadístico

## Descripción

DataCentral es una librería Python diseñada para realizar análisis estadístico básico sobre conjuntos de datos. Proporciona funcionalidades para calcular medidas de tendencia central, dispersión y variabilidad, tanto para datos agrupados como no agrupados.

## Instalación

```bash
pip install eviastatistics 
```

## Requisitos

- Python 3.6 o superior
- No requiere dependencias externas adicionales

## Uso Básico

### Importar la librería

```python
from eviastatistics import DataCentral


# Crear una instancia con datos
datos = [23, 45, 67, 89, 12, 34, 56, 78, 90, 11]
descripcion = "Edades de participantes en el estudio"
dc = DataCentral(datos, descripcion)
```

## Métodos Disponibles

### Constructor

```python
DataCentral(data, description)
```

**Parámetros:**
- `data` (list): Lista de valores numéricos (mínimo 2 elementos)
- `description` (str): Descripción textual del conjunto de datos

**Ejemplo:**
```python
try:
    datos = [15, 22, 30, 35, 42, 50, 55, 60]
    dc = DataCentral(datos, "Edades de empleados")
except (TypeError, ValueError) as e:
    print(f"Error: {e}")
```

### 1. Media Aritmética (`mean()`)

Calcula el promedio de los datos.

```python
mean(grouped=False, decimal_places=2)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados
- `decimal_places` (int): Número de decimales para redondear

**Ejemplos:**
```python
# Datos no agrupados
media_no_agrupada = dc.mean(grouped=False, decimal_places=2)
print(f"Media no agrupada: {media_no_agrupada}")

# Datos agrupados
media_agrupada = dc.mean(grouped=True, decimal_places=2)
print(f"Media agrupada: {media_agrupada}")
```

### 2. Mediana (`median()`)

Encuentra el valor central de los datos ordenados.

```python
median(grouped=False)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados

**Ejemplos:**
```python
# Datos no agrupados
mediana_no_agrupada = dc.median(grouped=False)
print(f"Mediana no agrupada: {mediana_no_agrupada}")

# Datos agrupados
mediana_agrupada = dc.median(grouped=True)
print(f"Mediana agrupada: {mediana_agrupada}")
```

### 3. Moda (`mode()`)

Encuentra el valor o valores más frecuentes.

```python
mode(grouped=False)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados

**Ejemplos:**
```python
# Datos no agrupados
moda_no_agrupada = dc.mode(grouped=False)
print(f"Moda no agrupada: {moda_no_agrupada}")

# Datos agrupados
moda_agrupada = dc.mode(grouped=True)
print(f"Moda agrupada: {moda_agrupada}")
```

### 4. Varianza (`variance()`)

Calcula la varianza de los datos.

```python
variance(grouped=False, decimal_places=2)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados
- `decimal_places` (int): Número de decimales para redondear

**Ejemplo:**
```python
varianza = dc.variance(grouped=False, decimal_places=3)
print(f"Varianza: {varianza}")
```

### 5. Desviación Estándar (`standard_deviation()`)

Calcula la desviación estándar (raíz cuadrada de la varianza).

```python
standard_deviation(grouped=False, decimal_places=2)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados
- `decimal_places` (int): Número de decimales para redondear

**Ejemplo:**
```python
desviacion = dc.standard_deviation(grouped=False, decimal_places=3)
print(f"Desviación estándar: {desviacion}")
```

### 6. Coeficiente de Variación (`coefficient_of_variation()`)

Calcula el coeficiente de variación (CV) como porcentaje.

```python
coefficient_of_variation(grouped=False, decimal_places=2)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados
- `decimal_places` (int): Número de decimales para redondear

**Ejemplo:**
```python
cv = dc.coefficient_of_variation(grouped=False, decimal_places=2)
print(f"Coeficiente de variación: {cv}%")
```

### 7. Desviación Media (`mean_deviation()`)

Calcula la desviación absoluta promedio respecto a la media.

```python
mean_deviation(grouped=False, decimal_places=2)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados
- `decimal_places` (int): Número de decimales para redondear

**Ejemplo:**
```python
desv_media = dc.mean_deviation(grouped=False, decimal_places=3)
print(f"Desviación media: {desv_media}")
```

### 8. Desviación Mediana (`median_deviation()`)

Calcula la desviación absoluta promedio respecto a la mediana.

```python
median_deviation(grouped=False, decimal_places=2)
```

**Parámetros:**
- `grouped` (bool): `True` para datos agrupados, `False` para no agrupados
- `decimal_places` (int): Número de decimales para redondear

**Ejemplo:**
```python
desv_mediana = dc.median_deviation(grouped=False, decimal_places=3)
print(f"Desviación mediana: {desv_mediana}")
```

## Atributos de la Clase

| Atributo | Descripción | Tipo |
|----------|-------------|------|
| `data` | Lista original de datos | list |
| `description` | Descripción del conjunto de datos | str |
| `n` | Número total de elementos | int |
| `amplitude` | Amplitud de intervalo para datos agrupados | float |
| `intervalos` | Número de intervalos para datos agrupados | int |

## Ejemplo Completo

```python
from datacentral import DataCentral

# Crear conjunto de datos
calificaciones = [85, 92, 78, 90, 88, 76, 95, 89, 84, 91, 87, 93, 79, 86, 94]
estadisticas = DataCentral(calificaciones, "Calificaciones de estudiantes")

# Calcular todas las medidas
print(f"Descripción: {estadisticas.description}")
print(f"Número de datos: {estadisticas.n}")
print(f"Media: {estadisticas.mean(grouped=False, decimal_places=2)}")
print(f"Mediana: {estadisticas.median(grouped=False)}")
print(f"Moda: {estadisticas.mode(grouped=False)}")
print(f"Varianza: {estadisticas.variance(grouped=False, decimal_places=3)}")
print(f"Desviación estándar: {estadisticas.standard_deviation(grouped=False, decimal_places=3)}")
print(f"Coeficiente de variación: {estadisticas.coefficient_of_variation(grouped=False, decimal_places=2)}%")
print(f"Desviación media: {estadisticas.mean_deviation(grouped=False, decimal_places=3)}")
print(f"Desviación mediana: {estadisticas.median_deviation(grouped=False, decimal_places=3)}")

# Para datos agrupados
print(f"\nPara datos agrupados:")
print(f"Media: {estadisticas.mean(grouped=True, decimal_places=2)}")
print(f"Mediana: {estadisticas.median(grouped=True)}")
print(f"Moda: {estadisticas.mode(grouped=True)}")
```

## Manejo de Errores

La librería incluye validaciones que generan excepciones específicas:

```python
try:
    # Error: datos no es una lista
    dc = DataCentral("no es una lista", "descripción")
except TypeError as e:
    print(f"TypeError: {e}")

try:
    # Error: lista vacía
    dc = DataCentral([], "descripción")
except ValueError as e:
    print(f"ValueError: {e}")

try:
    # Error: menos de 2 elementos
    dc = DataCentral([1], "descripción")
except ValueError as e:
    print(f"ValueError: {e}")
```

## Notas Importantes

1. **Ordenamiento automático**: Los métodos que lo requieren ordenan automáticamente los datos.
2. **Agrupación de datos**: Cuando se usa `grouped=True`, la librería calcula automáticamente la amplitud y número de intervalos usando la regla de Sturges.
3. **Redondeo**: Todos los métodos que aceptan `decimal_places` redondean el resultado al número de decimales especificado.
4. **Datos agrupados vs no agrupados**: Algunas medidas pueden tener fórmulas diferentes según el tipo de datos.

## Limitaciones

- Diseñada para análisis estadístico básico
- No incluye pruebas de hipótesis
- No incluye análisis de correlación o regresión
- La agrupación automática usa la regla de Sturges exclusivamente

## Licencia

[MIT License](https://opensource.org/licenses/MIT)
