h1. ALLEN BRAIN ATLAS API

{toc:minLevel=2\|maxLevel=3\|class=toc-style}

!CellTypes.png|width=32! The *Allen Cell Types Database* provides multimodal single cell characterization data to enable data-driven approaches to cell type classification.

From the API, you can:

[!download_image.png|width=32!|#NWB] *Download electrophysiology data in Neurodata Without Borders (NWB) format*
!structure_level_expression.png|width=32! *Download computed electrophysiology features*
!download_image.png|width=32! *Download images of cell morphology images*
!download_image.png|width=32! *Download morphological reconstructions in SWC format*
!structure_level_expression.png|width=32! *Download computed morphology features*
!download_image.png|width=32! *Download neuronal models trained on this data set*

This document provides a brief overview of the data, database  organization and example queries. API database object names are in camel  case. See the main [API Documentation|api:Allen Brain Atlas API] for more information on data models and query syntax.

The accompanying [Allen Software Development Kit (SDK)|http://sdk.brain-map.org/] provides python code for accessing electrophysiology data (NWB files) for all cells and morphological reconstructions (SWC files) for a subset of cells. The Allen SDK also provides sample code demonstrating how to download neuronal model parameters and run your own simulations using stimuli for the experiments or custom current injections.


h2. Experimental Overview And Metadata

Experimental data from Allen Cell Types Database is associated with the "Mouse Cell Types" Product.

Each brain specimen is sectioned in the coronal plane at section thickness of 350 µm. The sections are then hemisected along the midline and a single cell in the hemisected tissue is targeted for electrophysiological recording and biocytin fill to visualize the cell morphology. Each cell is represented as Specimen object.

Each cell Specimen is associated with an anatomical Structure and CellSomaLocation record containing the coordinate of the cell in the Common Coordinate Framework and a normalized depth between pia (value of 0) and white matter (value of 1) surfaces.

Each cell Specimen is also associated with two SpecimenTags describing the “dendrite type” (spiny, aspiny, sparsely spiny) and the “apical dendrite” (intact, truncated, n/a).

See [whitepapers|celltypes:Documentation] for detailed experimental and annotation information.

From the API, detailed information about cells can be obtained using [RMA |api:RESTful Model Access (RMA)]queries.

*Examples:*
* All cells in the "Mouse Cell Types" Product
{noformat}
http://api.brain-map.org/api/v2/data/query.xml?criteria=
model::Specimen
,rma::criteria,[is_cell_specimen$eq'true'],products[name$eq'Mouse Cell Types']
,rma::include,structure,donor(transgenic_lines),specimen_tags,cell_soma_locations
,rma::options[num_rows$eqall]
{noformat}
* All cells tagged with 'dendrite type - spiny'
{noformat}
http://api.brain-map.org/api/v2/data/query.xml?criteria=
model::Specimen
,rma::criteria,[is_cell_specimen$eq'true'],products[name$eq'Mouse Cell Types']
,rma::include,
structure,donor(transgenic_lines),specimen_tags[name$eq'dendrite type - spiny'],cell_soma_locations
,rma::options[num_rows$eqall]
{noformat}
* All cells annotated to be in layer 4
{noformat}
http://api.brain-map.org/api/v2/data/query.xml?criteria=
model::Specimen
,rma::criteria,[is_cell_specimen$eq'true'],products[name$eq'Mouse Cell Types']
,rma::include,structure[name$il'*layer 4*'],donor(transgenic_lines),specimen_tags,cell_soma_locations
,rma::options[num_rows$eqall]
{noformat}

h2. Electrophysiology


All cells in the Allen Cell Types Database have electrophysiological recordings of responses to stimuli from a common set of current injection protocols. Please see the (TODO) electrophysiology technical white paper for details on specimen selection, tissue processing, recording, and quality control.


The Cell Types Database categorizes detailed stimulus protocols into set of high level descriptions:
|| Stimulus Group Name \\ || Description \\ ||
| Short Square \\ | 3 ms square pulse injections from 100 pA to action potential generation, then 10 pA increments to further probe action potential threshold. |
| Short Square - Hold \-60mV \\ | Short Square, holding rest at \-60mV \\ |
| Short Square - Hold \-70mV \\ | Short Square, holding rest at \-70mV |
| Short Square - Hold \-80mV \\ | Short Square, holding rest at \-80mV |
| Short Square - Triple \\ | 3 x 3 ms square current injections at threshold amplitude. Interpulse intervals (start to start) are 7, 11, 15, 19, 23, 27, 31, and 35 ms. |
| Long Square \\ | 1 s square current injections from \-110 pA (or \-190 pA for some Pvalb neurons) to rheobase + 160 pA, in 20 pA increments. For a subset of cells, rheobase is further probed to within 10 pA. |
| Square - 2s Suprathreshold \\ | 2 s square current injections to rheobase + 40 pA and 80 pA. Each amplitude is repeated 3-4 times. |
| Square - 0.5ms Subthreshold \\ | 0.5 ms square current injections to \+/\- 200 pA, repeated 20 times (200 ms intervals). |
| Ramp \\ | A ramp current injection with a slope of 25 pA/s is delivered, then terminated after the neuron fires a short series of action potentials. |
| Ramp to Rheobase \\ | 1 s pink noise epochs created using two different random seeds riding on top of a ramp transitioning to a plateau. The ramp portion of the stimulus is 14 seconds long.  The noise on the ramp consists of alternating seeds all with a CV of .01. The noise on the plateau are organized into periods of six seconds containing noise of three different CV's with increasing and decreasing CV at 0.2, 0.4, 0.6, 0.4, and 0.2. After a period is completed using one random seed, the other random seed is played for a total of three periods. |
| Noise 1 \\ | Pink noise with a coefficient of variation (CV) equal to 0.2 is used to as it resembles _in vivo_ data. These stimuli consist of 3 x 3 s noise epochs riding on top of square pulses at 0.75, 1, and 1.5 times rheobase. Recovery intervals between stimuli are 5 s. |
| Noise 2 \\ | Noise 1, with a different random seed \\ |
| Test \\ | General protocols used for testing experiment status \\ |

\\
{anchor:NWB}

Stimulus sweeps that pass quality control standards are available for download as Neurodata Without Borders (NWB) files. To find the NWB download link for Rorb cell specimen [320654829|http://celltypes.brain-map.org/mouse/experiment/electrophysiology/320654829], use this query:


{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::Specimen
,rma::criteria,[id$eq320654829]
,rma::include,ephys_result(well_known_files(well_known_file_type[name$eqNWB]))
{noformat}
Please see the Allen SDK pages (LINKS TODO) on perisomatic biophysical models and generalized leaky integrate-and-fire models for details showing how to download these files in the context of neuronal model simulation.

!Scnn1a_ephys_page.png|border=1!

A standard set of electrophysiological features are automatically computed from the recorded responses of each cell.  A subset of those features are displayed at the top of the electrophysiology page for a cell:
|| Feature \\ || Description \\ ||
| Upstroke:downstroke ratio \\ | |
| Fast AP trough \\ | |
| FI curve slope \\ | |
| Rheobase \\ | |
| Ramp AP Time \\ | |
| Resting Vm \\ | |
Please read the electrophysiology technical white paper (TODO) for a complete list of computed features and their interpretations.

Use this query to download the features computed for Scnn1a cell specimen 467703703:

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::EphysFeature
,rma::criteria,[specimen_id$eq467703703]
{noformat}



h2. Morphology

The Allen Cell Types Database contains morphological reconstructions generated from bright-field images of biocytin-stained cells. Reconstructions are generated by manually curating the results of an automated segmentation algorithm.  Please see the morphology technical white paper for more details (TODO).


A standard set of morphological features were computed for all reconstructed cells.  A subset of those features are displayed at the top of the cell-specific morphology page:

|| Feature Name \\ || Description \\ ||
| Max Euclidean Distance \\ | |
| Number of Stems \\ | |
| Number of Bifurcations \\ | |
| Average Contraction \\ | |
| Parent:Daughter \\ | |

For a complete list of computed morphological features, please see the morphology technical white paper (TODO).

The API provides programmatic access to the microscopy images used  for reconstruction, axis-oriented projections of those images, and  morphological reconstructions.

*Examples*:
* Find all cells with morphological images

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::Specimen
,rma::criteria,[is_cell_specimen$eq'true'],data_sets
{noformat}
* Find projection image IDs for layer 4 spiny cell (Specimen 313862022):

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::ProjectionImage
,rma::criteria,[specimen_id$eq313862022]
{noformat}
* Download an image from its ID

{noformat}

{noformat}
* Find all images used for reconstruction for a layer 4 spiny cell (Specimen 313862022)

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?criteria=model::SubImage,rma::criteria,data_set[specimen_id$eq313862022]
{noformat}
* Download an image from the image stack

{noformat}
http://api.brain-map.org/api/v2/section_image_download/321549675
{noformat}
* Find all cells with morphological reconstructions

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::Specimen
,rma::criteria,[is_cell_specimen$eq'true'],neuron_reconstructions
{noformat}
* Find the reconstruction file for one of those cells

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::NeuronReconstruction
,rma::criteria,[specimen_id$eq313862306],rma::include,well_known_files
{noformat}
* Download the reconstruction file

{noformat}
http://api.brain-map.org/api/v2/well_known_file_download/475125282
{noformat}


* Download all of the morphology features for Scnn1a cell 313862022

{noformat}
 http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::NeuronReconstruction
,rma::criteria,[specimen_id$eq313862022]
{noformat}



h2. Single Cell Neuronal Models

The Allen Cell Types Database contains two types of neuronal models: perisomatic biophysical models and generalized leaky integrate-and-fire (GLIF) models.  These models attempt to mathematically reproduce a cell's recorded response to a current injection.  The perisomatic biophysical models take into account dendritic morphological structure, whereas GLIF models rely strictly on the cell's stimulus and response. 

There are five types of GLIF models with varying levels of complexity.  The most basic model is a simple leaky integrate-and-fire equation.  More advanced GLIFs attempt to model variable spike threshold, afterspike currents, and threshold adaptation. 
|| Model Name \\ || Description \\ ||
| Biophysical, perisomatic \\ | |
| 1 Leak Integrate and Fire (LIF) \\ | |
| 2 LIF + Reset Rules (LIF-R) \\ | |
| 3 LIF + Afterspike Currents (LIF-ASC) \\ | |
| 4 LIF-R + Afterspike Currents (LIF-R-ASC) \\ | |
| 5 LIF-R-ASC + Threshold Adaptation (LIF-R-ASC-A) \\ | |
Please see the perisomatic biophysical and GLIF technical white papers for more details on how these models were created (TODO). !models_celltypes.png|border=1!


A cell's electrophysiology page displays all available models.  Choose a model to see its simulated response to all stimuli presented to the cell.  If the required sweeps are available, two model evaluation metrics are computed per model:
|| Metric Name \\ || Required Sweeps \\ || Description \\ ||
| Explained Variance Ratio \\ | Noise 2 (at least two) \\ | |
| Feature Average \\ | Sweeps used for biophysical model fitting \\ | |


After selecting a model for display, the models ID number and a link for downloading necessary to run the model are available.  For example, the link to download model 472427473 (a LIF model for Scnn1a cell 467703703) looks like this:

{noformat}
 http://api.brain-map.org/neuronal_model/download/472427473
{noformat}All models in the Allen Cell Types Database are available for download and local execution via the [Allen Software Development Kit (SDK)|http://sdk.brain-map.org/].  The biophysical models require [NEURON|http://www.neuron.yale.edu/neuron/] to be run, which the SDK helps to configure.  The GLIF simulation module comes as part of the Allen SDK. Please visit the Allen SDK page for more details.

*Examples:*
* Find all cells with perisomatic biophysical models

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::Specimen
,rma::criteria,neuronal_models(neuronal_model_template[name$eq'Biophysical - perisomatic'])
{noformat}
* Find all cells with GLIF models

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::Specimen,rma::criteria,neuronal_models(neuronal_model_template[description$il'*GLIF*'])
{noformat}
* Download all GLIF models for Scnn1a-Tg3 cell 469803127

{noformat}
http://api.brain-map.org/api/v2/data/query.xml?
criteria=model::Specimen,rma::criteria,[id$eq469803127]
,rma::include,neuronal_models(neuronal_model_template[name$il'*LIF*'])
{noformat}
* Download the files necessary to run simple LIF model 472423251

{noformat}
 http://api.brain-map.org/neuronal_model/download/472423251
{noformat}
* Allen SDK documentation for how to run simple LIF model 472423251

{noformat}
 http://sdk.brain-map.org/glif_models.html#downloading-glif-models
{noformat}
* Link to the electrophysiology page for Scnn1a-Tg3 cell 469803127

{noformat}
 http://celltypes.brain-map.org/mouse/experiment/electrophysiology/469803127
{noformat}| {color:hite}{*}Ramp{*}{color} | {color:hite}{*}A ramp current injection with a slope of 25   pA/s is delivered, then terminated after the neuron fires a short series of   action potentials.*{color} |<!--  /* Style Definitions */  table.MsoNormalTable 	{mso-style-name:"Table Normal"; 	mso-tstyle-rowband-size:0; 	mso-tstyle-colband-size:0; 	mso-style-noshow:yes; 	mso-style-priority:99; 	mso-style-qformat:yes; 	mso-style-parent:""; 	mso-padding-alt:0in 5.4pt 0in 5.4pt; 	mso-para-margin-top:0in; 	mso-para-margin-right:0in; 	mso-para-margin-bottom:10.0pt; 	mso-para-margin-left:0in; 	line-height:115%; 	mso-pagination:widow-orphan; 	font-size:11.0pt; 	font-family:"Calibri","sans-serif"; 	mso-ascii-font-family:Calibri; 	mso-ascii-theme-font:minor-latin; 	mso-hansi-font-family:Calibri; 	mso-hansi-theme-font:minor-latin;} table.AllenTable 	{mso-style-name:"Allen Table"; 	mso-tstyle-rowband-size:1; 	mso-tstyle-colband-size:1; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	margin-left:5.75pt; 	border:solid white 1.5pt; 	mso-border-themecolor:background1; 	mso-padding-alt:2.15pt 5.75pt 2.15pt 5.75pt; 	mso-border-insideh:1.5pt solid white; 	mso-border-insideh-themecolor:background1; 	mso-border-insidev:1.5pt solid white; 	mso-border-insidev-themecolor:background1; 	mso-para-margin:0in; 	mso-para-margin-bottom:.0001pt; 	mso-pagination:widow-orphan; 	font-size:10.0pt; 	mso-bidi-font-size:11.0pt; 	font-family:"Arial","sans-serif"; 	mso-bidi-font-family:"Times New Roman"; 	mso-bidi-theme-font:minor-bidi;} table.AllenTableFirstRow 	{mso-style-name:"Allen Table"; 	mso-table-condition:first-row; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#003768; 	mso-tstyle-border-top:cell-none; 	mso-tstyle-border-left:cell-none; 	mso-tstyle-border-bottom:cell-none; 	mso-tstyle-border-right:cell-none; 	mso-tstyle-border-insideh:1.5pt solid white; 	mso-tstyle-border-insideh-themecolor:background1; 	mso-tstyle-border-insidev:1.5pt solid white; 	mso-tstyle-border-insidev-themecolor:background1; 	font-size:10.0pt; 	mso-ansi-font-size:10.0pt; 	font-family:"Arial","sans-serif"; 	mso-ascii-font-family:Arial; 	mso-hansi-font-family:Arial; 	color:white; 	mso-ansi-font-weight:bold;} table.AllenTableLastRow 	{mso-style-name:"Allen Table"; 	mso-table-condition:last-row; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#D1E9FF;} table.AllenTableFirstCol 	{mso-style-name:"Allen Table"; 	mso-table-condition:first-column; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#003768; 	mso-tstyle-shading-themecolor:accent1;} table.AllenTableLastCol 	{mso-style-name:"Allen Table"; 	mso-table-condition:last-column; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#D1E9FF;} table.AllenTableOddColumn 	{mso-style-name:"Allen Table"; 	mso-table-condition:odd-column; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#BFBFBF; 	mso-tstyle-shading-themecolor:accent2;} table.AllenTableEvenColumn 	{mso-style-name:"Allen Table"; 	mso-table-condition:even-column; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#F2F2F2; 	mso-tstyle-shading-themecolor:background2;} table.AllenTableOddRow 	{mso-style-name:"Allen Table"; 	mso-table-condition:odd-row; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#B5B5B5; 	mso-tstyle-shading-themecolor:background2; 	mso-tstyle-shading-themeshade:191;} table.AllenTableEvenRow 	{mso-style-name:"Allen Table"; 	mso-table-condition:even-row; 	mso-style-priority:99; 	mso-style-unhide:no; 	mso-style-qformat:yes; 	mso-tstyle-shading:#F2F2F2; 	mso-tstyle-shading-themecolor:background1; 	mso-tstyle-shading-themeshade:242;} -->