Contributing to randomforge

Introduction

randomforge — An Open Project for Clinical Trial Randomization in R

randomforge is a newly started, open-source project on GitHub that aims to provide a clean and transparent implementation of clinical trial randomization methods in R. The initial version focuses on a flexible and modular implementation of permuted block randomization, with the goal of gradually expanding the framework to additional techniques.

The project is still in an early phase, but it is designed to be openly accessible and easy to extend. Contributions, discussions, and feedback from statisticians, programmers, and clinical trial practitioners are explicitly welcome as the project evolves.

This vignette explains how to:

Install and try the package with a small reproducible example
Contribute to the project
Use GitHub effectively even if you are new to it

Installing randomforge and running a simple randomization

At this stage, the package is not yet on CRAN.
You can install the development version directly from GitHub:

# install.packages("remotes")
remotes::install_github("RCONIS/randomforge")

Below is a minimal example that demonstrates a simple permuted block randomization workflow.

library(randomforge)
#> randomforge developer version 0.1.0.9046 loaded

# Create an in-memory randomization database
randomDataBase <- getRandomDataBase()

# Define a project and configuration
randomProject <- getRandomProject("Example Trial")
randomDataBase$persist(randomProject)

# Create a randomization configuration
config <- getRandomConfiguration(
    randomProject        = randomProject,
    treatmentArmIds      = c("A", "B"),
    seed                 = createSeed(),
    ravBufferMinimumSize = 1000L,
    ravBufferMaximumSize = 10000L
)

randomDataBase$persist(config)

# Define fixed block size
blockSizes <- getBlockSizes(config$treatmentArmIds, 8)

# Create a permuted block randomization method
randomMethodPBR <- getRandomMethodPBR(
    blockSizes = blockSizes
)

# Create a random allocation value service
ravService <- getRandomAllocationValueService()
ravService$createNewRandomAllocationValues(config)
#> Create 9000 new random allocation values (seed = 7877373)

# Create a few randomization results
resultList <- lapply(1:8, function(i) {
    suppressMessages(getNextRandomResult(
        randomDataBase               = randomDataBase,
        randomProject                = randomProject,
        randomMethod                 = randomMethodPBR,
        randomAllocationValueService = ravService
    ))
})

# Convert results to a data frame
randomDataBase |> 
    as.data.frame() |>
    knitr::kable()

project	random-number	treatment-arm	status	overall-levels-A	overall-levels-B	block-wise-levels-A	block-wise-levels-B	randomization-decision	unique-subject-id
Example Trial	1	A	RANDOMIZED	1	0	A:1/4	B:0/4	range-set[A=[0,0.5], B=[0.5,1]; rav=0.436194751877338]	7164d8a4-4853-44bb-80c4-c6328d2538a8
Example Trial	2	A	RANDOMIZED	2	0	A:2/4	B:0/4	range-set[A=[0,0.5], B=[0.5,1]; rav=0.212838937761262]	37e68cc4-36c9-41d3-8353-0f00e184b56f
Example Trial	3	A	RANDOMIZED	3	0	A:3/4	B:0/4	range-set[A=[0,0.5], B=[0.5,1]; rav=0.264616345288232]	dc45a4e0-ea76-41ec-8cfb-b7fe15b349c9
Example Trial	4	B	RANDOMIZED	3	1	A:3/4	B:1/4	range-set[A=[0,0.5], B=[0.5,1]; rav=0.645004761172459]	57a06f26-99bf-49e8-8ed3-37e4c6ec4db7
Example Trial	5	A	RANDOMIZED	4	1	A:4/4	B:1/4	range-set[A=[0,0.5], B=[0.5,1]; rav=0.474519594805315]	9e8d22b8-001a-4a35-b3b6-b3de074354ad
Example Trial	6	B	RANDOMIZED	4	2	A:4/4	B:2/4	range-set[A=[0,0], B=[0,1]; rav=0.598658049479127]	a778411a-038c-4169-ac35-c1c9dd4dc8c9
Example Trial	7	B	RANDOMIZED	4	3	A:4/4	B:3/4	range-set[A=[0,0], B=[0,1]; rav=0.478221806231886]	c6dcf1c2-dbb5-456a-866a-990281bcc29a
Example Trial	8	B	RANDOMIZED	4	4	A:4/4	B:4/4	range-set[A=[0,0], B=[0,1]; rav=0.730046623619273]	e1ffac64-55bf-4223-a0a4-900d018fad36

How to contribute to randomforge

Contributions of all kinds are welcome:

new randomization methods
improvements to the existing code
better documentation
tests and reproducible examples
fixing typos or cleaning up style
suggesting new functionality

You do not need to be an expert in R, Git, or clinical trial methodology to get involved.
We are happy to support new contributors.

Option A: Get invited as a direct contributor

If you prefer not to deal with forks or pull requests, you can simply request to be added as a contributor to the GitHub repository.

Please send an email to:

friedrich.pahlke@rpact.com

with a brief note explaining:

who you are
your GitHub username
why you would like to contribute

Once added, you will be able to push branches and open pull requests directly in the main repository.

Option B: Contribute via Fork (recommended for most users)

If you are not familiar with GitHub contribution workflows, here is a simple step-by-step guide.

Step 1 — Create a GitHub account

If you do not already have one, register at
https://github.com

Step 2 — Open the randomforge repository

Navigate to:
https://github.com/RCONIS/randomforge

Step 3 — Click “Fork”

The button is in the upper-right corner.
This creates your own copy of the repository under your GitHub account.

Step 4 — Clone your fork to your local machine

git clone https://github.com/YOUR_USERNAME/randomforge.git

Then:

cd randomforge

Step 5 — Create a new branch for your change

git checkout -b my-feature-branch

Step 6 — Make your changes locally

Edit R files, documentation, tests, examples, or vignettes.

Step 7 — Commit your changes

git add .
git commit -m "Add new feature / fix / improvement"

Step 8 — Push your branch to your fork

git push origin my-feature-branch

Step 9 — Open a Pull Request

Go back to your fork on GitHub and click:

“Compare & pull request”

In the Pull Request description, please provide:

a brief explanation of your change
any related issue numbers
optional: screenshots or examples

We will review all contributions as soon as possible.

Getting help

If you get stuck at any point — GitHub workflow, code questions, architecture discussion — feel free to:

open an issue in the GitHub repository, or
send an email to: friedrich.pahlke@rpact.com

All questions are welcome, especially from newcomers.
We want to make contributing as easy and friendly as possible.

Thank you

We appreciate your interest in contributing to the randomforge project.
Your ideas and contributions help shape a more open, transparent, and community-driven future for clinical trial randomization in R.

Friedrich Pahlke

2025-11-26