Skill 01 · Instrument Data To Allotrope
Subchapter 1.1
references/asm_schema_overview.mdMarkdown6 KBView on GitHub
The Allotrope Simple Model (ASM) is a JSON-based standard for representing laboratory instrument data with semantic consistency.
ASM uses a hierarchical document structure:
{
"$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": [ ... ]
}
}
]
}
}Every ASM output MUST include this document with:
ASM file identifier: Output filenamedata system instance identifier: System ID or “N/A”file name: Source input filenameUNC path: Path to source fileASM converter name: Parser identifier (e.g., “allotropy_beckman_coulter_biomek”)ASM converter version: Version stringsoftware name: Instrument software that generated the source fileEvery ASM output MUST include this document with:
equipment serial number: Main instrument serialproduct manufacturer: Vendor namedevice 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 serialproduct manufacturer: Component vendorThe 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-diffractionBelow are details for frequently-used techniques:
Schema: cell-counting/REC/2024/09/cell-counting.schema.json
Key fields:
viable-cell-density (cells/mL)viability (percentage)total-cell-countdead-cell-countcell-diameter-distribution-datumSchema: spectrophotometry/REC/2024/06/spectrophotometry.schema.json
Key fields:
absorbance (dimensionless)wavelength (nm)transmittance (percentage)pathlength (cm)concentration with unitsSchema: plate-reader/REC/2024/06/plate-reader.schema.json
Key fields:
absorbancefluorescenceluminescencewell-location (A1-H12)plate-identifierSchema: pcr/REC/2024/06/pcr.schema.json
Key fields:
cycle-threshold-resultamplification-efficiencymelt-curve-datumtarget-DNA-descriptionSchema: liquid-chromatography/REC/2023/09/liquid-chromatography.schema.json
Key fields:
retention-time (minutes)peak-areapeak-heightpeak-widthchromatogram-data-cubeSimple value with unit:
{
"value": 1.5,
"unit": "mL"
}Collection of related values:
{
"measurement-aggregate-document": {
"measurement-document": [
{ "viable-cell-density": {"value": 2.5e6, "unit": "(cell/mL)"} },
{ "viability": {"value": 95.2, "unit": "%"} }
]
}
}Multi-dimensional array data:
{
"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]]
}
}Validate ASM output against official schemas:
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 referencesOfficial schemas: https://gitlab.com/allotrope-public/asm/-/tree/main/json-schemas/adm (opens in a new tab)
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
└── ...Not all instrument exports contain all ASM fields. Report completeness:
def report_completeness(asm, expected_fields):
found = set(extract_all_fields(asm))
missing = expected_fields - found
return len(found) / len(expected_fields) * 100Instruments may use different unit formats. The allotropy library normalizes these:
ASM uses ISO 8601: 2024-01-15T10:30:00Z