# FIND Package Guidance

## Introduction

The FIND package provides tools for working with Phase I dose-finding trial designs. This vignette demonstrates how to use the package for the following designs: 3plus3, i3plus3, g3, boin, and mtpi2.

    library(FIND)

## Function Dependencies

The package functions follow a hierarchical structure:

    design_*()
        │
        ├──> get_decision()
        │         │
        │         └──> decision_table()
        │
        └──> run_simulation()
                  │
                  └──> oc_plot()

- Design constructors (`design_3plus3()`, `design_i3plus3()`, `design_g3plus3()`, `design_mtpi2()`, `design_boin()`): Create design objects that store all parameters.
- `get_decision()`: Takes a design object and generates decision tables.
- `decision_table()`: Takes multiple design objects and generates comparison plots.
- `run_simulation()`: Takes a design object plus toxicity scenarios and runs simulations.
- `oc_plot()`: Takes multiple simulation results and generates operating characteristic plots.

## Part 1: Generating Decision Tables

Decision tables provide the dose escalation/de-escalation rules for each design.

### Creating Design Objects

First, create design objects with the desired parameters:

    # Create a 3plus3 design
    design_3 <- design_3plus3(
      npts = 12,
      ncohort = 10,
      cohortsize = 3
    )

    # Create an i3plus3 design
    design_i3 <- design_i3plus3(
      pT = 0.25,
      EI = c(0.2, 0.3),
      npts = 12,
      ncohort = 10,
      cohortsize = 3
    )

    # Print the design
    print(design_3)
    print(design_i3)

### Generating Decision Tables for Individual Designs

Use `get_decision()` to generate decision tables:

    # Generate decision table for 3plus3
    decision_3 <- get_decision(design_3)

    # Generate decision table for i3plus3
    decision_i3 <- get_decision(design_i3)

    # View the decision table
    head(decision_3$tab)
    head(decision_i3$tab)

### Comparing Decision Tables Across Designs

The `decision_table()` function generates comparison plots for multiple designs:

    # Compare decision tables for 3plus3 and i3plus3
    decision_table(design_3, design_i3)

This generates a comprehensive comparison plot showing decision rules side-by-side.

### Saving Decision Table Plots

To save the generated plots, use `ggsave()`. By default, plots are saved to a newly created folder with a timestamp in the current working directory:

    # Create output folder with timestamp
    output_folder <- paste0("FIND_output_", format(Sys.time(), "%Y%m%d_%H%M%S"))
    dir.create(output_folder, showWarnings = FALSE)

    # Generate and save decision table plot
    p <- decision_table(design_3, design_i3)
    ggsave(
      filename = file.path(output_folder, "decision_table_comparison.png"),
      plot = p,
      width = 10,
      height = 6,
      dpi = 300
    )

### Other Designs

You can also create other design objects:

    # g3 design
    design_g3 <- design_g3plus3(
      npts = 12,
      ncohort = 10,
      cohortsize = 3
    )

    # mtpi2 design
    design_mtpi <- design_mtpi2(
      pT = 0.25,
      EI = c(0.2, 0.3),
      npts = 12,
      ncohort = 10
    )

    # boin design
    design_b <- design_boin(
      pT = 0.25,
      EI = c(0.15, 0.35),
      npts = 12,
      ncohort = 10,
      cohortsize = 3
    )

    # Compare all designs
    decision_table(design_3, design_i3, design_g3, design_mtpi, design_b)

## Part 2: Running Simulations

Simulations evaluate the operating characteristics of each design under different toxicity scenarios.

### Setting Up Simulations

Define the true toxicity probabilities and the true MTD:

    # Define toxicity scenario
    p.true <- c(0.05, 0.10, 0.20, 0.30, 0.45)
    mtd.true <- c(0, 0, 1, 0, 0)  # Dose 3 is MTD

### Running Simulations for Individual Designs

Use `run_simulation()` to run simulations:

    # Run simulation for 3plus3
    sim_3 <- run_simulation(design_3, p.true = p.true, mtd.true = mtd.true)

    # Run simulation for i3plus3
    sim_i3 <- run_simulation(design_i3, p.true = p.true, mtd.true = mtd.true)

    # View results
    sim_3$selection
    sim_3$allocation

    sim_i3$selection
    sim_i3$allocation

### Multiple Scenario Simulations

You can run simulations across multiple toxicity scenarios using matrix format:

    # Define multiple scenarios
    p.true <- matrix(
      c(0.05, 0.10, 0.20, 0.30, 0.45,
        0.10, 0.15, 0.25, 0.35, 0.50),
      nrow = 2, byrow = TRUE
    )

    mtd.true <- matrix(
      c(0, 0, 1, 0, 0,
        0, 0, 1, 0, 0),
      nrow = 2, byrow = TRUE
    )

    # Run simulations
    sim_3 <- run_simulation(design_3, p.true = p.true, mtd.true = mtd.true)
    sim_i3 <- run_simulation(design_i3, p.true = p.true, mtd.true = mtd.true)

### Using Pre-defined Scenarios

The package provides pre-defined toxicity scenarios:

    # Load pre-defined scenarios
    scenarios <- load_true(pT = 0.25)

    # Use a specific scenario
    p.true <- scenarios[["FFP-BOIN provided"]][["p.true"]][5,]
    mtd.true <- c(0, 0, 0, 0, 1, 0)  # Dose 5 is MTD

    # Run simulations
    sim_3 <- run_simulation(design_3, p.true = p.true, mtd.true = mtd.true)
    sim_i3 <- run_simulation(design_i3, p.true = p.true, mtd.true = mtd.true)

### Comparing Operating Characteristics

Use `oc_plot()` to compare operating characteristics across designs:

    # Compare OC plots for 3plus3 and i3plus3
    oc_plot(sim_3, sim_i3)

### Saving Operating Characteristic Plots

To save the OC plots:

    # Create output folder with timestamp (if not already created)
    output_folder <- paste0("FIND_output_", format(Sys.time(), "%Y%m%d_%H%M%S"))
    dir.create(output_folder, showWarnings = FALSE)

    # Generate and save OC plot
    p <- oc_plot(sim_3, sim_i3)
    ggsave(
      filename = file.path(output_folder, "oc_plot_comparison.png"),
      plot = p,
      width = 12,
      height = 8,
      dpi = 300
    )

### Modifying Simulation Parameters

Design objects can include additional simulation parameters:

    # Create design with specific simulation settings
    design_i3_custom <- design_i3plus3(
      pT = 0.25,
      EI = c(0.2, 0.3),
      npts = 12,
      ncohort = 15,          # More cohorts
      cohortsize = 3,
      ntrial = 1000,         # Number of simulation trials
      n.earlystop = 18,      # Early stopping parameter
      extrasafe = TRUE       # Extra safety rule
    )

    # Run simulation with custom settings
    sim_i3_custom <- run_simulation(design_i3_custom, p.true = p.true, mtd.true = mtd.true)