Managing Brain Data with the CLI

The BrainMaps CLI provides comprehensive tools for managing brain data entries in the platform. This guide covers how to list, create, update, and delete brain entries, as well as how to filter and view brain data.

What is a Brain Entry?

In BrainMaps, a “brain” is a record that represents a brain scan dataset along with its metadata. Brain entries include:

Name and description
Species and category information
Associated file upload(s)
Visualization settings
Reference information (optional)

Listing Brain Entries

To view all available brain entries:

brainmaps brain list

This returns a table of all brain entries you have access to.

Filtering Options

You can filter the list of brains by various criteria:

# Filter by category
brainmaps brain list --category "cephalopods"
 
# Filter by species
brainmaps brain list --species "octopus vulgaris"
 
# Combine filters
brainmaps brain list --category "primates" --species "homo sapiens"

Example Output

Available Brain Data:

ID    | Name                   | Category    | Species            
------+------------------------+-------------+--------------------
1     | Human Cortex Sample    | primates    | Homo sapiens       
2     | Octopus Brain Slice    | cephalopods | Octopus vulgaris   
3     | Mouse Hippocampus      | rodents     | Mus musculus

Getting Detailed Brain Information

To get detailed information about a specific brain entry:

brainmaps brain get <brain-id>

This returns comprehensive information about the brain entry, including visualization settings, file information, and more.

Example Output

{
  "id": 2,
  "name": "Octopus Brain Slice",
  "description": "Frontal section of adult octopus brain",
  "date_uploaded": "2023-12-21T14:30:45Z",
  "species": {
    "id": 3,
    "name": "octopus",
    "scientific_name": "Octopus vulgaris"
  },
  "category": {
    "id": 7,
    "name": "cephalopods"
  },
  "color": "#3366FF",
  "verified": false,
  "file_uploads": [
    {
      "id": "a1b2c3d4",
      "name": "octopus_brain.tiff",
      "status": "completed",
      "file_size_mb": 123.45,
      "s3_url": "https://example-bucket.s3.region.amazonaws.com/uploads/octopus_brain.tiff"
    }
  ],
  "uploader": {
    "id": 1,
    "username": "researcher1"
  },
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Creating a Brain Entry

To create a new brain entry:

brainmaps brain create \
  --name "Mouse Cerebellum" \
  --category "rodents" \
  --species "mus musculus" \
  --file /path/to/mouse_cerebellum.tiff \
  --color "#FF5733" \
  --verbose

Required Parameters

--name: Name of the brain dataset
--category: Category of the brain
--species: Species ID or name
--file: Path to the brain image file to upload

Optional Parameters

--color: Color for visualization (hex format)
--verbose: Show detailed output including API responses

Updating a Brain Entry

To update an existing brain entry:

brainmaps brain update <brain-id> \
  --name "Updated Brain Name" \
  --category "new-category" \
  --species "new-species"

You can update any combination of the following:

--name: New name for the brain
--category: New category
--species: New species

Deleting a Brain Entry

To delete a brain entry:

brainmaps brain delete <brain-id>

You will be prompted to confirm the deletion. This operation cannot be undone and will also delete any associated file uploads.

Example Workflows

Creating a Brain Entry from an Existing Upload

If you’ve already uploaded a file:

# 1. List your uploads to find the file
brainmaps upload list
 
# 2. Create a brain entry referencing the existing file
brainmaps brain create \
  --name "Rat Brain Section" \
  --category "rodents" \
  --species "rattus norvegicus" \
  --file rat_brain.tiff

Complete Brain Management Workflow

# 1. List available species
brainmaps species list
 
# 2. Upload a brain file
brainmaps upload file zebrafish_brain.tiff --species 5
 
# 3. Create a brain entry
brainmaps brain create \
  --name "Zebrafish Brain" \
  --category "fish" \
  --species "danio rerio" \
  --file zebrafish_brain.tiff \
  --color "#33AAFF"
 
# 4. List brains to verify creation
brainmaps brain list
 
# 5. Get details of the new brain
brainmaps brain get <brain-id>
 
# 6. Update the brain information
brainmaps brain update <brain-id> --name "Adult Zebrafish Brain"

Best Practices

Use descriptive names that clearly identify the brain sample
Include species information for proper categorization
Choose appropriate colors for better visualization
Verify uploads before creating brain entries with upload list
Check existing brains to avoid duplicates
Use the verbose flag when troubleshooting issues

CLI Species Management Uploading Brains