mediana-fundamentals

name	mediana-fundamentals
description	Core Mediana package functions for Clinical Scenario Evaluation (CSE). Use when designing data models, analysis models, evaluation models, and running comprehensive trial simulations.

Mediana Fundamentals

When to Use This Skill

• Building Clinical Scenario Evaluation (CSE) frameworks
• Defining data models with various endpoint distributions
• Configuring analysis models with statistical tests
• Setting up multiplicity adjustment procedures
• Defining evaluation criteria (power metrics)
• Running comprehensive trial simulations
• Generating Word-based simulation reports

Package Overview

Mediana by Gautier Paux and Alex Dmitrienko provides a general framework for clinical trial simulations based on the Clinical Scenario Evaluation approach (Benda et al., 2010).

CSE Framework Components

1. Data Models - Define data generation process
2. Analysis Models - Define statistical methods
3. Evaluation Models - Define success criteria

Data Model

Initialization

data.model <- DataModel()

OutcomeDist - Outcome Distribution

Specifies the distribution of patient outcomes.

OutcomeDist(
  outcome.dist = "NormalDist",   # Distribution type
  outcome.type = "standard"       # "standard" or "event"
)

Supported Distributions:

Distribution	Parameters	Use Case
UniformDist	max	Uniform outcomes
NormalDist	mean, sd	Continuous endpoints
BinomDist	prop	Binary endpoints
BetaDist	a, b	Proportions
ExpoDist	rate	Time-to-event
WeibullDist	shape, scale	Survival with shape
TruncatedExpoDist	rate, trunc	Truncated survival
PoissonDist	lambda	Count data
NegBinomDist	dispersion, mean	Overdispersed counts
MultinomialDist	prob	Categorical outcomes

Multivariate Distributions:

Distribution	Parameters	Use Case
MVNormalDist	par, corr	Correlated continuous
MVBinomDist	par, corr	Correlated binary
MVExpoDist	par, corr	Correlated survival
MVExpoPFSOSDist	par, corr	PFS/OS endpoints
MVMixedDist	type, par, corr	Mixed endpoint types

Sample - Treatment Arm Definition

# Normal distribution parameters
outcome.placebo <- parameters(mean = 0, sd = 70)
outcome.treatment <- parameters(mean = 40, sd = 70)

# Define samples
Sample(id = "Placebo",
       outcome.par = parameters(outcome.placebo))

Sample(id = "Treatment",
       outcome.par = parameters(outcome.treatment))

Multiple Scenarios:

# Define multiple effect size scenarios
outcome1.placebo <- parameters(mean = 0, sd = 70)
outcome1.treatment <- parameters(mean = 40, sd = 70)  # Conservative

outcome2.placebo <- parameters(mean = 0, sd = 70)
outcome2.treatment <- parameters(mean = 50, sd = 70)  # Optimistic

Sample(id = "Placebo",
       outcome.par = parameters(outcome1.placebo, outcome2.placebo))

Sample(id = "Treatment",
       outcome.par = parameters(outcome1.treatment, outcome2.treatment))

SampleSize - Balanced Design

SampleSize(c(50, 55, 60, 65, 70))  # Per arm
SampleSize(seq(50, 100, 10))

Event - Event-Driven Design

Event(
  n.events = c(390, 420),      # Total event counts to evaluate
  rando.ratio = c(1, 2)        # Control:Treatment ratio
)

Design - Enrollment and Dropout

# Non-uniform enrollment with beta distribution
# 50% enrolled at 75% of enrollment period
enroll.par <- parameters(
  a = log(0.5)/log(0.75),
  b = 1
)

Design(
  enroll.period = 12,              # Enrollment duration (months)
  study.duration = 36,             # Total study duration
  enroll.dist = "BetaDist",        # Or "UniformDist"
  enroll.dist.par = enroll.par,
  dropout.dist = "ExpoDist",
  dropout.dist.par = parameters(rate = 0.0115)
)

Complete Data Model Example

# Time-to-event trial with PFS and OS
median.pfs.placebo <- 6
median.pfs.treatment <- 9
median.os.placebo <- 15
median.os.treatment <- 19

placebo.par <- parameters(
  parameters(rate = log(2)/median.pfs.placebo),
  parameters(rate = log(2)/median.os.placebo)
)

treatment.par <- parameters(
  parameters(rate = log(2)/median.pfs.treatment),
  parameters(rate = log(2)/median.os.treatment)
)

corr.matrix <- matrix(c(1.0, 0.3, 0.3, 1.0), 2, 2)

data.model <- DataModel() +
  OutcomeDist(outcome.dist = "MVExpoPFSOSDist",
              outcome.type = c("event", "event")) +
  Event(n.events = c(390, 420), rando.ratio = c(1, 2)) +
  Design(enroll.period = 12, study.duration = 30,
         enroll.dist = "BetaDist",
         enroll.dist.par = parameters(a = log(0.5)/log(0.75), b = 1),
         dropout.dist = "ExpoDist",
         dropout.dist.par = parameters(rate = 0.0115)) +
  Sample(id = list("Placebo PFS", "Placebo OS"),
         outcome.par = parameters(parameters(par = placebo.par,
                                             corr = corr.matrix))) +
  Sample(id = list("Treatment PFS", "Treatment OS"),
         outcome.par = parameters(parameters(par = treatment.par,
                                             corr = corr.matrix)))

Analysis Model

Initialization

analysis.model <- AnalysisModel()

Test - Statistical Tests

Test(
  id = "Primary",                           # Unique test ID
  samples = samples("Placebo", "Treatment"), # Samples to compare
  method = "TTest",                          # Test method
  par = parameters(...)                      # Optional parameters
)

Built-in Tests:

Method	Description	Parameters
TTest	Two-sample t-test	larger (optional)
TTestNI	Non-inferiority t-test	margin, larger
WilcoxTest	Wilcoxon-Mann-Whitney	larger
PropTest	Two-sample proportion	yates, larger
PropTestNI	NI proportion test	margin, yates, larger
FisherTest	Fisher exact test	larger
GLMPoissonTest	Poisson regression	larger
GLMNegBinomTest	Negative binomial	larger
LogrankTest	Log-rank test	larger
OrdinalLogisticRegTest	Ordinal logistic	larger

Note: Tests are one-sided. By default, larger values expected in Sample 2. Set larger = FALSE if larger values expected in Sample 1.

Statistic - Descriptive Statistics

Statistic(
  id = "Mean Treatment",
  method = "MeanStat",
  samples = samples("Treatment")
)

Built-in Statistics:

Method	Description	Samples Required
MeanStat	Mean	1
MedianStat	Median	1
SdStat	Standard deviation	1
MinStat	Minimum	1
MaxStat	Maximum	1
PropStat	Proportion	1
DiffMeanStat	Difference in means	2
DiffPropStat	Difference in proportions	2
EffectSizeContStat	Effect size (continuous)	2
EffectSizePropStat	Effect size (binary)	2
EffectSizeEventStat	Effect size (survival)	2
HazardRatioStat	Hazard ratio	2
EventCountStat	Number of events	1+
PatientCountStat	Number of patients	1+

MultAdjProc - Multiplicity Adjustment

MultAdjProc(
  proc = "HolmAdj",
  par = parameters(weight = c(0.5, 0.5)),
  tests = tests("Test1", "Test2")  # Optional: applies to all if omitted
)

Built-in Procedures:

Procedure	Type	Parameters
BonferroniAdj	Single-step	weight
HolmAdj	Step-down	weight
HochbergAdj	Step-up	weight
HommelAdj	Step-up	weight
FixedSeqAdj	Sequential	(order from tests)
ChainAdj	Graphical	weight, transition
FallbackAdj	Fallback	weight
NormalParamAdj	Parametric	corr, weight
ParallelGatekeepingAdj	Gatekeeping	family, proc, gamma
MultipleSequenceGatekeepingAdj	Gatekeeping	family, proc, gamma
MixtureGatekeepingAdj	Gatekeeping	family, proc, gamma, serial, parallel

Multiplicity Examples

Chain Procedure:

MultAdjProc(
  proc = "ChainAdj",
  par = parameters(
    weight = c(0.5, 0.5),
    transition = matrix(c(0, 1,
                          1, 0), 2, 2, byrow = TRUE)
  )
)

Parallel Gatekeeping:

MultAdjProc(
  proc = "ParallelGatekeepingAdj",
  par = parameters(
    family = families(
      family1 = c(1, 2),    # Primary endpoints
      family2 = c(3, 4)     # Secondary endpoints
    ),
    proc = families(
      family1 = "HolmAdj",
      family2 = "HolmAdj"
    ),
    gamma = families(
      family1 = 0.8,        # Truncation parameter
      family2 = 1
    )
  ),
  tests = tests("Primary1", "Primary2", "Secondary1", "Secondary2")
)

Multiple-Sequence Gatekeeping:

MultAdjProc(
  proc = "MultipleSequenceGatekeepingAdj",
  par = parameters(
    family = families(family1 = c(1, 2), family2 = c(3, 4)),
    proc = families(family1 = "HolmAdj", family2 = "HochbergAdj"),
    gamma = families(family1 = 0.8, family2 = 1)
  )
)

Complete Analysis Model Example

analysis.model <- AnalysisModel() +
  # Primary tests
  Test(id = "PFS test",
       samples = samples("Placebo PFS", "Treatment PFS"),
       method = "LogrankTest") +
  Test(id = "OS test",
       samples = samples("Placebo OS", "Treatment OS"),
       method = "LogrankTest") +

  # Fixed-sequence multiplicity adjustment
  MultAdjProc(proc = "FixedSeqAdj") +

  # Descriptive statistics
  Statistic(id = "Patients Placebo",
            samples = samples("Placebo PFS"),
            method = "PatientCountStat") +
  Statistic(id = "Patients Treatment",
            samples = samples("Treatment PFS"),
            method = "PatientCountStat")

Evaluation Model

Initialization

evaluation.model <- EvaluationModel()

Criterion - Success Metrics

Criterion(
  id = "Marginal power",
  method = "MarginalPower",
  tests = tests("Primary"),
  labels = c("Primary Power"),
  par = parameters(alpha = 0.025)
)

Built-in Criteria:

Method	Description	Parameters
MarginalPower	Power for each test	alpha
WeightedPower	Weighted combination	alpha, weight
DisjunctivePower	P(reject at least one)	alpha
ConjunctivePower	P(reject all)	alpha
ExpectedRejPower	Expected # rejected	alpha
MeanSumm	Mean of statistics	-
MedianSumm	Median of statistics	-

Complete Evaluation Model Example

evaluation.model <- EvaluationModel() +
  Criterion(id = "Marginal power",
            method = "MarginalPower",
            tests = tests("PFS test", "OS test"),
            labels = c("PFS Power", "OS Power"),
            par = parameters(alpha = 0.025)) +

  Criterion(id = "Disjunctive power",
            method = "DisjunctivePower",
            tests = tests("PFS test", "OS test"),
            labels = c("At least one significant"),
            par = parameters(alpha = 0.025)) +

  Criterion(id = "Average patients",
            method = "MeanSumm",
            statistics = statistics("Patients Placebo", "Patients Treatment"),
            labels = c("Mean Placebo N", "Mean Treatment N"))

Running Simulations

SimParameters

sim.parameters <- SimParameters(
  n.sims = 10000,        # Number of simulations
  proc.load = "full",    # Parallelization: "low", "med", "high", "full", or integer
  seed = 42938001        # For reproducibility
)

CSE Function

results <- CSE(
  data.model,
  analysis.model,
  evaluation.model,
  sim.parameters
)

# View summary
summary(results)

Results Structure

The CSE function returns a list with:

• simulation.results: Data frame of results per scenario
• analysis.scenario.grid: Grid of data/analysis combinations
• data.structure: Data model structure
• analysis.structure: Analysis model structure
• evaluation.structure: Evaluation model structure
• sim.parameters: Simulation parameters
• timestamp: Start/end time and duration

Report Generation

PresentationModel

presentation.model <- PresentationModel() +
  Project(username = "Analyst Name",
          title = "Phase III Trial Simulation",
          description = "Power analysis for multi-endpoint trial") +
  Section(by = "outcome.parameter") +
  Subsection(by = "sample.size") +
  Table(by = "multiplicity.adjustment") +
  CustomLabel(param = "sample.size",
              label = paste0("N = ", c(50, 60, 70))) +
  CustomLabel(param = "outcome.parameter",
              label = c("Conservative", "Expected", "Optimistic"))

GenerateReport

GenerateReport(
  presentation.model = presentation.model,
  cse.results = results,
  report.filename = "Simulation_Report.docx"
)

Complete Example: Multi-Endpoint Trial

library(Mediana)

# Data Model
outcome.placebo <- parameters(mean = 0, sd = 1)
outcome.trt.conservative <- parameters(mean = 0.3, sd = 1)
outcome.trt.expected <- parameters(mean = 0.5, sd = 1)

data.model <- DataModel() +
  OutcomeDist(outcome.dist = "NormalDist") +
  SampleSize(seq(80, 120, 10)) +
  Sample(id = "Placebo",
         outcome.par = parameters(outcome.placebo, outcome.placebo)) +
  Sample(id = "Treatment",
         outcome.par = parameters(outcome.trt.conservative, outcome.trt.expected))

# Analysis Model
analysis.model <- AnalysisModel() +
  Test(id = "Primary",
       samples = samples("Placebo", "Treatment"),
       method = "TTest") +
  Statistic(id = "Effect Size",
            samples = samples("Placebo", "Treatment"),
            method = "EffectSizeContStat")

# Evaluation Model
evaluation.model <- EvaluationModel() +
  Criterion(id = "Power",
            method = "MarginalPower",
            tests = tests("Primary"),
            labels = "Primary Power",
            par = parameters(alpha = 0.025)) +
  Criterion(id = "Mean Effect",
            method = "MeanSumm",
            statistics = statistics("Effect Size"),
            labels = "Mean Effect Size")

# Run Simulations
results <- CSE(
  data.model,
  analysis.model,
  evaluation.model,
  SimParameters(n.sims = 10000, proc.load = "full", seed = 12345)
)

# View Results
summary(results)

# Generate Report
presentation.model <- PresentationModel() +
  Project(title = "Sample Size Analysis") +
  Section(by = "outcome.parameter") +
  Table(by = "sample.size") +
  CustomLabel(param = "outcome.parameter",
              label = c("Conservative", "Expected"))

GenerateReport(presentation.model, results, "Analysis_Report.docx")

Best Practices

1. Multiple Scenarios: Always evaluate multiple treatment effect assumptions
2. Sample Size Range: Test a range of sample sizes to build power curves
3. Reproducibility: Always set seed in SimParameters
4. Parallelization: Use proc.load = "full" for large simulations
5. Report Labels: Use CustomLabel for interpretable scenario names
6. Validation: Compare CSE results to analytical formulas where available
7. Multiplicity: Select appropriate procedures based on hypothesis structure