{"id":23632204,"url":"https://github.com/harmonydata/harmony_r","last_synced_at":"2025-04-09T23:32:39.994Z","repository":{"id":182797899,"uuid":"669116698","full_name":"harmonydata/harmony_r","owner":"harmonydata","description":"R library for Harmony. R package - open source tool using AI for psychology and mental health. Actively recruiting contributors.","archived":false,"fork":false,"pushed_at":"2025-03-13T12:48:39.000Z","size":1158,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T01:22:46.873Z","etag":null,"topics":["ai","cran","data-science","help-wanted","multilingual-nlp","natural-language-processing","nlp","psychology","r"],"latest_commit_sha":null,"homepage":"https://harmonydata.ac.uk","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harmonydata.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-21T11:34:26.000Z","updated_at":"2025-03-13T12:48:43.000Z","dependencies_parsed_at":"2024-12-28T03:28:05.703Z","dependency_job_id":"655bda9f-6d3e-4864-b681-394451df85fa","html_url":"https://github.com/harmonydata/harmony_r","commit_stats":null,"previous_names":["harmonydata/harmony_r"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonydata%2Fharmony_r","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonydata%2Fharmony_r/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonydata%2Fharmony_r/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonydata%2Fharmony_r/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harmonydata","download_url":"https://codeload.github.com/harmonydata/harmony_r/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248129593,"owners_count":21052601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cran","data-science","help-wanted","multilingual-nlp","natural-language-processing","nlp","psychology","r"],"created_at":"2024-12-28T03:27:59.739Z","updated_at":"2025-04-09T23:32:39.981Z","avatar_url":"https://github.com/harmonydata.png","language":"HTML","readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n![](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)\n\n# Harmony R library: harmonydata\n\n\nYou can also **join our [Discord server](https://discord.gg/harmonydata)!**  \nIf you found Harmony helpful, you can [leave us a review](https://g.page/r/CaRWc2ViO653EBM/review)!  \n\n## 🧠 What Does Harmony Do?\n\nPsychologists and social scientists often have to **match items** in different questionnaires, such as:  \n\n\u003e *\"I often feel anxious\"*  \n\u003e *\"Feeling nervous, anxious or afraid\"*\n\nThis process is called **harmonisation**.\n\n### 🔹 The Problem\n- Harmonisation is a **time-consuming** and **subjective** process.  \n- Researchers have to **manually go through long PDFs** of questionnaires.  \n- Extracting questions and putting them into **Excel** is tedious.  \n\n### 🔹 The Solution: Harmony  \n🚀 **Harmony** uses **natural language processing (NLP)** and **generative AI models** to:\n- Automatically **match similar questionnaire items**.  \n- Help researchers work across **multiple languages**.  \n- Save **time** and **effort** in data harmonisation.\n\n\n## 📂 Looking for Examples?  \n\nCheck out our **[examples repository](https://github.com/harmonydata/harmony_examples)** for hands-on demonstrations.  ## 🌍 The Harmony Project  \n\n**Harmony** is an **AI-powered tool** that helps researchers **compare items from questionnaires** and **identify similar content**.  \n\n🔹 **Try Harmony:** [Harmony Web App](https://harmonydata.ac.uk/app)  \n🔹 **Read our blog:** [Harmony Blog](https://harmonydata.ac.uk/blog/)  \n\n\n## 📞 Who to Contact?  \n\n🔹 **Harmony Team:** [harmonydata.ac.uk](https://harmonydata.ac.uk/)  \n🔹 **Thomas Wood:** [fastdatascience.com](https://fastdatascience.com/)  \n\n\n## Getting started with the Harmony R library\n\n* Check out [this video walkthrough](https://www.youtube.com/watch?v=hFqg6T_BqZc\u0026t=1s) installing and running R on Windows 10.\n\n* You can run the walkthrough Python notebook in [Google Colab](https://colab.research.google.com/github/harmonydata/harmony/blob/main/Harmony_example_walkthrough.ipynb) with a single click: \u003ca href=\"https://colab.research.google.com/github/harmonydata/harmony/blob/main/Harmony_example_walkthrough.ipynb\" target=\"_parent\"\u003e\u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/\u003e\u003c/a\u003e\n\n* You can also download an R markdown notebook to run in R Studio: \u003ca href=\"https://harmonydata.ac.uk/harmony_r_example.nb.html\" target=\"_parent\"\u003e\u003cimg src=\"https://img.shields.io/badge/RStudio-4285F4\" alt=\"Open In R Studio\"/\u003e\u003c/a\u003e\n\n* You can run the walkthrough R notebook in Google Colab with a single click: \u003ca href=\"https://colab.research.google.com/github/harmonydata/experiments/blob/main/Harmony_R_example.ipynb\" target=\"_parent\"\u003e\u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/\u003e\u003c/a\u003e\n\n* [View the PDF documentation of the R package on CRAN](https://cran.r-project.org/web/packages/harmonydata/harmonydata.pdf)\n\n\n### Installing R library\n\nYou can install the development version of harmonydata from [GitHub](https://github.com/harmonydata/harmony_r) with:\n\n```{r}\n#install.packages(\"devtools\") # If you don't have devtools installed already.\nlibrary(devtools)\ndevtools::install_github(\"harmonydata/harmony_r\")\n```\n\nor you can install it via [CRAN](https://cran.r-project.org/):\n\n```{r, eval = FALSE}\ninstall.packages(\"harmonydata\")\n```\n\n## Setting up domain\n\nBefore starting, you can set up the remote API endpoint for harmony using this function. By default it uses the remote Harmony API [https://api.harmonydata.ac.uk](https://api.harmonydata.ac.uk){.uri}\n\n\n```{r}\nharmonydata::set_url()\n```\n\nFor example, if you want to use Harmony locally, you can run the [Harmony API as a Docker container](https://github.com/harmonydata/harmonyapi). By default it runs on localhost at port 8000. In this case you can run this command to run it locally:\n\n```{bash, eval=FALSE}\ndocker run -p 8000:8000 harmonydata/harmonylocal\n```\n\nNow in R you can set the R library to point to your local Harmony on Docker.\n\n```{r, eval = FALSE}\nharmonydata::set_url(\"http://localhost:8000\")\n```\n\n## Parsing a raw file into an Instrument\n\nIf you want to read in a raw (unstructured) PDF or Excel file, you can do this via a POST request to the REST API. This will convert the file into an Instrument object in JSON. It returns the instrument as a list.\n\n```{r example}\nlibrary(harmonydata)\ninstrument = load_instruments_from_file(path = \"examples/GAD-7.pdf\")\nnames(instrument[[1]])\n\n```\n\nYou can also input a url containing the questionnaire.\n\n```{r}\ninstrument_2 = load_instruments_from_file(\"https://medfam.umontreal.ca/wp-content/uploads/sites/16/GAD-7-fran%C3%A7ais.pdf\") \nnames(instrument_2[[1]])\n```\n\n## Matching instruments\n\nYou can get a list containing the results of the match. Here we can see a list of similarity score for each question comapred to all the other questions in th other questionaire.\n\n```{r}\ninstruments = append(instrument, instrument_2)\nmatch = match_instruments(instruments)\nnames(match)\n```\n\nHere is how the matches look like.\n\n```{r}\n\nmatch$matches\n```\n\n# Running harmonydata locally from a docker image\n\nTo run harmonydata locally, first you need to pull the docker image using the terminal.\n\n## 1. Pull docker image\n\n```{bash, eval=FALSE}\ndocker pull harmonydata/harmonyapi\n```\n\n## 2. Run docker image\n\n```{bash, eval=FALSE}\ndocker run -p 8000:80 harmonyapi\n```\n\n## 3. Configure harmonydata to run locally\n\nSet url to use localhost. Don't forget to expose port 8000:\n\n```{r, eval = FALSE}\nset_url(harmony_url = \"http://localhost:8000\")\n```\n\n\n## 📜 How do I cite Harmony?\n\nYou can cite our validation paper:\n\n McElroy, Wood, Bond, Mulvenna, Shevlin, Ploubidis, Scopel Hoffmann, Moltrecht, [Using natural language processing to facilitate the harmonisation of mental health questionnaires: a validation study using real-world data](https://bmcpsychiatry.biomedcentral.com/articles/10.1186/s12888-024-05954-2#citeas). BMC Psychiatry 24, 530 (2024), https://doi.org/10.1186/s12888-024-05954-2\n \n\nA BibTeX entry for LaTeX users is\n\n```bibtex\n@article{mcelroy2024using,\n  title={Using natural language processing to facilitate the harmonisation of mental health questionnaires: a validation study using real-world data},\n  author={McElroy, Eoin and Wood, Thomas and Bond, Raymond and Mulvenna, Maurice and Shevlin, Mark and Ploubidis, George B and Hoffmann, Mauricio Scopel and Moltrecht, Bettina},\n  journal={BMC Psychiatry},\n  volume={24},\n  number={1},\n  pages={530},\n  year={2024},\n  publisher={Springer}\n}\n\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmonydata%2Fharmony_r","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharmonydata%2Fharmony_r","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmonydata%2Fharmony_r/lists"}