Download via MATLAB

MATLAB scripts for downloading data from XNAT, integrating seamlessly with MATLAB analysis workflows.

Overview

MATLAB scripts provide automated data download capabilities within the MATLAB environment, ideal for researchers who work primarily in MATLAB and want to integrate data retrieval with their analysis pipelines.

Available Scripts

The matlab-example folder contains three main MATLAB scripts:

1. Environment Setup (setup_xnat_env.m)

Creates and configures a conda environment with required Python packages.

2. Download Function (downloadXNAT.m)

Main download function that handles DICOM files and session resources.

3. Example Usage (run_download.m)

Demonstrates configuration and usage patterns.

Setup Instructions

1. Prerequisites

  • MATLAB installed

  • Miniconda or Anaconda installed

  • Network access to XNAT server

2. Get Template Scripts

git clone https://github.com/XNAT-NYUAD/template-scripts.git
cd template-scripts/matlab-example

3. Environment Setup

Run this once to create the Python environment:

setup_xnat_env;

This creates a conda environment named xnat_env with required Python packages.

4. Configure Authentication

Edit run_download.m and update:

config.api_token_id = 'your_token_alias';
config.api_token_secret = 'your_token_secret';
config.project_id = 'your_project_id';

Basic Usage

Download DICOM Files

% Configure XNAT connection
config = struct();
config.server_url = 'https://xnat.abudhabi.nyu.edu/';
config.api_token_id = 'your_alias';
config.api_token_secret = 'your_secret';
config.project_id = 'your_project';

% Download specific subject/session
status = downloadXNAT('config', config, ...
                     'subjects', {'sub-001'}, ...
                     'sessions', {'ses-01'});

Download Session Resources

% Download processed data (e.g., 'rawdata' folder)
status = downloadXNAT('config', config, ...
                     'subjects', {'sub-001'}, ...
                     'sessions', {'ses-01'}, ...
                     'resource', 'rawdata');

Test Mode

% Test connection without downloading
status = downloadXNAT('config', config, ...
                     'test', true);

Function Parameters

The downloadXNAT function accepts these parameters:

  • config (required): Struct with server and authentication settings

  • subjects: Cell array of subject IDs to download

  • sessions: Cell array of session IDs to download

  • resource: Specific resource name (e.g., ‘rawdata’, ‘BIDS’)

  • test: Boolean flag for test mode (no actual download)

Output Structure

Downloads are organized in the script directory:

matlab-example/
├── downloads/           # Downloaded data
│   ├── session-ses-01/
│   └── session-ses-02/
└── logs/               # Download logs
    ├── download.log
    └── download_complete

Configuration Options

Server Configuration

config.server_url = 'https://xnat.abudhabi.nyu.edu/';
config.api_token_id = 'your_alias';
config.api_token_secret = 'your_secret';
config.project_id = 'your_project';

Download Options

  • Download entire sessions (DICOM files)

  • Download specific resources (processed data)

  • Test connections before downloading

  • Filter by subject and session IDs

Integration with Workflows

Example Analysis Pipeline

% 1. Download data
status = downloadXNAT('config', config, ...
                     'subjects', {'sub-001'});

% 2. Process downloaded data
if status == 0
    dataPath = fullfile(pwd, 'downloads', 'session-ses-01');
    % Add your analysis code here
    dicomFiles = dir(fullfile(dataPath, '**', '*.dcm'));
    % Process DICOM files...
end

Security Best Practices

  • Store API tokens securely, never in version control

  • Use project-specific tokens when possible

  • Regularly rotate API tokens

  • Test with limited data first

Troubleshooting

Conda Environment Issues

Run setup_xnat_env again or check conda installation.

Authentication Errors

Verify API token alias and secret are correct and haven’t expired.

Download Failures

Check project access permissions and network connectivity.

Python Environment Problems

Ensure conda is properly installed and accessible from MATLAB.

Next Steps