---
title: "MEA_well_barchart"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{MEA_well_barchart}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, include = FALSE}
library(MEAanalysis)
library(tidyverse)
knitr::opts_knit$set(root.dir = '..')
```

# Creating a bar Chart to display well average MEA burst data

The following vignette describes the workflow used to create a barchart visualisation of MEA well average burst duration data. Similar visualisations can be created for other burst parameters using different functions within the MEAanalysis package; these include the number of bursts, number of spikes per burst, and mean inter-spike interval within a burst for a given time interval of a recording. These visualisations enable the user to explore and compare extracellular field potentials occurring within a well.

Further examples and information on the arguments of each function can be found on the individual function help pages. To access these pages, please run the following code:

```{r, warning = FALSE, message = FALSE}
help(package = "MEAanalysis")
```

# Workflow

There are 4 steps to create this visualisation:

1. Load electrode burst datasets.
2. Merge electrode burst datasets.
3. Calculate MEA parameters for specific time intervals of a recording.
4. Create barchart of well average burst data for a specific parameter.

# 1. Load electrode burst datasets

First, electrode burst csv files need to be processed and loaded into the R environment. This can be done using the MEAanalysis:: create_electrode_dataset function, which reads in, filters, and reformats the data for use in analysis. This function is compatible with electrode burst csv files produced by the axis navigator tool (Axion Biosystems). As demonstrated in the below example, the user should assign the data table to an object name so that it is accessible from the R environment. The user should update the data path with respect to their current working directory. The user should also provide a unique identifier for the loaded recording; this will be used by other MEAanalysis functions to filter the data and calculate burst parameters. This step should be done for all MEA recordings the user wishes to include in the analysis.

```{r, warning = FALSE, message = FALSE}
burst_recording_1 <- create_electrode_dataset(
  data_path = system.file("extdata", "input_electrode_burst.csv", package = "MEAanalysis"), 
  recording_identifier = "burst_recording_1")

# view first 10 lines of dataset

head(burst_recording_1, 10)
```

```{r, warning = FALSE, message = FALSE}
burst_recording_2 <- create_electrode_dataset(
  data_path = system.file("extdata", "comparison_agonist_challenge_electrode_burst_list.csv", package = "MEAanalysis"), 
  recording_identifier = "burst_recording_2")

# view first 10 lines of dataset

head(burst_recording_2, 10)
```

# 2. Merge electrode burst datasets

The electrode burst data tables for each individual MEA recording should then be merged vertically. This can be done using the rbind() function, as demonstrated below. The user should update this function to include the data table object names assigned when loading the electrode burst data into the R environment. As shown in the below example, the MEA recording which the burst data belongs too can still be identified using the ‘Recording_identifier’ column.


```{r}
output_table <- rbind(burst_recording_1, burst_recording_2)

# view first 10 lines of dataset

head(output_table, 10)
```

# 3. Calculate MEA parameters for specific time intervals of a recording

Columns containing information regarding the mean, standard deviation (SD), and standard error of the mean (SEM) for a specific MEA burst parameter should then be calculated and added to the merged electrode burst data table. This should be done for defined time intervals of specified MEA recordings. These calculated columns can then be plotted in the barchart visualisation, grouped by well. The MEAanalysis package contains functions which calculate these measures for burst duration, number of bursts, number of spikes per burst, and mean inter-spike interval within a burst.

In the below example, the merged electrode burst data table (‘output_table’) is assigned as a new object in the R environment (‘analysis_dataset’); this enables the user to refresh and remove any calculated columns from the analysis_dataset by rerunning this line of code. Using the MEAanalysis::well_burst_duration function, the mean, SD, and SEM burst duration within each well are then calculated for defined time intervals of an MEA recording. Additional columns are added to the analysis_dataset each time this function is run. Alternatively, the well_mean_burst_ISI, well_number_of_bursts, and well_spikes_per_burst functions from the MEAanalysis package can be used to respectively calculate these measures for mean inter-spike interval within a burst, number of bursts, and number of spikes per burst.

```{r}
# assign the 'output_table' data table object created above to a different object name 'analysis_dataset'
# this means that when columns are added to the 'analysis_dataset' the data table can be refreshed by rerunning this line of code
analysis_dataset <- output_table

# add burst duration calculated columns for defined time intervals to the 'analysis_dataset' 
analysis_dataset <- well_burst_duration(data = analysis_dataset, 0, 60, recording_identifier = "burst_recording_1")
analysis_dataset <- well_burst_duration(data = analysis_dataset, 0, 60, recording_identifier = "burst_recording_2")
analysis_dataset <- well_burst_duration(data = analysis_dataset, 60, 120, recording_identifier = "burst_recording_1")
analysis_dataset <- well_burst_duration(data = analysis_dataset, 60, 120, recording_identifier = "burst_recording_2")
```

```{r, echo = FALSE}
# view first 10 lines of analysis dataset

knitr::kable(analysis_dataset[1:10,]) %>% kableExtra::scroll_box(width = "100%")
```

# 4. Create barchart of well average burst data for a specific parameter

The analysis dataset created above can then be used as an input for the MEAanalysis: well_barchart function. This function will create a barchart of the well average for a specified MEA parameter, grouped by time interval of a recording.  The user should define which burst parameter they wish to visualise using the well_parameter argument. The user may also filter for specific wells using the well_filter argument and decide whether the error bars represent SD or SEM using the statistic argument.

```{r, warning = FALSE, fig.height = 5, fig.width = 7}
p <- well_barchart(data = analysis_dataset, 
                   well_parameter = "burst_duration", 
                   well_filter = "A1|A2|A3|A4", 
                   statistic = se)
print(p)
```
As the underlying code for the well_barchart function utilises ggplot2, the user can add layers of code to personalise the output further.

```{r, warning = FALSE, fig.height = 5, fig.width = 7}
p <- p + 
  scale_fill_grey() +
  ggtitle("A barchart to show MEA well average burst duration 
          within a given time period")

print(p)

```