Instance Matcher

Instance-based matching: probe SPARQL endpoints for bioregistry URI patterns.

Given a bioregistry resource prefix (e.g. "ensembl"), this module queries every rdfsolve data source for the RDF classes whose instances match the resource’s known URI prefixes. When two datasets both contain instances of the same resource, a mapping edge is emitted between their respective classes.

The result is an InstanceMapping that can be serialised to JSON-LD and imported into the rdfsolve database alongside mined schemas. The JSON-LD format is identical to a mined schema’s, so the frontend parseJSONLD pipeline works without any changes - skos:narrowMatch edges become walkable graph edges in the UI.

Typical usage:

from rdfsolve.sources import load_sources_dataframe
from rdfsolve.instance_matcher import probe_resource

datasources = load_sources_dataframe()
mapping = probe_resource("ensembl", datasources)
jsonld = mapping.to_jsonld()
discover_mapping_prefixes(*mapping_dirs: str, glob_pattern: str = '*.jsonld') → list[str][source]

Discover canonical bioregistry prefixes from mapping JSON-LD files.

For each file, reads the @context to find CURIE-prefix → namespace mappings (e.g. "chebi": "http://purl.obolibrary.org/obo/CHEBI_"), normalises each prefix via bioregistry.normalize_prefix(), and returns the deduplicated sorted list of canonical prefixes.

These are then passed to probe_resource(), which expands each canonical prefix to all its known URI namespaces (via bioregistry) and uses them as STRSTARTS patterns against SPARQL endpoints.

Parameters:

  • mapping_dirs – One or more directory paths to scan for *.jsonld.

  • glob_pattern – Glob pattern for mapping files (default *.jsonld).

Returns:

Sorted, deduplicated list of canonical bioregistry prefix strings.

probe_resource(prefix: str, datasources: DataFrame, predicate: str = 'http://www.w3.org/2004/02/skos/core#narrowMatch', dataset_names: list[str] | None = None, timeout: float = 60.0, inter_request_delay: float = 0.0, uri_formats: list[str] | None = None) → InstanceMapping[source]

Probe SPARQL endpoints for a bioregistry resource.

Steps:

  1. Resolve URI format prefixes for prefix via bioregistry.

  2. Optionally filter datasources to dataset_names.

  3. For each dataset, query its endpoint with each URI prefix using STRSTARTS-based SELECT DISTINCT ?c.

  4. Build pairwise MappingEdge instances between any two distinct classes that both matched the resource - including two classes within the same dataset (e.g. Gene and GeneAnnotation in the same endpoint both having Ensembl instance URIs are linked just like cross-dataset classes).

  5. Return an InstanceMapping ready for .to_jsonld().

Parameters:

  • prefix – Bioregistry prefix, e.g. "ensembl".

  • datasources – DataFrame with at least columns dataset_name and endpoint_url.

  • predicate – Mapping predicate URI. Defaults to skos:narrowMatch. Override to skos:exactMatch, owl:sameAs, etc. as appropriate.

  • dataset_names – If given, only probe these datasets.

  • timeout – SPARQL HTTP timeout per request in seconds.

  • inter_request_delay – Seconds to sleep before each SPARQL request (forwarded to SparqlHelper). Pass a positive value for remote public endpoints to avoid rate-limiting; use 0.0 (default) for local QLever.

Returns:

InstanceMapping with edges, match_results, and provenance about.

Raises:

ValueError – If prefix is unknown to bioregistry.

seed_instance_mappings(prefixes: list[str], sources_csv: str | None = None, *, sources: str | None = None, output_dir: str = 'docker/mappings/instance_matching', predicate: str = 'http://www.w3.org/2004/02/skos/core#narrowMatch', dataset_names: list[str] | None = None, timeout: float = 60.0, skip_existing: bool = False, ports_json: str | None = None, inter_request_delay: float = 0.0) → dict[str, Any][source]

Probe multiple bioregistry resources and write mapping JSON-LD files.

Iterates over prefixes, runs probe_resource() for each, and writes the result to {output_dir}/{prefix}_instance_mapping.jsonld.

When a file already exists on disk the new probe results are merged into it rather than overwriting it.

Parameters:

  • prefixes – List of bioregistry prefixes to process.

  • sources_csv – Deprecated - use sources instead.

  • sources – Path to the sources file (JSON-LD or CSV).

  • output_dir – Directory where JSON-LD files are written.

  • predicate – Mapping predicate URI.

  • dataset_names – Restrict probing to these dataset names.

  • timeout – SPARQL request timeout per request.

  • skip_existing – If True, skip prefixes whose output file already exists without re-probing.

  • ports_json – Path to QLever ports.json mapping {dataset_name: port}. When supplied, queries go to local QLever (http://localhost:{port}) instead of the remote endpoints in sources.yaml.

  • inter_request_delay – Seconds to sleep before each SPARQL request (forwarded to SparqlHelper). Defaults to 0.0 (no delay) — suitable for local QLever. Pass a positive value when querying remote public endpoints.

Returns:

{"succeeded": [...], "failed": [...]}.

Return type:

Summary dict