Updating the cran branch to reflect all changes upto 1.1.3 already in…

… CRAN

DESCRIPTION

@@ -1,14 +1,11 @@
 Package: clinfun
 Title: Clinical Trial Design and Data Analysis Functions
-Version: 1.1.1
+Version: 1.1.3.990
 Depends: R (>= 3.0.0), graphics, stats
 Imports: mvtnorm
-Suggests: 
-    knitr,
-    rmarkdown,
-    survival
+Suggests: knitr, rmarkdown, survival
 Author: Venkatraman E. Seshan [aut, cre], Karissa Whiting [aut]
-Authors@R:
+Authors@R: 
     c(person(given = "Venkatraman E.", family = "Seshan", role = c("aut", "cre"), email = "seshanv@mskcc.org"),
       person(given = "Karissa", family = "Whiting", role = "aut"))
 Description: Utilities to make your clinical collaborations easier if not
@@ -19,5 +16,3 @@ Maintainer: Venkatraman E. Seshan <seshanv@mskcc.org>
 License: GPL (>= 2)
 NeedsCompilation: yes
 VignetteBuilder: knitr
-RoxygenNote: 7.2.3
-Encoding: UTF-8

NEWS.md

@@ -1,14 +1,25 @@
-# clinfun 1.1.1 (03/07/2023)
+# clinfun 1.1.3 (07/11/2023)
 
-* changed class check to use `inherits()` instead of comparing strings
+* fixed the bug in ph2simon/twostage.admissible when minimax is also optimal
+* ph2simon and toxbdry help have been made more clear
 
-### New Documentation
+# clinfun 1.1.2 (06/19/2023)
+
+* changed all dfloat in fortran to dble
+* print method for ph2simon now lists admissible designs
+
+### New Functionality
+
+* plot and lines method for roc.curve includes the option for precision-recall curve
+* roc.curve returns PPV and NPV which are needed for precision-recall curve
+
+# clinfun 1.1.1 (03/06/2023)
 
-* Added new vignette highlighting clinical trial functions ([on website](https://veseshan.github.io/clinfun/articles/clinical-trial-functions.html)
+* changed class check to use inherits instead of comparing strings
 
 ### New Functionality
 
-* Added out.ties option to `coxphCPE()` for discrete risk score case
+* Added out.ties option to coxphCPE for discrete risk score case
 
 # clinfun 1.1.0 (02/22/2022)
 

R/ph2simon.R

@@ -1,49 +1,3 @@
-##' Simon's two-stage Phase II design
-##'
-##' Calculates the sample size and decision rules for Optimal and Minimax
-##' two-stage Phase II designs given by Richard Simon. The trial proceeds to
-##' the second stage only if a minimal number of responses is observed at the
-##' end of the first stage.
-##'
-##'
-##' @aliases ph2simon print.ph2simon plot.ph2simon
-##' @param pu unacceptable response rate; baseline response rate that needs to
-##' be exceeded for treatment to be deemed promising
-##' @param pa response rate that is desirable; should be larger than pu
-##' @param ep1 threshold for the probability of declaring drug promising under
-##' pu (target type 1 error rate); between 0 and 1
-##' @param ep2 threshold for the probability of declaring the drug not
-##' promising under pa (target type 2 error rate); between 0 and 1
-##' @param nmax maximum total sample size (default 100; can be at most 1000)
-##' @param x object returned by ph2simon
-##' @param ... arguments to be passed onto plot and print commands
-##' @return ph2simon returns a list with pu, pa, alpha, beta and nmax (as defined above)
-##' and: \item{out}{matrix of best two-stage designs for each value of total
-##' sample size n. The 6 columns in the matrix are: \tabular{rl}{ r1 \tab
-##' number of responses needed to exceeded in first stage \cr n1 \tab number of
-##' subjects treated in first stage \cr r \tab number of responses needed to
-##' exceeded at the end of trial \cr n \tab total number of subjects to be
-##' treated in the trial \cr EN(pu) \tab expected number pf patients in the
-##' trial under pu \cr PET(pu) \tab probability of stopping after the first
-##' stage under pu } }
-##'
-##' Trial is stopped early if <= r1 responses are seen in the first stage and
-##' treatment is considered desirable only when >r responses seen.
-##'
-##' @seealso \code{\link{twostage.inference}}, \code{\link{oc.twostage.bdry}}
-##' @references Simon R. (1989).  Optimal Two-Stage Designs for Phase II
-##' Clinical Trials. \emph{Controlled Clinical Trials} 10, 1-10.
-##'
-##' Jung SH, Carey M and Kim KM. (2001). Graphical Search for Two-Stage Designs
-##' for Phase II Clinical Trials. \emph{Controlled Clinical Trials} 22,
-##' 367-372.
-##' @keywords design design
-##' @examples
-##'
-##'   ph2simon(0.2, 0.4, 0.1, 0.1)
-##'   ph2simon(0.2, 0.35, 0.05, 0.05)
-##'   ph2simon(0.2, 0.35, 0.05, 0.05, nmax=150)
-##'
 ph2simon <- function(pu, pa, ep1, ep2, nmax = 100) {
   if(nmax > 1000) stop("nmax cannot exceed 1000")
   nmax1 <- nmax + 1
@@ -92,14 +46,14 @@ ph2simon <- function(pu, pa, ep1, ep2, nmax = 100) {
   ph2
 }
 
-#' @describeIn ph2simon formats and returns the minimax and optimal designs
 print.ph2simon <- function(x, ...) {
   xout <- x$out
   nmax <- x$nmax
   n <- nrow(xout)
   nopt <- ((1:n)[xout[,5]==min(xout[,5])])[1]
-  xopt <- xout[c(nopt,1),]
-  dimnames(xopt)[[1]] <- c("Optimal","Minimax")
+  #xopt <- xout[c(nopt,1),]
+  #dimnames(xopt)[[1]] <- c("Optimal","Minimax")
+  xopt <- twostage.admissible(x)
   cat("\n Simon 2-stage Phase II design \n\n")
   cat("Unacceptable response rate: ",x$pu,"\n")
   cat("Desirable response rate: ",x$pa,"\n")
@@ -109,7 +63,6 @@ print.ph2simon <- function(x, ...) {
   if(xopt[1,4]>nmax-10) warning(paste("  Optimal sample size too close to nmax. \n  Try increasing nmax (current value = ",nmax,")\n",sep=""))
 }
 
-#' @describeIn ph2simon plots the expected sample size against the maximum sample size ass in Jung et al., 2001
 plot.ph2simon <- function(x, ...) {
   xout <- x$out
   n <- nrow(xout)
@@ -209,13 +162,20 @@ twostage.admissible  <- function(x) {
     adm[istart+imin] = 1
     istart = istart+imin
   }
-  xout = xout[1:nopt,][adm==1,]
-  # find weight probability at which each rule is admissible
-  dmss = diff(xout[,4])
-  dess = diff(xout[,5])
-  qwt = round(dess/(dess - dmss),3)
-  # admissible designs
-  xout = cbind(xout, c(qwt, 0), c(1, qwt))
+  # this gives an error if minimax design is also optimal
+  # example ph2simon(0.8, 0.95, 0.05, 0.2)
+  if (nopt == 1) { # when minimal is also optimal
+    xout = xout[c(1, nopt),]
+    xout = cbind(xout, c(0, 0), c(1, 1))
+  } else {
+    xout = xout[1:nopt, ][adm == 1, ]
+    # find weight probability at which each rule is admissible
+    dmss = diff(xout[, 4])
+    dess = diff(xout[, 5])
+    qwt = round(dess/(dess - dmss), 3)
+    # admissible designs
+    xout = cbind(xout, c(qwt, 0), c(1, qwt))
+  }
   colnames(xout)[7:8] = c("qLo", "qHi")
   rownames(xout) = c("Minimax", rep("Admissible", nrow(xout)-2), "Optimal")
   xout

R/roc.curve.R

@@ -22,6 +22,10 @@ roc.curve <- function(marker, status, method=c("empirical")) {
   out$status <- status
   out$tpr <- zzz$tpr
   out$fpr <- zzz$fpr
+  # add PPV for precision(ppv)-recall(tpr) curve (and NPV for completeness)
+  prev = n1/n
+  out$ppv = prev*out$tpr/(prev*out$tpr + (1-prev)*out$fpr)
+  out$npv = (1-prev)*(1-out$fpr)/(prev*(1-out$tpr) + (1-prev)*(1-out$fpr))
   class(out) <- "roc.curve"
   out
 }
@@ -31,10 +35,18 @@ print.roc.curve <- function(x, ...) {
   cat("  ROC curve with AUC =", out$area, "and s.e. =", sqrt(out$var), "\n")
 }
 
-plot.roc.curve <- function(x, ...) {
-  plot(x$fpr, x$tpr, xlab="False positive rate", ylab="True positive rate", type="l", ...)
+plot.roc.curve <- function(x, PRC=FALSE, ...) {
+  if (PRC) {
+    plot(x$tpr, x$ppv, xlab="Recall (TPR)", ylab="Precision (PPV)", ylim=c(0,1), type="l", ...)
+  } else {
+    plot(x$fpr, x$tpr, xlab="False positive rate", ylab="True positive rate", type="l", ...)
+  }
 }
 
-lines.roc.curve <- function(x, ...) {
-  lines(x$fpr, x$tpr, ...)
+lines.roc.curve <- function(x, PRC=FALSE, ...) {
+  if (PRC) {
+    lines(x$tpr, x$ppv, ...)
+  } else {
+    lines(x$fpr, x$tpr, ...)
+  }
 }

man/ph2simon.Rd

@@ -1,78 +1,73 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/ph2simon.R
 \name{ph2simon}
+\title{Simon's 2-stage Phase II design}
 \alias{ph2simon}
 \alias{print.ph2simon}
 \alias{plot.ph2simon}
-\title{Simon's two-stage Phase II design}
+\keyword{design}
+\description{
+  Calculates Optimal and Minimax 2-stage Phase II designs given by
+  Richard Simon
+}
 \usage{
-ph2simon(pu, pa, ep1, ep2, nmax = 100)
-
-\method{print}{ph2simon}(x, ...)
-
-\method{plot}{ph2simon}(x, ...)
+ph2simon(pu, pa, ep1, ep2, nmax=100)
+\method{print}{ph2simon}(x, \dots)
+\method{plot}{ph2simon}(x, \dots)
 }
 \arguments{
-\item{pu}{unacceptable response rate; baseline response rate that needs to
-be exceeded for treatment to be deemed promising}
-
-\item{pa}{response rate that is desirable; should be larger than pu}
-
-\item{ep1}{threshold for the probability of declaring drug promising under
-pu (target type 1 error rate); between 0 and 1}
-
-\item{ep2}{threshold for the probability of declaring the drug not
-promising under pa (target type 2 error rate); between 0 and 1}
-
-\item{nmax}{maximum total sample size (default 100; can be at most 1000)}
-
-\item{x}{object returned by ph2simon}
-
-\item{...}{arguments to be passed onto plot and print commands}
+  \item{pu}{unacceptable response rate; baseline response rate that needs to
+    be exceeded for treatment to be deemed promising}
+  \item{pa}{response rate that is desirable; should be larger than pu}
+  \item{ep1}{threshold for the probability of declaring drug desirable
+    under pu (target type 1 error rate); between 0 and 1}
+  \item{ep2}{threshold for the probability of rejecting the drug under
+    pa (target type 2 error rate); between 0 and 1}
+  \item{nmax}{maximum total sample size (default 100; can be at most 1000)}
+  \item{x}{object returned by ph2simon}
+  \item{...}{arguments to be passed onto plot and print commands called
+    within}
 }
 \value{
-ph2simon returns a list with pu, pa, alpha, beta and nmax (as defined above)
-and: \item{out}{matrix of best two-stage designs for each value of total
-sample size n. The 6 columns in the matrix are: \tabular{rl}{ r1 \tab
-number of responses needed to exceeded in first stage \cr n1 \tab number of
-subjects treated in first stage \cr r \tab number of responses needed to
-exceeded at the end of trial \cr n \tab total number of subjects to be
-treated in the trial \cr EN(pu) \tab expected number pf patients in the
-trial under pu \cr PET(pu) \tab probability of stopping after the first
-stage under pu } }
+  ph2simon returns a list with pu, pa, alpha, beta and nmax as above
+  and: \item{out}{matrix of best 2 stage designs for each value of total
+    sample size n.  The 6 columns in the matrix are:
+    \tabular{rl}{
+      r1 \tab number of responses needed to exceeded in first stage \cr
+      n1 \tab number of subjects treated in first stage \cr
+      r \tab number of responses needed to exceeded at the end of trial \cr 
+      n \tab total number of subjects to be treated in the trial \cr
+      EN(pu) \tab expected number pf patients in the trial under pu \cr
+      PET(pu) \tab probability of stopping after the first stage under pu 
+    }}
 
-Trial is stopped early if <= r1 responses are seen in the first stage and
-treatment is considered desirable only when >r responses seen.
-}
-\description{
-Calculates the sample size and decision rules for Optimal and Minimax
-two-stage Phase II designs given by Richard Simon. The trial proceeds to
-the second stage only if a minimal number of responses is observed at the
-end of the first stage.
+  Trial is stopped early if <= r1 responses are seen in the first stage
+  and treatment is considered desirable only when >r responses seen.
 }
 \section{Methods (by generic)}{
-\itemize{
-\item \code{print(ph2simon)}: formats and returns the minimax and optimal designs
-
-\item \code{plot(ph2simon)}: plots the expected sample size against the maximum sample size ass in Jung et al., 2001
+  \itemize{
+    \item \code{print(ph2simon)}: formats and returns the minimax,
+    optimal and any admissible designs.
+    \item \code{plot(ph2simon)}: plots the expected sample size against
+    the maximum sample size as in Jung et al., 2001
+  }
+}
 
-}}
 \examples{
-
   ph2simon(0.2, 0.4, 0.1, 0.1)
   ph2simon(0.2, 0.35, 0.05, 0.05)
   ph2simon(0.2, 0.35, 0.05, 0.05, nmax=150)
-
 }
+
 \references{
-Simon R. (1989).  Optimal Two-Stage Designs for Phase II
-Clinical Trials. \emph{Controlled Clinical Trials} 10, 1-10.
+  Simon R. (1989).  Optimal Two-Stage Designs for Phase II Clinical
+  Trials. \emph{Controlled Clinical Trials} 10, 1-10.
 
-Jung SH, Carey M and Kim KM. (2001). Graphical Search for Two-Stage Designs
-for Phase II Clinical Trials. \emph{Controlled Clinical Trials} 22,
-367-372.
+  Jung SH, Carey M and Kim KM. (2001). Graphical Search for Two-Stage
+  Designs for Phase II Clinical Trials. \emph{Controlled Clinical
+    Trials}  22, 367-372.
 }
+
 \seealso{
-\code{\link{twostage.inference}}, \code{\link{oc.twostage.bdry}}
+  \code{\link{twostage.inference}}, \code{\link{oc.twostage.bdry}}
 }
+
 \keyword{design}

man/roc.curve.Rd

@@ -10,22 +10,25 @@
 \usage{
   roc.curve(marker, status, method=c("empirical"))
   \method{print}{roc.curve}(x, \dots)
-  \method{plot}{roc.curve}(x, \dots)
-  \method{lines}{roc.curve}(x, \dots)
+  \method{plot}{roc.curve}(x, PRC=FALSE, \dots)
+  \method{lines}{roc.curve}(x, PRC=FALSE, \dots)
 }
 \arguments{
   \item{marker}{the marker values for each subject.}
   \item{status}{binary disease status indicator}
   \item{method}{the method for estimating the ROC curve.  Currently only
     the empirical curve is implemented.}
   \item{x}{object of class roc.area.test output from this function.}
+  \item{PRC}{flag to tell whether ROC or Precision-Recall curve plotted.}
   \item{...}{optional arguments to the print, plot and lines functions.}
 }
 \value{a list with the following elements
-  \item{tpr}{true positive rates for all thresholds.}
-  \item{fpr}{true positive rates for all thresholds.}
   \item{marker}{the diagnostic marker being studied.}
   \item{status}{binary disease }
+  \item{tpr}{true positive rates for all thresholds.}
+  \item{fpr}{true positive rates for all thresholds.}
+  \item{ppv}{positive predictive values for all thresholds.}
+  \item{npv}{negative predictive values for all thresholds.}
 
   The "print" method returns the nonparametric AUC and its s.e.
 

man/toxbdry.Rd

@@ -63,16 +63,33 @@ bdrycross.prob(n, r, ptox)
   \item{bdry.alpha}{the alpha levels for testing at each look for the
     two boundaries.}
 
-  stopping for toxicity is done when the number of toxicities exceeda
+  stopping for toxicity is done when the number of toxicities exceeds
   the boundary i.e. the boundary gives the maximum acceptable number.
 }
 \details{
-  Default value of boundary shape corresponds to the Pocock boundary
-  where the same significance level is used for all looks. For a more
-  conservative stopping rule use delta greater than 0 where 0.5
-  corresponds to the O'Brien-Fleming boundary which is extremely
-  conservative in the early looks. Value between 0.1 and 0.2 is a
-  reasonable compromise.
+  The shape parameter delta is used to determine the stopping boundary
+  with 0 corresponding to the Pocock boundary where the same
+  significance level is used for all looks and 0.5 corresponding to the
+  O'Brien-Fleming boundary which has smaller probability of stopping at
+  early looks.
+
+  Default value of delta for toxicity monitoring is 0; value between 0.1
+  and 0.2 is a reasonable choice to make it less likely to stop early.
+  Default values of delta for futility stopping is 0.5.
+
+  For toxicity monitoring two sets of probabilities - pstop and pcross -
+  are given which correspond to probability of stopping early and
+  probability of declaring the treatment too toxic with the full
+  complement of study subjects accrued and treated.
+
+  For futility monitoring instead two sets of probabilities - pstop and
+  peffective - are given corresponding to the probability of stopping
+  early for futility and probability of finishing the trial and
+  declaring it a success. Note that peffective is the complement of
+  pcross in toxicity monitoring.
+
+  The futility boundary can have a -1 in earlier looks which means that
+  even zero responses is not sufficient for stopping at that look.
 
   The exact calculations in this function are done along the lines of
   the method in Chapter 12 of Jennison and Turnbull (2000). Ivanova,