بيانات الأداة إلى Allotrope

# محول بيانات الأجهزة إلى صيغة Allotrope

تحويل ملفات الأجهزة إلى صيغة النموذج البسيط من Allotrope (ASM) الموحدة لتحميل نظام LIMS أو بحيرات البيانات أو التسليم إلى فرق هندسة البيانات.

> **ملاحظة: هذه مهارة مثالية** > > توضح هذه المهارة كيف يمكن للمهارات أن تدعم مهام هندسة البيانات لديك — أتمتة تحويلات المخطط الانسيابي وتحليل مخرجات الأجهزة وإنشاء أكواد جاهزة للإنتاج. > > **لتخصيصها لمؤسستك:** > - عدّل ملفات `references/` لتضمين المخططات الانسيابية أو تعيينات الأنطولوجيا الخاصة بشركتك > - استخدم خادم MCP للاتصال بالأنظمة التي تحدد مخططاتك (مثل نظام LIMS أو كتالوج البيانات أو سجل المخطط الانسيابي) > - وسّع `scripts/` للتعامل مع تنسيقات الأجهزة الملكية أو معايير البيانات الداخلية > > يمكن تكييف هذا النمط لأي سير عمل تحويل بيانات حيث تحتاج إلى التحويل بين الصيغ أو التحقق من معايير المؤسسة.

## نظرة عامة على سير العمل

1. **كشف نوع الجهاز** من محتويات الملف (كشف تلقائي أو محدد من قبل المستخدم) 2. **تحليل الملف** باستخدام مكتبة allotropy (أصلية) أو محلل احتياطي مرن 3. **إنشاء المخرجات**: - ASM JSON (الهيكل الدلالي الكامل) - CSV مسطح (صيغة جدولية ثنائية الأبعاد) - كود محلل Python (لتسليم مهندس البيانات) 4. **تسليم** الملفات مع ملخص وتعليمات الاستخدام

> **عند عدم التأكد:** إذا كنت غير متأكد من كيفية تعيين حقل إلى ASM (مثلاً، هل هذه بيانات خام أم محسوبة؟ إعداد جهاز أم شرط بيئي؟)، اطلب توضيحاً من المستخدم. راجع `references/field_classification_guide.md` للحصول على إرشادات، لكن عندما تبقى غموض، أكّد مع المستخدم بدلاً من التخمين.

## البدء السريع

```python # قم بتثبيت المتطلبات أولاً pip install allotropy pandas openpyxl pdfplumber --break-system-packages

# التحويل الأساسي from allotropy.parser_factory import Vendor from allotropy.to_allotrope import allotrope_from_file

# التحويل باستخدام allotropy asm = allotrope_from_file("instrument_data.csv", Vendor.BECKMAN_VI_CELL_BLU) ```

## اختيار صيغة المخرجات

**ASM JSON (الافتراضي)** - هيكل دلالي كامل مع URIs الأنطولوجيا - الأفضل لـ: أنظمة LIMS التي تتوقع ASM وبحيرات البيانات والأرشفة طويلة الأجل - يتحقق من مخططات Allotrope

**CSV مسطح** - تمثيل جدولي ثنائي الأبعاد - الأفضل لـ: التحليل السريع وجداول Excel والأنظمة التي لا تدعم JSON - يصبح كل قياس صفاً واحداً مع تكرار البيانات الوصفية

**كلاهما** - إنشاء كلا الصيغتين للحصول على أقصى مرونة

## معالجة البيانات المحسوبة

**مهم:** فصل القياسات الخام عن القيم المحسوبة/المشتقة.

- **البيانات الخام** → `measurement-document` (قراءات الجهاز المباشرة) - **البيانات المحسوبة** → `calculated-data-aggregate-document` (القيم المشتقة)

يجب أن تتضمن القيم المحسوبة إمكانية التتبع عبر `data-source-aggregate-document`:

```json "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" }] } }] } ```

**حقول محسوبة شائعة حسب نوع الجهاز:** | الجهاز | الحقول المحسوبة | |--------|-------------------| | عداد الخلايا | نسبة الحيوية %، كثافة الخلايا القيم المعدلة حسب التخفيف | | مطياف التحديد الضوئي | التركيز (من الامتصاصية)، نسبة 260/280 | | قارئ اللوحة | التركيزات من منحنى المعايرة، CV% | | الرحلان الكهربائي | DIN/RIN، تركيزات المنطقة، متوسط الأحجام | | qPCR | الكميات النسبية، ثني التغيير |

راجع `references/field_classification_guide.md` للحصول على إرشادات مفصلة حول تصنيف الخام مقابل المحسوب.

## التحقق

تحقق دائماً من مخرجات ASM قبل تسليمها للمستخدم:

```bash python scripts/validate_asm.py output.json python scripts/validate_asm.py output.json --reference known_good.json # المقارنة بمرجع python scripts/validate_asm.py output.json --strict # معاملة التحذيرات كأخطاء ```

**قواعد التحقق:** - بناءً على مواصفات Allotrope ASM (ديسمبر 2024) - آخر تحديث: 7 يناير 2026 - المصدر: https://gitlab.com/allotrope-public/asm

**نهج التحقق الناعم:** التقنيات غير المعروفة أو الوحدات أو أدوار العينات تولد **تحذيرات** (وليس أخطاء) للسماح بالتوافق العكسي. إذا أضافت Allotrope قيماً جديدة بعد ديسمبر 2024، فلن يمنع المدقق — سيعلمك عنها للتحقق اليدوي. استخدم وضع `--strict` لمعاملة التحذيرات كأخطاء إذا كنت تحتاج إلى تحقق أصارم.

**ما الذي يتحقق منه:** - اختيار التقنية الصحيح (مثل التنميط متعدد المحللات مقابل قارئ اللوحة) - اتفاقيات تسمية الحقول (مفصولة بمسافات، وليس بواصلة) - البيانات المحسوبة لها إمكانية التتبع (`data-source-aggregate-document`) - وجود معرفات فريدة للقياسات والقيم المحسوبة - البيانات الوصفية المطلوبة موجودة - الوحدات وأدوار العينات صحيحة (مع التحقق الناعم للقيم غير المعروفة)

## الأجهزة المدعومة