---
title: "Complex censoring with rcenscomp"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Complex censoring with rcenscomp}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

The `rcenscomp` family separates latent event times from the observation
operator. Every specialized function returns the observed table in `data`,
optional exact quantities in `latent`, and design-specific diagnostics.

## A latent sample

The Weibull helpers use shape `alpha` and rate-like `beta`.

```{r latent}
library(rcens)
set.seed(2026)
x <- rcenscomp_rweibull_rate(20, beta = 2.5, alpha = 1.5)
head(x)
```

## Interval censoring

A common visit schedule replaces each exact event by a left, interval, or
right-censored record.

```{r interval}
interval_dat <- rcenscomp_interval(x, visits = c(0.2, 0.4, 0.8))
head(as.data.frame(interval_dat))
interval_dat$diagnostics[c("n_left", "n_interval", "n_right")]
```

## Current status

Current-status data record whether an event occurred by one inspection time;
the inspection is not an exact event time.

```{r current}
inspection <- seq(0.1, 1, length.out = length(x))
current_dat <- rcenscomp_current_status(x, inspection)
head(as.data.frame(current_dat))
```

## Hybrid Type-I and Type-II

The two schemes differ only in whether the stopping time is the minimum or
maximum of `T` and the target order statistic.

```{r hybrid}
hybrid_i <- rcenscomp_hybrid_type1(x, T = 0.6, r = 10)
hybrid_ii <- rcenscomp_hybrid_type2(x, T = 0.6, r = 10)
c(Type_I = hybrid_i$design$Tstar, Type_II = hybrid_ii$design$Tstar)
c(Type_I = hybrid_i$design$D, Type_II = hybrid_ii$design$D)
```

## Progressive Type-II

Withdrawal selection is uniform among eligible survivors. A valid plan has
`sum(R) = n - length(R)`.

```{r progressive-type2}
set.seed(2027)
R <- rep(1L, 10)
prog_ii <- rcenscomp_progressive_type2(x, R)
prog_ii$design$compact
```

## Progressive hybrid

The time cap can stop a progressive plan before its target failure count.

```{r progressive-hybrid}
set.seed(2028)
prog_hybrid <- rcenscomp_progressive_hybrid(x, R, T = 0.5)
prog_hybrid$diagnostics[c("D", "Rstar", "stopping_time")]
```

## Delayed entry

Units that fail before entry are absent because of truncation. They are not
censored observations.

```{r delayed-entry}
entry <- seq(0, 0.3, length.out = length(x))
delayed <- rcenscomp_delayed_entry(x, entry, censor = rep(1.5, length(x)))
head(as.data.frame(delayed))
delayed$diagnostics[c("n_truncated", "n_observed", "n_events")]
```

## Informative censoring through shared frailty

This generator shares an unobserved individual frailty between the event and
censoring processes. It is a sensitivity mechanism, not an inferential
correction.

```{r informative}
set.seed(2029)
informative <- rcenscomp_informative_frailty(
  n = 20,
  beta_x = 2.5, alpha_x = 1.5,
  beta_c = 1.3, alpha_c = 1.1,
  gamma_x = c(0.5, -0.3), gamma_c = c(-0.2, 0.4),
  theta = 0.6, rho = 0.8
)
head(as.data.frame(informative))
```

## Competing risks

Status zero is censoring; positive integers identify the observed cause. The
independence of latent cause times is a simulation assumption.

```{r competing}
set.seed(2030)
competing <- rcenscomp_competing_risks(
  n = 20,
  beta = c(1.2, 0.8),
  alpha = c(1.4, 1.1),
  censor_time = 1
)
table(as.data.frame(competing)$status)
```

## Interpreting the observed objects

The observed columns determine the appropriate likelihood representation:

- interval data use `(L, R]` probabilities;
- current status uses a binary probability at `inspection`;
- delayed entry conditions on survival to `entry`;
- hybrid and progressive outputs use subject-wise `(time, delta)` records;
- frailty-dependent censoring requires a joint or sensitivity interpretation;
- competing risks use `(time, status)` with an explicitly defined estimand.

Keeping `latent` is useful for auditing simulation code. Setting
`keep_latent = FALSE` removes those unobserved values from the returned object.