NAICS Hierarchy API

Code lineage, the tree metric D (Req 7) and unary pairs (Req 9). The supervision bundle and Stage 4's diagnostics read D from the same function.

HierarchyIntegrityError

Bases: ValueError

A relations file lacks a NAICS parent link between two codes it contains.

NaicsHierarchy

In-memory representation of the NAICS hierarchy derived from relations parquet data.

from_relations_parquet(relations_path) classmethod

Build a hierarchy object from the relations parquet.

Expects columns code_i, code_j, and either relation_id or relation/relationship.

Raises:

Type Description
HierarchyIntegrityError

If the file lacks a parent link between two codes it contains.

NAICS (parent, child) links between two of codes that this hierarchy lacks, sorted.

A code whose parent is absent from codes is a root of a partial tree, not a gap.

code_lineage(code) cached

The code's ancestors from its sector down to the code itself.

load_naics_hierarchy(relations_path) cached

Load (and cache) a NAICS hierarchy from the relations parquet file.

naics_parent_code(code)

The code's parent in the NAICS tree, or None for a sector.

tree_distance_matrix(codes)

D* between every two codes (Req 7): the tree path length through a virtual root.

A code's depth is the length of its lineage, 1 for a sector, and D* is depth_i + depth_j - 2 depth_LCA with the virtual root at depth 0. Pairs across sectors therefore get λ(i) + λ(j) − 2, where λ is the number of digits. Combined sectors (31-33, 44-45, 48-49) count as one. Only the code strings are read, so ancestors need not be among codes.

Returns:

Type Description
ndarray

(len(codes), len(codes)) int64 matrix, zero on the diagonal.

unary_pairs(codes)

The unary pairs among codes (Req 9): a five-digit code and its only six-digit child.

Returns:

Type Description
List[Tuple[str, str]]

(parent, child) pairs sorted by parent.