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
syndbcommand-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.