swaggylei/dataset-difficulty-skill

Skill de Dificultad de Conjunto de Datos

Produce una prioridad de dificultad reproducible e independiente del modelo para un conjunto de datos de clasificación de imágenes. Utiliza embeddings de CLIP cuando estén disponibles, pero mantén cada métrica y componente en bruto visible. Nunca presentes la puntuación final como una precisión predicha o como un sustituto de la validación posterior.

Cuándo Usarlo

Usa este Skill cuando el usuario quiera:

• auditar un conjunto de datos de clasificación de imágenes antes del entrenamiento;
• encontrar valores atípicos corruptos, duplicados, sin etiquetar, con etiquetas conflictivas o estadísticos;
• comparar la dificultad relativa Fácil/Media/Difícil;
• crear manifiestos de Entrenamiento/Validación/Prueba estratificados por clase y dificultad;
• obtener informes legibles por máquina y revisables por humanos.

No lo uses para detección de objetos, segmentación, análisis de video o ajuste fino de un clasificador.

Primero, Verifica las Entradas

1. Confirma que el directorio del conjunto de datos existe.
2. Determina el formato: carpeta-por-clase, CSV o JSON.
3. Para CSV/JSON, confirma el archivo de etiquetas y las columnas de ruta/etiqueta relevantes.
4. Si se requiere agrupación segura contra fugas, confirma el nombre opcional de la columna group_id.
5. Selecciona un directorio de salida fuera del árbol del conjunto de datos.
6. Nunca modifiques ni elimines imágenes o etiquetas originales.
7. No descargues pesos de CLIP a menos que el usuario lo autorice explícitamente.

Estructura de carpeta admitida:

dataset/
  gato/
    imagen-1.jpg
  perro/
    imagen-2.png

Los ejemplos de CSV y JSON y las anulaciones de columnas están en references/configuration.md.

Ejecuta el Análisis

El árbol fuente es directamente ejecutable:

python scripts/analyze_dataset.py DATA_ROOT \
  --output DIRECTORIO_SALIDA \
  --config configs/default.yaml

Con un archivo de etiquetas:

python scripts/analyze_dataset.py DATA_ROOT \
  --labels etiquetas.csv \
  --format csv \
  --output DIRECTORIO_SALIDA

Con grupos seguros contra fugas:

python scripts/analyze_dataset.py DATA_ROOT \
  --labels etiquetas.csv \
  --format csv \
  --group-column group_id \
  --output DIRECTORIO_SALIDA

Análisis sin conexión sin CLIP:

python scripts/analyze_dataset.py DATA_ROOT \
  --output DIRECTORIO_SALIDA \
  --no-semantic

CLIP es solo local por defecto. Si el usuario autoriza explícitamente la descarga del modelo y el uso de red:

python scripts/analyze_dataset.py DATA_ROOT \
  --output DIRECTORIO_SALIDA \
  --semantic-backend clip \
  --allow-model-download

Ejecuta python scripts/analyze_dataset.py --help para todas las anulaciones.

Interpreta en Este Orden

1. Lee summary.json primero.
2. Maneja corrupt_image, empty_label y conflicting_label como hallazgos de integridad de datos.
3. Revisa grupos duplicados y casi duplicados.
4. Revisa los valores atípicos de calidad por separado de la dificultad.
5. Compara accesibilidad visual, complejidad visual descriptiva, componentes semánticos en bruto, pesos y valores de contribución.
6. Interpreta Fácil/Media/Difícil solo entre muestras puntuadas no anómalas.
7. Verifica los diagnósticos y advertencias de la división antes de usar el manifiesto.

Informa los componentes que impulsan un resultado. Por ejemplo: "Difícil porque la muestra está lejos de su centroide de clase y es inestable bajo aumento; su calidad de imagen en sí es normal." No digas "el modelo fallará" o "esta muestra tiene baja precisión".

Si los campos semánticos son nulos, indica que CLIP no estaba disponible o estaba deshabilitado. No infieras ni inventes embeddings. No trates la mala calidad como dificultad semántica. No combines etiquetas de anomalía en Fácil/Media/Difícil.

Las anomalías solo estadísticas y las imágenes de baja calidad pero legibles son suaves por defecto: conserva su bandera de anomalía pero mantenlas en la puntuación y división como Estadísticamente_Inusual o Calidad_Marcada. Solo las anomalías graves de integridad, como datos corruptos, con etiquetas conflictivas, duplicados o de tamaño insuficiente, permanecen excluidas por defecto. No describas cada valor atípico estadístico o de calidad como datos inválidos.

Para afirmaciones de validación reales, inspecciona summary.json["provenance"], summary.json["dataset"] y summary.json["semantic_runtime"]. Verifica el commit de Git registrado, el estado sucio, el comando, la ruta de configuración, la fuente del modelo, el lote, los recuentos de caché, fallos y el dispositivo antes de afirmar reproducibilidad.

La rareza de la etiqueta es una estadística independiente del conjunto de datos con peso cero y contribución cero. La entropía de la imagen y la complejidad de frecuencia son complejidad visual descriptiva, no evidencia de que una muestra sea más difícil. Cuando difficulty_scope=visual_only, advierte explícitamente que la prioridad carece de evidencia semántica de CLIP.

Lee summary.json["semantic_runtime"] y summary.json["performance"] para el dispositivo real, tamaño de lote, aciertos/fallos de caché, fallos, tiempos de etapa y memoria máxima de CUDA. No informes esos campos a menos que provengan de una ejecución real.

Lee:

• references/metrics.md para fórmulas y límites;
• references/configuration.md para cada sección de configuración, esquema de entrada y anulación CLI;
• references/outputs.md para contratos de artefactos y columnas.

Verifica

Usa el entorno del proyecto que tiene las dependencias requeridas:

python -c "import cv2, numpy, pandas, sklearn, matplotlib, yaml, torch, transformers"
python -m pytest -v

Para una ejecución real, confirma que samples.csv, summary.json, report.html, hard_samples.png, anomaly_samples.png, split_manifest.csv y split_summary.json existan. Verifica que summary.json no contenga tokens NaN o Infinity.

Seguridad y Alcance

• Toda la escritura del análisis se dirige a los directorios de salida y caché explícitos.
• Las rutas de salida y caché deben estar fuera del árbol de entrada del conjunto de datos.
• Las entradas de la caché de características se clavean por el hash del contenido de la imagen y la firma del modelo.
• Las métricas faltantes permanecen nulas; los componentes disponibles se reponderan y se informa la cobertura.
• La puntuación final es una prioridad relativa, no una probabilidad calibrada.
• El equilibrio de clases y la estratificación por dificultad son aproximados para estratos pequeños; informa advertencias de división.