Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started for researchers

This page takes you from a biological question to a table of numbers. You need a browser; nothing has to be installed.

Important

Repository access

The syndb command-line tool and the Python client are not published packages yet. Both live in the private SynDB repository, so you need read access granted on request before you can install either. The web app at app.syndb.xyz and the public HTTP API at api.syndb.xyz need no account and no repository access. Get help explains how to request it.

1. Sign in

Open app.syndb.xyz and pick one:

  • Sign in with your institution (CILogon), or
  • Sign in with GitHub.

Either one creates your account and marks it as an academic account in the same step, so there is no separate verification email to wait for. SynDB does not offer email sign-up or passwords, and there is no password to reset: your identity stays with the provider. Details are in Authentication.

Reading metadata and the public API works without signing in. Running a query, graph analysis, meta-analysis or an upload needs the academic account.

2. Find datasets

In the web app, type a species, dataset label or DOI into the search box and open a result. Each dataset page shows its species, microscopy, licence, and the tables it contains with their row counts.

The same list is available as JSON, with no account:

curl https://api.syndb.xyz/v1/neurodata/datasets

That returns an ID-to-label map. One level down is per-dataset metadata, including species, licence and the tables the dataset carries:

curl https://api.syndb.xyz/v1/neurodata/datasets/676f5945-b47e-5ed9-9279-401342059449

Hemibrain v1.2.1 is 676f5945-b47e-5ed9-9279-401342059449. Every dataset has a stable ID of this form; use it in queries.

3. Check what the columns mean

Column names are only useful with their units. Tables, columns and units lists every table, its columns, and the unit each column is in — or says “unit: to be confirmed” when the project has not fixed one yet.

4. Run a query

Open the Query page, paste a SyQL query, and press Explain query to check it, then Execute query to run it as a job. The job page shows the job status; when it finishes, Download result gives an Arrow IPC file.

A full walk-through in six browser steps, no installation: Worked example: read a dataset page.

5. Python client (requires repository access)

The client is not on PyPI yet. From a SynDB checkout (Python 3.10 or newer):

pip install ./packages/client

or, with repository access, pip install "git+ssh://git@github.com/memorycircuits/SynDB.git#subdirectory=packages/client".

The client reads the token that syndb auth login stored (see section 6); you can also pass SYNDB_AUTH_TOKEN in the environment.

import syndb_client

hemibrain = "676f5945-b47e-5ed9-9279-401342059449"
neurons = syndb_client.table(hemibrain, "neurons")
synapses = syndb_client.table(hemibrain, "synapses")

Tables arrive as Polars DataFrames, streamed over Arrow Flight.

syndb_client.query runs any SyQL query on the server, so only the result is transferred:

out_degree = syndb_client.query(f"""
SELECT pre_neuron_id, sum(synapse_count) AS synapses_out
FROM synapses
WHERE dataset_id = '{hemibrain}'
GROUP BY pre_neuron_id
ORDER BY synapses_out DESC
LIMIT 100
""")

syndb_client.corpus_status() returns the public corpus counts without a token.

6. Command line interface (requires repository access)

With a SynDB checkout and read access:

cargo run -p cli --features full -- --help

Log in through GitHub:

cargo run -p cli --features full -- auth login github

For brevity the rest of this section writes syndb. From a checkout that is cargo run -p cli --features full --, and after cargo build -p cli --features full it is ./target/debug/syndb.

The browser opens, you sign in, and you paste the JSON token block that the browser shows back into the terminal. The token is saved to ~/.config/syndb/auth.json.

syndb api datasets and syndb api corpus print the public catalogue without a login; syndb query exec "<syql>" submits a SyQL query as a job. The full command set is in the CLI reference.

7. Cite and acknowledge

Cite SynDB itself and every dataset you used; the citing guide has copy-paste entries. Check the data-use terms before you publish results, and read each dataset’s own licence: it governs the data, not SynDB’s licence.

If something does not work, Get help.