Deploying to gh-pages from @ 67222cb 🚀

Author: saumil-sh

404.html

@@ -257,9 +257,7 @@ If all three gates pass, the analysis function is called on the filtered
 data and the result is stored. Trigger state (`trigger_count`,
 `last_trigger_time`) is updated automatically.
 
-Construct a `Condition` with
-[`rlang::quos()`](https://rlang.r-lib.org/reference/defusing-advanced.html)
-to capture the filter predicates:
+Build a `Condition` from a validated trigger helper:
 
 ``` r
 # A toy snapshot data frame
@@ -272,7 +270,7 @@ snapshot <- data.frame(
 
 # Fire when at least 4 subjects are enrolled
 cond_interim <- Condition$new(
-  where    = rlang::quos(sum(!is.na(enroll_time)) >= 4),
+  where    = enroll_trigger(1.0, 4),
   analysis = function(df, current_time) {
     data.frame(n_enrolled = sum(!is.na(df$enroll_time)),
                fired_at   = current_time)
@@ -367,8 +365,8 @@ tm$add_timepoint(time = 15, arm = "A", enroller = 0L, dropper = 0L)
 tm$add_timepoint(time = 15, arm = "B", enroller = 0L, dropper = 0L)
 
 # Trigger: fire at calendar time 15
-cond_final <- Condition$new(
-  where    = rlang::quos(.data$time %in% 15),
+cond_final <- trigger_by_calendar(
+  cal_time = 15,
   analysis = function(df, current_time) {
     enrolled <- subset(df, !is.na(enroll_time))
     data.frame(
@@ -404,61 +402,40 @@ Triggers are the mechanism by which rxsim knows when to analyse the data
 and what to compute. Understanding how they are stored and evaluated is
 key to writing correct and flexible simulation code.
 
-### Why rlang::exprs()?
+### Safe trigger helpers
 
-A trigger condition needs to be a *stored* expression, not an
-immediately evaluated one. When you write
-`sum(!is.na(enroll_time)) >= 20`, R would evaluate it at the point of
-definition — before any data exists.
-[`rlang::exprs()`](https://rlang.r-lib.org/reference/defusing-advanced.html)
-wraps the expression in a quoted form so it is only evaluated later,
-inside `check_conditions()`, against the actual snapshot:
+Triggers for `analysis_generators` are created with validated helper
+constructors rather than quoted expressions. Use
+[`enroll_trigger()`](https://boehringer-ingelheim.github.io/rxsim/reference/trigger_primitives.md)
+for enrollment milestones,
+[`calendar_trigger()`](https://boehringer-ingelheim.github.io/rxsim/reference/trigger_primitives.md)
+for calendar-time analyses, and
+[`value_trigger()`](https://boehringer-ingelheim.github.io/rxsim/reference/trigger_primitives.md)
+/
+[`count_trigger()`](https://boehringer-ingelheim.github.io/rxsim/reference/trigger_primitives.md)
+when you want to write a predicate against a specific snapshot column.
 
 ``` r
-# Stored expressions, not immediately evaluated:
-rlang::exprs(sum(!is.na(enroll_time)) >= 20)
+enroll_trigger(0.5, 100)
+calendar_trigger(c(12, 24))
+value_trigger("time", ">=", 24)
+count_trigger("enroll_time", ">=", 50)
 ```
 
-`Condition$new()` uses
-[`rlang::quos()`](https://rlang.r-lib.org/reference/defusing-advanced.html)
-instead of
-[`rlang::exprs()`](https://rlang.r-lib.org/reference/defusing-advanced.html).
-The difference is that `quos()` also captures the *calling environment*,
-so values from the surrounding scope (e.g., `target_n`) are available
-inside the expression when it is evaluated. Use
-[`rlang::quos()`](https://rlang.r-lib.org/reference/defusing-advanced.html)
-in `Condition$new(where = ...)` and
+The helpers take plain R values, so there is no need for
 [`rlang::exprs()`](https://rlang.r-lib.org/reference/defusing-advanced.html)
-when supplying triggers to
-[`replicate_trial()`](https://boehringer-ingelheim.github.io/rxsim/reference/replicate_trial.md)’s
-`analysis_generators`.
-
-### The !! (bang-bang) operator
+or `!!` anymore. Invalid operators, wrong column names, and type
+mismatches are rejected immediately when the trigger is constructed.
 
-When you want to inject a value from the current R environment into a
-stored expression, use `!!`. Without it, the variable name is treated as
-a column name in the snapshot data frame — almost certainly not what you
-want:
-
-``` r
-target_n <- 40
-
-# CORRECT: !! injects the value 40 at definition time
-trigger <- rlang::exprs(sum(!is.na(enroll_time)) >= !!target_n)
-
-# WRONG: "target_n" would be looked for as a column name in the snapshot
-trigger_bad <- rlang::exprs(sum(!is.na(enroll_time)) >= target_n)
-```
+Compose helper triggers with `&` (AND) and `|` (OR), then pass the
+result directly as the `trigger` field in `analysis_generators`, or
+construct a `Condition` with `Condition$new(where = trigger, ...)`.
 
-This distinction matters when you loop over scenarios with different
-sample sizes: each iteration should bake in its own `target_n` value via
-`!!`.
+### Columns available to trigger helpers
 
-### Columns available in a trigger expression
-
-The trigger expression is evaluated against the snapshot data frame,
-which contains all columns from the `Population`’s `data` plus the four
-columns appended by `Trial`:
+Trigger helpers are evaluated against the snapshot data frame after they
+are converted to a `Condition`. The snapshot contains all columns from
+the `Population`’s `data` plus the four columns appended by `Trial`:
 
 - `enroll_time` — calendar enrollment time (`NA` if not enrolled)
 - `drop_time` — calendar dropout time (`NA` if not dropped)
@@ -471,17 +448,13 @@ also available.
 
 ### trigger_by_calendar() and trigger_by_fraction()
 
-> **Note:** These helper functions are being refactored in an upcoming
-> release to accept a `Trial` object directly. In the meantime, use
-> `Condition$new()` (shown below) to build triggers.
-
-`Condition$new()` with a calendar-time filter is the recommended
-approach for pre-planned analyses:
+For the two most common cases, use the convenience constructors directly
+to create `Condition` objects:
 
 ``` r
 # Fire at calendar time 24
-cond_final <- Condition$new(
-  where    = rlang::quos(.data$time %in% 24),
+cond_final <- trigger_by_calendar(
+  cal_time = 24,
   analysis = function(df, current_time) {
     data.frame(n_enrolled = sum(!is.na(df$enroll_time)))
   },
@@ -490,27 +463,40 @@ cond_final <- Condition$new(
 trial$conditions <- append(trial$conditions, list(cond_final))
 ```
 
-For information-fraction-based interims, filter on enrolled count:
-
 ``` r
 # Interim at 50% enrollment (target = 100)
-cond_interim <- Condition$new(
-  where    = rlang::quos(sum(!is.na(enroll_time)) >= 50),
+cond_interim <- trigger_by_fraction(
+  fraction = 0.5,
+  sample_size = 100,
   analysis = function(df, current_time) {
     enrolled <- subset(df, !is.na(enroll_time))
     data.frame(n = nrow(enrolled), time = current_time)
   },
-  name     = "interim_50pct",
-  max_triggers = 1L
+  name = "interim_50pct"
 )
 trial$conditions <- append(trial$conditions, list(cond_interim))
 ```
 
+When you need more than one predicate, compose helpers before building
+the `Condition`:
+
+``` r
+trig_both <- enroll_trigger(0.5, 100) & calendar_trigger(24)
+
+cond_both <- Condition$new(
+  where    = trig_both,
+  analysis = my_analysis,
+  name     = "interim_after_half_enrollment_at_day_24"
+)
+trial$conditions <- append(trial$conditions, list(cond_both))
+```
+
 ### Custom conditions
 
-You can condition on any expression involving the snapshot columns. For
-time-to-event endpoints this commonly means waiting for a target number
-of events rather than a target enrollment count:
+For trigger logic that cannot yet be expressed with the safe helpers,
+`Condition$new(where = rlang::quos(...))` remains the advanced escape
+hatch. For time-to-event endpoints this commonly means waiting for a
+target number of events rather than a target enrollment count:
 
 ``` r
 # Fire when 30 events have been observed (event = 1, censored = 0)
@@ -522,32 +508,35 @@ cond_events <- Condition$new(
 trial$conditions <- append(trial$conditions, list(cond_events))
 ```
 
-Multiple predicates in `where` are ANDed together, exactly as in
-[`dplyr::filter()`](https://dplyr.tidyverse.org/reference/filter.html):
+When the logic *can* be expressed with helper predicates, prefer
+composing `rxsim_trigger` objects with `&` instead of supplying multiple
+`where` quosures:
 
 ``` r
-# Fire only once the treatment arm has 15 enrolled subjects
-cond_trt <- Condition$new(
-  where    = rlang::quos(
-    arm == "treatment",
-    sum(!is.na(enroll_time[arm == "treatment"])) >= 15
-  ),
+# Fire once time 12 is reached and at least 15 subjects are enrolled
+cond_interim <- Condition$new(
+  where    = value_trigger("time", ">=", 12) & count_trigger("enroll_time", ">=", 15),
   analysis = my_analysis,
-  name     = "trt_interim"
+  name     = "interim_after_time12"
 )
-trial$conditions <- append(trial$conditions, list(cond_trt))
+trial$conditions <- append(trial$conditions, list(cond_interim))
 ```
 
 ### The analysis function signature
 
-Every analysis function receives two arguments:
+The analysis function always receives the filtered data frame and clock
+time as its first two positional arguments. Scenario-specific values can
+be declared as additional named parameters and injected via
+`analysis_args`:
 
 - `df`: the **full snapshot** — all arms, all currently enrolled
   subjects. The condition filter determined *whether* to fire; the
   analysis function decides *what to compute* from the full data.
 - `current_time`: the numeric clock time at which the condition fired.
+- `...`: any extra named values supplied through `analysis_args`.
 
 ``` r
+# Basic signature
 my_analysis <- function(df, current_time) {
   enrolled <- subset(df, !is.na(enroll_time))
   data.frame(
@@ -558,6 +547,20 @@ my_analysis <- function(df, current_time) {
                 mean(enrolled$data[enrolled$arm == "control"])
   )
 }
+
+# With extra scenario-specific arguments
+my_analysis_ext <- function(df, current_time, alpha, cov_matrix) {
+  # alpha and cov_matrix are injected from analysis_args at call time
+  enrolled <- subset(df, !is.na(enroll_time))
+  data.frame(fired_at = current_time, n = nrow(enrolled), alpha = alpha)
+}
+
+cond <- Condition$new(
+  where         = enroll_trigger(1.0, 100),
+  analysis      = my_analysis_ext,
+  analysis_args = list(alpha = 0.05, cov_matrix = diag(2)),
+  name          = "final"
+)
 ```
 
 ### Return values
@@ -633,9 +636,7 @@ dropout    <- function(n) rexp(n, rate = 0.02)
 # Step 4 — analysis trigger: fire when full enrollment is reached
 analysis_generators <- list(
   final = list(
-    trigger = rlang::exprs(
-      sum(!is.na(enroll_time)) >= !!sample_size
-    ),
+    trigger = enroll_trigger(1.0, sample_size),
     analysis = function(df, current_time) {
       enrolled <- subset(df, !is.na(enroll_time))
       data.frame(

LICENSE.html

@@ -456,7 +456,7 @@ population_generators <- list(
 
 analysis_generators <- list(
   final = list(
-    trigger = rlang::exprs(sum(!is.na(enroll_time)) >= 12L),
+    trigger = enroll_trigger(1.0, 12L),
     analysis = function(df, current_time) {
       enrolled <- subset(df, !is.na(enroll_time))
       data.frame(
@@ -532,8 +532,8 @@ add_timepoints(tmr3, fixed_plan)
 
 # Condition: fire at the final calendar time
 final_t <- tmr3$get_end_timepoint()
-cond_final <- Condition$new(
-  where    = rlang::quos(.data$time %in% !!final_t),
+cond_final <- trigger_by_calendar(
+  cal_time = final_t,
   analysis = function(df, current_time) {
     enrolled <- subset(df, !is.na(enroll_time))
     data.frame(n_enrolled = nrow(enrolled), time = current_time)