/instrument-data-to-allotrope

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

{
  "$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:

{
  "value": 1.5,
  "unit": "mL"
}

Aggregate Datum

Collection of related values:

{
  "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:

{
  "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:

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:

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