RandIMI

RandIMI allows for participants of studies to be randomized. It implements a number of randomization algorithms with different guarantees.

Documentation

More detailed documentation of RandIMI and its features can be found in the GitHub Wiki.

Randomization

RandIMI currently supports the different randomization algorithms; blocked randomization, minimization, and randomization by tossing a coin.

Coin toss is the simplest for of randomization. A subject will simply be assigned to a random study arm.

Blocked randomization is more complicated, as it divides the randomization list into blocks to which the subjects will be assigned evenly, yet random. This guarantees that if a subset of subjects is selected, those are evenly distributed across the studies' strata.

Minimization is a more sophisticated randomization method that calculates an imbalance for all possible study arm assignments. By assigning the subject to the study arm that minimizes the imbalance, RandIMI ensures that the study arms are balanced in terms of subject characteristics, reducing potential biases.

REDCap Integration

RandIMI can be integrated into REDCap projects using the REDCap RandIMI Integration.

Installation

Using Docker

RandIMI can be installed using Docker. A docker-compose file is provided in the project's root directory.

1. Configure the .env file. Create a new .env file and paste the content of the provided .env.example file into it. The only mandatory step is to set the database password PG_PASSWORD.

2. Start the containers

docker-compose up -d

Manual Installation

Before deploying RandIMI to a server, you need to install Java 17, Tomcat 10 and configure a PostgreSQL database. Database name, user, and password can be chosen freely, but remember to change the values in the property file as well! The file must be place in /etc/randimi/db.properties. The application will create the required schema automatically.

First Setup

Change the password of the admin account and configure the mail server. You should also adapt the content of the Imprint, Data Privacy, and Support popups.

Development

Build

Now RandIMI should be good to go to be built using mvn package from the project's root directory. You can deploy RandIMI to the tomcat server by moving the war file inside the ./target directory to ~tomcat/webapps/.

Installation of the development environment

1. Install Java 17
2. Install the latest PostgreSQL. If this fails, tested versions are: 15.1
3. Install Tomcat 10
   1. Download Tomcat 10 Core from here: https://tomcat.apache.org/download-10
   2. Unzip the file and move the folder to your preferred destination
4. Checkout RandIMI
5. Set up the database. Execute the script src/main/resources/db/db_create.sql as user postgres
6. Add run configuration to your IDE
   1. IntelliJ
      1. Create a new configuration for a local Tomcat server
      2. Select the previous installed Tomcat 10 server as the Application server. You might have to add the server by clicking the Configure... button. Tomcat Home and Tomcat base directory should point to the extracted directory.
      3. (Optional) Add -Dspring.profiles.active=dev to your VM options. This enables hot reloading for frontend resources.
      4. Select your JRE
      5. Under the Deployment Tab add the artifact RandIMI.war exploded and set the Application context to your preferred value
   2. IntelliJ Community
      1. Install the plugin Smart Tomcat
      2. Select the previous installed Tomcat 10 server as the Tomcat server. You might have to add the server by clicking the Configure... button.
      3. (Optional) Add -Dspring.profiles.active=dev to your VM options. This enables hot reloading for frontend resources.
7. (Optional) Install Docker for Selenium test

Thymeleaf Templates

The user interface is being generated using thymeleaf, so the source code of all pages can be found in src/main/webapp/WEB-INF/views/. Check out the thymeleaf documentation for more information.

Database Schema

During development, you may make changes to the database schema. To ensure upgradability, RandIMI uses flyway for database migrations. Instead of applying your changes to the database scheme directly, you should create a migration script in src/main/resources/db/migration/. Although flyway keeps track of already applied migrations, it is best practice if the script itself checks if it is necessary to apply it, eg.

CREATE TABLE IF NOT EXISTS example...

Those scripts should be numbered and should not be modified once released.

License

RandIMI is licensed under the Apache-2.0 license.

Third party libraries

RandIMI uses the following open-source libraries:

• Spring Framework
• Jackson
• Jakarta
• Thymeleaf
• Bootstrap
• Font Awesome
• JQuery
• DataTables

Credits

RandIMI was developed by the Medical Data Integration Center (MeDIC), Institute of Medical Informatics, University of Münster

Medical Data Integration Center (MeDIC)
Institute of Medical Informatics
University of Münster
Albert-Schweitzer-Campus 1, Gebäude A11
48149 Münster
medic@uni-muenster.de
0251 / 83 – 5 57 22