Using the REPL#

NeuroLang is used by typing queries into a REPL: a prompt that runs each statement as it is entered and shows its result. The same REPL runs in two places:

in the browser, at the REPL page, with nothing to install;
in a terminal, as neurolang-query -i, with all the engines and their precomputed analyses, files on your disk, and scripts.

Both take the same statements and the same dot-commands, so every example of this documentation runs in either. Under each one, Run in the browser REPL opens the page with the example in its box; press Run, or type it in a terminal.

Starting it #

In the browser

Open the REPL page. The first start takes about 30 s: the browser loads Python, NeuroLang and the engine’s data, and keeps them for the next visit. The selector at the top of the page chooses the engine; the address can name it too, as index.html?engine=neurosynth.

The engine of the page leaves out the precomputed analyses (lift, relative_risk, uniformity, ratios): they need several GB, more than a browser tab is given. ?engine=full builds them on a machine with the memory.

In a terminal

Install the applications (see Installing NeuroLang), then start the REPL on an engine:

pip install "neurolang[apps]"
neurolang-query -i --engine neurosynth

The first start downloads the engine’s data into neurolang_data (--data-dir puts it elsewhere) and takes a few minutes; later starts build the engine from it, in well under a minute. neurolang-query --list-engines lists the engines; --resolution 2 builds the voxel relations at 2 mm.

The REPL greets you with the engine’s relations and an example to try:

ans(s) :- mentions(s, "pain")

Run in the browser REPL

╭──────────╮
│ s        │
├──────────┤
│  9862924 │
│ 10601675 │
│ …        │
╰──────────╯
516 rows · showing 1–20 · .more for next
Query completed in 1.30 s

The answer is a table: here the PubMed ids of the 516 studies of Neurosynth that mention pain. In the browser, the table can be sorted, filtered and downloaded.

Statements #

A statement is a rule, a fact, a query or a dot-command. A rule defines a relation; a query, whose head is ans, asks for one:

pain_study(s) :- mentions(s, "pain")
ans(s) :- pain_study(s) & mentions(s, "memory")

Run in the browser REPL

A % starts a comment, to the end of the line. Get Started with NeuroLang introduces the rules, and Datalog: A Rule-Based Query Language for NeuroLang the whole language; .mode squall switches to SQUALL, controlled English (SQUALL: Controlled English for NeuroLang).

In the browser

The box takes as many statements as you like, on as many lines; Run (or Ctrl+Enter) runs them in order.

In a terminal

Enter runs a statement. One left unfinished (an open bracket, a trailing , or :-) continues on the next line, and an empty line runs it; Alt+Enter inserts a newline. Tab completes commands, relations and their columns; the arrows and Ctrl+R go through the history.

The session #

The rules you define stay for the rest of the session, so that a query can use the rules of earlier statements. One exception: rules that come in the same submission as a query (in the browser, in the same box; in a terminal, in the same file) belong to that query and are discarded after it, so that the next query can define rules of the same names. .scope off keeps them too.

Command	What it does
`.idb [PREDICATE]`	lists the relations defined in the session, or the numbered rules of one
`.drop PREDICATE [N]`	removes rule `N` of a relation, all its rules, or a loaded relation
`.clear [PREDICATE]`	clears what the session defined, or one relation
`.scope [on\|off]`	keeps the rules of a query local to it (on, the default), or in the session

In the browser, Save session writes the session’s rules to a file and Open session defines them again; facts typed in the session are not in it.

The engine’s data #

An engine is a set of relations built from a dataset: the studies of Neurosynth with the terms they mention and the peaks they report, brain atlases, an ontology. .predicates lists them with their columns, and .sets the stored ones; in the browser, Examples and relations lists them too, each with its documentation. Engine Configuration (engines.yaml) describes the engines and how to make one.

Your own data#

Facts are typed as statements without a body:

liked("pain")
liked("memory")
ans(t) :- liked(t)

Run in the browser REPL

In a terminal, .load PATH [NAME] reads a CSV or TSV file (optionally gzipped) into a relation whose columns are the file’s header:

nl(neurosynth:DL)> .load my_terms.csv my_terms
loaded my_terms(term, group): 2 rows from my_terms.csv

Results #

Command	What it does
`.sort [COL[:asc\|desc] ...\|none]`	sorts the results, e.g. `.sort n:desc`
`.head [N]`, `.more`, `.all`	sets the page size, shows the next page, or every row
`.format [table\|csv\|json]`	prints the results as a table, CSV or JSON
`.save PATH`	saves the last result as CSV or TSV, or as a NIfTI image for a `.nii` or `.nii.gz` path (`.help save`)
`.view`	shows the last result, or a NIfTI file, in a brain viewer (`.help view`)
`.graph`	shows where the answer of the last query comes from: its data, rules and probabilities, as a graph

In the browser, the result is a table to sort, filter and download (CSV, TSV, or NIfTI for voxels), with tabs for the brain viewer and the graph.

The query assistant #

.ask QUESTION writes a query answering a question in English with a large language model, and .explain reads the last query in English; see LLM Query Assistant. In the browser, the box above the code takes the question, with your own API key.

Scripts and transcripts #

A terminal session can start from a file of statements, or be one:

neurolang-query -i --engine neurosynth --file rules.dl   # then the prompt
neurolang-query -i --engine neurosynth < session.dl      # runs it and exits

The second form runs the file statement by statement, as if typed, and exits with status 1 if one failed. .transcript PATH writes the session as Markdown, or, with --inputs, as such a file. A single query can also run without the REPL: see Appendix B: Querying from the Command Line.

Every command #

.help lists them in the REPL, and .help TOPIC tells more about save, view, feedback and squall.

Command	What it does	Where
`.help [squall\|TOPIC]`	this help, a primer on SQUALL, or help on a topic	both
`.mode datalog\|squall\|vi\|emacs`	the query language, or the editing keys of the terminal	both
`.sort`, `.more`, `.head`, `.all`, `.format`	how the results are shown (see Results)	both
`.save PATH`	the last result in a file (see Results)	terminal; the browser has its download menu
`.view`, `.graph`	the last result in the brain viewer, or as a graph (see Results)	both
`.idb`, `.drop`, `.clear`, `.scope`	the session’s rules (see The session)	both
`.load PATH [NAME]`	a CSV or TSV file as a relation	terminal
`.sets`, `.predicates`, `.engines`	the engine’s relations, and the engines	both
`.datalog [PREDICATE]`	the Datalog of the last SQUALL query, or the rules of a relation	both
`.rewritten [on\|off]`, `.ra [on\|off]`	the program as rewritten for the solver, and its relational algebra plans (see Appendix B: Querying from the Command Line)	both
`.ask`, `.explain`, `.llm`, `.rate`, `.refine`	the query assistant (see LLM Query Assistant)	both
`.transcript PATH`	the session as Markdown or as a script	terminal
`.import("m.dl")`	a Datalog module, once	both
`.name(...)`	any other: a command of the engine, as `.load_csv(name, "url")`	both
`.quit`, `.exit`	leaves the REPL (also Ctrl+D)	terminal