neurolang.utils.engine_registry#

Declarative engine registry for the neurolang-query CLI.

Engines are declared in engines/engines.yaml. Each engine may define:

a Python initialisation script (python_init);
optional Datalog initialisation code (datalog_init) evaluated after the Python script;
optional CSV/TSV relations (relations) loaded as extensional predicates after the Datalog init. Each relation entry may carry optional name and description fields for predicate metadata used by the --list-predicates command. The file value may be a URL (http:// / https://) for automatic download;
downloads — files to fetch (with optional archive extraction);
templates — neuroimaging templates (brain masks, anatomical templates) downloaded via nilearn or TemplateFlow (if the templateflow package is installed). Each template may optionally register a voxel(i, j, k) predicate from its non-zero mask:
```
templates:
  mni_brain:
    source: nilearn
    variant: brain_mask
    predicate: voxel
  t1_ref:
    source: templateflow
    template: MNI152NLin2009cAsym
    resolution: 1
```
ontologies — OWL/RDF ontologies to load from URLs or local paths;
builtins — list of known function names (exp, log, startswith, etc.) to register as callable symbols;
probabilistic_choice — uniform probabilistic choices declared as name: {source: other_predicate}.
atlases — brain atlases downloaded via nilearn (e.g. destrieux, schaefer, difumo) and registered as predicates with ExplicitVBR regions. Deterministic atlases use ExplicitVBR.from_spatial_image_label; probabilistic atlases are thresholded (default 0.5) to create binary region masks.
extends — one engine name, or a list of them, whose configuration is inherited (see resolve_engine_config()); engines marked abstract: true only serve as bases and cannot be built or listed;

text_embeddings — semantic search over document texts (e.g. PubMed abstracts) with SPECTER2, registered as a function f(query, doc) -> similarity; see neurolang.utils.text_embeddings:

text_embeddings:
  study_abstracts:
    ids_from: study
    source: pubmed          # or {file: ...} or {predicate: ...}
    function: query_similarity

Usage#

from pathlib import Path
from neurolang.utils.engine_registry import (
    build_engine,
    show_engines,
    list_engine_names,
    get_engine_config,
)

# Load engine from the built-in YAML
nl = build_engine("neurosynth", data_dir=Path("data"))

# Load engine from a custom YAML file
nl = build_engine("my_engine", yaml_path=Path("my_engines.yaml"),
                  data_dir=Path("data"))

# Print available engines with descriptions
show_engines()

# List engine names from a custom YAML
for name in list_engine_names(yaml_path=Path("my_engines.yaml")):
    print(name)

Functions

`atlas_activation`(img, label_names, peaks_mm, ...)	Return the `(label, study)` pairs of the studies activating the regions of the atlas image img: one of their peaks is within radius_mm of the centre of a voxel of the region.
`atlas_label_values`(nl, name)	Return the values labelling each region of the atlas name of nl in the image of its grid (`nl.grids[name]`), by region name.
`build_engine`(name, data_dir[, resolution, ...])	Create and populate a `NeurolangPDL` engine from its declarative YAML config.
`engine_bases`(name[, yaml_path])	Return the engines name extends, directly or not, bases first.
`engine_grid_names`(cfg)	Return the names of the grids of the engine cfg.
`get_engine_config`(name[, yaml_path])	Return the YAML configuration dict for a single engine.
`get_hidden_predicates`(name[, yaml_path])	Return the predicates of an engine its SQUALL completion withholds.
`get_predicates`(name[, yaml_path])	Return the predicate metadata dict for an engine from its YAML config.
`get_probabilistic_predicates`(name[, yaml_path])	Return the predicates of an engine declared with a probability.
`get_signatures`(name[, yaml_path])	Return the arguments of the predicates of an engine, by predicate.
`get_sorts`(name[, yaml_path])	Return the sorts an engine declares, by name.
`list_engine_names`([yaml_path])	Return the names of all registered, non-abstract engines.
`read_relation_file`(path)	Return the rows of the CSV or TSV file path as a DataFrame.
`relation_file_separator`(path)	Return the column separator of the relation file path.
`resolve_engine_config`(engines, name[, _stack])	Return the configuration of name with all `extends` resolved.
`show_engines`([yaml_path])	Print a formatted description of all available engines.

Classes

`Argument`(sort, columns[, type])	An argument of a predicate: an entity of a sort over columns.
`Sort`(name, columns[, type, description, ...])	A sort of entities an engine declares once, in its `sorts` section.

Exceptions

UnsupportedRelationFile

Raised for a relation file whose extension is not supported.