Group Analysis #

Deprecated Workflow

Performing group analysis by querying product.json records through raw local scripts has been deprecated and superseded by in-platform Group Analysis.

To perform statistical analyses, profile averages, and visualizations directly on brainlife.io without downloading data to your local machine, please see our dedicated guide:

👉 In-Platform Group Analysis Guide

Overview #

Historically, Brainlife allowed users to download condensed textual data derivatives (product.json) using the REST API to conduct group analysis locally in Matlab or Python.

Today, Brainlife provides a built-in Group Analysis notebook environment directly within each project on brainlife.io:

Integrated JupyterLab: Launch interactive Python 3 (brainlife/ga-python) or Octave/Matlab (brainlife/ga-octave) notebooks directly from the Analyses tab in your project.
Direct Data Access: Notebooks run directly on connected compute resources with access to all project data objects without requiring manual download scripts.
Reproducibility: Analysis code and notebooks can be archived alongside project publications.

Programmatic API Access (Legacy / Advanced) #

If you are building external automated pipelines or custom services that need to query dataset metadata and product.json output summaries directly from the Brainlife warehouse API, you can authenticate using your Brainlife JWT token.

1. Authentication #

The Brainlife CLI stores your current authentication token in:

bash

~/.config/brainlife.io/.jwt

You can generate or refresh this token using:

bash

bl login --ttl 30

2. Python Example (Warehouse API Query) #

python

#!/usr/bin/env python3
import os
import json
import requests

# Load the JWT token generated by 'bl login'
jwt_path = os.path.expanduser('~/.config/brainlife.io/.jwt')
with open(jwt_path, 'r') as f:
    jwt = f.read().strip()

headers = {
    'Authorization': f'Bearer {jwt}',
    'Content-Type': 'application/json'
}

# Define search parameters for the warehouse API
# Replace 'YOUR_PROJECT_ID' and 'YOUR_DATATYPE_ID' with valid Brainlife IDs
find_query = {
    'project': 'YOUR_PROJECT_ID',
    'datatype': 'YOUR_DATATYPE_ID',
    'removed': False
}

params = {
    'limit': 100,
    'select': 'product meta tags',
    'find': json.dumps(find_query)
}

url = 'https://brainlife.io/api/warehouse/dataset'
res = requests.get(url, params=params, headers=headers)

if res.status_code == 200:
    data = res.json()
    datasets = data.get('datasets', [])
    print(f"Found {len(datasets)} dataset records.")
    for d in datasets:
        subject = d.get('meta', {}).get('subject', 'unknown')
        print(f"Dataset {d['_id']} - Subject: {subject}")
else:
    print(f"Failed to query datasets: {res.status_code} - {res.text}")

3. Recommended Alternative: Brainlife CLI #

To inspect and download datasets locally from the command line, use the native bl CLI commands instead of writing custom API queries:

To query datasets:
bash
```
bl data query --project  --subject 
```

To download datasets in BIDS format:

bash

bl bids download --project  --output ./bids_output

To download individual datasets:
bash
```
bl data download -i 
```

For full details on using the CLI, visit CLI Installation and Downloading Data.