Analysis
Load the package
Start by loading the package.
Establish analysis settings
Provide the path to the IDOC session you want to analyze. In this vignette, we will use an example dataset packaged together with the code.
Give names to treatments A and B placeholders -> See paradigms section
Optionally provide a description that briefly documents or describes the session.
Minimal number of exits required to consider the data of one animal significant and so, compute a preference index based on the behavior.
Optionally, apply a time offset to the treatment time series to account for the time it takes for odour to arrive to the chambers. In seconds.
Carefully define a distance from the center of the chamber to the decision zone, in mm
Caution The choice of border_mm can
have a big impact in the interpretation of the results. You should
define it based on empirical evidence that within this distance from the
center of the chambers, both treatments are mixed. We found that to be 5
mm either side based on tests with smoke.
Ignore exits happening this amount of seconds after the previous exit to avoid counting the same exit as two exits happening within ridiculously little time.
Generate analysis_params.yaml by providing 3 numbers:
pixel_to_mm_ratio: Number of pixels that make up 1 mm in
your setup. Simply place a ruler and count how many pixels cover 1 mm,
or 1 cm and divide by 10.
limits: mm away from the center to the left (negative)
or right (positive) to be included in the plot. For example:
analysis_params.yaml
pixel_to_mm_ratio: 2.3
limits:
- -70
- 70Run the analysis
src_file <- rstudioapi::getActiveDocumentContext()$path
p1 <- idocr(
experiment_folder = experiment_folder,
treatments = c(
TREATMENT_A = treatment_A,
TREATMENT_B = treatment_B
),
border_mm = border_mm,
min_exits_required = min_exits_required,
src_file = src_file,
subtitle = description,
delay = delay,
mask_duration = mask_duration
)
#> Backing up script ->/home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/script_idocr2.R
#> Loading dataset <- /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Animal 6 is missing
#> Animal 10 is missing
#> Preprocessing dataset - /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Reading /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/2020-11-01_10-11-31_7eb8e224bdb944a68825986bc70de6b1_ROI_CENTER.csv
#> Reading configuration from analysis_params.yaml
#> Warning in check_api_version(treatments): Passing named treatments is deprecated.
#> Your code will still work fine, but you should provide the treatment name
#> (OCT, ...) via the labels argument in idocr::idocr.
#> In that case, the labels are assigned in alphabetic order to the treatments
#> i.e. the first label goes to TREATMENT_A and the second to B
#>
#> Analysing dataset - /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Preparing controller data
#> Detecting decision zone exits i.e. crosses
#> Assigning sign to exits (appetitive or aversive)
#> Computing channel-wise preference index
#> Joining with `by = join_by(id, region_id)`
#> Plotting dataset ->
#> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Validating passed data
#> Generating facet labels
#> Marking controller events
#> Generating base plot
#> Marking decision zone
#> Marking decision zone crosses
#> Documenting plot
#> Saving plot to
#> ->/home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Saving pdf format
#> Warning: Removed 2 rows containing missing values (`geom_line()`).
#> Saving png format
#> Warning: Removed 2 rows containing missing values (`geom_line()`).
#> Exporting results -> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Saving PI -> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/2020-11-01_10-11-31_7eb8e224bdb944a68825986bc70de6b1_PI.csv
#> Saving SUMMARY -> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/2020-11-01_10-11-31_7eb8e224bdb944a68825986bc70de6b1_SUMMARY.csvThis function will generate a plot and a .csv dataset. The plot is saved as .png and .pdf.
The plot displays the trajectory of the fly contained in each of the
20 ROIs of the experiment in one panel. The panel displays time along
the Y axis and position along the X dimension of the chamber, in the X
axis. Time starts at the top, and flows downwards. The black line
represents the trajectory of the fly. The dashed line represents the
computed decision zone, based on the _ROI_CENTERS.csv file
and the border_mm parameter. Whenever the trajectory of the
fly crosses from inside to outside of the decision zone, the software
quantifies that as a preference decision, and the plot reflects that
with a marker. The marker is a circle when the decision displays
preference for treatment A, and a cross when for treatment B. At the top
of each panel, the software collects the preference index
(PI) for treatment A obtained by the animal in the
session. It reflects how strong is the preference for A or the aversion
for B, and it goes from -1 to 1. -1 indicates strong preference for B
and +1 strong preferenece for A. The preference index is computed with
the following formula:
\[
\frac{exits_{A} - exits{B}}{exits_{A}+exits{B}}
\] This information is also saved to the mentioned .csv dataset,
called YYYY-MM-DD_HH-MM-SS_machine-id_PI.csv. It contains
one row per ROI, summarizing the decisions of the corresponding
animal.
region_id: indicates the ROI.
appetitive: number of exits towards the side of the
chamber exposed to treatment A.
aversive: number of exits towards the side of the
chamber exposed to treatment B.
preference_index: statistic computed using the formula
above.
test: the first 5 characters that make up the result
folder. See analysis mask section on how to modify it from R.
id,region_id,appetitive,aversive,preference_index,test
2020-11-01_10-11-31_7eb8e|02,2,2,2,0,Analysis mask
If you wish to compute multiple PI for the same fly within the same
session, you can provide a named list called analysis_mask
to partition the session. Each entry in the analysis_mask
must be a vector of length 2 with the start and end time of the selected
mask, in seconds. If you indeed provide an analysis_mask
then a sub folder will be created in the experiment folder for every
provided mask. The name of the folder will follow the name you give in
the list, and it will contain the plots and a PI computation using only
the exits within the mask.
For example, if we wish to count only exits in the first half of the exposure to treatments A and B:
analysis_mask <- list(
first_half = c(60, 105)
)
src_file <- rstudioapi::getActiveDocumentContext()$path
p1 <- idocr(
experiment_folder = experiment_folder,
treatments = c(
TREATMENT_A = treatment_A,
TREATMENT_B = treatment_B
),
border_mm = border_mm,
min_exits_required = min_exits_required,
src_file = src_file,
subtitle = description,
delay = delay,
mask_duration = mask_duration,
analysis_mask=analysis_mask
)
#> Backing up script ->/home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/script_idocr2.R
#> Loading dataset <- /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Animal 6 is missing
#> Animal 10 is missing
#> Preprocessing dataset - /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Reading /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/2020-11-01_10-11-31_7eb8e224bdb944a68825986bc70de6b1_ROI_CENTER.csv
#> Reading configuration from analysis_params.yaml
#> Warning in check_api_version(treatments): Passing named treatments is deprecated.
#> Your code will still work fine, but you should provide the treatment name
#> (OCT, ...) via the labels argument in idocr::idocr.
#> In that case, the labels are assigned in alphabetic order to the treatments
#> i.e. the first label goes to TREATMENT_A and the second to B
#>
#> Analysing dataset - /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31 first_half
#> Preparing controller data
#> Detecting decision zone exits i.e. crosses
#> Assigning sign to exits (appetitive or aversive)
#> Computing channel-wise preference index
#> Joining with `by = join_by(id, region_id)`
#> Plotting dataset ->
#> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Validating passed data
#> Generating facet labels
#> Marking controller events
#> Generating base plot
#> Marking analysis mask
#> Marking decision zone
#> Marking decision zone crosses
#> Documenting plot
#> Saving plot to
#> ->/home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Saving pdf format
#> Warning: Removed 2 rows containing missing values (`geom_line()`).
#> Saving png format
#> Warning: Removed 2 rows containing missing values (`geom_line()`).
#> Exporting results -> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31
#> Saving PI -> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/first_half/2020-11-01_10-11-31_7eb8e224bdb944a68825986bc70de6b1_PI_first_half.csv
#> Saving SUMMARY -> /home/vibflysleep/R/x86_64-pc-linux-gnu-library/4.1/idocr/extdata/2020-11-01_10-11-31/first_half/2020-11-01_10-11-31_7eb8e224bdb944a68825986bc70de6b1_SUMMARY_first_half.csvThis can be useful if you perform more than 1 preference test in the same session (for example test two odors and then flip sides) and you wish to consider them as independent observations of preference.