---
title: "MEA_synchrony_index_heatmap"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{MEA_synchrony_index_heatmap}
  %\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 Heat Map of Multi-electrode Array Well Synchrony Index

The following vignette describes the workflow used to create a heat map visualisation of the well average synchrony index recorded by a multi-electrode array (MEA). The purpose of this visualisation is to compare the synchronicity of excitable cells in different experimental conditions, for example before and after addition of a pharmacological agent during an MEA recording.

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 3 steps to create this heatmap visualisation:

1. Load neural metric dataset outputs for each experimental condition.
2. Merge and reformat neural metric datasets.
3. Create a heat map of well average synchrony index.

# 1. Load neural metric dataset outputs for each experimental condition.

First, the user should use the axis navigator and neural metric tools (Axion Biosystems) to generate neuralMetric csv files containing information related to network synchrony. This should be done for each experimental condition the user wishes to include in the heatmap analysis. For example, the user may generate separate csv files for before or after an agonist challenge during an experiment. These neuralMetric csv files need to be processed and loaded into the R environment. This can be done using the MEAanalysis:: create_synchrony_dataset function, which reads in, filters, and reformats the data for use in analysis. 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 experimental condition the neuralMetric csv file is associated with in the function's heatmap_condition argument.

```{r, warning = FALSE, message = FALSE}
baseline_data <- create_synchrony_dataset(
  data_path = system.file("extdata", "input_neuralMetric.csv", package = "MEAanalysis"), 
  heatmap_condition = "Baseline")

# view first 10 lines of dataset
head(baseline_data, 10)
```
```{r, warning = FALSE, message = FALSE}
agonist_challenge_data <- create_synchrony_dataset(
  data_path = system.file("extdata", "comparison_agonist_challenge_neuralMetrics.csv", package = "MEAanalysis"),
  heatmap_condition = "Agonist Challenge")

# view first 10 lines of dataset
head(agonist_challenge_data, 10)
```

# 2. Merge and reformat neural metric datasets.

The neuralMetric datasets for each experimental condition should then be merged. This can be done using the reduce() function, as demonstrated below. The user should update the df_list to include the data table object names assigned when loading the neuralMetric data into the R environment. As shown in the below example, the column titles will ensure the heatmap condition can still be identified.  

```{r}
df_list <- list(baseline_data, agonist_challenge_data)
heatmap_data <- df_list %>%
  reduce(full_join, by = 'Well')

# view first 10 lines of dataset
head(heatmap_data, 10)
```

# 3. Create a heat map of well average synchrony index.

The heatmap dataset created above can then be used as an input for the MEAanalysis: MEA_heatmap function. This function will create a heatmap of the well average synchrony index grouped by experimental condition. The function contains a 'well_filter' argument enabling the user to filter by specific well.

```{r, warning = FALSE, fig.height = 5, fig.width = 7}
p <- MEA_heatmap(data = heatmap_data, 
            x_axis_title = "Experimental Condition", 
            well_filter = "A1|A2|A3|A4|A5|A6|B1|B2|B3|B4|B5|B6|C1|C2|C3|C4|C5|C6|D1|D2|D3|D4|D5|D6")
print(p)
```


As the underlying code for the MEA_heatmap 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 + 
  ggtitle("A heatmap to show the average synchrony index for an MEA well")

print(p)

```











