Harmonise questionnaire items with **Harmony**.

Harmonise questionnaire items with Harmony.

Harmony is a tool for retrospective harmonisation of questionnaire items.

Do you need to compare questionnaire items across studies? Do you want to find the best match for a set of items? Are there are different versions of the same questionnaire floating around and you want to make sure how compatible they are? Are the questionnaires written in different languages that you would like to compare?

The Harmony project is a data harmonisation project that uses Natural Language Processing 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, University College London, the Universidade Federal de Santa Maria, and Fast Data Science. Harmony is funded by Wellcome as part of the Wellcome Data Prize in Mental Health.

Harmony is a project in active development and you can contribute. If you find a problem or would like a new feature, you can raise an issue on our Github.


Introduction to Harmony

Item harmonisation with natural language processing

Use Harmony in the browser

You can use Harmony on the web.
Try Harmony App
Use Harmony in the browser

Use Harmony in Python

We’ve released Harmony as an easy-to-use Python library on Pypi.
pip install harmonydata
import harmony
instruments = harmony.example_instruments["CES_D English"], 
harmony.example_instruments["GAD-7 Portuguese"]
questions, similarity, query_similarity, _ = harmony.match_instruments
# How to load a PDF, Excel or Word into an instrument
# install.packages("devtools") # If you don't have devtools installed already or CRAN is down.
# library(devtools)
# devtools::install_github("harmonydata/harmony_r")
instrument = load_instruments_from_file(path = "examples/GAD-7.pdf")
instrument_2 = load_instruments_from_file("https://medfam.umontreal.ca/wp-content/uploads/sites/16/GAD-7-fran%C3%A7ais.pdf") 
instruments = append(instrument, instrument_2)
match = match_instruments(instruments)

Harmony Docker container/API

We’ve released Harmony as a Docker container on Dockerhub, running a REST API using FastAPI.
docker pull harmonydata/harmonywithtika
docker run -p 8000:8000 -p 3000:3000 harmonydata/harmonywithtika

Our Partners


Really useful! Would have been a great tool and saved me a lot of time when I was trying to externally validate my risk prediction model in two cohorts.

Researcher at Kings College London
Researcher at Kings College London
on using Harmony the first time

Our tool, Harmony, allows researchers to upload a set of mental health questionnaires in PDF or Excel format, such as the GAD-7 anxiety questionnaire. It identifies which questions among questionnaires are identical, similar in meaning, or antonyms of each other, and generates a network graph. This allows researchers to harmonise datasets.

Uniquely, Harmony relies on Transformer neural network architectures and is not dependent on a dictionary approach or word list. This allows for multilingual support (English and Portuguese are our languages of focus), and Harmony is able to correctly map the GAD-7 used in the UK to the GAD-7 used in Brazil, despite the Brazilian questionnaire being in Brazilian Portuguese.

Using Harmony, our team was able to conduct groundbreaking research into social isolation and anxiety with NLP supplying a quantitative measure of the equivalence of the different mental health datasets.


A global platform for contextual harmonisation, translation and cooperation in mental health research

This team will support better integration of mental health research through a natural language processing harmonisation tool (Harmony), allowing researchers to compare data from existing studies to investigate the active ingredients of mental health. Led by Dr Eoin McElroy from Ulster University and Dr Bettina Moltrecht from University College London, the team will develop and demonstrate Harmony to answer research questions around human connection and its influence on the development of depression and anxiety in young people.