From cbe9e602ab4309c19b4e54dd5e9358a3ce78a222 Mon Sep 17 00:00:00 2001
From: Friedrich Pahlke <friedrich.pahlke@rpact.com>
Date: Tue, 25 Nov 2025 16:31:18 +0100
Subject: [PATCH] Update documentation to use bold for randomforge and add
 flexible PBR vignette

- Change *randomforge* to **randomforge** in R and vignette files
- Add vignette for flexible block size permuted block randomization
- Demonstrate project setup and randomization workflow in new vignette
- Include quality control and output inspection steps
- Provide system information in vignette output
- Improve clarity and reproducibility in documentation
---
 R/pkgname.R                                   |   2 +-
 vignettes/randomforge_contribution.Rmd        |   2 +-
 .../randomforge_flexible_pbr_example.Rmd      | 163 ++++++++++++++++++
 3 files changed, 165 insertions(+), 2 deletions(-)
 create mode 100644 vignettes/randomforge_flexible_pbr_example.Rmd

diff --git a/R/pkgname.R b/R/pkgname.R
index 0684465..9791b6b 100644
--- a/R/pkgname.R
+++ b/R/pkgname.R
@@ -33,7 +33,7 @@
 #' The package aims to support a broad range of classical, 
 #' covariate-adaptive, and response-adaptive techniques while 
 #' enabling reproducibility, auditability, and methodological clarity.
-#' Built as part of the open *randomforge* initiative ("Innovating the 
+#' Built as part of the open **randomforge** initiative ("Innovating the 
 #' Future of Randomization"), the package encourages community 
 #' collaboration, modular extensions, and contributions from academia, 
 #' industry, and clinical researchers.
diff --git a/vignettes/randomforge_contribution.Rmd b/vignettes/randomforge_contribution.Rmd
index 9b249ff..c79c768 100644
--- a/vignettes/randomforge_contribution.Rmd
+++ b/vignettes/randomforge_contribution.Rmd
@@ -215,6 +215,6 @@ We want to make contributing as easy and friendly as possible.
 
 ## Thank you
 
-We appreciate your interest in contributing to the *randomforge* project.  
+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.
diff --git a/vignettes/randomforge_flexible_pbr_example.Rmd b/vignettes/randomforge_flexible_pbr_example.Rmd
new file mode 100644
index 0000000..3d20c91
--- /dev/null
+++ b/vignettes/randomforge_flexible_pbr_example.Rmd
@@ -0,0 +1,163 @@
+---
+title: "Randomization with Flexible Block Sizes with randomforge"
+author: "Friedrich Pahlke"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Randomization with Flexible Block Sizes with randomforge}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Introduction
+
+This vignette provides a practical example for **randomforge**. 
+It demonstrates:
+
+- How to define treatment arms  
+- How to configure project-level randomization  
+- How do you implement permuted block randomization (PBR) with a fixed starting
+  block size and continuation with variable block sizes
+- How to perform quality control of random values  
+- How to extract and inspect the generated randomization list  
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+options(scipen = 999)
+```
+
+## Loading the randomforge Package
+
+```{r}
+library(randomforge)
+```
+
+## Trial Setup
+
+### Treatment Arms
+
+```{r}
+treatmentArmIds = c("Treatment", "Control")
+```
+
+### Maximum Number of Subjects per Center
+
+```{r}
+maxNumberOfSubjects <- 40
+```
+
+### Seed
+
+The seeds in this example will be generated via  
+[random.org](https://www.random.org/)
+
+```{r}
+#| eval: FALSE
+seed <- createSeed()
+seed
+```
+
+```{r}
+#| echo: FALSE
+seed <- 1379678
+seed
+```
+
+## Creating Project and Configuration
+
+```{r}
+randomDataBase <- getRandomDataBase()
+
+randomProject <- getRandomProject(name = "Flexible PBR Example Trial")
+randomDataBase$persist(randomProject)
+
+randomConfiguration <- getRandomConfiguration(
+    randomProject = randomProject, 
+    treatmentArmIds = treatmentArmIds, 
+    seed = seed
+)
+randomDataBase$persist(randomConfiguration)
+
+ravService <- getRandomAllocationValueService()
+```
+
+## Initial Randomization Using Fixed Block Size
+
+### Define Initial Block Length
+
+```{r, message = FALSE}
+initialBlockLength <- 8
+randomMethod <- getRandomMethodPBR(
+    blockSizes = getBlockSizes(treatmentArmIds, initialBlockLength)
+)
+for (i in 1:initialBlockLength) {
+    suppressMessages(getNextRandomResult(
+        randomDataBase, randomProject, randomMethod, ravService
+    ))
+}
+```
+
+## Variable Block Sizes for Remaining Subjects
+
+### Define Candidate Block Sizes
+
+```{r}
+blockSizes <- getBlockSizes(treatmentArmIds, c(4, 6))
+blockSizeRandomizer <- getRandomBlockSizeRandomizer(
+    blockSizes = blockSizes,
+    seed = 2758500)
+blockSizeRandomizer$initRandomValues(numberOfBlockSizes = length(blockSizes))
+```
+
+### Randomize Remaining Subjects
+
+```{r, message = FALSE}
+randomMethod <- getRandomMethodPBR(
+    blockSizes = blockSizes, 
+    fixedBlockDesignEnabled = FALSE, 
+    blockSizeRandomizer = blockSizeRandomizer
+)
+
+for (i in 1:(maxNumberOfSubjects - initialBlockLength)) {
+    suppressMessages(getNextRandomResult(
+        randomDataBase, randomProject, randomMethod, ravService
+    ))
+}
+```
+
+## Quality Control
+
+### Distribution of Used Random Values
+
+```{r}
+plot(ravService)
+```
+
+No significant deviation from a uniform distribution is detected (p > 0.05).
+
+### Distribution of All Generated Random Values
+
+```{r}
+plot(ravService, usedValuesOnly = FALSE)
+```
+
+## Output: Randomization List
+
+```{r}
+randomList <- as.data.frame(randomDataBase)
+knitr::kable(randomList)
+```
+
+## System Information
+
+- System: `r R.version.string`  
+- randomforge version: `r packageVersion("randomforge")`  
+- Platform: `r R.version$platform`  
+- Working directory: `r getwd()`