pupil_timescales_dLGN/README.md

pupil_timescales_dLGN

Data and code for Crombie, D., Spacek, M.A., Leibold, C.*, Busse, L.*, (accepted). Spiking activity in the visual thalamus is coupled to pupil dynamics across temporal scales. PLoS Biology. [* shared senior authors]

Instructions for use

Figures

To generate figures from already processed data, copy the *.pkl data files out of data/original_cooked/ and data/original_raw into data/ and then run the corresponding cells in the figures_*.ipynp Jupyter notebooks. Note that notebook cells should be run in order to avoid variable name conflicts. Figures will by default be stored in the figures/ folder, which also contains sub-folder

Analyses

Data for this project is stored as pickled Pandas DataFrame objects. The "raw" data files, including pupil_*.pkl, spikes_*.pkl, ball_*.pkl, and trials_*.pkl, contain minimally-processed data to be used in further analyses.

To re-generate the processed ("cooked") data, run the corresponding *.py file with the desired arguments.

Note : Because many of the analyses involve randomization (e.g. comparison to random permutations of the data), the original figures may only be exactly reproduced by using the data files from the original_cooked folder.

The positional argument e_name specifies the experiment name, and is required for all scripts. It can be one of

• 'spontaneous' : experiments where the monitor displayed a uniform gray screen
• 'sparsenoise' : experiments with sparse noise visual stimulation
• 'dark' : experiments where the display monitor was switched off and other sources of illumination were covered
• 'natmov' : experiments with repeated trial of a naturalistic video clip
• 'natmov_opto' : experiments with repeated trials of a naturalistic video clip, trials with optogenetic stimulation of V1 PV neurons are interleaved pseudo-randomly

Note : Spontaneous and sparse noise experiments are generally analyzed together, but the analysis scripts need to be run separately for each experiment type.

Other arguments may include:

Spike type : --spk_type -s

• 'tonicskp' : tonic spikes, i.e. all spikes that are not part of a burst
• 'burst' : burst events, i.e. the first spike in a burst
• 'spk' : all spikes, i.e. any spike regardless of whether it is part of a burst or not

Time ranges : --tranges -t

• 'run' : bouts of locomotion
• 'sit' : behavioral quiescence (no locomotion)
• 'nosaccade' : periods with no saccadic eye movements
• 'noopto' : trials without optogenetic stimulation
• 'desync' : exclusion of time periods during which the IMF goes through phase combinations with other IMFs that occur more frequently than by chance (as per the analysis in Figure S1D)
• 'sizematched' : time periods sub-sampled so as to match the distribution of pupil sizes across IMF phase bins (as per Figure 3A)

Note : the imf_decoding.py script will automatically look for phasetuning data from the noopto time ranges.

Analysis and plotting parameters are stored in parameters.py. Useful, general-purpose functions are stored in the util.py module.

Nomenclature

Experimental units are defined using a MSEU nomenclature: mouse (the strain, year, and ID of a mouse, e.g. 'PVCre_2020_0001'), series (recording session, during which several experimental stimulation protocols are carried out, e.g. 's01'), experiment (a single experiment, e.g. e01), unit (a putative neuron identified by spike sorting, e.g. 'u10'). Every row in a dataframe typically has some combination of these dentifiers which can be used as an index, and to group or merge the data.

The folloing terms are used interchangeably:

Intrinsic mode function (IMF) == component of pupil dynamics (CPD) == timescale

• a component resulting from application of Empirical Mode Decomposition (EMD) to the pupil size timeseries

Characteristic frequency == frequency == timescale

• the value (1/seconds) used to characterise a CPD by taking the mean amplitude-weighted instantaneous frequency

Phase tuning == phase coupling

• the tendency for spikes or bursts to occur more during certain phases of the IMFs derived from the pupil size time series, as per the analysis method introduced in Figure 2