-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path1_Prepare-a-SLAV_config.toml
226 lines (212 loc) · 7.74 KB
/
1_Prepare-a-SLAV_config.toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
# --------------------------
# --- What is this file? ---
# --------------------------
# This file contains instructions for Prepare-a-SLAV on which files to process,
# some configuration options which will be described individually throughout
# this config file, and, finally, the description of your experimental setup in
# terms of cage mappings (definitions of which MIROSLAV "PHL" inputs correspond
# to which cage as labelled in your experimental protocol).
# This file uses the TOML format.
# --------------------
# --- ID variables ---
# --------------------
# MIROSLAV raw log files have a defined name structure which the script uses
# to appropriately organise the data. These are the experiment and device
# names, as defined in the MIROSLAV devices' Arduino "config.h" file, and
# then appropriately specified in "Record-a-SLAV.py". Therefore, these names
# are also visible in filenames of raw logs themselves, which use the
# following structure:
# [experiment name]-[log type]-[device name].[timestamp].gz
# Names of the experiment and the devices used in that experiment correspond
# to those specified to MIROSLAV devices themselves in their Arduino config.h
# files upon uploading Arduino code. The log type may be either "pir" for data
# recorded from cage-mounted PIR sensors, or "env" for environmental data
# recorded from the habitat room. The timestamp is dynamically generated by
# Record-a-SLAV, and is used by Prepare-a-SLAV to sort the logs in order.
# In our example files, a raw log filename looks like this:
# mph-pir-rack_R.2022-05-06T19-19-57-667479.gz
# So we set the ID variables accordingly:
[id_variables]
# All filenames start with the experiment name:
experiment = "mph"
# We will define the devices used in the experiment at the bottom,
# along with the mapping of their inputs to cages.
# --------------------------------
# --- Processing configuration ---
# --------------------------------
# Here, we can adjust how Prepare-a-SLAV processes the data.
# This variable can be "true" or "false". If set to "true", the script will
# parse timestamps and values in the dataframe from strings to numerical types
# (integers and timestamps). This is useful for further processing of the data,
# and necessary for resampling, but slows down the script somewhat.
[processing_params]
set_dtypes = true
# This variable can be "true" or "false". If set to "true", the script will
# resample the data to the frequency specified in the "resample_bin" variable.
# This means that multiple values of each animal will be merged into one based
# on the means of those values. "resample_bin" controls how many values are
# merged into one ("binned") based on a timeframe. This process is slow, but very
# useful to reduce the size of the data and to make it easier to work with.
resample = true
# This variable can be specified as a human-readable string, such as "1 minute",
# "15 minutes", "4 hours", etc. If you use a higher frequency, the data will
# effectively be "downsampled" (i.e. fewer values will be present in the data),
# which means that the data will be less detailed, but also smaller in size.
# Wider bins give you easy insight into general trends across longer time periods,
# while narrower bins give you more detailed insight into the data. You can run
# the script multiple times to resample the data to different frequencies, e.g.
# first at "4 hours" to see general trends, and then to "15 minutes" to be able
# to analyse interesting periods in more detail.
resample_bin = "1 minute"
# --------------------------
# --- Experimental setup ---
# --------------------------
# Here, we describe how our cages were hooked up to the MIROSLAV devices
# In this example experiment, we use two MIROSLAV devices, one attached to
# rack M (middle), and the other to rack R (right). Rack M has 3 input boards,
# and Rack R has 2 input boards. Each board always has 8 inputs, and one cage
# sensor array is hooked to each of the inputs. They are labelled in the
# MIROSLAV device and code as PH0 to PH7, and we want to assign human-readable
# labels that we've also used in our entire experimental protocol.
# --- How to define the setup in this file? ---
# So, an appropriate structure looks like this:
#
# mph
# ├── rack M
# │ ├── top_board
# │ │ ├── PHL0 ──── zeleni1
# │ │ ├── PHL1 ──── zeleni2
# │ │ ├── PHL2 ──── zeleni3
# │ │ ├── PHL3 ──── zeleni4
# │ │ ├── PHL4 ──── zeleni5
# │ │ ├── PHL5 ──── zeleni6
# │ │ ├── PHL6 ──── zeleni7
# │ │ └── PHL7 ──── zeleni8
# │ ├── board_1
# │ │ ├── PHL0 ──── zeleni9
# │ │ ├── ...
# │ │ └── PHL7 ──── crveni6
# │ └── board_2
# │ ├── PHL0 ──── crveni7
# │ ├── ...
# │ └── PHL7 ──── na4
# └── rack R
# ├── top_board
# │ ├── PHL0 ──── na5
# │ ├── ...
# │ └── PHL7 ──── crni5
# └── board_1
# ├── PHL0 ──── crni6
# ├── ...
# └── PHL7 ──── crni10
#
# A couple of things to note:
# i. Everything is nested under the "mph" key, where "mph" is the name of the
# experiment.
# ii. All devices have a "top_board" key, which is the topmost board in the input
# stack.
# iii. All additional boards are named "board_N", where N is an integer starting
# from 1.
# iv. Each boards' 8 inputs have their experimental labels written in extension.
# As we are SLAVs, the cage labels in this example are in Croatian :)
# v. If an input is disconnected on one of the daughterboards, the label needs to
# be "naN", where N is an integer (e.g. na1, na2, na5...).
# vi. Each device has a "process" flag, which can be set to true or false. This
# enables you to define many configurations in this file, but select the ones
# you want processed by Prepare-a-SLAV in the following steps.
#
# After this, hopefully, it will make sense how the rest of the config file below
# matches to a custom experimental setup.
[mph.rack_M]
process = true
[mph.rack_M.top_board]
PHL0 = "zeleni1"
PHL2 = "zeleni2"
PHL1 = "zeleni3"
PHL3 = "zeleni4"
PHL4 = "zeleni5"
PHL5 = "zeleni6"
PHL6 = "zeleni7"
PHL7 = "zeleni8"
[mph.rack_M.board_1]
PHL0 = "zeleni9"
PHL1 = "zeleni10"
PHL2 = "crveni1"
PHL3 = "crveni2"
PHL4 = "crveni3"
PHL5 = "crveni4"
PHL6 = "crveni5"
PHL7 = "crveni6"
[mph.rack_M.board_2]
PHL0 = "crveni7"
PHL1 = "crveni8"
PHL2 = "crveni9"
PHL3 = "crveni10"
PHL4 = "na1"
PHL5 = "na2"
PHL6 = "na3"
PHL7 = "na4"
[mph.rack_R]
process = true
[mph.rack_R.top_board]
PHL0 = "na5"
PHL1 = "crni1"
PHL2 = "na6"
PHL3 = "crni2"
PHL4 = "crni3"
PHL5 = "crni4"
PHL6 = "na7"
PHL7 = "crni5"
[mph.rack_R.board_1]
PHL0 = "crni6"
PHL1 = "na8"
PHL2 = "na9"
PHL3 = "crni7"
PHL4 = "crni8"
PHL5 = "crni9"
PHL6 = "na10"
PHL7 = "crni10"
# Example column map for a MIROSLAV device with an input stack
# containing three input boards.
[exp_e1.example_3boards]
process = false
[exp_e1.example_3boards.top_board]
PHL0 = ""
PHL2 = ""
PHL1 = ""
PHL3 = ""
PHL4 = ""
PHL5 = ""
PHL6 = ""
PHL7 = ""
[exp_e1.example_3boards.board_1]
PHL0 = ""
PHL1 = ""
PHL2 = ""
PHL3 = ""
PHL4 = ""
PHL5 = ""
PHL6 = ""
PHL7 = ""
[exp_e1.example_3boards.board_2]
PHL0 = ""
PHL1 = ""
PHL2 = ""
PHL3 = ""
PHL4 = ""
PHL5 = ""
PHL6 = ""
PHL7 = ""
# Example column map for a MIROSLAV device with an input stack
# containing one input board.
[exp_e2.example_1board]
process = false
[exp_e2.example_1board.top_board]
PHL0 = ""
PHL2 = ""
PHL1 = ""
PHL3 = ""
PHL4 = ""
PHL5 = ""
PHL6 = ""
PHL7 = ""