validate_hierarchy#

scikitplot.corpus.validate_hierarchy(documents, *, max_depth=64, require_parent_present=True)[source]#

Check referential integrity, cycles and depth of the hierarchy.

Parameters:
documentsiterable of CorpusDocument

The collection to validate. Treated as a closed world: a parent_doc_id naming a document outside this collection counts as dangling unless require_parent_present is False.

max_depthint, optional

Maximum permitted ancestor chain length.

require_parent_presentbool, optional

When False, a parent_doc_id absent from documents is tolerated. Use for validating a partial page of a larger corpus, where the parent legitimately lives elsewhere.

Returns:
HierarchyReport

Violations found, as structured records rather than exceptions, so a caller can report all of them rather than only the first.

Parameters:
Return type:

HierarchyReport

Notes

Three violation classes are detected, each with its own code:

HIERARCHY_DANGLING_PARENT

parent_doc_id names a document not present.

HIERARCHY_CYCLE

Following parents revisits a document.

HIERARCHY_TOO_DEEP

The ancestor chain exceeds max_depth.

HIERARCHY_SELF_PARENT

A document is its own parent – reported distinctly from a general cycle because it is almost always a copy-paste error rather than a structural one.

Examples

>>> from scikitplot.corpus import CorpusDocument
>>> a = CorpusDocument.create(input_path="f.txt", chunk_index=0, text="a")
>>> validate_hierarchy([a]).ok
True