neurolang.utils.engine_registry#

Declarative engine registry for the neurolang-query CLI.

Engines are declared in engines/engines.yaml, into whose entries the files engines/<engine>/*.yaml (their example queries and the query assistant’s guidance) are merged with OmegaConf. Each engine may define:

  • Python initialisation scripts (python_init): a module name, or a list of them, whose init_engine(nl, mask, data_dir, **options) run in order, each given all the keyword arguments of python_init_options (an init_engine takes **options for those of the others);

  • 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}.

  • resamplings — replicates of a probabilistic choice for confidence intervals, name: {choice: selected_study, n: 1000, scheme: bayesian, seed: 0}, used as RESAMPLE[name](pred(x)) = b (see add_resampling()).

  • atlases — brain atlases downloaded via nilearn (e.g. destrieux, schaefer, difumo) and registered as predicates with ExplicitVBR regions. Deterministic atlases are Atlas objects, fetched as .load_atlas(name, kind=...) fetches them, added by add_atlas_set and recorded in the engine’s atlases; 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;

  • solver_mixins — classes, as "module:Class" strings, put before the solver of the engine’s NeurolangPDL (the classes of dimension_type_predicates after them), e.g. pattern-matching mixins adding Datalog commands .name(...); inherited parent first;

  • text_embeddings — semantic search over document texts (e.g. PubMed abstracts) with SPECTER2, registered as a function f(query, doc) -> similarity, with f_cutoff(query) the 95th percentile of the similarities to the query, or inf if the mean of its 20 largest is below similarity_gate (0.75 by default); see neurolang_apps.utils.text_embeddings:

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

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_colours(nl, name)

Return the colour, #rrggbb, of each value labelling a region of the atlas name of nl in the image of its grid, as its authors coloured it; {} for an atlas without colours.

atlas_coverage(img, label_names, peaks_mm, ...)

Return how much the studies cover the regions of the atlas image img, the rows (probability, label, study) of at least threshold.

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.

cached_atlas_activation(cache_dir, img, ...)

Return the pairs of atlas_activation(), kept in cache_dir, as a frame of label and study (read as arrays, not rebuilt as a list of tuples).

cached_atlas_coverage(cache_dir, img, ...[, ...])

Return the rows of atlas_coverage(), kept in cache_dir as the pairs of cached_atlas_activation() are, by what they depend on.

embeddings_owner(name, entry[, yaml_path])

Return the engine whose embeddings directory holds the caches of the text_embeddings entry entry of the engine name: the most basic non-abstract engine of its extends chain, itself included, whose resolved entry is the same.

engine_grid_names(cfg)

Return the names of the grids of the engine cfg.

get_acknowledgements(name[, yaml_path])

Return the acknowledgements of the data of an engine (its own and those of the engines it extends): a text per source, with its citation.

get_engine_config(name[, yaml_path])

Return the YAML configuration dict for a single engine.

get_euclidean_join_settings(name[, yaml_path])

Return the settings of the Euclidean join an engine changes.

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.

kernel_radius_voxels(cfg, mask)

Return the kernel_radius_mm of the engine configuration cfg in voxels of the grid of mask, whose voxels are cubes.

list_engine_names([yaml_path])

Return the names of all registered, non-abstract engines.

read_relation_file(path[, data])

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)

Return the configuration of name with all extends resolved: the configurations of its bases and its own, merged in the order of _linearized().

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.