swaggylei/dataset-difficulty-skill

Compétence de Difficulté du Jeu de Données

Produire un prior de difficulté reproductible et indépendant du modèle pour un jeu de données de classification d'images. Utiliser les embeddings CLIP lorsqu'ils sont disponibles, mais garder chaque métrique brute et chaque composant visible. Ne jamais présenter le score final comme une précision prédite ou comme un substitut à la validation aval.

Quand l'utiliser

Utilisez cette compétence lorsque l'utilisateur souhaite :

• auditer un jeu de données de classification d'images avant l'entraînement ;
• trouver des valeurs aberrantes corrompues, dupliquées, non étiquetées, à étiquettes conflictuelles ou statistiques ;
• comparer la difficulté relative Facile/Moyen/Difficile ;
• créer des manifestes Train/Val/Test stratifiés par classe et par difficulté ;
• obtenir des rapports exploitables par machine et révisables par un humain.

Ne pas l'utiliser pour la détection d'objets, la segmentation, l'analyse vidéo ou le réglage fin d'un classifieur.

Vérifier d'abord les entrées

1. Confirmer que le répertoire du jeu de données existe.
2. Déterminer le format : dossier-par-classe, CSV ou JSON.
3. Pour CSV/JSON, confirmer le fichier d'étiquettes et les colonnes chemin/étiquette pertinentes.
4. Si un regroupement anti-fuite est nécessaire, confirmer le nom de colonne group_id optionnel.
5. Sélectionner un répertoire de sortie en dehors de l'arborescence du jeu de données.
6. Ne jamais modifier ou supprimer les images ou les étiquettes originales.
7. Ne pas télécharger les poids CLIP sauf si l'utilisateur l'autorise explicitement.

Disposition de dossiers prise en charge :

dataset/
  cat/
    image-1.jpg
  dog/
    image-2.png

Les exemples CSV et JSON ainsi que les surcharges de colonnes se trouvent dans references/configuration.md.

Lancer l'analyse

L'arborescence source est directement exécutable :

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

Avec un fichier d'étiquettes :

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

Avec regroupement anti-fuite :

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

Analyse hors ligne sans CLIP :

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

CLIP est local par défaut. Si l'utilisateur autorise explicitement un téléchargement de modèle et une utilisation réseau :

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

Exécutez python scripts/analyze_dataset.py --help pour toutes les surcharges.

Interpréter dans cet ordre

1. Lire summary.json en premier.
2. Traiter corrupt_image, empty_label et conflicting_label comme des constats d'intégrité des données.
3. Examiner les groupes de doublons et quasi-doublons.
4. Examiner les valeurs aberrantes de qualité séparément de la difficulté.
5. Comparer l'accessibilité visuelle, la complexité visuelle descriptive, les composants sémantiques bruts, les poids et les valeurs de contribution.
6. Interpréter Facile/Moyen/Difficile uniquement parmi les échantillons notés non anormaux.
7. Vérifier les diagnostics et avertissements de partition avant d'utiliser le manifeste.

Signaler les composants qui conduisent à un résultat. Par exemple : « Difficile car l'échantillon est loin de son centroïde de classe et instable sous augmentation ; sa qualité d'image elle-même est normale. » Ne pas dire « le modèle échouera » ou « cet échantillon a une faible précision. »

Si les champs sémantiques sont nuls, indiquer que CLIP était indisponible ou désactivé. Ne pas inférer ou inventer des embeddings. Ne pas traiter une mauvaise qualité comme une difficulté sémantique. Ne pas fusionner les étiquettes d'anomalie dans Facile/Moyen/Difficile.

Les anomalies purement statistiques et les images de faible qualité mais lisibles sont par défaut souples : conserver leur indicateur d'anomalie mais les conserver dans le score et la partition en tant que Statistically_Unusual ou Quality_Flagged. Seules les anomalies d'intégrité dures telles que les données corrompues, à étiquettes conflictuelles, dupliquées ou de taille insuffisante restent exclues par défaut. Ne pas décrire chaque valeur aberrante statistique ou de qualité comme une donnée invalide.

Pour les réclamations de validation réelles, inspecter summary.json["provenance"], summary.json["dataset"] et summary.json["semantic_runtime"]. Vérifier le commit Git enregistré, l'état sale, la commande, le chemin de configuration, la source du modèle, le lot, les comptes de cache, les échecs et le périphérique avant de revendiquer la reproductibilité.

La rareté des étiquettes est une statistique de jeu de données indépendante avec un poids nul et une contribution nulle. L'entropie de l'image et la complexité fréquentielle sont une complexité visuelle descriptive, pas une preuve qu'un échantillon est plus difficile. Lorsque difficulty_scope=visual_only, avertir explicitement que le prior manque de preuves sémantiques CLIP.

Lire summary.json["semantic_runtime"] et summary.json["performance"] pour le périphérique réel, la taille du lot, les hits/misses de cache, les échecs, les temps d'étape et la mémoire pic CUDA. Ne pas rapporter ces champs sauf s'ils proviennent d'une exécution réelle.

Lire :

• references/metrics.md pour les formules et les limites ;
• references/configuration.md pour chaque section de configuration, schéma d'entrée et surcharge CLI ;
• references/outputs.md pour les contrats d'artefact et de colonne.

Vérifier

Utiliser l'environnement du projet qui a les dépendances requises :

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

Pour une exécution réelle, confirmer que samples.csv, summary.json, report.html, hard_samples.png, anomaly_samples.png, split_manifest.csv et split_summary.json existent. Vérifier que summary.json ne contient pas de jetons NaN ou Infinity.

Sécurité et Portée

• Toute écriture d'analyse va dans les répertoires de sortie et de cache explicites.
• Les chemins de sortie et de cache doivent être en dehors de l'arborescence du jeu de données d'entrée.
• Les entrées du cache de caractéristiques sont indexées par le hash du contenu de l'image et la signature du modèle.
• Les métriques manquantes restent nulles ; les composants disponibles sont repondérés et la couverture est rapportée.
• Le score final est un prior relatif, pas une probabilité calibrée.
• La balance des classes et la stratification par difficulté sont approximatives pour de petites strates ; signaler les avertissements de partition.