Mouse brain atlas placement

The BSB supports integration with atlases. All that’s required is to implement a Voxels partition so that the atlas data can be converted from the atlas raster format, into a framework object. The framework has the Allen Mouse Brain Atlas integration out of the box, and this example will use the AllenStructure partition to showcase its usages.

After loading the brain region shapes from the atlas, we will use a local data file to assign density values to each voxel, and place cells accordingly.

Topology

We start by defining the topology: a region, and an allen partition:

  "regions": {
    "brain": {"children": ["declive"]}
  },
  "partitions": {
    "declive": {
      "type": "allen",
      "struct_name": "DEC"
    }

BSB will here download the 2017 version of the CCFv3 mouse brain annotation atlas volume from the Allen Institute website to define the shape of the partition. Use mask_source to provide your own nrrd annotation volume file.

The struct_name refers to the Allen mouse brain region acronym or name. You can also replace that with struct_id, if you are using the numeric identifiers. You can find the ids, acronyms and names in the Allen Brain Atlas brain region hierarchy file.

Cell types

We now add a cell population my_cell in the declive, it will be placed with a fixed density of 0.003/μm^3:

  "cell_types": {
    "my_cell": {
      "spatial": {
        "radius": 2.5,
        "density": 0.003
      }
    },
  },
  "placement": {
    "example_placement": {
      "strategy": "bsb.placement.RandomPlacement",
      "cell_types": [
        "my_cell",
      ],
      "partitions": ["declive"]
    }
  },

Cell Density files

Now in case we know the cell densities distribution inside the declive, we can store it inside a nrrd file and link it to the partition and cell population. Here, we add a my_cell_density.nrrd file to the declive partition using the sources attribute and finally to a cell population my_other_cell using the density_key attribute:

  "partitions": {
    "declive": {
      "type": "allen",
      "sources": [
      {
        "type": "nrrd",
        "file": "data/my_cell_density.nrrd"
      }
      ],
      "struct_name": "DEC"
    }
  },
  "cell_types": {
    "my_other_cell": {
      "spatial": {
        "radius": 2.5,
        "density_key": "my_cell_density"
      }
    }
  },
  "placement": {
    "example_placement": {
      "strategy": "bsb.placement.RandomPlacement",
      "cell_types": [
        "my_other_cell"
      ],
      "partitions": ["declive"]
    }
  },

Note that here the reference to the file data/my_cell_density.nrrd in my_other_cell is the name of the file without the extension (similar to the morphologies).

The sources file(s) will be loaded during the placement, and the values at the coordinates of the voxels that make up our partition will be used to compute the number of cells.

Finally, let us imagine we need to define 2 partitions, corresponding to 2 regions of the mouse brain and place our two cell populations in both, then the simplest solution would be to declare our density file in each partition. However, this solution will add the file to the Storage twice.

Hence, we strongly recommend you to declare any file that might be reused at different steps of the reconstruction in the files root component (see also this section).

  "files": {
    "my_cell_density":
      {
        "type": "nrrd",
        "file": "data/my_cell_density.nrrd"
      }
  },
  "partitions": {
    "declive": {
      "type": "allen",
      "sources": [
        "my_cell_density"
      ],
      "struct_name": "DEC"
    }
  },
  "cell_types": {
    "my_other_cell": {
      "spatial": {
        "radius": 2.5,
        "density_key": "my_cell_density"
      }
    }
  },

Final configuration file

{
  "name": "Using the Allen Atlas and a density file to place cells",
  "storage": {
    "engine": "hdf5",
    "root": "allen_densities.hdf5"
  },
  "network": {
    "x": 13200,
    "y": 8000,
    "z": 11400,
    "chunk_size": 250
  },
  "files": {
    "my_cell_density":
      {
        "type": "nrrd",
        "file": "data/my_cell_density.nrrd"
      }
  },
  "regions": {
    "brain": {"children": ["declive"]}
  },
  "partitions": {
    "declive": {
      "type": "allen",
      "sources": [
        "my_cell_density"
      ],
      "struct_name": "DEC"
    }
  },
  "cell_types": {
    "my_cell": {
      "spatial": {
        "radius": 2.5,
        "density": 0.003
      }
    },
    "my_other_cell": {
      "spatial": {
        "radius": 2.5,
        "density_key": "my_cell_density"
      }
    }
  },
  "placement": {
    "example_placement": {
      "strategy": "bsb.placement.RandomPlacement",
      "cell_types": [
        "my_cell",
        "my_other_cell"
      ],
      "partitions": ["declive"]
    }
  },
  "connectivity": {}
}