From 916f6db5b2eb8eed3e2ecbb42e5140fc8de536db Mon Sep 17 00:00:00 2001 From: Jagoda Date: Thu, 8 Feb 2024 10:48:34 +0100 Subject: [PATCH 1/6] first part of README --- DESCRIPTION | 2 + README.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 141 insertions(+), 6 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index e1ea907..78894ef 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -10,6 +10,8 @@ Authors@R: c( role = c("aut")), person("Łukasz", "Wałejko", , "lukasz.walejko@ttsi.com.pl", role = c("aut")), + person("Jagoda", "Głowacka-Walas", "jagoda.glowacka-walas@ttsi.com.pl", + role = c("aut"), comment = c(ORCID = "0000-0002-7628-8691")), person("Michał", "Seweryn", , "michal.seweryn@biol.uni.lodz.pl", role = c("ctr"), comment = c(ORCID = "0000-0002-9090-3435")), person("Transition Technologies Science Sp. z o.o.", role = c("fnd", "cph")) diff --git a/README.md b/README.md index 5eadab3..c53bd9e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,95 @@ -# unbiased -API for clinical trial randomization +# **unbiased**: An R package for Clinical Trial Randomization -## Configuration +The challenge of allocating participants fairly and efficiently is a cornerstone for the success of clinical trials. Recognizing this critical need, we developed the **unbiased** package. This tool is designed to offer a comprehensive suite of randomization algorithms, suitable for a wide range of clinical trial designs. -The Unbiased API server can be configured using environment variables. The following environment variables need to be set for the server to start: +## Why choose **unbiased**? + +Our goal in creating **unbiased** was to provide a user-friendly yet powerful tool that addresses the nuanced demands of clinical trial randomization. It offers: + +- **Ease of Integration**: Designed to fit effortlessly into your research workflow. +- **Adaptability**: Whether for small-scale studies or large, multi-center trials, **unbiased** scales to meet your needs. +- **Comprehensive Documentation**: To support you in applying the package effectively. + +By choosing **unbiased**, you're adopting a sophisticated approach to trial randomization, ensuring fair and efficient participant allocation across your studies. + +## Core features + +The **unbiased** package integrates dynamic and traditional randomization methods, including: + +- **Minimization Method**: For balanced allocation considering covariates. +- **Simple Randomization**: For straightforward, unbiased participant assignment. +- **Block Randomization**: To ensure equal group sizes throughout the trial. + +Available both as a standard R package and through an API, **unbiased** provides flexibility for researchers. It ensures seamless integration with electronic Case Report Form (eCRF) systems, facilitating efficient patient management. + +## Table of Contents +1. [Background](#background) + - [Purpose and Scope for Clinical Trial Randomization](#purpose-and-scope-for-clinical-trial-randomization) + - [Comparative Analysis of Randomization Methods](#comparative-analysis-of-randomization-methods) + - [Comparison with other solutions](#comparison-with-other-solutions) +2. [Installation](#installation) + - [Installation Instructions](#installation-instructions) + - [Deploying the API](#deploying-the-api) +4. [Getting Started](#getting-started) + - [Quickstart Guide](#quickstart-guide) + - [Basic Usage Examples](#basic-usage-examples) +3. [Technical Implementation](#technical-implementation) + - [Quality Assurance Measures](#quality-assurance-measures) + +# Background + +## Purpose and Scope for Clinical Trial Randomization + +Randomization is a fundamental aspect of clinical trials, ensuring that participants are allocated to treatment groups in an unbiased manner. This is essential for maintaining the integrity of the trial and ensuring that the results are reliable. The primary goal of randomization is to minimize the potential for bias and confounding factors that could affect the outcome of the trial. + +The **unbiased** package provides a comprehensive suite of randomization algorithms to support a wide range of clinical trial designs. It is designed to be flexible and adaptable, allowing researchers to select the most appropriate randomization method for their specific study. + +## Comparative Analysis of Randomization Methods + +(Ola - skrócona wersja z winietki, może obrazki?) + +The **unbiased** package offers a range of randomization methods, each with its own strengths and limitations. The choice of randomization method will depend on the specific requirements of the trial, including the number of treatment groups, the size of the trial, and the need for stratification or minimization. + +The **unbiased** package includes the following randomization methods: + +- **Simple Randomization**: This is the most basic form of randomization, in which participants are assigned to treatment groups with equal probability. This method is simple and easy to implement, but it does not account for any potential imbalances in baseline characteristics between treatment groups. + +- **Block Randomization**: This method involves dividing participants into blocks and then randomly assigning them to treatment groups within each block. This ensures that the number of participants in each treatment group is balanced over time, but it does not account for any potential imbalances in baseline characteristics between treatment groups. + +- **Minimization Method**: This method is designed to minimize imbalances in baseline characteristics between treatment groups. It uses an adaptive algorithm to assign participants to treatment groups based on their baseline characteristics, with the goal of achieving balance across treatment groups. + +... + +To find out more, read our vignette on [Comparative Analysis of Randomization Methods](vignettes/minimization_randomization_comparison.Rmd). + +## Comparison with other solutions + +(Ola - randpack, others...?) + + +# Getting Started + +Initiating your work with **unbiased** involves simple setup steps. Whether you're integrating it into your R environment or deploying its API, we provide detailed instructions and examples to facilitate a smooth start. We aim to equip you with a reliable tool that enhances the integrity and efficiency of your clinical trials. + +## Installation + +The **unbiased** package can be installed from GitHub using the `devtools` package. To install **unbiased**, run the following command in your R environment: + +```R +devtools::install_github("ttscience/unbiased") +``` + +## Deploying the API + +Execute the API by calling the`run_unbiased()` function: +```R +unbiased::run_unbiased() +``` +After running this command, the API should be up and running, as default listening on a port on your localhost (http://localhost:3838). You can interact with the API using any HTTP client, such as curl in the command line, Postman, or directly from R using packages like httr. + +## API configuration + +The **unbiased** API server can be configured using environment variables. The following environment variables need to be set for the server to start: - `POSTGRES_DB`: The name of the PostgreSQL database to connect to. - `POSTGRES_HOST`: The host of the PostgreSQL database. This could be a hostname, such as `localhost` or `database.example.com`, or an IP address. @@ -13,6 +99,53 @@ The Unbiased API server can be configured using environment variables. The follo - `UNBIASED_HOST`: The host on which the API will run. Defaults to `0.0.0.0` if not provided. - `UNBIASED_PORT`: The port on which the API will listen. Defaults to `3838` if not provided. +# Use Cases + +## Using randomization functions within R + +The **unbiased** package provides a set of functions that can be used to perform randomization within R. These functions can be used to assign participants to treatment groups in a clinical trial, ensuring that the randomization process is unbiased and transparent. + + +### Simple randomization + +```R +# Load the unbiased package +library(unbiased) + +# Create a data frame with participant IDs and treatment group assignments +participants <- data.frame( + id = 1:100, + treatment_group = simple_randomization(100, 2) +) + +``` + +### Minimization method + +The minimization method function provided by **unbiased** assume that there is a study initialized and the previous patients assigments is stored in the dataframe/database. The functions will then use this data to assign new participant to treatment groups in a way that minimizes the potential for bias and confounding factors. If the data is not available (e.g. when first patient is randomized), he will be randomly assigned to a treatment group. + +```R +# Load the unbiased package +library(unbiased) + +# Create a data frame with participant IDs and treatment group assignments +participants <- data.frame( + id = 1:100, + treatment_group = minimization_method( + 100, + 2, + covariates = c("age + )) +``` + +## API endpoints + +### Study creation + +### Patient randomization + +# Technical details + ## Running Tests Unbiased provides an extensive collection of tests to ensure correct functionality. @@ -23,7 +156,7 @@ To execute tests using an interactive R session, run the following commands: ```R devtools::load_all() -testthat::test_package("unbiased") +testthat::test_package(**unbiased**) ``` Make sure that `devtools` package is installed in your environment. @@ -54,4 +187,4 @@ To calculate code coverage, you will need to install the `covr` package. Once in - `covr::report()`: This method runs all tests and generates a detailed coverage report in HTML format. - `covr::package_coverage()`: This method provides a simpler, text-based code coverage report. -Alternatively, you can use the provided `run_tests_with_coverage.sh` script to run Unbiased tests with code coverage. \ No newline at end of file +Alternatively, you can use the provided `run_tests_with_coverage.sh` script to run Unbiased tests with code coverage. From 5ac44cadf623b937f4dd5d7c06d8608a8efadd53 Mon Sep 17 00:00:00 2001 From: Ola Date: Thu, 8 Feb 2024 12:24:30 +0000 Subject: [PATCH 2/6] add text to readme and png --- README.md | 24 +++++++++++++++++------- vignettes/boxplot.png | Bin 0 -> 25970 bytes 2 files changed, 17 insertions(+), 7 deletions(-) create mode 100644 vignettes/boxplot.png diff --git a/README.md b/README.md index c53bd9e..4951bba 100644 --- a/README.md +++ b/README.md @@ -40,32 +40,42 @@ Available both as a standard R package and through an API, **unbiased** provides ## Purpose and Scope for Clinical Trial Randomization -Randomization is a fundamental aspect of clinical trials, ensuring that participants are allocated to treatment groups in an unbiased manner. This is essential for maintaining the integrity of the trial and ensuring that the results are reliable. The primary goal of randomization is to minimize the potential for bias and confounding factors that could affect the outcome of the trial. +Randomization is the gold standard for conducting clinical trials and a fundamental aspect of clinical trials, in studies comparing two or more arms. Although there are sometimes ethical constraints preventing the use of randomization, in most cases randomization is a desirable technique that will ensure that patients are randomly allocated to defined groups. -The **unbiased** package provides a comprehensive suite of randomization algorithms to support a wide range of clinical trial designs. It is designed to be flexible and adaptable, allowing researchers to select the most appropriate randomization method for their specific study. +Randomization then ensures that the predictability of the allocation of consecutive patients to groups is blinded, allowing the study participants overseeing the clinical trial to be appropriately blinded. This is essential for maintaining the integrity of the trial and ensuring that the results are reliable. + +However, there are situations where it is desirable for studies to balance patients in terms of numbers in each group or, in addition, to achieve balance with respect to other relevant factors, such as sex or diabetes type. + +Adequate selection of randomization methods allows the intended randomization goals to be realized; however, in the case of balance between groups in terms of patient characteristics, more adaptive methods of patient allocation are required, e.g. by verifying the overall imbalance on the basis of current allocations to the study groups. This is ensured, for example, by using the minimization method. + +**Unbiased** specifically caters to the needs of clinical trial randomization. It streamlines the randomization process, ensuring a balanced and impartial allocation of participants across different trial groups, which is vital for minimizing bias and ensuring the reliability of trial outcomes. Unbiased allows the use of simple, block and advanced randomization methods relevant to the conduct of clinical trials. Consequently, it addresses the needs arising from the need to balance against key variables, ensuring that the population in each treatment group is as comparable as possible. ## Comparative Analysis of Randomization Methods -(Ola - skrócona wersja z winietki, może obrazki?) +**Unbiased** compared to standard and most commonly used randomization methods, e.g. the simple method or the block method, additionally offers enhanced features of more flexible adaptive methods, which are based on current information about the allocation of patients in the trial. Compared to, for example, block randomization, adaptive randomization not only ensures relatively equal allocation to patient groups, but also allows the groups to be balanced on the basis of certain important covariates, which is its key advantage. This randomization requires predefined criteria, such as the probability with which a given patient will be assigned to a group based on minimizing the total imbalance, or weights that can be assigned personally for each individual covariate. Its advanced algorithmic approach sets it apart from others by minimizing selection bias and improving the overall efficiency of the randomization process in clinical trials. -The **unbiased** package offers a range of randomization methods, each with its own strengths and limitations. The choice of randomization method will depend on the specific requirements of the trial, including the number of treatment groups, the size of the trial, and the need for stratification or minimization. +The **unbiased** package offers the use of different randomization methods, each with its own strengths and limitations. The choice of randomization method will depend on the specific requirements of the trial, including the number of treatment groups, the size of the trial, and the need for stratification or covariate balance. The **unbiased** package includes the following randomization methods: -- **Simple Randomization**: This is the most basic form of randomization, in which participants are assigned to treatment groups with equal probability. This method is simple and easy to implement, but it does not account for any potential imbalances in baseline characteristics between treatment groups. +- **Simple Randomization**: This is the most basic form of randomization, in which participants are assigned to treatment groups with equal probability. This method is simple and easy to implement. Since this is simple randomization, it does not take into account the initial covariates, and treatment assignment occurs randomly (flip coin method). + +- **Minimization Method**: This method is designed to minimize imbalances in baseline characteristics between treatment groups. It uses an adaptive algorithm to assign participants to treatment groups based on their baseline characteristics, with the goal of achieving balance across treatment groups. - **Block Randomization**: This method involves dividing participants into blocks and then randomly assigning them to treatment groups within each block. This ensures that the number of participants in each treatment group is balanced over time, but it does not account for any potential imbalances in baseline characteristics between treatment groups. -- **Minimization Method**: This method is designed to minimize imbalances in baseline characteristics between treatment groups. It uses an adaptive algorithm to assign participants to treatment groups based on their baseline characteristics, with the goal of achieving balance across treatment groups. +Depending on the aims and objectives of the randomised trial, the **unbiased** approach allows a choice of alternative methods to effectively implement appropriate algorithms for the randomized patient allocation process in a clinical trial. A comparison of these methods is shown in a boxplot, where a lower threshold value of the SMD index indicates a greater balance in covariates retained by the method. +![Comparison of covariate balances.](vignettes/boxplot.png) ... To find out more, read our vignette on [Comparative Analysis of Randomization Methods](vignettes/minimization_randomization_comparison.Rmd). ## Comparison with other solutions -(Ola - randpack, others...?) +There are many packages that perform specific randomization methods in R. Most of them are designed for stratified randomization, and permuted blocks -e.g. blockrand, randomizeR. More recently, there have also been options for using minimization randomization - randpack, or minirand. +Unlike the other packages, unbiased incorporates several different types of minimization algorithms - from simple simple randomization methods to advanced ones based on the Pocok minimization method. In addition, the advantage of using unbiased is that it can be used in the form of an API, which is not possible in the existing software, making **unbiased** appear complete from the point of view of usability, as well as the possibility of testing multiple methods for an individual study within a single package. # Getting Started diff --git a/vignettes/boxplot.png b/vignettes/boxplot.png new file mode 100644 index 0000000000000000000000000000000000000000..aac9a3eb1462403b971358cdb13bcde234a686f3 GIT binary patch literal 25970 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≦wt*J95eQ+QL!eo=q4B zJT9uqTt*M8f%vbaSU0t;_G*%&3ijW^_ew{`!9zhEL|D>v_3L@v2 z<#GsYh}UR9vrs;rm^eW8)244#)lZdMRb|$Cn+&Wzct^sIIRg1!PT()XTp{18(|w}U z^U)mL`!M(V46e<~e6(MRx#Vf&Y$Z2Zb>F*WORr*cYi?7xTVUsYmKus~=1c-!w z?pcR^oDw&N;qy8@HsR5kloSKWFxSo%Aoh5jgg7*SX!?vKxSj87fL$fg$t|~N&7&|` zB%s$2%!-V>0OSIwd1QcVeEJN6$8Oza_!ok6D;_)$_%Y?vu;iyt=TcfxEz^yPswK0< z6a?X^kwcXL3o-o(7%}{qAMsX`94a+HSrYVD^F9lTD1>nFo!Fbt# z5mQzbYC15lceunfZP%Q}&BZuvSSWg>fHeS^XS#{f&Nm^rlJyv(*zt9^Lta3Lv_hGNQ%DSata)WXeTeQ+JE+=M5W$`gPBiesUWP<}P z?@asJ^yAAZmwO6!dA&LqnEF%vfv^O!7bY-XY0aMf2i{4PC{ZL}gk(3pPGbNcywJ!7 zZ>kDiX+Bu?vM|VZw=AvzAJ92;^Fn=WX9)LXOcr4m*@Sx%0jE*}5CS=s=z zbKSD=icj)7r}i9MpS-*9Lh$3xfr#>(J$-xl-(5)n#RHTvA(vJ9@ZkpUw1PnH1;AI( zOgfg~fqb`tL3bqQ(qlZJxB0<_1B72z~GBfoRQL;^pU_Rmp$xy?Og-C&F4 z0zy}RX}1xbso9--%{g~I*S69-m+#is)hC-(b-B#&x9>CR@&6nV8fTmPp)^e@QV5N6 zL%K3T+1udD;H}7CDW5O55r&^76TfPv zSEp^X`~I4lR;X<+b403Atjf;%K2g=sAS`c!1K2q*g5lss+f}2VbbcNSYT(Du&JJj8 z9o5?VFiWHOBW;IS0WHP4%jQj+np#Vwmpg{sOqFTV3YG(8ZM4gNJ2X@z@*`1p>qt^C z_76eR%9|4$Al}knN{a#}{47agKnh%j#2dq4jrHg?)G=)zcY#!PXFyG!Q+ZL0d5n_3 zP+vdeo#FHZlZbTxypsnueixAd?mN#iyq7j2ndOz=WIf?!FfcR}Fx)pMWc-v{ao`s_ z0t34;s|SKqy$(-|4ROc@L2@K9F@^gpcgA|NVvn1f4}+z%V)2%LZ`dU3 zyLjo+pU{#iXz>KF8+RJryFwQ8?B?j_Jn!*4=&^3D3p=k{=KtIvyk7q$b+@I(Us-dgL`AVnXiJrAzZqKFGs2f`DFGmu%T^P&mNH<9E>3>ue}foTS@W1l~&erf079sL0fTnhz%rdcybgiL`qW|c4ZI?pZhzkMJjXi9Bk;}EY1J!U0>94<$$ z^808otcYG7;f}gdM{$`|h+u|?;E66Xj>!MkI7AH{rk~_LlN;H{dbwc1 ze-PVs2t^*`=kldXuZkZ{HEV}3vjLvCVxl3XjX>d zmQOgZt;->U@%N2B^UeO!owjwo){vPHF^`a?14%8bn(`)ZZ|FA>8X;juJ?3Xw$|?o` z-jjoa10wPP?KzOC)0dO;c^jsZ!tz;p@LROB;#e#b^3&_J&vGv#l^+l~E$Isri$S$h z7az3j@{hBf+?l;R1ZC1U`Uhvq8)A{gZ;p(Y{loZx=his?J(~i4$+TN#Wb_u{Hdu(N zxWBW}&SKvp&6LoC2M==mQPPnYfwLTZ?v1vZU(`|7ns^JEE1)&4#t|b~s4%<`;-E*$%5mSm2*!7`518sd zSlBbuWZNX}+CKGHgz)Bt3tdYNE@WdaS+Zoo0#7(cX$T+E!avs5?vcwyURCot?lm#o zpj%>9-(%40@PWhQsL)f35$F{`C1u`#MC0X`g>k=Q-p;~id7I-uy=rm>J*pnxl z%MTY-7HKFv*8Fh(<2H^KEq^6#lvB;DAcIDWQjP)gURy4TxtKEQnS@TQx_D2we&n?c(fg?o+>*JEenz zDe)q@_i?ba9qFrPkbmT1xOgR0>3O&wg~j_(os5rvJZNRk47I$WEE!rj>aIjZ94q)N02a8ptm1WLY)dCYFMYDrMMR85 za$%rAy?=iswYGRq#SD>1q${ya&)12WqEHOv@wn{+C8bRtQ89Y*3jURpwDUFOpqx!$IMw`_W^{ zKd(&e;pfMRU_cANC?y@?HJD!eo>R^~Gg-uM4xk+3 zL9k%>ph06aY@%$?w{;~uGOdww(Tcap&JmDKNN$yJjVE$dFE4981b9O7KG7_CF?Q14NHt3JlxN-kNiZK8qk8^H66~U#* uPvNLn24H|xz|WuCfWGke|4qz|&)jymLThu2VLx9*;mdWlYqP{2$NmkCU9Win literal 0 HcmV?d00001 From 4b72c8139230e5ca9ac8271af441c26ccd2dc6e4 Mon Sep 17 00:00:00 2001 From: Jagoda Date: Thu, 8 Feb 2024 14:29:12 +0100 Subject: [PATCH 3/6] README v2 --- README.md | 144 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 105 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 4951bba..5216e49 100644 --- a/README.md +++ b/README.md @@ -23,18 +23,30 @@ The **unbiased** package integrates dynamic and traditional randomization method Available both as a standard R package and through an API, **unbiased** provides flexibility for researchers. It ensures seamless integration with electronic Case Report Form (eCRF) systems, facilitating efficient patient management. ## Table of Contents + 1. [Background](#background) - [Purpose and Scope for Clinical Trial Randomization](#purpose-and-scope-for-clinical-trial-randomization) - [Comparative Analysis of Randomization Methods](#comparative-analysis-of-randomization-methods) - - [Comparison with other solutions](#comparison-with-other-solutions) -2. [Installation](#installation) - - [Installation Instructions](#installation-instructions) - - [Deploying the API](#deploying-the-api) -4. [Getting Started](#getting-started) - - [Quickstart Guide](#quickstart-guide) - - [Basic Usage Examples](#basic-usage-examples) -3. [Technical Implementation](#technical-implementation) + - [Comparison with Other Solutions](#comparison-with-other-solutions) +2. [Quickstart Guide](#quickstart-guide) + - [Installation Instructions](#installation-instructions) + - [Deploying the API](#deploying-the-api) + - [API Configuration](#api-configuration) +3. [Getting started with **unbiased**](#getting-started-with-unbiased) + - [Using Randomization Functions within R](#using-randomization-functions-within-r) + - [Simple Randomization](#simple-randomization) + - [Minimization Method](#minimization-method) + - [API Endpoints](#api-endpoints) + - [Study Creation](#study-creation) + - [Patient Randomization](#patient-randomization) +4. [Technical Implementation](#technical-implementation) - [Quality Assurance Measures](#quality-assurance-measures) + - [Running Tests](#running-tests) + - [Executing Tests from an R Interactive Session](#executing-tests-from-an-r-interactive-session) + - [Executing Tests from the Command Line](#executing-tests-from-the-command-line) + - [Running Tests with Docker Compose](#running-tests-with-docker-compose) + - [Code Coverage](#code-coverage) + # Background @@ -77,11 +89,11 @@ There are many packages that perform specific randomization methods in R. Most o Unlike the other packages, unbiased incorporates several different types of minimization algorithms - from simple simple randomization methods to advanced ones based on the Pocok minimization method. In addition, the advantage of using unbiased is that it can be used in the form of an API, which is not possible in the existing software, making **unbiased** appear complete from the point of view of usability, as well as the possibility of testing multiple methods for an individual study within a single package. -# Getting Started +# Quickstart Guide -Initiating your work with **unbiased** involves simple setup steps. Whether you're integrating it into your R environment or deploying its API, we provide detailed instructions and examples to facilitate a smooth start. We aim to equip you with a reliable tool that enhances the integrity and efficiency of your clinical trials. +Initiating your work with **unbiased** involves simple setup steps. Whether you're integrating it into your R environment or deploying its API, we aim to equip you with a reliable tool that enhances the integrity and efficiency of your clinical trials. -## Installation +## Installation instructions The **unbiased** package can be installed from GitHub using the `devtools` package. To install **unbiased**, run the following command in your R environment: @@ -109,50 +121,104 @@ The **unbiased** API server can be configured using environment variables. The f - `UNBIASED_HOST`: The host on which the API will run. Defaults to `0.0.0.0` if not provided. - `UNBIASED_PORT`: The port on which the API will listen. Defaults to `3838` if not provided. -# Use Cases +# Getting started with **unbiased** -## Using randomization functions within R +The **unbiased** package offers functions for randomizing participants in clinical trials, ensuring a fair and transparent process. -The **unbiased** package provides a set of functions that can be used to perform randomization within R. These functions can be used to assign participants to treatment groups in a clinical trial, ensuring that the randomization process is unbiased and transparent. +### Simple Randomization - -### Simple randomization +Use `simple_randomization` for uncomplicated, unbiased assignment, giving each participant an equal chance of being allocated to any group. This method requires specifying the `arms` and `ratio` parameters, where `arms` is a vector of treatment group names, and `ratio` is a vector of integers indicating the allocation proportions. ```R -# Load the unbiased package -library(unbiased) +# Treatment group assignments with a 1:1 ratio +treatment_group <- + randomize_simple( + arms = c("treatment", "placebo"), + ratio = c("treatment" = 1, "placebo" = 1) + ) +``` -# Create a data frame with participant IDs and treatment group assignments -participants <- data.frame( - id = 1:100, - treatment_group = simple_randomization(100, 2) -) +*Note: Ensure that the `ratio` parameter accurately reflects an allocation proportion vector, using numeric values to denote the proportions.* + +### Minimization Method +The minimization method considers existing participant assignments to minimize bias. New participants are allocated based on an imbalance score, calculated using specified weights for each covariate. This method dynamically adjusts to maintain balance across treatment groups. + +```R +# Treatment group assignment considering previous participants' data +treatment_group <- randomize_minimisation_pocock( + arms = c("treatment", "placebo"), + current_state = previous_data, + weights = c( + "sex" = 1, + "age" = 1 + ), + ratio = c(1, 1), # Ensure ratio is defined correctly + method = "var", + p = 0.85 +) ``` -### Minimization method +## API Endpoints + +The **unbiased** API facilitates randomization and clinical trial management via HTTP clients. -The minimization method function provided by **unbiased** assume that there is a study initialized and the previous patients assigments is stored in the dataframe/database. The functions will then use this data to assign new participant to treatment groups in a way that minimizes the potential for bias and confounding factors. If the data is not available (e.g. when first patient is randomized), he will be randomly assigned to a treatment group. +### Study Creation + +To initialize a study using Pocock's minimization method, use the POST /minimisation_pocock endpoint. The required JSON payload should detail the study, including treatment groups, allocation ratios, and covariates. ```R -# Load the unbiased package -library(unbiased) - -# Create a data frame with participant IDs and treatment group assignments -participants <- data.frame( - id = 1:100, - treatment_group = minimization_method( - 100, - 2, - covariates = c("age - )) +# Initialize a study with Pocock's minimisation method +response <- request(api_url) |> + req_url_path("study", "minimisation_pocock") |> + req_method("POST") |> + req_body_json( + data = list( + identifier = "My_study_1", + name = "Study 1", + method = "var", + p = 0.85, + arms = list( + "placebo" = 1, + "treatment" = 1 + ), + covariates = list( + sex = list( + weight = 1, + levels = c("female", "male") + ), + age = list( + weight = 1, + levels = c("up to 50", "51 or more") + ) + ) + ) + ) ``` -## API endpoints +This call sets up the study and returns an ID for accessing further study-related endpoints. + +### Patient Randomization -### Study creation +The POST /{study_id}/patient endpoint assigns a new patient to a treatment group, requiring patient details and covariate information in the JSON payload. + +```R +# Randomize a new patient +req_url_path("study", my_study_id, "patient") |> + req_method("POST") |> + req_body_json( + data = list( + current_state = + tibble::tibble( + "sex" = c("female"), + "age" = c("up to 50"), + "arm" = c("") + ) + ) + ) +``` -### Patient randomization +This endpoint determines the patient's treatment group. # Technical details From f1f97340dfdc2ef4d6fbf4a19317ab2c6f3dfbae Mon Sep 17 00:00:00 2001 From: Jagoda Date: Tue, 13 Feb 2024 13:43:00 +0100 Subject: [PATCH 4/6] README after Kamil's review --- README.md | 99 ++++++++++++++++++++++--------------------------------- 1 file changed, 39 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 5216e49..8ba83c4 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,18 @@ -# **unbiased**: An R package for Clinical Trial Randomization +# **unbiased**: An API-based solution for Clinical Trial Randomization -The challenge of allocating participants fairly and efficiently is a cornerstone for the success of clinical trials. Recognizing this critical need, we developed the **unbiased** package. This tool is designed to offer a comprehensive suite of randomization algorithms, suitable for a wide range of clinical trial designs. +In clinical trials, the fair and efficient allocation of participants is essential for achieving reliable results. While there are many excellent R randomization packages available, none, to our knowledge, provide a dedicated API for this purpose. The **unbiased** package fills this gap by featuring a production-ready REST API designed for seamless integration. This unique combination allows for easy connection with electronic Case Report Forms (eCRF), enhancing data management and streamlining participant allocation. ## Why choose **unbiased**? Our goal in creating **unbiased** was to provide a user-friendly yet powerful tool that addresses the nuanced demands of clinical trial randomization. It offers: -- **Ease of Integration**: Designed to fit effortlessly into your research workflow. +- **Production-Ready REST API**: Built for seamless integration with eCRF/EDC systems, facilitating real-time randomization and automation. +- **Extensive Database Integration**: Supports robust data management practices, ensuring that participant information and randomization outcomes are securely managed and easily accessible. +- **Commitment to Quality**: Emphasizes development best practices, including comprehensive code coverage, to deliver a reliable and trustworthy solution. - **Adaptability**: Whether for small-scale studies or large, multi-center trials, **unbiased** scales to meet your needs. - **Comprehensive Documentation**: To support you in applying the package effectively. -By choosing **unbiased**, you're adopting a sophisticated approach to trial randomization, ensuring fair and efficient participant allocation across your studies. - -## Core features - -The **unbiased** package integrates dynamic and traditional randomization methods, including: - -- **Minimization Method**: For balanced allocation considering covariates. -- **Simple Randomization**: For straightforward, unbiased participant assignment. -- **Block Randomization**: To ensure equal group sizes throughout the trial. - -Available both as a standard R package and through an API, **unbiased** provides flexibility for researchers. It ensures seamless integration with electronic Case Report Form (eCRF) systems, facilitating efficient patient management. +By choosing **unbiased**, you're adopting a sophisticated approach to trial randomization, ensuring fair and efficient participant allocation across your studies and support of the broader objectives of clinical research through technology. ## Table of Contents @@ -29,13 +21,10 @@ Available both as a standard R package and through an API, **unbiased** provides - [Comparative Analysis of Randomization Methods](#comparative-analysis-of-randomization-methods) - [Comparison with Other Solutions](#comparison-with-other-solutions) 2. [Quickstart Guide](#quickstart-guide) - - [Installation Instructions](#installation-instructions) - - [Deploying the API](#deploying-the-api) - - [API Configuration](#api-configuration) + - [Quick Setup with Docker](#quick-setup-with-docker) + - [API Configuration](#api-configuration) + - [Alternative Installation Method](#alternative-installation-method) 3. [Getting started with **unbiased**](#getting-started-with-unbiased) - - [Using Randomization Functions within R](#using-randomization-functions-within-r) - - [Simple Randomization](#simple-randomization) - - [Minimization Method](#minimization-method) - [API Endpoints](#api-endpoints) - [Study Creation](#study-creation) - [Patient Randomization](#patient-randomization) @@ -46,6 +35,7 @@ Available both as a standard R package and through an API, **unbiased** provides - [Executing Tests from the Command Line](#executing-tests-from-the-command-line) - [Running Tests with Docker Compose](#running-tests-with-docker-compose) - [Code Coverage](#code-coverage) + - [Configuring Sentry](#configuring-sentry) # Background @@ -81,33 +71,33 @@ Depending on the aims and objectives of the randomised trial, the **unbiased** a ![Comparison of covariate balances.](vignettes/boxplot.png) ... -To find out more, read our vignette on [Comparative Analysis of Randomization Methods](vignettes/minimization_randomization_comparison.Rmd). +To find out more, read our vignette on [Comparative Analysis of Randomization Methods](vignettes/articles/minimization_randomization_comparison.Rmd). ## Comparison with other solutions -There are many packages that perform specific randomization methods in R. Most of them are designed for stratified randomization, and permuted blocks -e.g. blockrand, randomizeR. More recently, there have also been options for using minimization randomization - randpack, or minirand. +There are many packages that perform specific randomization methods in R. Most of them are designed for stratified randomization and permuted blocks, such as [blockrand](https://CRAN.R-project.org/package=blockrand) and [randomizeR](https://CRAN.R-project.org/package=randomizeR). Some of them also utilize the options for using minimization randomization - e.g. [randpack]( https://bioconductor.org/packages/randPack/) or [Minirand]( https://CRAN.R-project.org/package=Minirand). -Unlike the other packages, unbiased incorporates several different types of minimization algorithms - from simple simple randomization methods to advanced ones based on the Pocok minimization method. In addition, the advantage of using unbiased is that it can be used in the form of an API, which is not possible in the existing software, making **unbiased** appear complete from the point of view of usability, as well as the possibility of testing multiple methods for an individual study within a single package. +Our unique contribution to the landscape is the integration of a comprehensive API and a commitment to rigorous testing. This dual focus ensures that **unbiased** not only supports the practical needs of clinical trials, but also aligns with the technical requirements of modern clinical research environments. By prioritizing these aspects, **unbiased** addresses a critical gap in the market: the need for an eCRF-compatible randomization solution that is both dependable and easily integrated into existing workflows. This, together with the implementation of minimization techniques, sets **unbiased** apart as a novel, comprehensive tool. # Quickstart Guide Initiating your work with **unbiased** involves simple setup steps. Whether you're integrating it into your R environment or deploying its API, we aim to equip you with a reliable tool that enhances the integrity and efficiency of your clinical trials. -## Installation instructions +## Quick Setup with Docker -The **unbiased** package can be installed from GitHub using the `devtools` package. To install **unbiased**, run the following command in your R environment: +The most straightforward way to deploy **unbiased** is through our Docker images. This ensures that you can get **unbiased** up and running with minimal setup, regardless of your local environment. To use **unbiased**, pull the latest Docker image: -```R -devtools::install_github("ttscience/unbiased") +```sh +docker pull ghcr.io/ttscience/unbiased ``` -## Deploying the API +To run **unbiased** with Docker, ensuring you have set the necessary environment variables: -Execute the API by calling the`run_unbiased()` function: -```R -unbiased::run_unbiased() +```sh +docker run -e POSTGRES_DB=mydb -e POSTGRES_USER=myuser -e POSTGRES_PASSWORD=mypassword -e UNBIASED_PORT=3838 ghcr.io/ttscience/unbiased ``` -After running this command, the API should be up and running, as default listening on a port on your localhost (http://localhost:3838). You can interact with the API using any HTTP client, such as curl in the command line, Postman, or directly from R using packages like httr. + +This command starts the **unbiased** API, making it accessible on the specified port. It's crucial to have your PostgreSQL database ready, as **unbiased** will automatically configure the necessary database structures upon startup. ## API configuration @@ -121,47 +111,36 @@ The **unbiased** API server can be configured using environment variables. The f - `UNBIASED_HOST`: The host on which the API will run. Defaults to `0.0.0.0` if not provided. - `UNBIASED_PORT`: The port on which the API will listen. Defaults to `3838` if not provided. -# Getting started with **unbiased** +## Alternative Installation Method -The **unbiased** package offers functions for randomizing participants in clinical trials, ensuring a fair and transparent process. +For those preferring to work directly within the R environment, the **unbiased** package offers an alternative installation method via GitHub. This approach allows users to easily integrate **unbiased** into their R projects. To proceed with this method, utilize the `devtools` package for installation by executing the following command: -### Simple Randomization +```R +devtools::install_github("ttscience/unbiased") +``` -Use `simple_randomization` for uncomplicated, unbiased assignment, giving each participant an equal chance of being allocated to any group. This method requires specifying the `arms` and `ratio` parameters, where `arms` is a vector of treatment group names, and `ratio` is a vector of integers indicating the allocation proportions. +Following the package installation, the **unbiased** API can be launched within R. Simply invoke the `run_unbiased()` function to start the API: ```R -# Treatment group assignments with a 1:1 ratio -treatment_group <- - randomize_simple( - arms = c("treatment", "placebo"), - ratio = c("treatment" = 1, "placebo" = 1) - ) +unbiased::run_unbiased() ``` -*Note: Ensure that the `ratio` parameter accurately reflects an allocation proportion vector, using numeric values to denote the proportions.* +This initiates the API server, by default, on your local machine (http://localhost:3838), making it accessible for interaction through various HTTP clients, including curl, Postman, or R's `httr` package. -### Minimization Method -The minimization method considers existing participant assignments to minimize bias. New participants are allocated based on an imbalance score, calculated using specified weights for each covariate. This method dynamically adjusts to maintain balance across treatment groups. +# Getting started with **unbiased** -```R -# Treatment group assignment considering previous participants' data -treatment_group <- randomize_minimisation_pocock( - arms = c("treatment", "placebo"), - current_state = previous_data, - weights = c( - "sex" = 1, - "age" = 1 - ), - ratio = c(1, 1), # Ensure ratio is defined correctly - method = "var", - p = 0.85 -) -``` +The **unbiased** package offers functions for randomizing participants in clinical trials, ensuring a fair and transparent process. + +Complete documentation for the implemented methodology and examples of how to use them are available on our GitHub Pages, providing all the information you need to integrate **unbiased** into your trial management workflow. Below, we present the basic steps for using **unbiased** through the API. ## API Endpoints -The **unbiased** API facilitates randomization and clinical trial management via HTTP clients. +The **unbiased** API is designed to facilitate clinical trial management through a set of endpoints: + +- **Study Management**: Create and configure new studies, including specifying randomization parameters and treatment arms. +- **Participant Randomization**: Dynamically randomize participants to treatment groups based on the study's configuration and existing participant data. + ### Study Creation From 2b3c6c8ed3c402e54656e91da226bcb7eaced097 Mon Sep 17 00:00:00 2001 From: Ola Date: Tue, 13 Feb 2024 13:19:50 +0000 Subject: [PATCH 5/6] changes in part of purpose and scope delate comparative part --- README.md | 31 ++++--------------------------- 1 file changed, 4 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 8ba83c4..0f93ed4 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,6 @@ By choosing **unbiased**, you're adopting a sophisticated approach to trial rand 1. [Background](#background) - [Purpose and Scope for Clinical Trial Randomization](#purpose-and-scope-for-clinical-trial-randomization) - - [Comparative Analysis of Randomization Methods](#comparative-analysis-of-randomization-methods) - [Comparison with Other Solutions](#comparison-with-other-solutions) 2. [Quickstart Guide](#quickstart-guide) - [Quick Setup with Docker](#quick-setup-with-docker) @@ -42,36 +41,14 @@ By choosing **unbiased**, you're adopting a sophisticated approach to trial rand ## Purpose and Scope for Clinical Trial Randomization -Randomization is the gold standard for conducting clinical trials and a fundamental aspect of clinical trials, in studies comparing two or more arms. Although there are sometimes ethical constraints preventing the use of randomization, in most cases randomization is a desirable technique that will ensure that patients are randomly allocated to defined groups. +Randomization is the gold standard for conducting clinical trials and a fundamental aspect of clinical trials, in studies comparing two or more arms. In most cases randomization is a desirable technique that will ensure that patients are randomly allocated to defined groups. This is essential for maintaining the integrity of the trial and ensuring that the results are reliable, and blinding of research personnel. However, there are situations where it is desirable for studies to balance patients in terms of numbers in each group or, in addition, to achieve balance with respect to other relevant factors, such as sex or diabetes type. Adequate selection of randomization methods allows the intended randomization goals to be realized. -Randomization then ensures that the predictability of the allocation of consecutive patients to groups is blinded, allowing the study participants overseeing the clinical trial to be appropriately blinded. This is essential for maintaining the integrity of the trial and ensuring that the results are reliable. +**Unbiased** compared to standard and most commonly used randomization methods, e.g. the simple method or the block method, apart from these methods, additionally offers enhanced features of more flexible adaptive methods, which are based on current information about the allocation of patients in the trial. Compared to, for example, block randomization, adaptive randomization not only ensures relatively equal allocation to patient groups, but also allows the groups to be balanced on the basis of certain important covariates, which is its key advantage. This randomization requires predefined criteria, such as the probability with which a given patient will be assigned to a group based on minimizing the total imbalance, or weights that can be assigned personally for each individual covariate. Its advanced algorithmic approach sets it apart from others by minimizing selection bias and improving the overall efficiency of the randomization process in clinical trials. -However, there are situations where it is desirable for studies to balance patients in terms of numbers in each group or, in addition, to achieve balance with respect to other relevant factors, such as sex or diabetes type. - -Adequate selection of randomization methods allows the intended randomization goals to be realized; however, in the case of balance between groups in terms of patient characteristics, more adaptive methods of patient allocation are required, e.g. by verifying the overall imbalance on the basis of current allocations to the study groups. This is ensured, for example, by using the minimization method. - -**Unbiased** specifically caters to the needs of clinical trial randomization. It streamlines the randomization process, ensuring a balanced and impartial allocation of participants across different trial groups, which is vital for minimizing bias and ensuring the reliability of trial outcomes. Unbiased allows the use of simple, block and advanced randomization methods relevant to the conduct of clinical trials. Consequently, it addresses the needs arising from the need to balance against key variables, ensuring that the population in each treatment group is as comparable as possible. - -## Comparative Analysis of Randomization Methods - -**Unbiased** compared to standard and most commonly used randomization methods, e.g. the simple method or the block method, additionally offers enhanced features of more flexible adaptive methods, which are based on current information about the allocation of patients in the trial. Compared to, for example, block randomization, adaptive randomization not only ensures relatively equal allocation to patient groups, but also allows the groups to be balanced on the basis of certain important covariates, which is its key advantage. This randomization requires predefined criteria, such as the probability with which a given patient will be assigned to a group based on minimizing the total imbalance, or weights that can be assigned personally for each individual covariate. Its advanced algorithmic approach sets it apart from others by minimizing selection bias and improving the overall efficiency of the randomization process in clinical trials. - -The **unbiased** package offers the use of different randomization methods, each with its own strengths and limitations. The choice of randomization method will depend on the specific requirements of the trial, including the number of treatment groups, the size of the trial, and the need for stratification or covariate balance. - -The **unbiased** package includes the following randomization methods: - -- **Simple Randomization**: This is the most basic form of randomization, in which participants are assigned to treatment groups with equal probability. This method is simple and easy to implement. Since this is simple randomization, it does not take into account the initial covariates, and treatment assignment occurs randomly (flip coin method). - -- **Minimization Method**: This method is designed to minimize imbalances in baseline characteristics between treatment groups. It uses an adaptive algorithm to assign participants to treatment groups based on their baseline characteristics, with the goal of achieving balance across treatment groups. - -- **Block Randomization**: This method involves dividing participants into blocks and then randomly assigning them to treatment groups within each block. This ensures that the number of participants in each treatment group is balanced over time, but it does not account for any potential imbalances in baseline characteristics between treatment groups. - -Depending on the aims and objectives of the randomised trial, the **unbiased** approach allows a choice of alternative methods to effectively implement appropriate algorithms for the randomized patient allocation process in a clinical trial. A comparison of these methods is shown in a boxplot, where a lower threshold value of the SMD index indicates a greater balance in covariates retained by the method. - -![Comparison of covariate balances.](vignettes/boxplot.png) +**Unbiased** allows the use of simple, block and adaptive minimization randomization methods relevant to the conduct of clinical trials, so package caters to the needs of clinical trial randomization. ... -To find out more, read our vignette on [Comparative Analysis of Randomization Methods](vignettes/articles/minimization_randomization_comparison.Rmd). +To find out more on differences in randomization methods, read our vignette on [Comparative Analysis of Randomization Methods](vignettes/articles/minimization_randomization_comparison.Rmd). ## Comparison with other solutions From ddcfcf6191d9d6aee642721a8035924c15364690 Mon Sep 17 00:00:00 2001 From: kamilsi Date: Thu, 15 Feb 2024 10:52:03 +0000 Subject: [PATCH 6/6] Update documentation --- man/unbiased-package.Rd | 1 + 1 file changed, 1 insertion(+) diff --git a/man/unbiased-package.Rd b/man/unbiased-package.Rd index 1ef7b04..3b046fa 100644 --- a/man/unbiased-package.Rd +++ b/man/unbiased-package.Rd @@ -23,6 +23,7 @@ Authors: \item Kinga Sałata \email{kinga.salata@ttsi.com.pl} \item Aleksandra Duda \email{aleksandra.duda@ttsi.com.pl} \item Łukasz Wałejko \email{lukasz.walejko@ttsi.com.pl} + \item Jagoda jagoda.glowacka-walas@ttsi.com.pl Głowacka-Walas (\href{https://orcid.org/0000-0002-7628-8691}{ORCID}) } Other contributors: