mediana-fundamentals

What this skill does

# 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

```r
data.model <- DataModel()
```

### OutcomeDist - Outcome Distribution

Specifies the distribution of patient outcomes.

```r
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

```r
# 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:**
```r
# 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

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

### Event - Event-Driven Design

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

### Design - Enrollment and Dropout

```r
# 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

```r
# 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

```r
analysis.model <- AnalysisModel()
```

### Test - Statistical Tests

```r
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

```r
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

```r
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:**
```r