# event_extractor()

## Introduction

The proprietary data output format from the ‘MED-PC’ software suite for experimental chambers is often coded in a `time.event` manner, in which users assign arbitrary numeric codes for each type of event, such that when analyzing the data there are specific events marking the start and end of each individual trail.

Here we present a function to slice ‘MED-PC’ data based on start and end events. This function should be used after `read_med()`, which outputs a data frame or/and `.csv` (depending on how it’s used) with 2 columns: time and events (in that order). The function returns a data frame with n x 4 columns:

- `time`: the time of the event.
- `events`: the event numeric ID.
- `cum_id`: the index of each extracted trail (note that these will be in a i·2+1 sequence due how the internal processing is done).
- `evname`: the assigned identifier for the extracted trails.

The `event_extractor()` function include the following parameters:

- `data_df`: a data frame of n rows x 2 columns, where columns corresponds to time and events IDs, in that order.
- `ev0`: start event ID (where the trials we want to extract begins).
- `ev1`: end event ID (where the trials we want to extract ends).
- `evname`: a string for the event name, for identification purposes.

## Example

First let’s load a raw ‘MED-PC’ file from an experimental session and assign it to a data frame:

    data("fi60_raw_from_med")
    temp_file <- tempfile(fileext = ".txt")
    writeLines(fi60_raw_from_med, temp_file)

    example_processed <- read_med(
      fname = temp_file, save_file = FALSE,
      path_save = path_to_save, col_r = "C:", out = TRUE,
      col_names = c("time", "event"), num_col = 6, time_dot_event = TRUE
    )

    head(example_processed, 10)

    ##    time event
    ## 1     9    12
    ## 2    32    12
    ## 3    36    12
    ## 4    39    12
    ## 5    42    12
    ## 6    48    12
    ## 7    67    12
    ## 8    68    12
    ## 9    70    12
    ## 10   83    11

In this specific example session we have four types of trials:

- FI15 with start code 5 and end code 3
- FI30 with start code 55 and end code 33
- Peak 15s with start code 4 and end code 41
- Peak 30s with start code 44 and end code 42

If we wanted to extract the FI15 trials, we would do it like this:

    extracted_FI15 <- event_extractor(
      data_df = example_processed,
      ev0 = 5, ev1 = 3,
      evname = "IF15"
    )

    head(extracted_FI15, 30)

    ##    time event cum_id evname
    ## 65 1442     5      1   IF15
    ## 66 1612    12      1   IF15
    ## 67 1613    12      1   IF15
    ## 68 1616    12      1   IF15
    ## 69 1630    12      1   IF15
    ## 70 1632    12      1   IF15
    ## 71 1809    12      1   IF15
    ## 72 1811    12      1   IF15
    ## 73 1813    12      1   IF15
    ## 74 1816    12      1   IF15
    ## 75 1818    12      1   IF15
    ## 76 1821    12      1   IF15
    ## 77 1823    12      1   IF15
    ## 78 1827    12      1   IF15
    ## 79 1828    12      1   IF15
    ## 80 1891    12      1   IF15
    ## 81 1892    12      1   IF15
    ## 82 1894    12      1   IF15
    ## 83 1895    12      1   IF15
    ## 84 1897    12      1   IF15
    ## 85 1945     1      1   IF15
    ## 86 1950    12      1   IF15
    ## 87 1959    12      1   IF15
    ## 88 1966    12      1   IF15
    ## 89 1981     1      1   IF15
    ## 90 1985    12      1   IF15
    ## 91 1996    12      1   IF15
    ## 92 2038     1      1   IF15
    ## 93 2043     1      1   IF15
    ## 94 2045     1      1   IF15

Now let’s assume we want to extract all four types of trails and store them in separated data frames. We can do that using a `for` cycle like this:

    extracted_trials_df <- list() # A list to store the resulting data frames.

    param_list <- list( # A list of parameters for each trial type.
      list(ev0 = 5, ev1 = 3, evname = "IF15"),
      list(ev0 = 55, ev1 = 33, evname = "IF30")
    )

    for (parameters in param_list) {
      trial_df <- event_extractor(
        data_df = example_processed,
        ev0 = parameters$ev0,
        ev1 = parameters$ev1,
        evname = parameters$evname
      )
      extracted_trials_df[[length(extracted_trials_df) + 1]] <- trial_df # Store the extracted data frame in the data frames list.
    }

Here’s a preview of how each data frame would look like:

    ## Data frame 1 :
    ##    time event cum_id evname
    ## 65 1442     5      1   IF15
    ## 66 1612    12      1   IF15
    ## 67 1613    12      1   IF15
    ## 68 1616    12      1   IF15
    ## 69 1630    12      1   IF15
    ## Data frame 2 :
    ##      time event cum_id evname
    ## 529 13115    33      1   IF30
    ## 530 13132    12      1   IF30
    ## 531 13155    12      1   IF30
    ## 532 13157    12      1   IF30
    ## 533 13159    12      1   IF30

After this process you can analyze each trial data separately in whichever way you need.