Quick Reference: `parse()` Function¶

What It Does¶

The parse() function extracts ontology entities from free-form text by matching text tokens against an OWL ontology file.

Function Call¶

entities = parse(ontology_name, ontology_path, test_string)

Parameters¶

Parameter	Type	Description	Example
`ontology_name`	`str`	Name of the ontology file (without .owl extension)	`'catmanifest'`
`ontology_path`	`str`	Directory path containing the ontology file	`'../../testdir/ontologies'`
`test_string`	`str`	Free-form text to analyze	`"I love traveling to seattle, Washington."`

Return Value¶

Returns a list of unique entity names (strings) found in the text that match the ontology.

Example Output:

['seattle', 'washington', 'many', 'home']

How It Works (Simple Explanation)¶

Loads the ontology from the specified path
Splits text into paragraphs, then sentences
For each sentence:
Tokenizes into words
Matches tokens against ontology labels
Uses three matching strategies:
- Exact match: Direct word-to-label matching
- Span match: Multi-word phrase matching
- Hierarchical match: Parent/child relationship matching
Extracts matched entities (tokens that have ontology matches)
Removes duplicates and returns unique list

Key Components¶

1. Parser Caching¶

Parsers are cached by {ontology_path}/{ontology} key
Reuses same parser instance for performance

2. Text Segmentation¶

Splits text into paragraphs (by \n\n)
Splits paragraphs into sentences (using spaCy)

3. Matching Pipeline¶

Token → Exact Match → Span Match → Hierarchical Match → Entity

4. Matching Strategies¶

Exact Matching¶

Matches individual words against ontology labels
Checks: rdfs:label, rdfs:seeAlso, skos:altLabel, :inflection
Uses sliding window for n-grams (1-5 words)

Span Matching¶

Matches multi-word phrases
Handles discontinuous matches
Only runs if ontology has span definitions

Hierarchical Matching¶

Matches based on ontology class hierarchy
Uses rdfs:subClassOf relationships
Finds parent/child entity relationships

Example Usage¶

from notebooks import parse

# Define parameters
ontology_name = 'catmanifest'
ontology_path = '../../testdir/ontologies'
test_string = """
I love traveling to many states especially seattle, Washington. 
I also love visiting my home state!
"""

# Parse text
entities = parse(ontology_name, ontology_path, test_string)

# Print results
for entity in entities:
    print(entity)
# Output:
# seattle
# washington
# many
# home

Internal Data Flow¶

Input Text
    ↓
[Segment into paragraphs & sentences]
    ↓
For each sentence:
    ↓
[Tokenize] → ['i', 'love', 'seattle', ...]
    ↓
[Parse tokens with NLP]
    ↓
[Match against ontology]
    ├─ Exact: 'seattle' → ✓ Match
    ├─ Span: 'new york' → ✓ Match
    └─ Hierarchical: 'state' → ✓ Match (via hierarchy)
    ↓
[Extract matched tokens]
    ↓
[Add to entities list]
    ↓
[Deduplicate]
    ↓
Return: ['seattle', 'washington', 'many', 'home']

Performance Notes¶

Parser caching: First call loads ontology, subsequent calls reuse parser
Recursive limit: Maximum 2 passes to prevent infinite loops
Segmenter caching: Uses @lru_cache for repeated text segmentation

Error Cases¶

Empty ontology: Raises ValueError("Empty Ontology")
Missing ontology file: Handled by FindOntologyData
Invalid input: Validation at each processing step

Files Involved¶

File	Purpose
`tests/notebooks/__init__.py`	Contains `parse()` function
`src/python/parse_owl/bast_ai_parseowl/parser/bp/mutato_api.py`	Main parsing API
`src/python/parse_owl/bast_ai_parseowl/finder/multiquery/bp/find_ontology_data.py`	Ontology loader
`src/python/segmenter/bast_ai_segmenter/bp/segmenter.py`	Text segmentation

Detailed Analysis: See PARSE_FUNCTION_ANALYSIS.md
Visual Diagrams: See PARSE_FUNCTION_DIAGRAMS.md

Quick Reference: parse() Function¶