Managing Species with the BrainMaps CLI

The BrainMaps CLI provides commands to help you work with species data in the platform. This guide covers how to list, search, and retrieve species information - essential for properly categorizing and organizing brain scans.

Why Species Matter

Every brain scan in BrainMaps is associated with a species. Using the correct species when uploading or creating brain entries ensures:

• Proper categorization and searchability
• Correct display in the user interface
• Appropriate atlas associations
• Accurate scientific record-keeping

Listing Available Species

To view all species available in the platform:

brainmaps species list

This returns a list of all species with their IDs, names, and scientific names.

Example Output

Available Species:
+----+----------------+--------------------+-------------------------+
| ID | Name           | Scientific Name    | Category                |
+----+----------------+--------------------+-------------------------+
| 1  | human          | Homo sapiens       | primates                |
| 2  | mouse          | Mus musculus       | rodents                 |
| 3  | octopus        | Octopus vulgaris   | cephalopods            |
| 4  | rat            | Rattus norvegicus  | rodents                 |
| 5  | zebrafish      | Danio rerio        | fish                    |
+----+----------------+--------------------+-------------------------+

Searching for Species

To find specific species by name:

brainmaps species search "octopus"

This performs a case-insensitive search for any species with “octopus” in the name or scientific name.

Search Tips

• You can search for partial names: brainmaps species search "oct"
• The search covers both common and scientific names
• Multiple words are treated as separate search terms
• Results are sorted by relevance

Getting Detailed Species Information

To get detailed information about a specific species:

brainmaps species get 3  # Using ID

Or:

brainmaps species get "octopus vulgaris"  # Using scientific name

Example Output

{
  "id": 3,
  "name": "octopus",
  "scientific_name": "Octopus vulgaris",
  "description": "The common octopus is the most studied of all octopus species.",
  "category": {
    "id": 7,
    "name": "cephalopods",
    "description": "Includes octopuses, squids, cuttlefish, and nautiluses."
  },
  "brains_count": 12,
  "has_official_atlas": true
}

Using Species in Other Commands

Many BrainMaps CLI commands accept species IDs or names:

When Uploading Files

brainmaps upload file octopus_brain.tiff --species 3

When Creating Brain Entries

brainmaps brain create \
  --name "Octopus Brain Sample" \
  --category "cephalopods" \
  --species "octopus vulgaris" \
  --file octopus_brain.tiff

When Filtering Brain Lists

brainmaps brain list --species "octopus vulgaris"

Working with Categories

Species in BrainMaps are organized into categories. You can see the category information when listing or getting species details.

Common categories include:

• primates
• rodents
• cephalopods
• fish
• birds
• reptiles

Command Aliases

For convenience, you can use the spec alias instead of species:

brainmaps spec list
brainmaps spec search "mouse"
brainmaps spec get 2

Best Practices

1. Always verify species before upload - Use species search to find the correct species
2. Use scientific names for precision - Scientific names avoid ambiguity
3. Note species IDs for scripting - Using IDs in scripts is more reliable than names
4. Check for existing brains of the same species - See what’s already in the system

Example Workflow: Finding and Using the Right Species

# 1. Search for species related to "squid"
brainmaps species search "squid"
 
# 2. Get detailed information about a specific result
brainmaps species get 8  # Assuming the ID from search results
 
# 3. Use the species in an upload
brainmaps upload file squid_brain.tiff --species 8
 
# 4. Create a brain entry with this species
brainmaps brain create \
  --name "Giant Squid Brain Section" \
  --category "cephalopods" \
  --species 8 \
  --file squid_brain.tiff