Get Started with NeuroLang#
First Steps With NeuroLang#
NeuroLang is a unifying formalism to perform complex queries and explorations using heterogeneous data sources like tabular data, volumetric images, and ontologies. To perform this in a sound manner, NeuroLang is a probabilistic logic programming language based on Datalog [abiteboul1995], [maier2018].
The examples of this page run in the REPL, in the browser or in a terminal
(Using the REPL), on the neurosynth engine: type them at the prompt, or
follow Run in the browser REPL under each one. They use the Destrieux
atlas of the engine, destrieux(label, region), whose labels are written
"L G front sup" (left superior frontal gyrus) or "R S central" (right
central sulcus).
Note
To write the same rules in Python, see NeuroLang in Python.
The whole idea of logic programming is to be able to make assertions of the style:
region x is a left hemisphere gyrus if the label of x in Destrieux et al’s atlas starts with “L G”.
which can be formalised in first order logic as
which, if we assume that \(x\) being on Destrieux et al’s atlas means that \(x\) is already a region, can be shortened as
Finally, for notation convenience, we will drop the quantifiers, assuming that all variables on the left of the arrow (such as \(x\)) are universally quantified, and all variables appearing only on the right of the arrow (such as \(l\)) will be existentially quantified [maier2018]. This leads to the expression
which is written in NeuroLang, :- standing for the arrow and & for
the conjunction, and keeping the label rather than the region:
left_hemisphere_gyrus(l) :- destrieux(l, x) & startswith("L G", l)
The REPL answers defined left_hemisphere_gyrus/1: the rule is in the
session. A query, whose head is ans, asks for its rows:
ans(l) :- left_hemisphere_gyrus(l)
╭────────────────────────────╮
│ l │
├────────────────────────────┤
│ L G and S frontomargin │
│ L G and S occipital inf │
│ L G and S paracentral │
│ … │
╰────────────────────────────╯
38 rows · showing 1–20 · .more for next
Negation can also be used in NeuroLang, through the ~ operator. For
instance, the labels of the atlas which are not left hemisphere gyri are
not_left_hemisphere_gyrus(l) :- destrieux(l, x) & ~left_hemisphere_gyrus(l)
Note that every variable of a negated atom must also appear in a positive atom
of the same rule (here l is bound by destrieux).
Disjunctions in Logic Programming#
Disjunctions in logic programming merit a specific discussion. For instance, let’s say that all the regions in the left hemisphere’s cortex are either a sulcus or gyrus, or more specifically
x is a left hemisphere region if x is left sulcus or x is left gyrus
which in first order logic can be formalised as
alternatively, this can be written as a set of two propositions
which we write in NeuroLang as two rules of the same head, with the left sulci defined as the gyri were:
left_hemisphere_sulcus(l) :- destrieux(l, x) & startswith("L S", l)
left_hemisphere_region(l) :- left_hemisphere_sulcus(l)
left_hemisphere_region(l) :- left_hemisphere_gyrus(l)
or in a less verbose manner, with |:
left_hemisphere_region(l) :- left_hemisphere_sulcus(l) | left_hemisphere_gyrus(l)
The second form defines the same relation; typed after the first, it adds
rules of the same meaning, which change nothing. .idb lists the rules of
the session, and .drop left_hemisphere_region removes them.
Aggregations#
Aggregations combine information from a set of tuples. A good example of an aggregation is the maximum. As a mathematical definition we could define an aggregation as
which in NeuroLang is expressed as a rule whose head applies the aggregation to a variable of its body:
max_population_per_country(country, max(pop)) :- population_per_country_province(country, province, pop)
On the engine, destrieux_activated(label, study) holds the regions that
the peaks of each study fall in; the number of studies activating each region
is a count:
studies_per_region(l, count(s)) :- destrieux_activated(l, s)
ans(l, n) :- studies_per_region(l, n)
and .sort n:desc puts the regions most often activated first:
╭─────────────────────────────┬──────╮
│ l │ n │
├─────────────────────────────┼──────┤
│ L G front sup │ 6939 │
│ R G front sup │ 6389 │
│ R G front middle │ 4953 │
│ L G front middle │ 4892 │
│ … │ │
╰─────────────────────────────┴──────╯
148 rows · showing 1–20 · .more for next
The next steps are Datalog: A Rule-Based Query Language for NeuroLang, the whole language through a complete analysis of the literature, and Using the REPL, the REPL itself.
Abiteboul, S., Hull, R. & Vianu, V. Foundations of databases. (Addison Wesley, 1995).