Datamodel for Surgical Information in the Brain (And Elsewhere?!) + Imaging Properties

[jmdelahanty]

Hey everyone!

I was chatting with @sneakers-the-rat over Twitter a little bit ago and was discussing how to store weights in a useful/easily accessible way. They showed me how to do it really nicely using whatever serialization format I wanted! Here was an example they sent along for posterity:

from typing import TypedDict, List
from dataclasses import dataclass
import yaml # or json if you want that!
from datetime import datetime
from pathlib import Path


# Type hinting for the win
class Weight(TypedDict):
    timestamp: datetime
    value: float

@dataclass
class Weights:
    id: str
    """subject ID"""
    weights: List[Weight]

    def append(self, weight:Weight):
        if not isinstance(weight, Weight):
            weight = Weight(**weight)
        self.weights.append(weight)

    @classmethod
    def from_yaml(cls, path:Path) -> 'Weights':
        # ensure path type
        path = Path(path)
        # get id from file name?
        id = path.stem
        # load yaml file
        with open(path, 'r') as yfile:
            weights = yaml.safe_load(yfile)

        weights = [Weight(**w) for w in weights]

        return Weights(id=id, weights=weights)

    def to_yaml(self, directory:Path=Path('.')):
        directory = Path(directory)

        if not directory.is_dir():
            raise ValueError('Path needs to be a directory.')
        
        out_file = directory / (self.id + ".yml")
        with open(out_file, 'w') as yfile:
            yaml.dump(self.weights, yfile)

The subject of this post, however, is to open up a discussion about how to incorporate surgical information into autopilot's datamodel. Here's an example file that I made by taking all the stuff lab mates recorded in different places as well as some stuff that the NWB standard asked for:

# Subject Metadata used for grabbing information 
# Jeremy Delahanty, Tye Lab Februrary 2022
# This was generated by taking all available fields labmembers had stored
# in their surgery logs and joining it with NWB metadata fields.
subject_id: "A000"
subject_alias: "best-mouse"
ear_tag:
  l_ear: true
  r_ear: false
ear_notch:
  l_ear: false
  r_ear: false
# Cage IDs MUST be the barcode for the cage
cage_id: 0123456
# Cage Alias is whatever the experimenter likes to refer the cage as
cage_alias: "cage-alias"
# Date of birth in YYYMMDD format
dob: "20220205"
# Descriptions
description: "Mouse Description"
genotype: "HET DAT Cre"
sex: "M"
species: "Mus Musculus"
strain: "C57BL/6J"
# Surgeries are organized by date
surgery:
  "20210924":
    surgeon: "Jeremy Delahanty"
    start_time: "10:00"
    end_time: "11:00"
    stereotax: "Delta"
    anesthetic: "Isoflurane"
    skull_position:
      bregma: -0.02
      lambda: -0.02
      level_left: -0.01
      level_right: -0.01
    headplate:
      num_screws: 1
      skull_hashing: true
    grin_implant:
      target: "mPFC"
      hemisphere: "R"
      type: "Proview"
      dims: [1, 4]
      supplier: "Inscopix"
      ap: 1.90
      ml: 0.45
      dv: -2.18
      angle: null
      notes: "None"
    brain_injections:
      gcamp:
        target: "mPFC"
        hemisphere: "R"
        virus: "AAV8"
        promoter: "promoter"
        opsin: null
        fluorophore: "jGCaMP7f"
        fluorophore_excitation_lambda: 482.5
        fluorophore_emission_lambda: 513.0
        supplier: "The Salk Institute for Biological Studies"
        description: "Calcium Sensitive Green Fluorescent Indicator"
        lot: null
        ap: 1.90
        ml: 0.45
        dv: -2.20
        angle: null
        # Volume in nL
        volume: 300
        # Rate in nL/min
        rate: 100.0
        # Bevel Direction: Away from you is 0 degrees
        bevel: 90
      chr:
        target: "VTA"
        hemisphere: "R"
        virus: "AAV8"
        promoter: "hSyn"
        cre: "FLEX"
        flp: null
        opsin: "chrimsonR"
        opsin_excitation_lambda: 100.0
        fluorophore: "tdTomato"
        fluorophore_excitation_lambda: 482.5
        fluorophore_emission_lambda: 581.0
        supplier: "Supplier"
        description: "description"
        lot: null
        ap: -3.30
        ml: 0.35
        dv: -4.05
        angle: null
        # Volume in nL
        volume: 700.0
        # Rate in nL/min
        rate: 100.0
        # Bevel Direction
        bevel: 180
    analgesics:
      buprinex:
        route: "IP"
        location: "abdomen"
        # Dosages are in mg/kg
        dose: 1.0
        # Volumes here in mL
        volume: 2.0
      lidocaine:
        route: "SQ"
        location: "scalp"
        dose: null
        volume: 0.5
      loxicam:
        route: "IP"
        location: "abdomen"
        # Dosages are in mg/kg
        dose: 5.0
        volume: 0.5
    fluids:
      ringers:
        route: "IP"
        location: "abdomen"
        percent: 20.0
        volume: 1.0

status:
  alive: true
  time_of_death: null
  death_notes: null

This method of doing things basically has an individual file per subject, and there's different sorts of metadata stored in different files. I think the way Autopilot does things is the way to go, where there's a deliberate subject data model that's flexible and easy to append to/load however you need. However, the world of performing surgery upon the brain of model organisms is so crazy complex/varied that I have no idea what a good datamodel for these sorts of things should or really could even look like. Autopilot already has solutions for this sort of thing but I'm still working on getting people to join me on the journey...

One immediate change that Jonny suggested is to no longer have the key be a specific date but rather have a surgeries field that gets appended to. I'm not sure when I'll get to changing that for how one project is doing things, but moving forward I'd like to have things organized how Autopilot does it.

I think the main overall "categories" of things I've experienced recording during surgeries is:

• Medicines (anesthetics, anti-biotics, etc)
• Fluids (ringers)
• Brain Injections (channel rhodopsin, tracers/labels, fluorescent indicators, a million other kinds of things....)
• Hardware (e-phys probes, GRIN lenses, cannulas for fiber optics, head-plates, whatever else people use...)
• Which surgical station I used (we have a few stereotax stations, each with their own quirks and, sometimes, problems)
• Start/stop times

Another thing that's related to all this is stuff that's stored as imaging parameters for a given mouse in a 2-photon setup. There are settings related to how much voltage to pass through photo-multiplier tubes (or PMTs) and how much power to send through the laser for example. Currently, these things will probably be stored in yet another file because I'm a doofus. However, things like this would be quite helpful to have available in an autopilot datamodel I think!

Similar settings associated with electrical/optical stimulation parameters for example could also probably be stored on a per subject basis instead of a per project basis.

I figured I'd post here and open a discussion about what a datamodel for storing things like this should look like.

[jmdelahanty]

Going to post a json formatted thing in the next couple of days. It's ugly. One could say it's been... botched? Like a botched surgery, get it?

...sorry