api-referenceModels

Data Models

This document describes the core data models in BrainMaps and their relationships.

Overview

BrainMaps uses a hierarchical data structure:

  • Categories contain Species
  • Species contain Brains
  • Brains contain visualization data and metadata

Core Models

Category

Categories group species by type (e.g., ants, birds, cephalopods).

class Category:
    id: int                  # Primary key
    name: str               # Display name (e.g., "Ants")
    description: str        # Optional description
    created_at: datetime    # Creation timestamp
    updated_at: datetime    # Last update timestamp

Species

Species represent individual animal species within a category.

class Species:
    id: int                  # Primary key
    name: str               # Common name (e.g., "House Mouse")
    scientific_name: str    # Scientific name (e.g., "Mus musculus")
    description: str        # Optional description
    category: Category      # Foreign key to Category
    created_at: datetime    # Creation timestamp
    updated_at: datetime    # Last update timestamp

Brain

Brain objects store individual brain scans and their metadata.

class Brain:
    id: int                  # Primary key
    name: str               # Display name
    description: str        # Optional description
    date_uploaded: datetime # Upload timestamp
    image: FileField        # Reference image file
    website: URLField       # Optional website link
    verified: bool         # Verification status
    atlas: ForeignKey      # Reference to Atlas model
    category: ForeignKey   # Reference to Category model
    uploader: ForeignKey   # Reference to User model
    uuid: UUIDField        # Unique identifier
    zarr_file: FileField   # Path to Zarr file
    is_reference: bool     # Whether this is a reference brain
    extra_link: URLField   # Additional external link
    readable_id: str       # Human-readable unique identifier
    s3_url: str           # URL to S3 storage

FileUpload

Tracks file uploads and their processing status.

class FileUpload:
    id: int                  # Primary key
    name: str               # File name
    date_uploaded: datetime # Upload timestamp
    uploader: ForeignKey    # Reference to User model
    file: FileField        # Uploaded file
    status: str            # Status (uploaded/processing/completed/failed)
    processing_started: datetime  # When processing began
    processing_completed: datetime # When processing finished
    error_message: str     # Error details if failed
    metadata: JSONField    # Additional metadata
    file_size_kb: float   # File size in kilobytes
    file_size_mb: float   # File size in megabytes
    associated_brain: ForeignKey # Link to Brain model

User

User accounts for authentication and data management.

class User:
    id: int                  # Primary key
    email: str              # Email address (unique)
    first_name: str         # First name
    last_name: str          # Last name
    is_active: bool        # Account status
    is_staff: bool         # Admin status
    date_joined: datetime  # Registration date
    avatar: str            # Profile image URL

Relationships

One-to-Many

  • Category → Species
  • Species → Brains
  • User → Brains
  • User → FileUploads
  • Brain → FileUploads

Many-to-One

  • Species → Category
  • Brain → Species
  • Brain → User
  • Brain → Atlas
  • FileUpload → User
  • FileUpload → Brain (optional)

Field Types

Common Fields

  • id: Auto-incrementing primary key
  • created_at: Automatically set on creation
  • updated_at: Automatically updated on changes
  • name: String, usually required
  • description: Optional text field

Special Fields

  • uuid: Unique identifier for each brain
  • readable_id: Human-readable unique identifier (e.g., “elegant-pangolin”)
  • scientific_name: Follows binomial nomenclature
  • verified: Boolean for content verification
  • s3_url: URL to cloud storage
  • zarr_file: Path to Zarr dataset
  • file_size_mb: Automatically calculated file size

Validation

FileUpload

  • File extension must be one of: .nii, .nii.gz, .zarr, .tif, .tiff
  • File size is automatically calculated
  • Status transitions: uploaded → processing → completed/failed

Brain

  • Must have either zarr_file or s3_url
  • Readable ID is automatically generated
  • UUID is automatically generated
  • Category is set based on atlas

User

  • Email must be unique
  • Password strength requirements
  • Valid email format

API Serialization

Models are serialized to JSON for API responses:

{
  "brain": {
    "id": 1,
    "readable_id": "elegant-pangolin",
    "name": "Sample Brain",
    "species": {
      "id": 1,
      "name": "House Mouse",
      "scientific_name": "Mus musculus",
      "category": {
        "id": 3,
        "name": "Rodents"
      }
    },
    "uploader": {
      "id": 1,
      "email": "researcher@example.com",
      "name": "John Doe"
    },
    "date_uploaded": "2023-12-22T12:00:00Z",
    "verified": true,
    "s3_url": "https://storage.example.com/brain1.tiff"
  }
}

Database Indexes

Recommended indexes for performance:

  • Species.scientific_name
  • Brain.readable_id
  • Brain.species_id
  • Brain.uploader_id
  • FileUpload.uploader_id

Usage Examples

Creating a New Brain Entry

brain = Brain.objects.create(
    name="Mouse Brain Sample 1",
    species=Species.objects.get(scientific_name="Mus musculus"),
    uploader=request.user,
    s3_url="https://storage.example.com/brain1.tiff",
    verified=False
)

Querying Related Data

# Get all verified brains for a species
verified_brains = Brain.objects.filter(
    species__scientific_name="Mus musculus",
    verified=True
)
 
# Get all brains in a category
category_brains = Brain.objects.filter(
    species__category__name="Rodents"
)
EndpointsTokens
BrainMaps Documentation