harmony_r_example.Rmd

---
title: Harmony R Walkthrough
output:
  html_document:
    df_print: paged
---

# Harmony walkthrough - R library

![](https://raw.githubusercontent.com/harmonydata/brand/main/Logo/PNG/%D0%BB%D0%BE%D0%B3%D0%BE%20%D1%84%D1%83%D0%BB-05.png)

This notebook shows how you can use Harmony to find the similarity matrix between two questionnaires.
  
The Harmony project is a data harmonisation project that uses [Natural Language Processing](https://fastdatascience.com/guide-natural-language-processing-nlp/) to help researchers make better use of existing data from different studies by supporting them with the harmonisation of various measures and items used in different studies.

Harmony is a collaboration project between [Ulster University](https://ulster.ac.uk/), [University College London](https://ucl.ac.uk/), the [Universidade Federal de Santa Maria](https://www.ufsm.br/), and [Fast Data Science](http://fastdatascience.com/).  Harmony is funded by [Wellcome](https://wellcome.org/) as part of the [Wellcome Data Prize in Mental Health](https://wellcome.org/grant-funding/schemes/wellcome-mental-health-data-prize).

First let's install and import Harmony. If you haven't already, you need to install it with `install.packages("harmonydata")`.

```{r}
#install.packages("harmonydata")
```

```{r}
library(harmonydata)
```
```{r, echo=FALSE}
#set_url("localhost:8000")
```

Now we can create our instruments.

If you had everything in a PDF or Excel file, you could load the instruments directly from the file: `instrument = load_instruments_from_file(path = "CBCL_GOASSESS.xlsx")`.
In this example we will load two questionnaires from Harmony's database and manually input a third questionnaire.

First we load the instruments from Harmony's database:

```{r}
example_instruments <- get_example_instruments()
names(example_instruments)
```

Let's use the CES-D English, GAD-7 Portuguese and create a GAD-7 Norwegian instrument.

```{r}
ces_d_english <- example_instruments[["CES_D English"]]
gad_7_portuguese <- example_instruments[["GAD-7 Portuguese"]]

gad_7_norwegian <- create_instrument_from_list(
    list(
        "Følt deg nervøs, engstelig eller veldig stresset",
        "Ikke klart å slutte å bekymre deg eller kontrolleren bekymringene dine"
    ),
    instrument_name = "GAD-7 Norwegian"
)
```

We can concatenate our instruments together:

```{r}
instruments_list <- list(ces_d_english, gad_7_portuguese, gad_7_norwegian)
```

Let’s call Harmony to calculate the match:

```{r}
match <- match_instruments(instruments_list, topics=list("anxiety", "depression", "bother"))
```

We also

```{r}
help(match_instruments)
```

**Check** what has come out of the match:

```{r}
names(match)
```

The first question is CES_D English question 1.

```{r}
match$questions[[1]]
```

The total number of questions is:

```{r}
length(match$questions)
```

We can view the first few rows of the similarity matrix for the questions.

```{r}
head(match$matches)
```

We can also plot a heat map of the questions similarity matrix. Please bare in mind however that R will compress the matrix to fit the size of the plotting area, which may reduce the visible resolution for large matrices.

```{r}
heatmap(as.matrix(match$matches), 
        Rowv = NA, Colv = NA, main = "Questions Similarity Matrix",
        margins = c(10, 10))
```

We can view the first few rows of the similarity matrix for the response options.

```{r}
head(match$response_options_similarity)
```

We can also plot a heat map of the response options similarity matrix.

```{r}
heatmap(as.matrix(match$response_options_similarity),
        Rowv = NA, Colv = NA, main = "Response Options Similarity Matrix",
        margins = c(10, 10))
```

## Generate a Crosswalk table

We can generate a crosswalk table to match questions with a cosine similarity above a certain threshold.

```{r}
threshold <- 0.7

df_crosswalk_table <- generate_crosswalk_table(
    match$instruments,
    match$matches,
    threshold,
    is_allow_within_instrument_matches = TRUE,
    is_enforce_one_to_one = TRUE
)

df_crosswalk_table
```

## Cluster the questions

Display the clusters and cluster keywords that come out of Harmony by default.

```{r}
for (i in seq_along(match$clusters)) {
    print(paste0("Cluster ", match$clusters[[i]]$cluster_id, ": ", match$clusters[[i]]$text_description))

    keywords <- c()
    for (j in seq_along(match$clusters[[i]]$keywords)) {
        keywords <- c(keywords, match$clusters[[i]]$keywords[[j]])
    }
    keywords_output <- paste("Keywords:", paste(keywords, collapse = ", "))
    print(keywords_output)

    for (j in seq_along(match$clusters[[i]]$item_ids)) {
        id <- match$clusters[[i]]$item_ids[[j]]
        print(paste("    ", match$questions[[id]]$question_text))
    }
}
```

We can also choose between different clustering algorithms for the matcher to use.

```{r}
match <- match_instruments(instruments_list, clustering_algorithm = "kmeans")

for (i in seq_along(match$clusters)) {
    print(paste0("Cluster ", match$clusters[[i]]$cluster_id, ": ", match$clusters[[i]]$text_description))

    keywords <- c()
    for (j in seq_along(match$clusters[[i]]$keywords)) {
        keywords <- c(keywords, match$clusters[[i]]$keywords[[j]])
    }
    keywords_output <- paste("Keywords:", paste(keywords, collapse = ", "))
    print(keywords_output)

    for (j in seq_along(match$clusters[[i]]$item_ids)) {
        id <- match$clusters[[i]]$item_ids[[j]]
        print(paste("    ", match$questions[[id]]$question_text))
    }
}
```

## Display the similarities between instruments

Let's display the similarities between the instruments.

```{r}
for (i in seq_along(match$instrument_to_instrument_similarities)) {
    obj <- match$instrument_to_instrument_similarities[[i]]
    print(paste("F1 similarity of", obj$instrument_1_name, "to", obj$instrument_2_name, "is", obj$f1))
}
```

## Saving to CSV/Excel

We can simply export the `match$matches` data frame to a CSV file.

```{r}
write.csv(match$matches, "matches.csv")
```

Similarly we can export `df_crosswalk_table`.

```{r}
write.csv(df_crosswalk_table, "crosswalk_table.csv")
```

If you open the CSV generated, you can see the complete matrix. You can also open in Excel.

You can also see the file in Google Colab online by going into the file system on the left panel (see below screenshot).

![Screenshot](https://raw.githubusercontent.com/harmonydata/experiments/main/csv_colab.png)

Let's take a look at the first few lines of the CSV file using the Bash command `head`:

```{r}
#system("head matches.csv", intern = TRUE)
```