find_terms

find_terms(
    query,
    role=None,
    sources=None,
    expand_query=True,
    release=None,
    snapshot_dir=None,
)

Find ontology terms across OLS, NVS, and other vocab sources.

Parameters

Name Type Description Default
query str Search text. required
role Optional[str] Optional I-ADOPT role. It shapes ranking and, when sources is None, chooses the sources searched. None
sources Optional[Sequence[str]] Sources to search, or None (the default) for sources_for_role(role); with no role that is ["smn", "gcdfo", "ols", "nvs"]. A list you supply is a strict allowlist: each name is trimmed and lower-cased, a missing or empty name is dropped, and a repeat is dropped after its first appearance. An empty list returns an empty frame. metasalmon’s find_terms() reads sources the same way (hub B-420 and B-421). An unknown name is reported with status="unsupported" and no lookup is performed for it; supported sources in the same call still return their results. None
expand_query bool Search role-aware variants of query as well as query itself. True
release Optional[Mapping[str, str]] Release versions of smn and gcdfo to search instead of the latest ontology, keyed by ontology: {"smn": "0.0.3"}, or {"smn": "0.0.3", "gcdfo": "0.0.9"}. Each is read from its release snapshot, downloaded from its version IRI (https://w3id.org/smn/0.0.3) once per process, and checked against the snapshot’s MANIFEST.sha256 when it carries one. A pin never falls back to the latest ontology: a release that cannot be read or does not match its manifest raises OntologyReleaseError. Only smn and gcdfo can be pinned; other sources are searched as they are. None
snapshot_dir Optional[Mapping[str, Union[str, 'os.PathLike[str]']]] Local release snapshots, keyed by ontology the same way, such as a checkout’s docs/releases/0.0.3/. Each is read from disk, with no download. When release names the same ontology too, a snapshot that declares an owl:versionIRI must declare that version. A pinned smn release is read from its RDF/XML (smn.owl), which holds the same terms as the latest ontology’s modules, and its terms get the role hints the module reader gives them, with one difference: a release records no module, so a term whose entity hint comes only from belonging to the 01-entity-systematics module has no entity hint in a release. None

Returns

Name Type Description
pandas.DataFrame The ranked candidates, with per-source diagnostics in attrs["diagnostics"]. Diagnostic status is success, http_error, error or unsupported; a supported search with no matches remains success. Unsupported and failed lookups warn that the result is incomplete and are not cached. When release or snapshot_dir pins an ontology the call searched, attrs["ontology_release"] records which release was searched: a DataFrame with one row per pinned ontology and the columns ontology, version, version_iri (as the snapshot declares it, or None), file, sha256 (of the bytes read), manifest_verified (True when the snapshot’s MANIFEST.sha256 vouched for them, False when it carries none) and source (the version IRI or the snapshot directory). metasalmon’s find_terms() records the same in its "ontology_release" attribute.

Examples

Search smn release 0.0.3 rather than the latest ontology, and record it:

>>> pinned = find_terms("escapement", sources=["smn"], release={"smn": "0.0.3"})
>>> pinned.attrs["ontology_release"]

Pin the searches suggest_semantics() makes:

>>> def search_fn(query, role=None, sources=None):
...     return find_terms(query, role=role, sources=sources, release={"smn": "0.0.3"})
Back to top