Convertisseur de données d'instrument au format Allotrope

Convertissez les fichiers d'instrument en format Allotrope Simple Model (ASM) standardisé pour le chargement LIMS, les data lakes, ou la transmission aux équipes d'ingénierie des données.

Note : Ceci est un exemple de skill

Ce skill démontre comment les skills peuvent soutenir vos tâches d'ingénierie des données – en automatisant les transformations de schéma, l'analyse des sorties d'instrument et la génération de code prêt pour la production.

Pour personnaliser pour votre organisation :

• Modifiez les fichiers references/ pour inclure les schémas ou mappages d'ontologie spécifiques à votre entreprise
• Utilisez un serveur MCP pour vous connecter à des systèmes qui définissent vos schémas (ex. : votre LIMS, catalogue de données ou registre de schémas)
• Étendez les scripts/ pour traiter les formats d'instrument propriétaires ou les normes de données internes

Ce modèle peut être adapté à n'importe quel flux de transformation de données où vous devez convertir entre formats ou valider par rapport aux normes de votre organisation.

Aperçu du flux de travail

1. Détecter le type d'instrument à partir du contenu du fichier (détection automatique ou spécifiée par l'utilisateur)
2. Analyser le fichier avec la bibliothèque allotropy (native) ou un analyseur de secours flexible
3. Générer les résultats :
   • ASM JSON (structure sémantique complète)
   • CSV aplati (format tabulaire 2D)
   • Code d'analyseur Python (pour transmission à l'ingénierie des données)
4. Livrer les fichiers avec un résumé et des instructions d'utilisation

En cas d'incertitude : Si vous ne savez pas comment mapper un champ à ASM (par ex., s'agit-il de données brutes ou calculées ? paramètre du dispositif ou condition environnementale ?), demandez une clarification à l'utilisateur. Consultez references/field_classification_guide.md pour obtenir des conseils, mais quand l'ambiguïté persiste, confirmez auprès de l'utilisateur plutôt que de deviner.

Démarrage rapide

# Installez d'abord les exigences
pip install allotropy pandas openpyxl pdfplumber --break-system-packages

# Conversion principale
from allotropy.parser_factory import Vendor
from allotropy.to_allotrope import allotrope_from_file

# Convertir avec allotropy
asm = allotrope_from_file("instrument_data.csv", Vendor.BECKMAN_VI_CELL_BLU)

Sélection du format de sortie

ASM JSON (par défaut) - Structure sémantique complète avec URIs d'ontologie

• Meilleur pour : les systèmes LIMS attendant ASM, les data lakes, l'archivage à long terme
• Valide par rapport aux schémas Allotrope

CSV aplati - Représentation tabulaire 2D

• Meilleur pour : l'analyse rapide, les utilisateurs Excel, les systèmes sans support JSON
• Chaque mesure devient une ligne avec les métadonnées répétées

Les deux - Générez les deux formats pour une flexibilité maximale

Traitement des données calculées

IMPORTANT : Séparez les mesures brutes des valeurs calculées/dérivées.

• Données brutes → measurement-document (lectures directes de l'instrument)
• Données calculées → calculated-data-aggregate-document (valeurs dérivées)

Les valeurs calculées DOIVENT inclure la traçabilité via data-source-aggregate-document :

"calculated-data-aggregate-document": {
  "calculated-data-document": [{
    "calculated-data-identifier": "SAMPLE_B1_DIN_001",
    "calculated-data-name": "DNA integrity number",
    "calculated-result": {"value": 9.5, "unit": "(unitless)"},
    "data-source-aggregate-document": {
      "data-source-document": [{
        "data-source-identifier": "SAMPLE_B1_MEASUREMENT",
        "data-source-feature": "electrophoresis trace"
      }]
    }
  }]
}

Champs calculés courants par type d'instrument : | Instrument | Champs calculés | |------------|-----------------| | Compteur de cellules | % viabilité, densité cellulaire, valeurs ajustées selon la dilution | | Spectrophotomètre | Concentration (à partir de l'absorbance), rapport 260/280 | | Lecteur de plaque | Concentrations à partir de la courbe d'étalonnage, %CV | | Électrophorèse | DIN/RIN, concentrations des régions, tailles moyennes | | qPCR | Quantités relatives, variation en fold |

Consultez references/field_classification_guide.md pour obtenir des conseils détaillés sur la classification brute vs calculée.

Validation

Validez toujours la sortie ASM avant de la livrer à l'utilisateur :

python scripts/validate_asm.py output.json
python scripts/validate_asm.py output.json --reference known_good.json  # Comparer avec une référence
python scripts/validate_asm.py output.json --strict  # Traiter les avertissements comme des erreurs

Règles de validation :

• Basé sur la spécification Allotrope ASM (décembre 2024)
• Dernière mise à jour : 2026-01-07
• Source : https://gitlab.com/allotrope-public/asm

Approche de validation souple : Les techniques inconnues, les unités ou les rôles d'échantillon génèrent des avertissements (pas des erreurs) pour permettre la compatibilité future. Si Allotrope ajoute de nouvelles valeurs après décembre 2024, le validateur ne les bloquera pas – il les signalera pour vérification manuelle. Utilisez le mode --strict pour traiter les avertissements comme des erreurs si vous avez besoin d'une validation plus stricte.

Ce qu'il vérifie :

• Sélection correcte de la technique (par ex., profilage multi-analyte vs lecteur de plaque)
• Conventions de nommage des champs (séparés par des espaces, pas des tirets)
• Les données calculées ont une traçabilité (data-source-aggregate-document)
• Les identifiants uniques existent pour les mesures et les valeurs calculées
• Les métadonnées requises sont présentes
• Unités et rôles d'échantillon valides (avec validation souple pour les valeurs inconnues)

Instruments supportés

Consultez references/supported_instruments.md pour la liste complète. Instruments clés :

Stratégie de détection et d'analyse

Niveau 1 : Analyse native allotropy (PRÉFÉRÉ)

Essayez d'abord allotropy. Vérifiez directement les vendeurs disponibles :

from allotropy.parser_factory import Vendor

# Lister tous les vendeurs supportés
for v in Vendor:
    print(f"{v.name}")

# Vendeurs courants :
# AGILENT_TAPESTATION_ANALYSIS  (pour TapeStation XML)
# BECKMAN_VI_CELL_BLU
# THERMO_FISHER_NANODROP_EIGHT
# MOLDEV_SOFTMAX_PRO
# APPBIO_QUANTSTUDIO
# ... beaucoup d'autres

Quand l'utilisateur fournit un fichier, vérifiez si allotropy le supporte avant de recourir à l'analyse manuelle. La détection automatique dans scripts/convert_to_asm.py ne couvre qu'un sous-ensemble de vendeurs allotropy.

Niveau 2 : Analyse de secours flexible

Utilisez uniquement si allotropy ne supporte pas l'instrument. Ce secours :

• Ne génère PAS calculated-data-aggregate-document
• N'inclut PAS la traçabilité complète
• Produit une structure ASM simplifiée

Utilisez l'analyseur flexible avec :

• Correspondance floue des noms de colonnes
• Extraction d'unités à partir des en-têtes
• Extraction de métadonnées à partir de la structure de fichier

Niveau 3 : Extraction PDF

Pour les fichiers PDF uniquement, extrayez les tableaux avec pdfplumber, puis appliquez l'analyse du niveau 2.

Liste de vérification pré-analyse

Avant d'écrire un analyseur personnalisé, TOUJOURS :

1. Vérifiez si allotropy le supporte - Utilisez l'analyseur natif si disponible
2. Trouvez un fichier ASM de référence - Consultez references/examples/ ou demandez à l'utilisateur
3. Consultez le guide spécifique à l'instrument - Consultez references/instrument_guides/
4. Validez par rapport à la référence - Exécutez validate_asm.py --reference <file>

Erreurs courantes à éviter

Export de code pour les ingénieurs des données

Générez des scripts Python autonomes que les scientifiques peuvent transmettre :

# Code d'analyseur d'export
python scripts/export_parser.py --input "data.csv" --vendor "VI_CELL_BLU" --output "parser_script.py"

Le script exporté :

• N'a pas de dépendances externes au-delà de pandas/allotropy
• Inclut la documentation inline
• Peut s'exécuter dans les notebooks Jupyter
• Est prêt pour la production dans les pipelines de données

Structure des fichiers

instrument-data-to-allotrope/
├── SKILL.md                          # Ce fichier
├── scripts/
│   ├── convert_to_asm.py            # Script de conversion principal
│   ├── flatten_asm.py               # Conversion ASM → CSV 2D
│   ├── export_parser.py             # Générer un code d'analyseur autonome
│   └── validate_asm.py              # Valider la qualité de sortie ASM
└── references/
    ├── supported_instruments.md     # Liste d'instruments complète avec énums Vendor
    ├── asm_schema_overview.md       # Référence de structure ASM
    ├── field_classification_guide.md # Où placer les différents types de champs
    └── flattening_guide.md          # Fonctionnement de l'aplatissement

Exemples d'utilisation

Exemple 1 : Fichier Vi-CELL BLU

Utilisateur : « Convertissez ces données de comptage de cellules au format Allotrope »
[uploads viCell_Results.xlsx]

Claude :
1. Détecte Vi-CELL BLU (95 % de confiance)
2. Convertit avec l'analyseur natif allotropy
3. Résultats :
   - viCell_Results_asm.json (ASM complet)
   - viCell_Results_flat.csv (format 2D)
   - viCell_parser.py (code exportable)

Exemple 2 : Demande de transmission de code

Utilisateur : « Je dois donner à notre ingénieur des données le code pour analyser les fichiers NanoDrop »

Claude :
1. Génère un script Python autonome
2. Inclut un exemple d'entrée/sortie
3. Documente toutes les hypothèses
4. Fournit une version notebook Jupyter

Exemple 3 : Sortie aplatie prête pour LIMS

Utilisateur : « Convertissez ces données ELISA en CSV que je peux charger dans notre LIMS »

Claude :
1. Analyse les données du lecteur de plaque
2. Génère un CSV aplati avec des colonnes :
   - sample_identifier, well_position, measurement_value, measurement_unit
   - instrument_serial_number, analysis_datetime, assay_type
3. Valide par rapport aux exigences d'importation LIMS courantes

Notes d'implémentation

Installation d'allotropy

pip install allotropy --break-system-packages

Gestion des échecs d'analyse

Si l'analyse native allotropy échoue :

1. Consignez l'erreur pour le débogage
2. Revenez à l'analyseur flexible
3. Signaler une intégrité de métadonnées réduite à l'utilisateur
4. Suggérer d'exporter un format différent à partir de l'instrument

Validation du schéma ASM

Validez la sortie par rapport aux schémas Allotrope si disponible :

import jsonschema
# URLs de schéma dans references/asm_schema_overview.md