EM Glossary Field Reference#

Added in version 2.2.0.

This document provides a reference for standardized field names in NexusLIMS metadata, aligned with the Electron Microscopy Glossary v2.0.0 community standard.

Field Coverage Statistics#

NexusLIMS v2.2.0 provides:

8 fields with full EM Glossary ID mappings (✅)
33 fields without EM Glossary ID mappings (🔷)
Additional fields available in extensions section

Coverage Note: EM Glossary v2.0.0 provides basic coverage for core electron microscopy parameters. Fields without EMG IDs either represent vendor-specific concepts or areas where the EM Glossary is still expanding. NexusLIMS provides display names for all fields to ensure consistent XML output.

Common Fields by Category#

The tables below show the 25 most commonly used metadata fields in NexusLIMS, organized by functional category.

Beam Parameters#

Fields describing the electron/ion beam characteristics:

Field Name	Display Name	EMG ID	Preferred Unit	Typical Use	Schema
`acceleration_voltage`	Acceleration Voltage	EMG_00000004 ✅	kilovolt (kV)	Beam accelerating voltage	Image, Diffraction
`beam_current`	Beam Current	EMG_00000006 ✅	picoampere (pA)	Probe current at sample	Image
`emission_current`	Emission Current	EMG_00000025 ✅	microampere (µA)	Filament emission current	Image
`convergence_angle`	Convergence Angle	EMG_00000010 ✅	milliradian (mrad)	Beam convergence angle	Diffraction, Image

Stage & Sample Position#

Fields describing stage coordinates and orientation:

Field Name	Display Name	EMG ID	Preferred Unit	Typical Use	Schema
`stage_x`	Stage X	- 🔷	micrometer (µm)	Stage X coordinate	Image, Spectrum
`stage_y`	Stage Y	- 🔷	micrometer (µm)	Stage Y coordinate	Image, Spectrum
`stage_z`	Stage Z	- 🔷	millimeter (mm)	Stage Z position (height)	Image, Spectrum
`tilt_alpha`	Stage Alpha	- 🔷	degree (°)	Primary tilt angle	Image, Spectrum
`tilt_beta`	Stage Beta	- 🔷	degree (°)	Secondary tilt (dual-tilt holders)	Image, Spectrum

Detector Parameters#

Fields describing detector configuration:

Field Name	Display Name	EMG ID	Preferred Unit	Typical Use	Schema
`detector_type`	Detector	- 🔷	N/A (string)	Detector name (e.g., “ETD”, “HAADF”)	Image, Spectrum
`working_distance`	Working Distance	EMG_00000050 ✅	millimeter (mm)	Distance from lens to sample	Image
`detector_energy_resolution`	Energy Resolution	- 🔷	electronvolt (eV)	EDS detector resolution	Spectrum

Acquisition Parameters#

Fields describing data acquisition settings:

Field Name	Display Name	EMG ID	Preferred Unit	Typical Use	Schema
`dwell_time`	Pixel Dwell Time	EMG_00000015 ✅	microsecond (µs)	Time per pixel (scanning)	Image
`acquisition_time`	Acquisition Time	EMG_00000055 ✅	second (s)	Total acquisition time	Spectrum
`live_time`	Live Time	- 🔷	second (s)	EDS live time (excludes dead time)	Spectrum
`pixel_time`	Pixel Time	- 🔷	second (s)	Acquisition time per pixel (spectrum imaging)	SpectrumImage

Optical Parameters#

Fields describing optical configuration and field of view:

Field Name	Display Name	EMG ID	Preferred Unit	Typical Use	Schema
`magnification`	Magnification	- 🔷	dimensionless	Nominal magnification	Image
`camera_length`	Camera Length	EMG_00000008 ✅	millimeter (mm)	Diffraction camera length	Diffraction
`horizontal_field_width`	Horizontal Field Width	- 🔷	micrometer (µm)	Scan width	Image
`pixel_width`	Pixel Width	- 🔷	nanometer (nm)	Physical pixel width	Image
`pixel_height`	Pixel Height	- 🔷	nanometer (nm)	Physical pixel height	Image

Spectrum Parameters#

Fields specific to spectral data acquisition:

Field Name	Display Name	EMG ID	Preferred Unit	Typical Use	Schema
`channel_size`	Channel Size	- 🔷	electronvolt (eV)	Energy width per channel	Spectrum
`starting_energy`	Starting Energy	- 🔷	kiloelectronvolt (keV)	Spectrum starting energy	Spectrum
`takeoff_angle`	Takeoff Angle	- 🔷	degree (°)	EDS X-ray takeoff angle	Spectrum

Legend:

✅ = Has EM Glossary v2.0.0 ID mapping (full semantic annotation)
🔷 = Has EM Glossary display name but no ID in v2.0.0 (may be added in future versions)
Schema column shows which Pydantic schemas use this field

For the complete list of all mapped fields (40+), see the NEXUSLIMS_TO_EMG_MAPPINGS in nexusLIMS/schemas/em_glossary.py.

Usage Examples#

Basic Usage in Extractors#

from nexusLIMS.schemas.units import ureg
from nexusLIMS.extractors.utils import add_to_extensions

# Using standardized field names with Pint Quantities
nx_meta = {
    "creation_time": "2024-01-15T10:30:00-05:00",
    "data_type": "SEM_Imaging",
    "dataset_type": "Image",
    "acceleration_voltage": ureg.Quantity(Decimal("15"), "kilovolt"),
    "working_distance": ureg.Quantity(Decimal("5.2"), "millimeter"),
    "beam_current": ureg.Quantity(Decimal("100"), "picoampere"),
    "dwell_time": ureg.Quantity(Decimal("2.5"), "microsecond"),
}

# Add vendor-specific fields
add_to_extensions(nx_meta, "quanta_spot_size", 3.5)
add_to_extensions(nx_meta, "facility", "Building 7 Lab 3")

Programmatic Lookup Functions#

The EM Glossary module provides functions for dynamically accessing field metadata:

from nexusLIMS.schemas.em_glossary import (
    get_emg_id,
    get_emg_uri,
    get_emg_label,
    get_display_name,
    get_description,
    has_emg_id,
)

# Get EMG ID from field name
emg_id = get_emg_id("acceleration_voltage")
print(emg_id)  # "EMG_00000004"

# Get full PURL for semantic web
emg_uri = get_emg_uri("acceleration_voltage")
print(emg_uri)  # "https://purls.helmholtz-metadaten.de/emg/v2.0.0/EMG_00000004"

# Get label from EMG ID
label = get_emg_label("EMG_00000004")
print(label)  # "Acceleration Voltage"

# Get display name for XML
display = get_display_name("acceleration_voltage")
print(display)  # "Acceleration Voltage"

# Get field description
desc = get_description("acceleration_voltage")
print(desc)  # "Accelerating voltage of the electron/ion beam"

# Check if field has EMG mapping
if has_emg_id("acceleration_voltage"):
    print("Field has full EMG annotation")

Using `emg_field()` Helper#

The emg_field() helper automatically injects EM Glossary metadata when defining Pydantic schemas:

from nexusLIMS.schemas.metadata import emg_field
from nexusLIMS.schemas.pint_types import PintQuantity
from pydantic import BaseModel

class MySEMSchema(BaseModel):
    # Automatically gets EM Glossary metadata
    acceleration_voltage: PintQuantity | None = emg_field("acceleration_voltage")
    beam_current: PintQuantity | None = emg_field("beam_current")
    working_distance: PintQuantity | None = emg_field("working_distance")

    # Custom field without EMG mapping goes in extensions
    # (Don't use emg_field for vendor-specific fields)

# The fields automatically have:
# - alias: "Acceleration Voltage", "Beam Current", "Working Distance"
# - description: From EM Glossary definitions
# - json_schema_extra: {"emg_id": "EMG_00000004", "emg_uri": "...", ...}

Real-World Extractor Example#

Complete example showing EM Glossary usage in an extractor:

from nexusLIMS.schemas.units import ureg
from nexusLIMS.extractors.utils import add_to_extensions
from datetime import datetime, timezone

def extract_sem_metadata(file_path):
    """Extract metadata from SEM TIFF file."""
    # Read metadata from file (vendor-specific code)
    voltage_v = read_voltage_from_file(file_path)  # Returns 15000 (volts)
    wd_mm = read_working_distance(file_path)  # Returns 5.2 (mm)
    current_pa = read_beam_current(file_path)  # Returns 100 (pA)
    timestamp = read_timestamp(file_path)

    # Build metadata using EM Glossary field names
    nx_meta = {
        "creation_time": timestamp.isoformat(),
        "data_type": "SEM_Imaging",
        "dataset_type": "Image",

        # Standard EM Glossary fields with Pint Quantities
        "acceleration_voltage": ureg.Quantity(voltage_v, "volt"),  # Auto-converts to kV
        "working_distance": ureg.Quantity(wd_mm, "millimeter"),
        "beam_current": ureg.Quantity(current_pa, "picoampere"),
    }

    # Vendor-specific metadata goes in extensions
    spot_size = read_vendor_spot_size(file_path)
    if spot_size is not None:
        add_to_extensions(nx_meta, "quanta_spot_size", spot_size)

    return nx_meta

XML Output#

Fields with units serialize to clean XML using the unit attribute:

<meta name="Voltage" unit="kV">15</meta>
<meta name="Working Distance" unit="mm">5.2</meta>
<meta name="Beam Current" unit="pA">100</meta>

EM Glossary Integration Architecture#

NexusLIMS integrates with the EM Glossary through dynamic OWL ontology parsing using RDFLib.

Architecture Components#

OWL Ontology File: nexusLIMS/schemas/references/em_glossary_2.0.owl
- Shipped with NexusLIMS (139 KB)
- Parsed at runtime using RDFLib
- Provides labels, definitions, and semantic structure
- License: CC BY 4.0
Mapping Dictionary: NEXUSLIMS_TO_EMG_MAPPINGS in em_glossary.py
- Maps internal field names to EM Glossary labels
- Format: {field_name: (display_name, emg_label, description)}
- Single source of truth for field metadata
- ~50 fields mapped
Lookup Functions: Dynamic queries against parsed RDF graph
- get_emg_id(): Field name → EMG ID via label matching
- get_emg_label(): EMG ID → Label from ontology
- get_emg_definition(): EMG ID → Formal definition (IAO_0000115)
- get_emg_uri(): Field name → Full PURL

Update Process#

To update to a new EM Glossary version:

Download new OWL file from EM Glossary project
Replace nexusLIMS/schemas/references/em_glossary_2.0.owl
Update EMG_VERSION constant in em_glossary.py
Review NEXUSLIMS_TO_EMG_MAPPINGS for new terms
Run tests to verify parsing and mappings

Contributing to EM Glossary#

If you need a term that doesn’t exist in EM Glossary v2.0.0:

Check latest EM Glossary version: New terms may have been added
Propose new term: Contact EM Glossary maintainers via project page
Use extensions in the meantime: Place custom fields in nx_meta["extensions"]

Preferred Units Rationale#

Physical Quantity	Preferred Unit	Pint String	Rationale
Voltage	kilovolt	`"kilovolt"` or `"kV"`	Standard EM range (1-300 kV); avoids large numbers
Distance (large)	millimeter	`"millimeter"` or `"mm"`	Common SEM/TEM working distances (1-50 mm)
Distance (small)	micrometer	`"micrometer"` or `"um"`	Field widths and stage coordinates (1-1000 µm)
Current (beam)	picoampere	`"picoampere"` or `"pA"`	Typical probe currents (10-1000 pA)
Current (emission)	microampere	`"microampere"` or `"uA"`	Filament emission range (100-300 µA)
Time	second	`"second"` or `"s"`	Acquisition times (1-1000 s)
Energy	electronvolt	`"electron_volt"` or `"eV"`	X-ray energies and detector resolution
Angle	degree	`"degree"` or `"deg"`	Stage tilt, detector angles

Pint automatically converts to the preferred unit during XML serialization, ensuring consistency across instruments and vendors.

Resources#

EM Glossary Project - Documentation and updates
QUDT Ontology - Units and quantities standard
Pint Documentation - Python units library

EM Glossary Field Reference#

Field Coverage Statistics#

Common Fields by Category#

Beam Parameters#

Stage & Sample Position#

Detector Parameters#

Acquisition Parameters#

Optical Parameters#

Spectrum Parameters#

Usage Examples#

Basic Usage in Extractors#

Programmatic Lookup Functions#

Using `emg_field()` Helper#

Real-World Extractor Example#

XML Output#

EM Glossary Integration Architecture#

Architecture Components#

Update Process#

Contributing to EM Glossary#

Preferred Units Rationale#

Resources#

See Also#

This Page

EM Glossary Field Reference#

Field Coverage Statistics#

Common Fields by Category#

Beam Parameters#

Stage & Sample Position#

Detector Parameters#

Acquisition Parameters#

Optical Parameters#

Spectrum Parameters#

Usage Examples#

Basic Usage in Extractors#

Programmatic Lookup Functions#

Using emg_field() Helper#

Real-World Extractor Example#

XML Output#

EM Glossary Integration Architecture#

Architecture Components#

Update Process#

Contributing to EM Glossary#

Preferred Units Rationale#

Resources#

See Also#

This Page

Using `emg_field()` Helper#