DashAIDataset

¿Qué Es DashAIDataset?

DashAIDataset es el primitivo central de datos de DashAI. Extiende la clase Dataset de HuggingFace con dos responsabilidades adicionales:

• Metadatos de tipo semántico — un diccionario _types (Dict[str, DashAIDataType]) que mapea cada nombre de columna a su tipo semántico DashAI (ver Tipos Semánticos). Estos metadatos se persisten dentro del esquema Apache Arrow para sobrevivir ciclos de guardado/carga.
• Metadatos de splits — un diccionario splits que registra qué índices de fila pertenecen a qué split (train, test, validation), junto con estadísticas agregadas calculadas durante la carga del dataset.

Cada pieza de datos que fluye por DashAI — carga, transformaciones en el notebook, entrenamiento de modelos, predicciones — se representa como un DashAIDataset.

---

Estructura Interna

Atributos de Instancia

Atributo	Tipo	Descripción
_table	pyarrow.Table	La tabla Arrow subyacente. Todos los datos de columnas residen aquí.
_types	Dict[str, DashAIDataType]	Tipo semántico de cada columna. Sincronizado con los metadatos de Arrow.
splits	dict	Índices de splits y estadísticas calculadas (ver abajo).

El Diccionario splits

splits es un dict Python plano. Sus claves se van poblando de forma progresiva:

Clave	Establecido por	Contenido
split_indices	split_dataset / update_dataset_splits	{"train": [...], "test": [...], "validation": [...]} — listas de índices de fila
column_names	compute_base_metadata / save_dataset	Lista de nombres de columnas
total_rows	compute_base_metadata / save_dataset	Número total de filas
nan	compute_base_metadata	Conteo de NaN por columna
general_info	compute_metadata	Conteo de filas/columnas, memoria, duplicados, mapa de dtypes
numeric_stats	compute_metadata	Estadísticas descriptivas por columna numérica
categorical_stats	compute_metadata	Conteos de valores y top-5 por columna categórica
text_stats	compute_metadata	Estadísticas de longitud y conteo de palabras para columnas de texto
quality_info	compute_metadata	Completitud, columnas constantes, columnas de alta cardinalidad, puntaje de calidad
correlations	compute_metadata	Matriz de correlación de Pearson para columnas numéricas

Metadatos de Arrow

Los tipos semánticos se serializan en los metadatos del esquema de la tabla Arrow bajo la clave dashai_types:

table.schema.metadata[b"dashai_types"]  # mapa de tipos serializado en JSON

Las utilidades save_types_in_arrow_metadata() y get_types_from_arrow_metadata() en DashAI/back/types/utils.py gestionan esta serialización. Cuando DashAIDataset se construye con types=None, lee el mapa de tipos directamente de los metadatos de Arrow.

---

Formato en Disco

save_dataset escribe dos archivos en un directorio:

<dataset_path>/
├── data.arrow    # Archivo IPC de PyArrow — tabla + metadatos de tipos en el esquema
└── splits.json   # JSON — índices de splits, conteos de filas, mapa de NaN, estadísticas calculadas

load_dataset lee ambos archivos y reconstruye el DashAIDataset. Los tipos se recuperan de los metadatos del esquema Arrow, por lo que no se necesita un archivo de tipos separado.

---

Métodos de Instancia Clave

get_split(split_name)

Devuelve un nuevo DashAIDataset que contiene solo las filas del split solicitado.

train_ds = dataset.get_split("train")  # usa split_indices["train"]

split_name debe existir en splits["split_indices"]. Los metadatos splits del dataset devuelto contienen únicamente la lista de índices de ese split.

select_columns(column_names)

Devuelve un nuevo DashAIDataset con solo las columnas especificadas, copiando los tipos correspondientes.

features_ds = dataset.select_columns(["age", "income", "city"])

sample(n, method, seed)

Devuelve n filas como un dict Python plano. method controla la selección:

Método	Comportamiento
"head"	Primeras n filas
"tail"	Últimas n filas
"random"	n filas aleatorias (reproducible con seed)

compute_metadata()

Ejecuta todos los cálculos de EDA y almacena los resultados en self.splits. Se llama una vez tras la carga. Requiere que _types esté definido. Devuelve self.

compute_base_metadata()

Subconjunto ligero de compute_metadata() — solo establece column_names, total_rows y nan. Se usa cuando no se necesitan estadísticas completas.

keys()

Devuelve la lista de nombres de splits disponibles en splits["split_indices"]. Refleja la interfaz DatasetDict.keys() para que DashAIDataset pueda usarse de forma intercambiable en algunos contextos.

---

Funciones del Ciclo de Vida del Dato

Estas funciones a nivel de módulo cubren el recorrido completo desde la entrada en bruto hasta los splits listos para entrenamiento.

Carga y Conversión

to_dashai_dataset(dataset, types=None)

Conversor universal. Acepta DashAIDataset (pass-through), Dataset de HuggingFace, DatasetDict de HuggingFace, o pandas.DataFrame. Los DatasetDict con múltiples splits se fusionan mediante merge_splits_with_metadata.

from DashAI.back.dataloaders.classes.dashai_dataset import to_dashai_dataset

ds = to_dashai_dataset(my_hf_dataset, types=my_type_map)

merge_splits_with_metadata(dataset_dict)

Concatena todos los splits de un DatasetDict en un único DashAIDataset y registra los rangos de índices de fila en splits["split_indices"]. Los splits se fusionan en orden de clave alfabético.

Persistencia

save_dataset(dataset, path, schema=None)

Escribe data.arrow y splits.json en path. Si se proporciona schema, se aplica transform_dataset_with_schema primero.

load_dataset(dataset_path)

Lee data.arrow y splits.json desde dataset_path y devuelve un DashAIDataset. Los tipos se recuperan de los metadatos de Arrow.

get_columns_spec(dataset_path)

Lee solo el esquema Arrow (sin datos de filas) y devuelve un Dict[str, Dict] que describe el tipo, dtype y — para columnas Categorical — la lista de categorías de cada columna. Es usado por la API para retornar metadatos de columnas sin cargar el dataset completo.

Transformación de Tipos

transform_dataset_with_schema(dataset, schema)

Aplica un esquema de tipos al dataset, convirtiendo las columnas a sus tipos Arrow destino y actualizando _types. El formato del schema es:

schema = {
    "age":    {"type": "Integer", "dtype": "int64"},
    "income": {"type": "Float",   "dtype": "float64"},
    "city":   {"type": "Categorical", "dtype": "string", "converted": False},
}

Las columnas Categorical tienen su lista de categorías inferida a partir de los datos reales en este punto, garantizando que ningún valor sea excluido silenciosamente.

Splitting

split_indexes(total_rows, train_size, test_size, val_size, seed, shuffle, stratify, labels)

Devuelve (train_indexes, test_indexes, val_indexes) como listas de índices de fila enteros. Usa una estrategia en dos fases:

1. Divide todas las filas en train vs test+validation.
2. Divide test+validation en test y validation proporcionalmente.

Soporta splitting estratificado: pasar el array de etiquetas en labels.

split_dataset(dataset, train_indexes, test_indexes, val_indexes)

Particiona dataset en un DatasetDict con claves "train", "test" y "validation", siendo cada uno un DashAIDataset. Los tipos de columnas del dataset original se preservan.

Si los tres argumentos de índice son None, la función lee los split_indices existentes en dataset.splits.

update_dataset_splits(dataset, new_splits, is_random)

Actualiza dataset.splits["split_indices"] en lugar.

• is_random=True — los valores de new_splits son proporciones flotantes; se llama a split_indexes para generar las listas de filas.
• is_random=False — los valores de new_splits ya son listas de índices de fila; se usan directamente.

Preparación para Entrenamiento

prepare_for_model_session(dataset, splits, output_columns)

Punto de entrada de alto nivel usado por el sistema de jobs antes del entrenamiento. Gestiona el pipeline completo de splits:

1. Determina el tipo de split desde splits["splitType"] ("manual", "predefined" o "random").
2. Llama a split_dataset con las listas de índices apropiadas.
3. Devuelve (prepared_dataset, index_map) donde index_map tiene las claves train_indexes, test_indexes, val_indexes.

Para splits aleatorios con stratify=True, lee los valores de la columna de salida y los pasa como etiquetas a split_indexes.

---

Modificar Datos — modify_table

modify_table(dataset, columns, types=None)

Usado dentro de converters y modelos para reemplazar o agregar columnas preservando todas las demás columnas y metadatos.

import pyarrow as pa
from DashAI.back.dataloaders.classes.dashai_dataset import modify_table

new_col = pa.array([1.0, 2.0, 3.0], type=pa.float64())
result = modify_table(dataset, {"scaled_age": new_col}, types={"scaled_age": Float("float64")})

• Las columnas en columns que ya existen en el dataset son reemplazadas.
• Las columnas nuevas requieren una entrada correspondiente en types.
• Los metadatos Arrow originales (incluyendo dashai_types) se preservan y extienden.

---

Relación con Otros Subsistemas

DataLoader
  └─ carga archivo en bruto → DashAIDataset (tipos inferidos por DashAIPtype)
        │
        ├─ Espacio de trabajo Notebook
        │     └─ Converter.fit_transform(DashAIDataset) → DashAIDataset
        │          (modify_table usado internamente)
        │
        └─ Entrenamiento de modelos
              └─ prepare_for_model_session → DatasetDict de DashAIDatasets
                    └─ select_columns → par (X_train, y_train)

• DataLoaders producen DashAIDataset mediante to_dashai_dataset.
• Converters consumen y devuelven DashAIDataset, usando modify_table para actualizar columnas.
• Modelos reciben un DatasetDict de prepare_for_model_session y llaman a get_split / select_columns para extraer sus entradas.
• Explorers reciben un DashAIDataset y leen _types para despachar visualizaciones apropiadas por tipo de columna.

---

Archivos Fuente

Archivo	Rol
DashAI/back/dataloaders/classes/dashai_dataset.py	Clase DashAIDataset y todas las funciones a nivel de módulo
DashAI/back/types/utils.py	Serialización de tipos Arrow ↔ DashAI (save_types_in_arrow_metadata, get_types_from_arrow_metadata)
DashAI/back/types/value_types.py	Clases de tipos de valor concretos usados en _types
DashAI/back/types/categorical.py	Tipo Categorical con codificación str2int / int2str