Uploading Brain Data with the CLI

The BrainMaps CLI provides powerful tools for uploading brain scan data to the platform. This guide covers the various methods and options for uploading different types of brain scan files.

Supported File Types

The BrainMaps CLI supports these file formats:

• .nii - NIfTI format (Neuroimaging Informatics Technology Initiative)
• .nii.gz - Compressed NIfTI
• .zarr - Zarr format directories (for large multi-dimensional arrays)
• .tif/.tiff - TIFF image format

Prerequisites

Before uploading, ensure you have:

1. Installed and configured the BrainMaps CLI
2. Configured S3 storage credentials
3. Authenticated with brainmaps login

Uploading a Single File

To upload a single file:

brainmaps upload file /path/to/brain_scan.tiff

With Additional Options

brainmaps upload file /path/to/brain_scan.nii.gz \
  --species 5 \            # Specify species ID
  --color "#3366FF" \      # Set visualization color
  --verbose                # Show detailed output

The response will include:

• Upload ID
• Status (should be “completed”)
• File size
• S3 URL

Uploading a ZARR Directory

For Zarr format data (which is directory-based):

brainmaps upload folder /path/to/zarr_directory \
  --species 3 \
  --color "#FF5733"

This will upload the entire directory structure to S3 and register it with the API.

Creating a Brain Entry from Uploads

After uploading files, you’ll typically want to create a Brain entry:

# 1. Find the appropriate species
brainmaps species search "octopus"
 
# 2. Create a brain entry with the uploaded file
brainmaps brain create \
  --name "Octopus Brain Sample 123" \
  --category "cephalopods" \
  --species "octopus vulgaris" \
  --file /path/to/brain_scan.tiff \
  --color "#3366FF" \
  --verbose

The Brain entry will be linked to the uploaded file.

Managing Uploads

List Recent Uploads

brainmaps upload list
# Or specify a limit
brainmaps upload list --limit 20

Get Detailed File Information

brainmaps file get <file-id>

This returns detailed information about the file, including:

• Upload date
• Size
• Status
• Associated brain (if any)
• S3 URL

Advanced Upload Scenarios

Large File Handling

For large files (>1GB), the CLI shows a progress bar by default:

brainmaps upload file /path/to/large_volume.nii.gz

The progress bar displays:

• Upload speed
• Estimated time remaining
• Percentage complete

Uploading Multiple Files

You can use shell scripts to batch upload multiple files:

#!/bin/bash
for file in *.tiff; do
  echo "Uploading $file..."
  brainmaps upload file "$file" --species 7
done

Troubleshooting Uploads

Invalid File Type

If you see an error about invalid file types:

Error: Invalid file type. Supported types: .nii, .nii.gz, .zarr, .tif, .tiff

Ensure your file has one of the supported extensions and is actually in that format.

S3 Upload Errors

For S3 configuration issues:

Error: AWS credentials not found or invalid

Verify your S3 configuration:

brainmaps s3 show

And reconfigure if needed:

brainmaps s3 configure \
  --bucket your-bucket \
  --region your-region \
  --access-key-id your-key \
  --secret-access-key your-secret

Network Issues

For network connectivity problems:

Error: Connection error: Connection refused

Check your network connection and the API URL:

brainmaps config get-api-url

Best Practices

1. Organize files by species for easier batch uploading
2. Use descriptive filenames to identify scan content
3. Check species IDs before upload to ensure correct association
4. Verify successful uploads with brainmaps upload list
5. Use scripts for batch processing of multiple files
6. Set appropriate metadata like species and color during upload

Example: Complete Upload Workflow

# 1. Login
brainmaps login
 
# 2. Search for the correct species
brainmaps species search "human"
# Note the species ID from the results
 
# 3. Upload the brain scan
brainmaps upload file human_brain_frontal.tiff --species 1 --color "#3366FF" --verbose
 
# 4. Verify the upload
brainmaps upload list
 
# 5. Create a brain entry with the uploaded file
brainmaps brain create \
  --name "Human Brain Frontal Section" \
  --category "human" \
  --species "homo sapiens" \
  --file human_brain_frontal.tiff \
  --color "#3366FF"
 
# 6. View the brain entry
brainmaps brain list