field_spec

MIAPPE field specification for the metadata editor UI

Defines every editable leaf field of the canonical MIAPPE-aligned scan metadata tree (see plantdb.commons.fsdb.metadata_schema) plus the detailed explanations of each field (sourced from the MIAPPE checklist data model TSV).

It also provides helpers to flatten a nested metadata dict to a flat {dot.path: value} mapping and to rebuild the tree, which the UI uses to render editable forms and to write values back.

coerce

coerce(path, value)

Coerce value to the declared type of the field at path.

Parameters:

Name	Type	Description	Default
path	str	Dot-separated field path whose declared type is applied.	required
value	Any	Value to coerce.	required

Returns:

Type	Description
Any	The coerced value, the original value if it cannot be coerced, or None for empty values.

Source code in plantdb/client/metadata_app/field_spec.py

def coerce(path: str, value: Any) -> Any:
    """Coerce ``value`` to the declared type of the field at ``path``.

    Parameters
    ----------
    path : str
        Dot-separated field path whose declared type is applied.
    value : Any
        Value to coerce.

    Returns
    -------
    Any
        The coerced value, the original value if it cannot be coerced, or
        ``None`` for empty values.
    """
    if value is None or value == "":
        return None
    spec = FIELD_BY_PATH[path]
    ftype = spec["type"]
    try:
        if ftype == "int":
            return int(float(value))
        if ftype == "float":
            return float(value)
    except (TypeError, ValueError):
        return value
    return str(value)

collect_suggestions

collect_suggestions(scans, path)

Return the sorted unique non-empty values of path across scans.

Parameters:

Name	Type	Description	Default
scans	list of dict of str to Any	A list of flattened scan dicts (see :func:flatten).	required
path	str	Dot-separated field path to collect values for.	required

Returns:

Type	Description
list of str	Sorted unique values.

Source code in plantdb/client/metadata_app/field_spec.py

def collect_suggestions(scans: list[dict[str, Any]], path: str) -> list[str]:
    """Return the sorted unique non-empty values of ``path`` across ``scans``.

    Parameters
    ----------
    scans : list of dict of str to Any
        A list of flattened scan dicts (see :func:`flatten`).
    path : str
        Dot-separated field path to collect values for.

    Returns
    -------
    list of str
        Sorted unique values.
    """
    values: set[str] = set()
    for flat in scans:
        v = flat.get(path)
        if v is not None and str(v) not in (None, "", "None"):
            values.add(str(v))
    return sorted(values)

flatten

flatten(metadata, prefix='')

Flatten a nested metadata dict into a flat {dot.path: value} mapping.

Only leaf fields declared in FIELD_SPECS are kept.

Parameters:

Name	Type	Description	Default
metadata	dict of str to Any	The nested metadata dict to flatten.	required
prefix	str	Dot-separated path prefix to prepend (used in recursion).	''

Returns:

Type	Description
dict of str to Any	The flattened mapping.

Source code in plantdb/client/metadata_app/field_spec.py

def flatten(metadata: dict[str, Any], prefix: str = "") -> dict[str, Any]:
    """Flatten a nested metadata dict into a flat ``{dot.path: value}`` mapping.

    Only leaf fields declared in ``FIELD_SPECS`` are kept.

    Parameters
    ----------
    metadata : dict of str to Any
        The nested metadata dict to flatten.
    prefix : str, default ''
        Dot-separated path prefix to prepend (used in recursion).

    Returns
    -------
    dict of str to Any
        The flattened mapping.
    """
    flat: dict[str, Any] = {}
    for key, value in metadata.items():
        path = f"{prefix}.{key}" if prefix else key
        if path in FIELD_BY_PATH:
            flat[path] = value
        elif isinstance(value, dict):
            flat.update(flatten(value, path))
    return flat

sections

sections()

Return the ordered top-level MIAPPE section names.

Returns:

Type	Description
list of str	The top-level keys of the biological schema.

Source code in plantdb/client/metadata_app/field_spec.py

def sections() -> list[str]:
    """Return the ordered top-level MIAPPE section names.

    Returns
    -------
    list of str
        The top-level keys of the biological schema.
    """
    return list(SCAN_BIOLOGICAL_SCHEMA.keys())

specs_for_section

specs_for_section(section)

Return the field specs whose dot-path starts with section.

Parameters:

Name	Type	Description	Default
section	str	Top-level MIAPPE section name, e.g. study.	required

Returns:

Type	Description
list of FieldSpec	The field specs belonging to the section.

Source code in plantdb/client/metadata_app/field_spec.py

def specs_for_section(section: str) -> list[FieldSpec]:
    """Return the field specs whose dot-path starts with ``section``.

    Parameters
    ----------
    section : str
        Top-level MIAPPE section name, e.g. ``study``.

    Returns
    -------
    list of FieldSpec
        The field specs belonging to the section.
    """
    return [s for s in FIELD_SPECS if s["path"].startswith(section + ".")]

unflatten

unflatten(flat)

Rebuild a nested metadata dict from a flat {dot.path: value} mapping.

Intermediate sections are created as needed. Values are coerced to the declared field type.

Parameters:

Name	Type	Description	Default
flat	dict of str to Any	The flattened mapping to rebuild.	required

Returns:

Type	Description
dict of str to Any	The nested metadata tree.

Source code in plantdb/client/metadata_app/field_spec.py

def unflatten(flat: dict[str, Any]) -> dict[str, Any]:
    """Rebuild a nested metadata dict from a flat ``{dot.path: value}`` mapping.

    Intermediate sections are created as needed. Values are coerced to the
    declared field type.

    Parameters
    ----------
    flat : dict of str to Any
        The flattened mapping to rebuild.

    Returns
    -------
    dict of str to Any
        The nested metadata tree.
    """
    tree: dict[str, Any] = {}
    for path, value in flat.items():
        parts = path.split(".")
        target = tree
        for part in parts[:-1]:
            target = target.setdefault(part, {})
        target[parts[-1]] = coerce(path, value)
    return tree