|
1 | 1 | # DataJoint Element - Array Electrophysiology Element |
2 | 2 |
|
3 | | -+ This repository features DataJoint pipeline design for extracellular array electrophysiology, |
4 | | -with Neuropixels probe and Kilosort spike sorting method. |
| 3 | +DataJoint Element for extracellular array electrophysiology. DataJoint Elements |
| 4 | +collectively standardize and automate data collection and analysis for neuroscience |
| 5 | +experiments. Each Element is a modular pipeline for data storage and processing with |
| 6 | +corresponding database tables that can be combined with other Elements to assemble a |
| 7 | +fully functional pipeline. |
5 | 8 |
|
6 | | -+ This module is designed to be integrated into a complete data pipeline and provides |
7 | | -data tables and computational dependencies specific to extracellular electrophysiology |
8 | | -processing and analysis. |
| 9 | + |
9 | 10 |
|
10 | | -+ This modular pipeline element can be flexibly attached downstream |
11 | | -to any particular design of experiment session, thus assembling a fully functional |
12 | | -ephys pipeline. |
13 | | - |
14 | | -+ This Element provides three schema options, selected via the DataJoint config file, with `dj.config['custom']['ephys_mode']` |
15 | | - + `acute` probe insertion, with curated clustering |
16 | | - + `chronic` probe insertion, with curated clustering |
17 | | - + `no-curation`, with kilosort triggered clustering |
18 | | - |
19 | | -+ See the [Element Array Electrophysiology documentation](https://elements.datajoint.org/description/array_ephys/) for the background information and development timeline. |
20 | | - |
21 | | -+ For more information on the DataJoint Elements project, please visit https://elements.datajoint.org. This work is supported by the National Institutes of Health. |
22 | | - |
23 | | -## Element architecture |
24 | | - |
25 | | -`element-array-ephys` is comprised of two schemas, `probe` and `ephys`. To handle |
26 | | -several use cases of this pipeline, we have designed several `ephys` schemas, including |
27 | | -`ephys_acute`, `ephys_chronic`, and `ephys_precluster`. |
28 | | - |
29 | | -+ `ephys_acute` - A probe(s) is inserted into a new location during each session. |
30 | | - |
31 | | -+ `ephys_chronic` - A probe(s) is inserted once and used to record across multiple |
32 | | -sessions. |
33 | | - |
34 | | -+ `ephys_precluster` - A probe(s) is inserted into a new location during each session. |
35 | | -And pre-clustering steps (e.g. CatGT) are performed on the data from each probe prior |
36 | | -to Kilosort analysis. |
37 | | - |
38 | | -### `ephys_acute` module |
39 | | - |
40 | | - |
41 | | - |
42 | | -### `ephys_chronic` module |
43 | | - |
44 | | - |
45 | | -### `ephys_precluster` module |
46 | | - |
48 | | - |
49 | | - |
50 | | -As the diagram depicts, the array ephys element starts immediately downstream from `Session`, |
51 | | -and also requires some notion of `Location` as a dependency for `InsertionLocation`. We |
52 | | -provide an [example workflow](https://github.com/datajoint/workflow-array-ephys/) with a |
53 | | -[pipeline script](https://github.com/datajoint/workflow-array-ephys/blob/main/workflow_array_ephys/pipeline.py) |
54 | | -that models (a) combining this Element with the corresponding [Element-Session](https://github.com/datajoint/element-session) |
55 | | -, and (b) declaring a `SkullReference` table to provide Location. |
56 | | - |
57 | | -## Table descriptions |
58 | | - |
59 | | -### Probe & electrodes |
60 | | - |
61 | | -The `probe` schema contains information regarding the Neuropixels probe and electrode configuration. |
62 | | - |
63 | | -<details> |
64 | | -<summary>Click to expand details</summary> |
65 | | - |
66 | | -+ `ProbeType` - a lookup table specifying the type of Neuropixels probe (e.g. "neuropixels 1.0", "neuropixels 2.0 single-shank") |
67 | | - |
68 | | -+ `ProbeType.Electrode` - all electrode and their properties for a particular probe type |
69 | | - + An electrode here refers to one recordable electrode site on the Neuropixels probe (e.g. for Neuropixels 1.0, there are 960 sites per shank) |
70 | | - |
71 | | -+ `Probe` - record of an actual physical probe, identifiable by some unique ID (e.g. probe's serial number) |
72 | | - |
73 | | -+ `ElectrodeConfig` - particular electrode configuration to be used for ephys recording |
74 | | - |
75 | | -+ `ElectrodeConfig.Electrode` - corresponding electrodes in `ProbeType.Electrode` that are used for recording in this electrode configuration (e.g. for Neuropixels 1.0 or 2.0, there can be at most 384 electrodes usable for recording per probe) |
76 | | - |
77 | | -</details> |
78 | | - |
79 | | -### Extracellular electrophysiology recording |
80 | | - |
81 | | -The `ephys` schema stores information regarding the recording from a probe for a given session. |
82 | | - |
83 | | -<details> |
84 | | -<summary>Click to expand details</summary> |
85 | | - |
86 | | -+ `ProbeInsertion` - a surgical insertion of a probe in the brain. Every experimental session consists of one or more entries in `ProbeInsertion` with a corresponding `InsertionLocation` each |
87 | | - |
88 | | -+ `EphysRecording` - each `ProbeInsertion` is accompanied by a corresponding `EphysRecording`, specifying the `ElectrodeConfig` used for the recording from the `Probe` defined in such `ProbeInsertion` |
89 | | - |
90 | | -</details> |
91 | | - |
92 | | -### Clusters and spikes |
93 | | - |
94 | | -The `ephys` schema features automatic ingestion of spike sorting results from the `Kilosort` analysis method. |
95 | | - |
96 | | -<details> |
97 | | -<summary>Click to expand details</summary> |
98 | | - |
99 | | -+ `Clustering` - specify instance(s) of clustering on an `EphysRecording`, by some `ClusteringMethod` |
100 | | - |
101 | | -+ `Curation` - specify instance(s) of curations performed on the output of a given `Clustering` |
102 | | - |
103 | | -+ `CuratedClustering` - set of results from a particular round of clustering/curation |
104 | | - + `CuratedClustering.Unit` - Identified unit(s) from one `Curation`, and the associated properties (e.g. cluster quality, spike times, spike depths, etc.) |
105 | | - + `WaveformSet` - A set of spike waveforms for units from a given CuratedClustering |
106 | | - |
107 | | -</details> |
108 | | - |
109 | | -## Installation |
110 | | -<details> |
111 | | -<summary>Click to expand details</summary> |
112 | | - |
113 | | -+ Install `element-array-ephys` |
114 | | - ``` |
115 | | - pip install element-array-ephys |
116 | | - ``` |
117 | | -
|
118 | | -+ Upgrade `element-array-ephys` previously installed with `pip` |
119 | | - ``` |
120 | | - pip install --upgrade element-array-ephys |
121 | | - ``` |
122 | | -
|
123 | | -+ Install `element-interface` |
124 | | - + `element-interface` is a dependency of `element-array-ephys`, however it is not contained within `requirements.txt`. |
125 | | - ``` |
126 | | - pip install "element-interface @ git+https://github.com/datajoint/element-interface" |
127 | | - ``` |
128 | | -
|
129 | | -</details> |
130 | | -
|
131 | | -## Usage |
132 | | -
|
133 | | -### Element activation |
134 | | -
|
135 | | -When using this Element, one needs to run `ephys.activate` to declare the schemas and tables on the database. |
136 | | -
|
137 | | -<details> |
138 | | -<summary>Click to expand details</summary> |
139 | | -
|
140 | | -To activate the `element-array-ephys`, ones need to provide: |
141 | | -
|
142 | | -1. Schema names |
143 | | - + schema name for the probe module |
144 | | - + schema name for the ephys module |
145 | | -
|
146 | | -2. Upstream tables |
147 | | - + Session table: A set of keys identifying a recording session (see [Element-Session](https://github.com/datajoint/element-session)). |
148 | | - + SkullReference table: A reference table for InsertionLocation, specifying the skull reference (see [example pipeline](https://github.com/datajoint/workflow-array-ephys/blob/main/workflow_array_ephys/pipeline.py)). |
149 | | -
|
150 | | -3. Utility functions. See [example definitions here](https://github.com/datajoint/workflow-array-ephys/blob/main/workflow_array_ephys/paths.py) |
151 | | - + get_ephys_root_data_dir(): Returns your root data directory. |
152 | | - + get_session_directory(): Returns the path of the session data relative to the root. |
153 | | -
|
154 | | -For more detail, check the docstring of the `element-array-ephys`: |
155 | | -
|
156 | | - help(probe.activate) |
157 | | - help(ephys.activate) |
158 | | -
|
159 | | -</details> |
160 | | -
|
161 | | -### Example usage |
162 | | -
|
163 | | -See [this project](https://github.com/datajoint/workflow-array-ephys) for an example usage of this Array Electrophysiology Element. |
164 | | -
|
165 | | -## Citation |
166 | | -
|
167 | | -+ If your work uses DataJoint and DataJoint Elements, please cite the respective Research Resource Identifiers (RRIDs) and manuscripts. |
168 | | -
|
169 | | -+ DataJoint for Python or MATLAB |
170 | | - + Yatsenko D, Reimer J, Ecker AS, Walker EY, Sinz F, Berens P, Hoenselaar A, Cotton RJ, Siapas AS, Tolias AS. DataJoint: managing big scientific data using MATLAB or Python. bioRxiv. 2015 Jan 1:031658. doi: https://doi.org/10.1101/031658 |
171 | | -
|
172 | | - + DataJoint ([RRID:SCR_014543](https://scicrunch.org/resolver/SCR_014543)) - DataJoint for `<Select Python or MATLAB>` (version `<Enter version number>`) |
173 | | -
|
174 | | -+ DataJoint Elements |
175 | | - + Yatsenko D, Nguyen T, Shen S, Gunalan K, Turner CA, Guzman R, Sasaki M, Sitonic D, Reimer J, Walker EY, Tolias AS. DataJoint Elements: Data Workflows for Neurophysiology. bioRxiv. 2021 Jan 1. doi: https://doi.org/10.1101/2021.03.30.437358 |
176 | | -
|
177 | | - + DataJoint Elements ([RRID:SCR_021894](https://scicrunch.org/resolver/SCR_021894)) - Element Array Electrophysiology (version `<Enter version number>`) |
| 11 | +Installation and usage instructions can be found at the |
| 12 | +[Element documentation](https://datajoint.com/docs/elements/element-array-ephys). |
0 commit comments