Classification API

The s3dgraphy.classification module is the JSON-driven single source of truth for stratigraphic family (real / virtual) and is_series membership. Consumers (EM-blender-tools pickers, GraphML importer BR-handling, filter chains) should use these helpers instead of hardcoding type lists.

Accessors

Stratigraphic type classification — JSON-driven single source of truth.

The canonical metadata for every stratigraphic type (label, abbreviation, family, is_series, CIDOC mapping, …) lives in JSON_config/s3Dgraphy_node_datamodel.json. This module is a thin Python facade that loads the JSON lazily, caches the parsed shape, and exposes convenient accessors so downstream consumers (e.g. the GraphML importer’s BR-handling logic, EM-blender-tools’ UI pickers, filters, and material maps) never need to hardcode type lists.

Rules validated by test_stratigraphic_classification:

Every node_type in STRATIGRAPHIC_CLASS_MAP has a matching subtype entry in the JSON datamodel.
Every JSON subtype has a Python class in STRATIGRAPHIC_CLASS_MAP.
Each subtype declares exactly one family in {"real", "virtual", null}.
is_series is True iff the abbreviation starts with ser.

Public API:

get_family() — return "real" | "virtual" | None.
is_real() / is_virtual() / is_series() — predicate helpers.
get_subtype_info() — full metadata dict for one type.
iter_subtypes() — iterate over (abbr, info) pairs.
REAL_US_TYPES, VIRTUAL_US_TYPES, SERIES_US_TYPES, ALL_US_TYPES — frozenset snapshots computed from the JSON on first access.

s3dgraphy.classification.get_subtype_info(node_type: str) → dict | None[source]: Return the full metadata dict for node_type (or None).

s3dgraphy.classification.iter_subtypes() → Iterator[Tuple[str, dict]][source]: Iterate over (abbreviation, info_dict) pairs, in JSON order.

s3dgraphy.classification.get_family(node_type: str) → str | None[source]

Return "real" / "virtual" / None for node_type.

None is used for helper nodes that are not proper stratigraphic units (BR, SE) and for unknown types.

s3dgraphy.classification.is_real(node_type: str) → bool[source]: True iff node_type is classified in the real family.

s3dgraphy.classification.is_virtual(node_type: str) → bool[source]: True iff node_type is classified in the virtual family.

s3dgraphy.classification.is_series(node_type: str) → bool[source]: True iff node_type is a series aggregate (serSU, serUSD, serUSVn, serUSVs, …). Derived from the JSON’s is_series field — kept in sync with the abbreviation prefix convention by the classification test.

s3dgraphy.classification.REAL_US_TYPES: frozenset = frozenset({'RSF', 'SF', 'TSU', 'UL', 'US', 'USD', 'USN', 'serSU', 'serUSD'}): Every stratigraphic type with family == "real".

s3dgraphy.classification.VIRTUAL_US_TYPES: frozenset = frozenset({'USVn', 'USVs', 'VSF', 'serUSVn', 'serUSVs'}): Every stratigraphic type with family == "virtual".

s3dgraphy.classification.SERIES_US_TYPES: frozenset = frozenset({'serSU', 'serUSD', 'serUSVn', 'serUSVs'}): Every stratigraphic type marked is_series.

s3dgraphy.classification.ALL_US_TYPES: frozenset = frozenset({'BR', 'RSF', 'SE', 'SF', 'TSU', 'UL', 'US', 'USD', 'USN', 'USVn', 'USVs', 'VSF', 'serSU', 'serUSD', 'serUSVn', 'serUSVs'}): Every stratigraphic subtype known to the datamodel (including BR/SE).

Re-exported constants

The following frozensets are also re-exported from the package root for convenience (from s3dgraphy import REAL_US_TYPES):

s3dgraphy.classification.REAL_US_TYPES: Every stratigraphic type with family == "real".

s3dgraphy.classification.VIRTUAL_US_TYPES: Every stratigraphic type with family == "virtual".

s3dgraphy.classification.SERIES_US_TYPES: Every stratigraphic type marked is_series.

s3dgraphy.classification.ALL_US_TYPES: Every stratigraphic subtype known to the datamodel (including BR/SE).

See Stratigraphic Classification for the conceptual overview and a worked example of extending the JSON datamodel with a new subtype.