opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/bio-research/skills/bio-research-instrument-data-to-allotrope/references/asm_schema_overview.md

@@ -0,0 +1,226 @@
+# ASM Schema Overview
+
+The Allotrope Simple Model (ASM) is a JSON-based standard for representing laboratory instrument data with semantic consistency.
+
+## Core Concepts
+
+### Structure
+ASM uses a hierarchical document structure:
+- **Manifest** - Links to ontologies and schemas
+- **Data** - The actual measurement data organized by technique
+
+### Key Components
+
+```json
+{
+  "$asm.manifest": {
+    "vocabulary": ["http://purl.allotrope.org/voc/afo/REC/2023/09/"],
+    "contexts": ["http://purl.allotrope.org/json-ld/afo-context-REC-2023-09.jsonld"]
+  },
+  "<technique>-aggregate-document": {
+    "device-system-document": { ... },
+    "<technique>-document": [
+      {
+        "measurement-aggregate-document": {
+          "measurement-document": [ ... ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Required Metadata Documents
+
+### data system document
+Every ASM output MUST include this document with:
+- `ASM file identifier`: Output filename
+- `data system instance identifier`: System ID or "N/A"
+- `file name`: Source input filename
+- `UNC path`: Path to source file
+- `ASM converter name`: Parser identifier (e.g., "allotropy_beckman_coulter_biomek")
+- `ASM converter version`: Version string
+- `software name`: Instrument software that generated the source file
+
+### device system document
+Every ASM output MUST include this document with:
+- `equipment serial number`: Main instrument serial
+- `product manufacturer`: Vendor name
+- `device document`: Array of sub-components (probes, pods, etc.)
+  - `device type`: Standardized type (e.g., "liquid handler probe head")
+  - `device identifier`: Logical name (e.g., "Pod1", not serial number)
+  - `equipment serial number`: Component serial
+  - `product manufacturer`: Component vendor
+
+## Available ASM Techniques
+
+The official ASM repository includes **65 technique schemas**:
+
+```
+absorbance, automated-reactors, balance, bga, binding-affinity, bulk-density,
+cell-counting, cell-culture-analyzer, chromatography, code-reader, conductance,
+conductivity, disintegration, dsc, dvs, electronic-lab-notebook,
+electronic-spectrometry, electrophoresis, flow-cytometry, fluorescence,
+foam-height, foam-qualification, fplc, ftir, gas-chromatography, gc-ms, gloss,
+hot-tack, impedance, lc-ms, light-obscuration, liquid-chromatography,
+loss-on-drying, luminescence, mass-spectrometry, metabolite-analyzer,
+multi-analyte-profiling, nephelometry, nmr, optical-imaging, optical-microscopy,
+osmolality, oven-kf, pcr, ph, plate-reader, pressure-monitoring, psd, pumping,
+raman, rheometry, sem, solution-analyzer, specific-rotation, spectrophotometry,
+stirring, surface-area-analysis, tablet-hardness, temperature-monitoring,
+tensile-test, thermogravimetric-analysis, titration, ultraviolet-absorbance,
+x-ray-powder-diffraction
+```
+
+See: https://gitlab.com/allotrope-public/asm/-/tree/main/json-schemas/adm
+
+## Common ASM Schemas by Technique
+
+Below are details for frequently-used techniques:
+
+### Cell Counting
+Schema: `cell-counting/REC/2024/09/cell-counting.schema.json`
+
+Key fields:
+- `viable-cell-density` (cells/mL)
+- `viability` (percentage)
+- `total-cell-count`
+- `dead-cell-count`
+- `cell-diameter-distribution-datum`
+
+### Spectrophotometry (UV-Vis)
+Schema: `spectrophotometry/REC/2024/06/spectrophotometry.schema.json`
+
+Key fields:
+- `absorbance` (dimensionless)
+- `wavelength` (nm)
+- `transmittance` (percentage)
+- `pathlength` (cm)
+- `concentration` with units
+
+### Plate Reader
+Schema: `plate-reader/REC/2024/06/plate-reader.schema.json`
+
+Key fields:
+- `absorbance`
+- `fluorescence`
+- `luminescence`
+- `well-location` (A1-H12)
+- `plate-identifier`
+
+### qPCR
+Schema: `pcr/REC/2024/06/pcr.schema.json`
+
+Key fields:
+- `cycle-threshold-result`
+- `amplification-efficiency`
+- `melt-curve-datum`
+- `target-DNA-description`
+
+### Chromatography
+Schema: `liquid-chromatography/REC/2023/09/liquid-chromatography.schema.json`
+
+Key fields:
+- `retention-time` (minutes)
+- `peak-area`
+- `peak-height`
+- `peak-width`
+- `chromatogram-data-cube`
+
+## Data Patterns
+
+### Value Datum
+Simple value with unit:
+```json
+{
+  "value": 1.5,
+  "unit": "mL"
+}
+```
+
+### Aggregate Datum
+Collection of related values:
+```json
+{
+  "measurement-aggregate-document": {
+    "measurement-document": [
+      { "viable-cell-density": {"value": 2.5e6, "unit": "(cell/mL)"} },
+      { "viability": {"value": 95.2, "unit": "%"} }
+    ]
+  }
+}
+```
+
+### Data Cube
+Multi-dimensional array data:
+```json
+{
+  "cube-structure": {
+    "dimensions": [{"@componentDatatype": "double", "concept": "elapsed time"}],
+    "measures": [{"@componentDatatype": "double", "concept": "absorbance"}]
+  },
+  "data": {
+    "dimensions": [[0, 1, 2, 3, 4]],
+    "measures": [[0.1, 0.2, 0.3, 0.4, 0.5]]
+  }
+}
+```
+
+## Validation
+
+Validate ASM output against official schemas:
+
+```python
+import json
+import jsonschema
+from urllib.request import urlopen
+
+# Load ASM output
+with open("output.json") as f:
+    asm = json.load(f)
+
+# Get schema URL from manifest
+schema_url = asm.get("$asm.manifest", {}).get("$ref")
+
+# Validate (simplified - real validation more complex)
+# Note: Full validation requires resolving $ref references
+```
+
+## Schema Repository
+
+Official schemas: https://gitlab.com/allotrope-public/asm/-/tree/main/json-schemas/adm
+
+Schema structure:
+```
+json-schemas/adm/
+├── cell-counting/
+│   └── REC/2024/09/
+│       └── cell-counting.schema.json
+├── spectrophotometry/
+│   └── REC/2024/06/
+│       └── spectrophotometry.schema.json
+├── plate-reader/
+│   └── REC/2024/06/
+│       └── plate-reader.schema.json
+└── ...
+```
+
+## Common Issues
+
+### Missing Fields
+Not all instrument exports contain all ASM fields. Report completeness:
+```python
+def report_completeness(asm, expected_fields):
+    found = set(extract_all_fields(asm))
+    missing = expected_fields - found
+    return len(found) / len(expected_fields) * 100
+```
+
+### Unit Variations
+Instruments may use different unit formats. The allotropy library normalizes these:
+- "cells/mL" → "(cell/mL)"
+- "%" → "%"
+- "nm" → "nm"
+
+### Date Formats
+ASM uses ISO 8601: `2024-01-15T10:30:00Z`