ComputationalStats — StatsLibX

Constructor

ComputationalStats(data, seed, lang)

data: pd.DataFrame | np.ndarray · seed: int | None = None · lang: 'es-ES' | 'en-US' = 'es-ES'

Inicializa con un DataFrame de pandas o array numpy. Detecta automáticamente columnas numéricas y categóricas. Con seed garantiza reproducibilidad en K-Means y Bootstrapping.

Parámetro	Tipo	Default	Descripción
data	pd.DataFrame \| np.ndarray	—	Dataset de entrada (requerido)
seed	int \| None	None	Semilla para reproducibilidad de métodos aleatorios
lang	str	'es-ES'	Idioma de salidas: `'es-ES'` o `'en-US'`

Python

from statslibx import ComputationalStats

from statslibx.datasets import load_iris



data = load_iris()

cs = ComputationalStats(data, seed=42)

Regresión

.regression(X, y, degree, interaction_terms)

X: str | List[str] · y: str · degree: int = 1 · interaction_terms: bool = False

→ RegressionResult

↩ RegressionResult

Regresión polinomial simple o múltiple. Para una variable, degree controla el grado del polinomio. Para varias variables usa regresión lineal múltiple. Internamente resuelve con ecuaciones normales y fallback a pseudo-inversa. Genera expresión simbólica con SymPy.

Parámetro	Tipo	Default	Descripción
X	str \| List[str]	—	Columna(s) predictora(s)
y	str	—	Columna objetivo
degree	int	1	Grado del polinomio (solo para una variable predictora)
interaction_terms	bool	False	Incluir términos de interacción en regresión múltiple

Python

# Regresión lineal simple

modelo = cs.regression(X='sepal_length', y='petal_length')

print(modelo)

# 



# Ver resumen completo

s = modelo.summary()

print(s['metrics'])      # R², RMSE, MAE, AIC, BIC...

print(s['coefficients']) # tabla con t-stats y p-values

print(s['formula']['latex'])  # expresión LaTeX



# Predicciones

preds = modelo.predict([5.0, 6.0, 7.0])



# Regresión polinomial grado 3

modelo3 = cs.regression('sepal_length', 'petal_length', degree=3)

print(f"R² = {modelo3.r2:.4f}")



# Regresión múltiple

modelo_m = cs.regression(['sepal_length', 'sepal_width'], 'petal_length')

print(modelo_m.get_formula())

.linear_regression(X, y)

Atajo de .regression(X, y, degree=1)

→ RegressionResult

Atajo para regresión lineal simple o múltiple (degree=1).

Python

modelo = cs.linear_regression('sepal_length', 'petal_length')

modelo.plot()                   # 4 paneles: fit, residuales, Q-Q, histograma

modelo.plot(interactive=True)  # Plotly interactivo

modelo.plot(plot_type='qq')    # Solo Q-Q plot

.polynomial_regression(X, y, degree)

X: str · y: str · degree: int = 2

→ RegressionResult

Atajo para regresión polinomial. Solo admite una variable predictora.

Python

modelo = cs.polynomial_regression('sepal_length', 'petal_length', degree=3)

print(f"Fórmula: {modelo.get_formula()}")

print(f"LaTeX:   {modelo.latex_expr}")



import numpy as np

preds = modelo.predict(np.linspace(4.5, 8.0, 20))

.find_best_degree(X, y, max_degree, metric)

X: str · y: str · max_degree: int = 5 · metric: 'r2' | 'aic' | 'bic' = 'r2'

→ dict

Evalúa grados 1 a max_degree y retorna el mejor según la métrica. 'r2' se maximiza; 'aic' y 'bic' se minimizan. Incluye todos los resultados en 'all_results'.

Python

resultado = cs.find_best_degree('sepal_length', 'petal_length', max_degree=5, metric='bic')

print(f"Mejor grado: {resultado['degree']}")

print(f"R²:  {resultado['r2']:.4f}")

print(f"BIC: {resultado['bic']:.4f}")



# Tabla comparativa

for r in resultado['all_results']:

    print(f"Grado {r['degree']}: R²={r['r2']:.4f}  AIC={r['aic']:.2f}  BIC={r['bic']:.2f}")



# Graficar el mejor modelo

resultado['model'].plot()

Interpolación

.interpolation(points, method, spline_degree)

points: List[Tuple[float, float]] · method: 'lagrange'|'newton'|'spline' = 'lagrange' · spline_degree: int = 3

→ InterpolationResult

↩ InterpolationResult

Calcula un polinomio de interpolación a partir de puntos (x, y). Lagrange y Newton generan expresión simbólica SymPy y código LaTeX. Spline usa scipy.interpolate.interp1d.

Método	Descripción	Expr. simbólica
'lagrange'	Polinomio de Lagrange clásico. Eficiente para pocos puntos.	Sí (SymPy)
'newton'	Diferencias divididas de Newton. Más estable numéricamente.	Sí (SymPy)
'spline'	Spline de grado `spline_degree` vía SciPy. Suaviza oscilaciones.	No

Python

points = [(0, 1), (1, 3), (2, 2), (3, 5), (4, 4)]



# Lagrange

interp = cs.interpolation(points, method='lagrange')

print(interp.summary())

print(f"LaTeX: {interp.latex_expr}")

interp.plot()

interp.plot(interactive=True)



# Newton

interp_n = cs.interpolation(points, method='newton')

print(f"En x=2.5: {interp_n.predict(2.5):.4f}")



# Evaluar en múltiples puntos

import numpy as np

x_new = np.linspace(0, 4, 100)

y_new = interp.predict(x_new)



# Spline cúbico

interp_s = cs.interpolation(points, method='spline', spline_degree=3)

Bootstrapping

.bootstrapping(column, n_samples, statistic, confidence_level, custom_func)

column: str · n_samples: int = 1000 · statistic: 'mean'|'median'|'std'|'custom' · confidence_level: float = 0.95

→ BootstrappingResult

↩ BootstrappingResult

Remuestreo bootstrap sobre una columna. Calcula tres tipos de intervalos de confianza: percentil, básico y normal. Acepta funciones personalizadas con statistic='custom'.

Parámetro	Tipo	Default	Descripción
column	str	—	Columna del DataFrame a remuestrear
n_samples	int	1000	Número de muestras bootstrap
statistic	str	'mean'	`'mean'`, `'median'`, `'std'` o `'custom'`
confidence_level	float	0.95	Nivel de confianza para los 3 tipos de IC
custom_func	callable \| None	None	Función personalizada si `statistic='custom'`. Recibe `np.ndarray`, retorna escalar.

Python

# Bootstrap de la media — IC 95%

boot = cs.bootstrapping('sepal_length', n_samples=2000, statistic='mean')

s = boot.summary()

print(f"Estadístico original: {s['original_statistic']:.4f}")

print(f"Sesgo:               {s['bias']:.6f}")

print(f"Error estándar:      {s['std_error']:.4f}")



ic = s['confidence_interval_95%']

print(f"IC Percentil: {ic['percentile']}")

print(f"IC Básico:    {ic['basic']}")

print(f"IC Normal:    {ic['normal']}")



boot.plot()

boot.plot(interactive=True)



# Bootstrap de la mediana con IC 99%

boot_med = cs.bootstrapping('petal_length', statistic='median', confidence_level=0.99)



# Bootstrap con función personalizada (coeficiente de variación)

boot_cv = cs.bootstrapping(

    'sepal_width',

    statistic='custom',

    custom_func=lambda x: x.std() / x.mean()

)

Clustering (K-Means)

.k_means(k, max_iters, init_method)

k: int · max_iters: int = 100 · init_method: 'random' | 'kmeans++' = 'kmeans++'

→ dict

K-Means implementado desde cero sobre todas las columnas numéricas. Usa K-Means++ por defecto para mejor inicialización y convergencia. Calcula inercia (WCSS) y silhouette score (requiere scikit-learn).

Parámetro	Tipo	Default	Descripción
k	int	—	Número de clusters (requerido)
max_iters	int	100	Iteraciones máximas hasta convergencia
init_method	str	'kmeans++'	`'kmeans++'` (recomendado) o `'random'`

Retorna dict con:

centroids

np.ndarray

Coordenadas de los k centroides finales

labels

np.ndarray

Cluster asignado a cada observación

inertia

float

Suma de cuadrados dentro del cluster (WCSS)

silhouette_score

float

Puntuación de silueta (-1 a 1)

n_iterations

int

Iteraciones hasta convergencia

Python

resultado = cs.k_means(k=3, init_method='kmeans++')

print(f"Inercia:     {resultado['inertia']:.2f}")

print(f"Silhouette:  {resultado['silhouette_score']:.4f}")

print(f"Iteraciones: {resultado['n_iterations']}")



# Añadir etiquetas al DataFrame

data['cluster'] = resultado['labels']

print(data.groupby('cluster').mean())

.elbow_method(max_k)

max_k: int = 10

→ dict

Evalúa K-Means para k = 2 a max_k. Retorna inercias y silhouette scores para cada k. Útil para determinar visualmente el número óptimo de clusters.

Python

elbow = cs.elbow_method(max_k=8)

# {'k_values': [2,3,...,8], 'inertias': [...], 'silhouettes': [...]}



import matplotlib.pyplot as plt

fig, axes = plt.subplots(1, 2, figsize=(12, 5))



axes[0].plot(elbow['k_values'], elbow['inertias'], 'bo-')

axes[0].set(xlabel='k', ylabel='Inercia', title='Método del Codo')

axes[0].grid(alpha=0.3)



axes[1].plot(elbow['k_values'], elbow['silhouettes'], 'rs-')

axes[1].set(xlabel='k', ylabel='Silhouette Score')

axes[1].grid(alpha=0.3)



plt.tight_layout(); plt.show()

Análisis de Correlación

.correlation_analysis(method)

method: 'pearson' | 'spearman' | 'kendall' = 'pearson'

→ dict

Calcula la matriz de correlación de todas las columnas numéricas. Para Pearson, calcula también la matriz de p-values par a par.

Python

resultado = cs.correlation_analysis(method='pearson')

print(resultado['correlation_matrix'])

print(resultado['p_values'])   # Solo para Pearson



resultado_sp = cs.correlation_analysis(method='spearman')

.plot_correlation_heatmap(method, annot, interactive)

method: str = 'pearson' · annot: bool = True · interactive: bool = False

Heatmap de correlación con escala RdBu centrada en 0. Con interactive=True usa Plotly con hover tooltips; de lo contrario usa seaborn.

Python

cs.plot_correlation_heatmap(method='pearson', annot=True)

cs.plot_correlation_heatmap(method='spearman', interactive=True)

Utilidades

.descriptive_statistics(by)

by: str | None = None

→ pd.DataFrame

Estadísticas descriptivas de columnas numéricas. Con by agrupa por una columna categórica.

Python

print(cs.descriptive_statistics())

print(cs.descriptive_statistics(by='species'))  # Agrupado por categoría

.plot_distribution(column, by, kind, interactive)

column: str · by: str | None · kind: 'hist'|'box'|'violin' = 'hist' · interactive: bool = False

Distribución de una columna con soporte de agrupamiento por variable categórica. Backend estático (matplotlib/seaborn) o interactivo (Plotly).

Python

cs.plot_distribution('sepal_length', kind='hist')

cs.plot_distribution('petal_length', by='species', kind='violin')

cs.plot_distribution('sepal_width', kind='box', interactive=True)

Objetos de Resultado

RegressionResult

Retornado por .regression() · .linear_regression() · .polynomial_regression() · .find_best_degree()

Objeto completo con coeficientes, métricas, expresión simbólica SymPy, código LaTeX y visualizaciones.

Atributos principales:

r2

float

Coeficiente R²

r2_adj

float

R² ajustado

intercept

float

Término independiente β₀

slopes

np.ndarray

Coeficientes β₁, β₂, …

residuals

np.ndarray

y − ŷ para cada observación

mse / rmse / mae / mape

float

Métricas de error

aic / bic

float

Criterios de información de Akaike y Bayesiano

p_values

np.ndarray

P-value de cada coeficiente

t_stats

np.ndarray

Estadístico t por coeficiente

symbolic_expr

sympy.Expr

Expresión simbólica simplificada

latex_expr

str

Fórmula en formato LaTeX

Métodos:

.summary()

→ dict

Tabla de coeficientes + todas las métricas + fórmula

.predict(X_new)

→ np.ndarray

Predicciones sobre nuevos datos

.get_formula(decimals)

→ str

Ecuación legible como string

.plot(plot_type, interactive)

→ None

'scatter', 'residuals', 'qq', 'all'. Plotly con interactive=True

InterpolationResult

Retornado por .interpolation()

Encapsula el interpolador vectorizado y la expresión simbólica (Lagrange/Newton).

.predict(x)

→ float | ndarray

Evalúa el interpolador en uno o varios puntos

.summary()

→ dict

Método, n_points, rangos x/y, expresión

.plot(n_points, interactive)

→ None

Curva de interpolación + puntos originales

.latex_expr

str

Polinomio en LaTeX (Lagrange / Newton)

BootstrappingResult

Retornado por .bootstrapping()

Contiene la distribución bootstrap y tres tipos de intervalos de confianza.

original_stat

float

Estadístico de la muestra original

bootstrap_stats

np.ndarray

Los n_samples estadísticos simulados

bias

float

Media bootstrap − estadístico original

std_error

float

Desviación estándar de las simulaciones

percentile_ci

tuple

IC por percentiles (más común)

basic_ci

tuple

IC básico por reflexión

normal_ci

tuple

IC normal con z-score

.summary()

→ dict

Resumen con los 3 ICs, bias y std_error

.plot(interactive)

→ None

Histograma bootstrap + Q-Q plot

Ejemplo integrador — Pipeline completo

Python — Flujo completo

from statslibx import ComputationalStats

from statslibx.datasets import load_iris



data = load_iris()

cs = ComputationalStats(data, seed=42)



# 1. Mejor grado de regresión por BIC

best = cs.find_best_degree('sepal_length', 'petal_length', max_degree=5, metric='bic')

print(f"Mejor grado: {best['degree']}, R²={best['r2']:.4f}")

best['model'].plot()



# 2. Bootstrap de la media con IC 99%

boot = cs.bootstrapping('sepal_length', n_samples=5000, confidence_level=0.99)

s = boot.summary()

print(f"IC 99% percentil: {s['confidence_interval_99%']['percentile']}")

boot.plot(interactive=True)



# 3. Interpolación de Newton

points = [(4.5, 1.3), (5.0, 1.8), (5.5, 2.5), (6.0, 3.8), (7.0, 5.1)]

interp = cs.interpolation(points, method='newton')

print(f"LaTeX: {interp.latex_expr}")

interp.plot()



# 4. Método del codo + clustering óptimo

elbow = cs.elbow_method(max_k=6)

clusters = cs.k_means(k=3)

data['cluster'] = clusters['labels']

print(f"Silhouette: {clusters['silhouette_score']:.4f}")



# 5. Heatmap de correlación interactivo

cs.plot_correlation_heatmap(method='spearman', interactive=True)

Tip: Los objetos RegressionResult, InterpolationResult y BootstrappingResult son independientes una vez creados. Puedes guardarlos, pasarlos a otras funciones o acceder a sus atributos directamente sin necesidad del objeto ComputationalStats padre.