Mapping file annotations

Mapping files support comment stubs — path entries whose value is a dict with a "comment" key rather than a mapper expression. They serve as structured documentation inside the mapping file and are treated as stubs: paths that exist in the schema but have not yet been implemented.

Syntax

A stub as generated by init-mapping (comment pre-filled from the IDS data dictionary):

{
  "magnetics/flux_loop[#]/flux/data[#]": {"comment": "Flux [Wb]"},
  "magnetics/b_field_pol_probe[#]/field/data[#]": {"comment": "Data [T]"}
}

A manually annotated stub:

{
  "magnetics/flux_loop[#]/field": {"comment": "Hall probe B-field"}
}

Extended form — all allowed keys:

{
  "magnetics/flux_loop[#]/field": {
    "comment": "flux loop field from UDA raw channel",
    "units": "T",
    "source": "AMC_FLUX_LOOP_{i}"
  }
}

Only "comment", "units", and "source" are recognised annotation keys. Any dict containing "comment" and only those keys is treated as a stub; any other key combination is forwarded to the mapper as a normal mapping value.

init-mapping generates stubs

munchi init-mapping generates stubs with comments drawn directly from the imas_data_dictionary package — documentation text and physical units are combined into a single "comment" string:

munchi init-mapping --ids magnetics --leaves-only --output magnetics.json

Output excerpt:

{
  "magnetics/flux_loop[#]/flux/data[#]": {"comment": "Flux [Wb]"},
  "magnetics/flux_loop[#]/position[#]/phi": {"comment": "Toroidal angle (oriented counter-clockwise when viewing from above) [rad]"},
  "magnetics/b_field_pol_probe[#]/field/data[#]": {"comment": "Data [T]"}
}

The comment is the field’s documentation text from the data dictionary, followed by its units in square brackets where available. Replace a stub value with your mapper expression once you have implemented a path; the original IDS documentation remains readable as context.

Adding stubs for missing paths

As the IDS schema evolves, new paths may appear that are not yet in your mapping file. Use munchi update-mapping to add stubs for those paths while preserving all existing entries:

munchi update-mapping --ids magnetics --mapping magnetics.json

This is a non-destructive operation: existing paths, including their comments and mapper expressions, are never modified. Only paths absent from the file gain a new stub with the IDS documentation as its comment. Write to a new file with --output:

munchi update-mapping --ids magnetics --mapping magnetics.json \
    --output magnetics-updated.json

Use --force to overwrite the output file if it already exists, and --leaves-only to restrict the stub generation to leaf (scalar) paths.

Interaction with --mapping filter

When you run munchi map --mapping magnetics.json, stub entries are skipped — they are included in the key intersection used for path selection, but because their value is a comment dict the mapper is never called for them. This means you can ship a partially-annotated file and only live paths will be evaluated:

# Paths with real mapper expressions are evaluated.
# Stub paths are silently skipped.
munchi map --ids magnetics --mapping magnetics.json --output results.json

Library usage

from tokamunch.templates import (
    is_comment_stub,
    merge_mapping_stubs,
    build_blank_mapping_template,
)

# Check whether a mapping value is an annotation stub.
is_comment_stub({"comment": "flux loop field"})  # True
is_comment_stub({"comment": "", "units": "T"})   # True
is_comment_stub({})                               # False
is_comment_stub("raw_channel_name")              # False

# Generate a mapping template with stubs.
template = build_blank_mapping_template("magnetics", leaves_only=True)

# Add stubs for any paths in the schema not already in an existing file.
merge_mapping_stubs("magnetics", "magnetics.json", leaves_only=True)