---
title: "Propensity Score-Integrated Kaplan-Meier (PSKM) Method in Augmenting Single-Arm Studies"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Propensity Score-Integrated Kaplan-Meier (PSKM) Method in Augmenting Single-Arm Studies}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r, eval=T, echo=FALSE}
suppressMessages(require(psrwe, quietly = TRUE))
org_digits <- options(digits = 3)
set.seed(1000)
```
<br>


## Introduction

In the **psrwe**, PS-integrated Kaplan-Meier (PSKM) method (Chen, et al., 2022)
is also implemented for leveraging real-world evidence in augmenting
single-arm studies.
The PSKM is an non-parametric approach for evaluating time-to-event endpoints.

Similar with the approaches: PSPP (Wang, et al., 2019) and
PSCL (Wang, et al., 2020),
the PS-integrated study design functions, `psrwe_est()` and `psrwe_borrow()`,
below estimate PS model, set borrowing parameters, and determine
discounting parameters for borrowing information.

```{r, eval=T, echo=TRUE}
data(ex_dta)
dta_ps <- psrwe_est(ex_dta,
                    v_covs = paste("V", 1:7, sep = ""),
                    v_grp = "Group",
                    cur_grp_level = "current",
                    nstrata = 5,
                    ps_method = "logistic")
ps_bor <- psrwe_borrow(dta_ps,
                       total_borrow = 30,
                       method = "distance")
```
<br>


## PS-integrated Kaplan-Meier method 

For single arm studies, when there is one external data source, the function
`psrwe_survkm()` allows one to conduct the survival analysis
via Kaplan-Meier (KM) estimates (Kaplan and Meier, 1985).
The PSKM approach is applied in each PS stratum to obtain stratum-specific
KM estimates on all distinctive time points, which are combined to complete
the overall survival estimates.
Suppose we are interested in the survival probability at one year, then
we may use the argument `pred_tp=365` (days) in the function
`psrwe_survkm()` to specify the time point of interest.

```{r, eval=T, echo=TRUE}
rst_km <- psrwe_survkm(ps_bor,
                       pred_tp = 365,
                       v_time  = "Y_Surv",
                       v_event = "Status")
rst_km
```

The `pred_tp_365` will be carried on to other down-stream analyses.
However, the function `psrwe_survkm()` still returns results on
all distinctive time points which may be also needed for down-stream analysis
(e.g., visualizing KM curves and confidence intervals).
Therefore, the returned object `rst_km` above may have different
data structure then those returned by the PSPP and PSCL approaches.
Please use `str()` to see the details.

The default method of `stderr_method` for KM estimates is
based on the Greenwood formula and the asymptotic theorem that
may rely on the independent assumption.
However, the Jackknife may provide more robust estimations for
the standard errors in general.

Two Jackknife options have been implemented for estimating standard
errors of the survival estimates via the options for the
function `psrwe_survkm()`:
* `stderr_method = "jk"` applies Jackknife by each stratum.
* `stderr_method = "sjk"` applies simple Jackknife on the overall
survival probability.
Both results may be similar but slightly different
since the overall weights are fixed and close to one over the
number of total strata.

Please see Section of Demo example below for examples using `stderr_method`.
<br>


## Visualized PSKM results

The overall survival estimates can be further visualized as below.

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst_km)
```

The stratum-specific survival estimates can be further visualized as below.

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst_km, add_ci = FALSE, add_stratum = TRUE)
```

The confidence intervals can be also visualized as below.

```{r, echo=TRUE, fig.width=6, fig.height=5}
plot(rst_km, conf_type = "plain")
```
<br>


## PSKM inference

The inference for the parameters of interest such as survival
probability or rate at one year (`pred_tp=365` days) can be
further arrived from the utility function `psrwe_outana()`.
For example, the code below test the one year survival probability
is `greater` than `mu = 0.7` (i.e., `70%`) or not,
i.e., the example tests
$$
H_0: S(\tau) \leq 0.7 \quad \mbox{vs.} \quad H_a: S(\tau) > 0.7 
$$
where $S(\tau)$ is the survival probability at time $\tau = 365$
days.

```{r, eval=T, echo=TRUE}
oa_km <- psrwe_outana(rst_km, mu = 0.70, alternative = "greater")
oa_km
```

The details of stratum-specific estimates can be printed via the `print()`
function with the option `show_details = TRUE`.

```{r, eval=T, echo=TRUE}
print(oa_km, show_details = TRUE)
```

As the **survival** package, the results of other time points can be also
predicted via the `summary()` with the option `pred_tps`.

```{r, eval=T, echo=TRUE}
summary(oa_km, pred_tps = c(180, 365))
```
<br>


## Demo example

The script in "**psrwe/demo/sec_4_4_ex.r**" source file has
the full example for the PSKM single-arm study which can be run via
the `demo("sec_4_4_ex", package = "psrwe")`.

Two Jackknife standard errors are also demonstrated in the script.
Note that Jackknife standard errors may take a while to finish.
<br>


## References

1. Kaplan, E. L. and Meier, P. (1958).
Nonparametric Estimation from Incomplete Observations.
Journal of the American Statistical Association, 53(282), 457-481.

2. Chen, W.-C., Lu, N., Wang, C., Li, H., Song, C., Tiwari, R., Xu, Y., and
Yue, L.Q. (2022).
Propensity Score-Integrated Approach to Survival Analysis: Leveraging External
Evidence in Single-Arm Studies.
Journal of Biopharmaceutical Statistics, 32(3), 400-413.

3. Wang, C., Li, H., Chen, W. C., Lu, N., Tiwari, R., Xu, Y., and Yue, L.Q.
(2019).
Propensity score-integrated power prior approach for incorporating
real-world evidence in single-arm clinical studies.
Journal of Biopharmaceutical Statistics, 29(5), 731-748.

4. Wang, C., Lu, N., Chen, W. C., Li, H., Tiwari, R., Xu, Y., and Yue, L.Q.
(2020).
Propensity score-integrated composite likelihood approach for
incorporating real-world evidence in single-arm clinical studies.
Journal of Biopharmaceutical Statistics, 30(3), 495-507.

<br>

```{r, eval=T, echo=FALSE}
## Reset to user's options.
options(org_digits)
```
<br>