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 in active development and you can contribute.

Raise NLP issue

Raise an issue with Harmony's natural language understanding.

Raise UI issue

Rise an issue with Harmony's user interface and graphics.


Join our Discord server.


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, so you can incorporate Harmony into your data harmonisation workflow.
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

Use Harmony in R

R users can now import Harmony as an R package for data harmonisation.
# 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/harmonyapi
docker run -p 8000:8000 -p 3000:3000 harmonydata/harmonyapi

Our Partners

Mental Health Catalogue

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 times

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 data harmonisation (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 harmonise multilingual datasets and 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

We aim to promote better integration of data harmonisation in 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.

Signup to our newsletter

The latest news on data harmonisation project.

Please select all the ways you would like to hear from Harmony project:

You can unsubscribe at any time by clicking the link in the footer of our emails. For information about our privacy practices, please visit our website. We use Mailchimp as our marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp's privacy practices.