## Brain Observatory Trace Analysis¶

This notebook demonstrates how to run the stimulus-specific tuning analysis code in the SDK. First let's instantiate a BrainObservatoryCache instance.

## Drifting Gratings¶

In this example, we'll show how you can plot a heatmap of a cell's response organized by orientation and temporal frequency. Here we start with a known experiment ID. Take a look at the other notebook to see how you can find experiments of interest. You can run the drifting grating analysis code on that experiment's NWB file as follows:

If you know which cell you're interested in, here's how you can find out where it is in the NWB File.

The response property of the stimulus-specific analysis objects is 4-D array organized with the following dimensions:

0: num. grating directions
1: num. grating temporal frequencies + 1 (0=blank sweep)
2: num. cells + 1 (running speed)
3: 0=response mean, 1=response standard error of the mean, 2=number of signficant trials



Dimension 2 of the response array has one index per cell in the experiment, plus one. The final index of that dimension is the running speed (response[:,:,-1,:]). This organization allows users to examine whether the mouse ran more for some specific stimulus conditions.

The peak property of the analysis object is a Pandas DataFrame of peak conditions (direction and temporal frequency) as well as computed response metrics. For drifting gratings this includes:

ori_dg: preferred direction (index into dg.orivals)
tf_dg: preferred temporal frequency (index into tf.tfvals)
response_reliability_dg: response reliability
osi_dg: orientation selectivity index
dsi_dg: direction selectivity index
ptest_dg: number of signficant cells
p_run_dg: K-S statistic comparing running trials to stationary trials
run_modulation_dg: ratio of mean fluorescence during running vs static
cv_dg: circular variance 

Next let's plot all trials for a given cell's preferred condition.

sweep_response is a DataFrame that contains the DF/F of each cell during each stimulus trial. It shares its index with stim_table. Each cell contains a timeseries that extends from 1 second prior to the start of the trial to 1 second after the end of the trial. The final column of sweep_response, named dx, is the running speed of the mouse during each trial. The data in this DataFrame is used to create another DataFrame called mean_sweep_response that contains the mean DF/F during the trial for each cell (and the mean running speed in the last column).

Here we look at the mean running speed during trials that presented the preferred condition.

Plot the response to each trial of the preferred condition, labeled with the mean running speed during the trial

## Static Gratings¶

The static gratings analysis object is quite similar to the drifting gratings analysis object. Here we'll just take a look at the peak table, which contains information about the preferred orientation, spatial frequency, phase, as well as a number of other metrics.

## Natural Scenes¶

The natural scenes analysis object is again similar to the others. In addition to computing the sweep_response and mean_sweep_response arrays, NaturalScenes reports the cell's preferred scene, running modulation, time to peak response, and other metrics.

## Locally Sparse Noise¶

The locally sparse noise stimulus object is a bit different from the others. It does not have a peak condition table, instead providing a method to retrieve the "on" and "off" receptive fields of all cells. The receptive field of a cell is computed by averaging responses to trials in which a given sparse noise grid location is on/off.