TomoBabel / CETS: cryoET geometry and LAMBDA integration

LAMBDA focuses on structural biology: linking proteins and complexes to specimens, experiments, and structure-determination workflows. Cryo-electron tomography (cryoET) places structures such as ribosomes, membranes, microtubules, and RubisCO complexes in their three-dimensional cellular surroundings. TomoBabel's Cryo Electron Tomography Standard (CETS) offers a way to exchange the images' coordinate systems, alignments, and spatial annotations. Connecting these to LAMBDA could help relate molecular identity to location and organization within a cell. The portal examples illustrate these imaging targets.

Research snapshot: 2026-09-17. This page incorporates a repository investigation and executable example checks. Core CETS refers to commit 0c8c4e3c7a2885f29caba551ffcaacde45c00101; experimental converter features are identified separately. Proposed LAMBDA mappings below are design recommendations. Source manifest and example provenance

What is TomoBabel?

TomoBabel is the organization; CETS is the standard under development. The project describes itself as funded by the Chan Zuckerberg Imaging Institute (CZII), with participants from CZII, CCP-EM, CSIC, and EMBL-EBI. Its repositories live under TomoBabel, outside the Chan Zuckerberg GitHub organization. Project statement

CETS builds on the earlier cryo-et-standards/cryoet-geometry work: merged PR #14 explicitly imports its LinkML definitions with adjustments. The schema still uses CETMD names and https://w3id.org/cetmd/ namespaces. Root schema

How it relates to the portal and LAMBDA

These roles follow from the CETS schema, portal schema, and LAMBDA schema. The dedicated portal converter exports portal runs into CETS and creates draft portal-ingestion staging files in the reverse direction. It does not establish that the portal has replaced its API or published metadata schema with CETS. See the separate CZ cryoET Data Portal background page.

Versions: distinguish core from converter profiles

The inspected Python package declares version 0.1.0 and Pre-Alpha status; its eight LinkML modules declare 0.0.1. Package and schema versions therefore need separate tracking. Package metadata, schema modules

The portal dependency declaration makes its PR-branch dependency explicit. An integration should record the schema commit, converter commit, profile, and companion-file version. Merely recording “CETS 0.1” would leave the coordinate contract ambiguous.

Main entities and relationships

CETS uses a nested document. A Dataset contains Regions and Averages. A Region groups raw and processed products from one specimen region. An Average groups particle maps. LAMBDA's Dataset instead contains flat entity collections and association tables, so the shared class names do not establish equivalent meanings. CETS entities, LAMBDA

Solid arrows show containment; dashed arrows show selected references. This diagram does not assert required cardinalities or automatic reference validation. Entities, image entities, alignment, annotations

Three details affect a crosswalk:

• Movie and stack terminology: a MovieFrame is an individual movie image. A TiltImage can reference its source movie and has a zero-based stack section.
• Reconstruction provenance: core Alignment has no identifier, and Tomogram has no explicit alignment reference. A shared tilt-series identifier does not identify which alignment produced a volume.
• Particle provenance: ParticleMap can reference a Region, an Annotation, and a zero-based coord_index. Those references are optional. Reordering picked coordinates can invalidate the index-based link.

Sources: image entities, alignment.

Coordinates, transformations, and image files

Each coordinate system has a name and named axes, with units and an axis type of space or array. Transformations identify their input and output systems by name. Supported forms are identity, axis mapping, translation, scale, affine, and an ordered sequence. This can describe how array indices relate to physical positions. Coordinate systems, transformations

Core Affine is constrained to a 3 × 3 matrix. It cannot directly accept the portal's 4 × 4 homogeneous transform. A profile must specify how to interpret the matrix and represent translation, axis order, origin, handedness, and operation order. Accepting the correct matrix shape alone does not establish geometric equivalence. Transforms, Python models, portal alignment background

The rigid profile makes a more specific choice, converting array indices to centered physical coordinates with per-axis values:

p_physical = (p_array - floor(N / 2)) * spacing

It then defines rotation and projection conventions. This is a profile convention, not a default imposed on every core CETS document. The synthetic example below deliberately uses a simpler corner origin. Rigid profile

Here N is the number of samples along an axis. For odd N, floor(N / 2) equals the midpoint (N - 1) / 2 of zero-based sample indices; for even N, it lies half a sample above that midpoint. For example, both centers are 2 when N = 5, while for N = 4 the profile uses 2 and the index midpoint is 1.5. Preserve the profile's explicit choice when converting coordinates.

Image records describe dimensions, coordinates, and paths; voxel arrays remain in external files. Tilt series and tomograms can reference even/odd products and record CTF correction. Core records do not provide a complete file-checksum or OME-Zarr multiscale model. LAMBDA's DataFile can supply file provenance, while a converter must preserve storage-specific axes and sampling metadata. Image definitions, image entities, LAMBDA

Annotations: geometry and biological meaning

CETS defines annotation types for 2D/3D points, vectors and rotations, segmentation masks and probability maps, meshes, geometric primitives, splines, and fitted density maps. A 3D point set uses origin3D; oriented representations can carry rotation matrices. Some representations remain sparse: the inspected TriMesh has no explicit vertices/faces payload. A type name alone is therefore insufficient to establish a complete exchange format. Annotation schema

Core CETS has no dedicated GO or UniProt classification fields, nor a full annotation method, authorship, evidence, or confidence model. Its Python models reject unknown fields, so adding ontology_id directly to core JSON is not a compatible extension. The portal converter preserves biological metadata and provenance in companion files. Annotations, models, portal converter

LAMBDA already has ImageFeature.terms containing OntologyTerm values, alongside protein-level GO and UniProt support. A useful extension would link these semantic assertions to explicitly identified CETS geometries and image frames. Keep three identities distinct:

1. Object class: for example, GO's cytosolic ribosome or membrane.
2. Observed occurrence: a particular picked point or segmented region in an image.
3. Molecular identity: a supported protein or complex assignment, potentially involving UniProt accessions.

An annotation record's id identifies the record; it should not be repurposed as the GO class. A ribosome pick also does not establish every constituent protein's identity. These are integration recommendations based on LAMBDA's semantic types and the portal's actual GO annotations.

YAML examples and actual image data

Yes, YAML is available, but the different kinds serve different purposes. CETS itself is defined in LinkML YAML. The EMPIAR converter supplies a YAML input configuration and a CETS JSON output example. For readability, this page includes selected real metadata reserialized as YAML, plus an authored, validated CETS teaching example. Example README

1. Minimal CETS document with a point annotation

Download minimal-cets.yaml. It contains a tilt series, tomogram, named voxel and physical frames, a point set, and a particle map linked to the first point. The document validates against the inspected core Python model and survives JSON serialization and reloading. Its file paths are illustrative.

The following is just the annotation excerpt; the full file supplies the referenced image and frame definitions:

annotations:
  - id: picks_1
    name: Example particle picks; no biological identification asserted
    annotation_type: point_set_3D
    source_tomogram_id: tomo_1
    coordinate_systems:
      - name: physical_xyz
        axes:
          - {name: x, axis_type: space, axis_unit: angstrom}
          - {name: y, axis_type: space, axis_unit: angstrom}
          - {name: z, axis_type: space, axis_unit: angstrom}
    origin3D:
      - [40.0, 80.0, 24.0]

With the example's 4 Å sampling and corner origin, this point corresponds to voxel coordinates [10, 20, 6]. The particle map references picks_1 with coord_index: 0. No biological class is asserted.

2. EMPIAR-12104: real CETS metadata and a tomogram

The upstream EMPIAR-12104 example includes region Control_TS_006, a 50-image tilt series, and a tomogram. Our YAML excerpt preserves the tomogram's values: dimensions 1022 × 1440 × 500, voxel-to-physical scale 13.699999809265137 Å on each axis, and a public MRC volume.

This is a historical example: its full original JSON fails current-core validation because 50 tilt images lack now-required IDs. The excerpt omits the referenced tilt series and is not a self-contained exchange document. It contains no biological annotations. These limitations distinguish a useful real-world illustration from a current conformance fixture. Upstream JSON, current image definitions

3. Portal run TS_105_5: images and a GO membrane annotation

The portal converter includes a recorded input fixture for dataset 10445, run 17687 / TS_105_5. Our YAML excerpt includes a denoised 630 × 630 × 184 reconstruction at 10.012 Å, links to its MRC/OME-Zarr data, and an automated membrane annotation labeled GO:0016020. This fixture is portal converter input, not CETS output.

The selected annotation metadata is under VoxelSpacing4.990, while that reconstruction is at VoxelSpacing10.012. They cannot be overlaid by assuming identical array coordinates; the applicable alignment and grid conversion must be established. For an already-inspected image/annotation pair, including a preview, ribosome points, and a membrane mask, see yeast TS_026.

The linked volumes remain external; the local examples contain small metadata files. Their provenance manifest records source commits, source-payload checksums, and the transformations used to create each excerpt.

Converter ecosystem

The investigation inspected implementations in the following repositories. This inventory describes implemented scope; converter suites and reconstruction equivalence were not tested.

For the portal exporter, alignment and grid compatibility affect whether annotations can be included. Reverse conversion produces a draft for ingestion, not an automatic submission. Preserve converter options, skipped products, and losses as part of workflow provenance. Converter implementation

Practical integration with LAMBDA

The following is a proposed crosswalk, not an implemented adapter:

Assessment sources: CETS entities, image entities, LAMBDA schema. Numeric fields also need semantic review: CETS accumulated_dose is pre-exposure, defocus U/V are in Å, and per-axis sampling may be anisotropic. They cannot automatically become an image's delivered dose, a single defocus value, or a scalar voxel size.

A useful first step is an external-artifact adapter: register CETS documents, original metadata, companion files, and image products as LAMBDA DataFile records associated with a conversion WorkflowRun. Retain source IDs, exact model/converter versions, checksums, and a mapping to LAMBDA entities. This provides traceability while coordinate and annotation extensions are evaluated.

Validation must go beyond loading the document. The investigation found that core models accept dangling image references, inconsistent point/vector counts, negative widths, and underspecified scale vectors. An adapter should check reference resolution, array dimensions, coordinate counts, and known coordinate conversions. The validated synthetic example demonstrates model acceptance; it does not certify every converter or a reconstructed volume's scientific correctness. Core models