Package {dnn}

An R package for the deep neural networks probability and statistics models

Description

This package provides tools for deep neural network which allow user define loss function for complex outcome data with probability and statistics models such as generalized linear models, accelerated failure time (AFT) models, and Cox proportional hazards models.

It contains the essential building blocks such as feed forward network and back propagation. This gives users the flexibility to write their own loss function (i.e. cost function) and train the neural network.

Details

{dnn} is a R package for deep learning neural network with probability models that use the negative of the log-likelihood as the loss function. It provides functions for feed forward network from covariates to the output layer and back propagation to find the derivatives of the weight parameters. Different optimization methods such as stochastic gradient descent (SGD), Momentum and ADAM can be used to train the network.

Currently, { dnn } can be install by the package source file 'dnn.tar.gz', use

install.packages("dnn.tar.gz", repos = NULL, type = "source")

users can use the following steps to install the most recent version of 'dnn' package:

1. First, you need to install the 'devtools' package. You can skip this step if you have 'devtools' installed in your R. Invoke R and then type

install.packages("devtools")

2. Load the devtools package.

library(devtools)

3. Install "dnn" package from github with R command

install_github("statapps/dnn")

A stable version of View the "dnn" package is also available from the Comprehensive R Archive Network (https://CRAN.R-project.org/package=dnn) and can be installed using R command

install.packages("dnn")

Author(s)

Bingshu E. Chen

Maintainer: Bingshu E. Chen <bingshu.chen@queensu.ca>

See Also

dNNmodel, bwdNN, fwdNN, deepAFT, deepGLM, deepSurv, glm, coxph, survreg

Examples

# Create the models with 3 layers
  model = dNNmodel(units=c(8, 6, 1), activation = c('elu', 'relu', 'sigmoid'), 
          input_shape = c(3))
  print(model)
# 
# Feed forward network with dummy data x
  x = matrix(runif(15), nrow = 5, ncol = 3)
  cache = fwdNN(x, model)
#
# Back propagation with dummy dy = dL/dyhat and minin batch for SGD
  dy = as.matrix(runif(5, -0.1, 0.1), nrow = 5)
  dW = bwdNN(dy, cache, model)
#
# Gradient descent with SGD 
  lr_rate = 0.0001
  sgd = function(w, dw) {w-lr_rate*dw}
  model$params = mapply(sgd, w = model$params, dw = dW)

Activation function

Description

Different type of activation functions and the corresponding derivatives

Usage

  sigmoid(x)
  elu(x)
  relu(x)
  lrelu(x)
  idu(x)
  dsigmoid(y, dy = 1)
  dsoftmax(y, dy = 1)
  delu(y, dy = 1)
  drelu(y, dy = 1)
  dlrelu(y, dy = 1)
  dtanh(y, dy = 1)   #activation function tanh(x) is already available in R

Arguments

Details

Each function returns either the activation function (e.g. sigmoid, relu) or its derivative (e.g. dsigmoid, drelu).

For dsoftmax, the function computes the Jacobian-vector product. When dy represents the gradient of the loss L with respect to the softmax output P, the gradient with respect to the input x is:

\frac{\partial L}{\partial x} = P \odot (dy - \sum (P \odot dy))

where \odot denotes element-wise multiplication.

Value

An activation function is applied to x and returns a matrix the same size as x. The detail formula for each activation function is:

Author(s)

Bingshu E. Chen

See Also

softmax, bwdNN, fwdNN, dNNmodel, optimizerSGD, optimizerNAG

Examples

  # Specify a dnn nodel with user define activation function in layer 2.
  model = dNNmodel(units=c(8, 6, 1), activation= c('relu', 'softmax', 'sigmoid'), 
          input_shape = c(3))
  print(model)

Back propagation for dnn Models

Description

{bwdNN} is an R function for back propagation in DNN network.

Usage

#
# To apply back propagation in with a feed forward model 
#
# use 
#
   bwdNN(dy, cache, model)
#
# to calculate derivative of dL/dW

Arguments

Details

Here 'dy' plays an import role in the back propagation { bwdNN } since the probability model's loss function takes the output layer of the { dnn } (denote as yhat) as one of its parameter. Then 'dy' equals to the partial derivative of the loss function (-Log Likelihood) with respect to yhat, that is, dy = dL/d(yhat). For example, if the 'dnn' predicts the probability (yhat = p) for the mixture of two populations f1 and f2, then the likelihood function is f = p*f1 + (1-p)*f2, and the loss function is L = -log(p*f1+(1-p)*f2). Hence, dy = dL/dp = -(f1-f2)/f.

'cache' is the cache of each input layer generated from the { fwdNN } function.

The function { bwdCheck } calculates the numerical derivatives of dL/dW, which can be used to check if the back propagation is correct or not, see example below.

Value

A list contains the derivatives dL/dW of weight parameter W is returned.

Author(s)

Bingshu E. Chen (bingshu.chen@queensu.ca)

See Also

dNNmodel, fwdNN, plot.dNNmodel, print.dNNmodel, summary.dNNmodel,

Examples

### define a dnn model, calculate the feed forward network
   model = dNNmodel(units = c(8, 6, 1), 
           activation = c("elu", "sigmoid", "sigmoid"), input_shape = 3)
   print(model)
   x = matrix(runif(15), nrow = 5, ncol = 3)
   cache = fwdNN(x, model)
   # dy = dL/dp, where L is the cost function such as the 
   # log-likehood and p is the output layer parameter of the DNN
   dy = as.matrix(runif(5, -0.1, 0.1), nrow = 5)  # a dummy dy for bwdNN input
   y  = predict(model, x) + dy
   
   # back propagation 
   dW = bwdNN(dy, cache, model)
   dw = bwdCheck(x, y, model)
   print(dW[[1]])
   print(dw[[1]])

Specify a deep neural network model

Description

{dNNmodel} is an R function to create a deep neural network model that is to be used in the feed forward network { fwdNN } and back propagation { bwdNN }.

Usage

  dNNmodel(units, input_shape, activation=NULL, type = NULL, 
        N = NULL, dropout_rate = 0, Rcpp=TRUE, 
        optimizer = c("momentum", "nag", "adam"))

Arguments

Details

dNNmodel returns an object of class "dNNmodel".

The function "print" (i.e., "print.dNNmodel") can be used to print a summary of the dnn model,

The function "summary" (i.e., "summary.dNNmodel") can be used to print a summary of the dnn model,

Value

An object of class "dNNmodel" is a list containing at least the following components:

Author(s)

Bingshu E. Chen (bingshu.chen@queensu.ca)

See Also

plot.dNNmodel, print.dNNmodel, summary.dNNmodel, fwdNN, bwdNN, optimizerSGD, optimizerNAG,

Examples

### To define a dnn model
 model = dNNmodel(units = c(8, 6, 1), activation = c("relu", "sigmoid", "sigmoid"), 
         input_shape = c(3))

Deep learning for the accelerated failure time (AFT) model

Description

Fit a deep learning survival regression model. These are location-scale models for an arbitrary transform of the time variable; the most common cases use a log transformation, leading to accelerated failure time models.

Usage

deepAFT(x, ...)

## S3 method for class 'formula'
deepAFT(formula, model, data, control = list(...), method =
                 c("BuckleyJames", "ipcw", "transform"), ...)

## Default S3 method:
deepAFT(x, y, model, control, ...)

## S3 method for class 'ipcw'
deepAFT(x, y, model, control, ...)
# use:
#   deepAFT.ipcw(x, y, model, control)
# or
#   class(x) = "ipcw"
#   deepAFT(x, y, model, control)
# 
## S3 method for class 'trans'
deepAFT(x, y, model, control, ...)
# use:
#   class(x) = "transform"
#   deepAFT(x, y, model, control)

Arguments

Details

When all observations are uncensored, the Buckley-James imputation step returns the observed times directly; no censoring-time maximum is needed.

For the IPCW method, the marginal censoring distribution can be estimated for datasets with fewer than 20 observations; there is no minimum sample-size threshold. The internal grouped nonparametric calculation permits at most five nonempty censoring groups, independently of sample size. Groups with one distinct observed time use their fitted survival value directly. The existing replacement of zero censoring survival by the smallest positive estimate within the group is retained. If no positive estimate exists, IPCW reports that the weights are undefined.

See "Deep learning with R" for details on how to build a deep learning model.

The following parameters in 'dnnControl' will be used to control the model fit process.

'epochs': number of deep learning epochs, default is 100.

'batch_size': batch size, default is 128. 'NaN' may be generated if batch size is too small and there is not event in a batch.

'verbose': verbose = 1 for print out verbose during the model fit, 0 for not print.

'epsilon': epsilon for convergence check, default is epsilon = 0.001.

'max.iter': number of maximum iteration, default is max.iter = 100.

When the variance for covariance matrix X is too large, please use xbar = apply(x, 2, stndx) to standardize X.

Value

An object of class "deepAFT" is returned. The deepAFT object contains the following list components:

Note

For right censored survival time only

Author(s)

Chen, B. E. and Norman P.

References

Buckley, J. and James, I. (1979). Linear regression with cencored data. Biometrika, 66, page 429-436.

Norman, P., Li, W., Jiang, W. and Chen, B. E. (2024). deepAFT: A non-linear accelerated failure time model with artificial neural network. Statistics in Medicine, 43, page 3689-3701.

See Also

dNNmodel, dnnControl, deepSurv, print.deepAFT, survreg, ibs.deepAFT

Examples

## Example for deep learning model for AFT survival data
  set.seed(101)
### define model layers
  model = dNNmodel(units = c(4, 3, 1), activation = c("elu", "sigmoid", "sigmoid"), 
                   input_shape = 3)
  x = matrix(runif(15), nrow = 5, ncol = 3)
  time = exp(x[, 1])
  status = c(1, 0, 1, 1, 1)
  fit = deepAFT(Surv(time, status) ~ x, model)

Deep learning for the generalized linear models

Description

Fit generalized linear models (Gaussian, Binomial and Poisson) using deep learning neural network (DNN). The glm formula is specified by giving a symbolic description of the predictor and a description of the error distribution.

Usage

deepGlm(formula, model, family = c("gaussian", "binomial",
        "poisson"), data, epochs = 200, lr_rate = 1e-04,
         batch_size = 64, alpha = 0.7, lambda = 1, verbose = 0,
         weights = 1, ...)

Arguments

Details

Weights are used as supplied and are not normalized. Scalar 1 means unit weights for all observations. Weight vectors need not sum to 1.

For the binomial family, neural-network outputs represent probabilities. Fitting minimizes weighted cross-entropy (the negative log likelihood), with weights applied to both success and failure contributions.

For the Poisson family, the neural-network output represents a positive Poisson rate. Fitting minimizes the weighted negative log likelihood, omitting response-only log-factorial constants. Weights scale observation contributions; they do not scale the predicted rates themselves.

See dNNmodel for details on how to specify a deep learning model.

The following parameters in 'dnnControl' will be used to control the model fit process.

'epochs': number of deep learning epochs, default is 200.

'verbose': verbose = 1 for print out verbose during the model fit, 0 for not print.

When the variance for covariance matrix X is too large, please use xbar = scale(x) to standardize X.

Value

An object of class "deepGlm" is returned. The deepGlm object contains the following list components:

Note

For glm models with Gaussian, Binomial and Poisson only

Author(s)

Bingshu E. Chen

References

Chollet, F. and Allaire J. J. (2017). Deep learning with R. Manning.

See Also

dNNmodel, deepAFT, deepSurv, dnnControl, glm, predict.deepGlm, print.deepGlm

Examples

## Example for deep learning for glm models
  set.seed(101)
### define model layers
  model = dNNmodel(units = c(4, 3, 1), activation = c("elu", "sigmoid", "sigmoid"), 
                   input_shape = 3)
  x = matrix(runif(15), nrow = 5, ncol = 3)
  y = exp(x[, 1] + rnorm(5))
  
  fit = deepGlm(y ~ x, model, family = "gaussian") 

Deep learning for the Cox proportional hazards model

Description

Fit a survival regression model under the Cox proportional hazards assumption using deep learning neural network (DNN).

Usage

deepSurv(formula, model, data, epochs = 100, lr_rate = 0.0001,
       batch_size = 64, alpha = 0.7, lambda = 1, verbose = 0,
       epsilon = 0.001, weights = 1, ...)

Arguments

Details

Cox partial likelihood uses the Breslow method for tied observed times, including events and censored observations at the same time in the risk set. The baseline cumulative hazard also uses Breslow increments and returns one row per distinct observed time, with grouped event and censoring counts. Direct calls to the fitters with Cox loss require finite times sorted from largest to smallest; deepSurv performs this sorting automatically. Tie groups are cached for full-batch fitting and rebuilt for sampled mini-batches. Mini-batch Cox loss uses risk sets within the sampled batch.

Weights are used as supplied and are not normalized. Scalar 1 means unit weights for all observations. Weight vectors need not sum to 1.

See dNNmodel for details on how to build a deep learning model.

For a deepSurv model, the activation function for the output layer of the dNN model shall be an identity function 'idu'.

When the variance for covariance matrix X is too large, please use xbar = scale(x) to standardize X.

Value

An object of class "deepSurv" is returned. The deepSurv object contains the following list components:

Note

For right censored survival time only

Author(s)

Chen, B. E. wrote the R code using the partial likelihood cost function proposed by Katzman et al (2018).

References

Katzman JL, Shaham U, Cloninger A, Bates J, Jiang T, Kluger Y. DeepSurv: Personalized treatment recommender system using a Cox proportional hazards deep neural network. BMC Medical Research Methodology 2018; 18: 24.

See Also

deepAFT, deepGlm, dNNmodel, print.deepSurv, survreg, coxph, Surv

Examples

## Example for deep learning proportional hazards survival model
  set.seed(101)
### define model layers
  model = dNNmodel(units = c(4, 3, 1), activation = c("elu", "sigmoid", "idu"), 
                   input_shape = 3)
  n = 15
  x = matrix(runif(n*3), nrow = n, ncol = 3)
  time = rexp(n, rate = 3*(0.1+abs(x[, 1]-0.5)))
  status = rbinom(n, 1, 0.8)
  fit = deepSurv(Surv(time, status) ~ x, model = model, epochs = 50)

Auxiliary function for dnnFit dnnFit

Description

dnnControl is an auxiliary function for dnnFit. Typically only used internally by the dnn package, may be used to construct a control argument for the deep learning neural network model to specify parameters such as a loss function.

Usage

  dnnControl(loss = c("mse", "cox", "bin", "log", "mae"), epochs = 300, 
	     batch_size = 64, verbose = 0, lr_rate = 0.0001,  
	     alpha = 0.5, lambda = 1.0, epsilon = 0.01, max.iter = 100, 
	     weights = 1)

Arguments

Details

Epochs, batch size, and maximum iteration counts must be finite positive integers no greater than the platform integer limit. Zero, negative, fractional, missing, and infinite counts are rejected before fitting.

Weights are used as supplied and are not normalized. Scalar 1 means unit weights for all observations. Weight vectors need not sum to 1.

dnnControl is used in model fitting of "dnnFit". Additional loss functions will be added to the library in the future.

Value

This function checks the internal consistency and returns a list of values as input to control model fitting of "dnnFit".

Author(s)

Chen, B. E. (bingshu.chen@queensu.ca)

References

Norman, P., Li, W., Jiang, W. and Chen, B. E. (2024). deepAFT: A non-linear accelerated failure time model with artificial neural network. Statistics in Medicine.

See Also

deepAFT, deepGLM, deepSurv, dnnFit

Examples

## Example for dnnControl
##
# model = dNNmodel()

  control = dnnControl(loss='mse')
  
# can also be used in   
# fit = dnnFit(y ~ x, model, control) 
# print(fit)

Fitting a Deep Learning model with a given loss function

Description

dnnFit is used to train a deep learning neural network model based on a specified loss function.

Usage

dnnFit(x, y, model, control)

Arguments

Details

Cox partial likelihood uses the Breslow method for tied observed times, including events and censored observations at the same time in the risk set. Direct calls to the fitters with Cox loss require finite times sorted from largest to smallest; deepSurv performs this sorting automatically. Tie groups are cached for full-batch fitting and rebuilt for sampled mini-batches. Mini-batch Cox loss uses risk sets within the sampled batch.

The 'dnnFit' function takes the input data, the target values, the network architecture, and the loss function as arguments, and returns a trained model that minimizes the loss function. The function also supports various options for regularization and optimization of the model.

See dNNmodel for details on how to specify a deep learning model.

Parameters in dnnControl will be used to control the model fit process. The loss function can be specified as dnnControl(loss = "lossFunction"). Currently, the following loss functions are supported:

'mse': Weighted square error loss = 0.5*sum(weights*(y-yhat)^2)

'cox': Cox partial likelihood loss = -sum(delta*(yhat - log(S0)))

'bin': Weighted cross-entropy = -sum(weights*(y*log(p) + (1-y)*log(1-p)))

'log': Poisson cost = sum(weights*(lambda-y*log(lambda)))

'mae': Weighted absolute error loss = sum(weights*abs(y-yhat))

Weights supplied through dnnControl(weights = ...) must be the scalar 1 (the default) or a finite, nonnegative numeric vector of length equal to the sample size. An n \times 1 numeric matrix is converted to a vector before validation. Other matrix shapes, NULL, and per-output weight arrays are not accepted. Each observation's weight is shared across all response outputs. Weights need not sum to 1 and are not normalized. Scalar 1 means unit weights for all observations. Mini-batches select the corresponding observation weights. Weight validation and column-matrix conversion are performed before training rather than at every loss evaluation.

For MSE loss, both implementations use the same weighted half-squared-error objective.

The package stops with an error when forward predictions, loss values, or output gradients become non-finite, including numerical overflow from extremely large values or invalid boundary arithmetic. Rescale the data or adjust model parameters and output activations. The underlying loss formulas are unchanged; no numerical stabilization or probability clipping is applied.

For MAE loss in dnnFit, the negative output subgradient used by backpropagation is weights * sign(y - yhat). The subgradient is chosen as zero when the response equals the prediction. Zero-weight observations contribute neither loss nor gradient. The loss is a sum, not a normalized mean.

For binomial loss (loss = "bin"), predictions are probabilities. Both implementations report the weighted negative log likelihood and apply weights to the complete success-and-failure contribution. The negative output derivative used in backpropagation is weights * (y / yhat - (1 - y) / (1 - yhat)). Native binomial fitting uses the same observation-weight contract as MSE fitting.

For Poisson loss (loss = "log"), predictions are positive rates, not log rates. The objective omits the response-only log-factorial constant. Weights multiply each observation's loss contribution rather than changing its predicted rate. Both R and native fitting use the negative output derivative weights * (y / yhat - 1) for backpropagation. Native Poisson fitting uses the same observation-weight contract as MSE fitting.

After training, dnnFit disables dropout before evaluating final predictions, loss, residuals, and dvi on the full training data. These diagnostics therefore match the returned prediction model rather than the last mini-batch. The history and dW fields retain their training-iteration meanings; they are not recomputed as final diagnostics.

Dropout is disabled for Rcpp fitting. A positive dropout rate produces a warning and is reset to zero; stored dropout masks are cleared. This applies to dnnFit when model$Rcpp = TRUE, and to all dnnFit2 calls because that fitter always uses native code. The supplied input model is not modified by dnnFit2. R-only fitting retains its existing dropout option.

Single-layer networks (no hidden layer) are supported by both fitters and by the R backpropagation implementation. Optimizer state is initialized for the supplied architecture. Native Cox fitting accepts the default weights = 1; Cox sample weights remain unsupported.

The native dnnFit2 fitter uses momentum optimization regardless of the model$optimizer setting. To select NAG or Adam, use dnnFit with model$Rcpp = TRUE.

The native dnnFit2 fitter trains a copy of the supplied model. The input model is not modified in place; use the returned model component to obtain the trained weights. Reusing the same input model therefore starts subsequent fits from the same supplied weights.

When the variance for covariance matrix X is too large, please use xbar = scale(x) to standardize X.

Value

An object of class "dnnFit" is returned. The dnnFit object contains the following list components:

Author(s)

Chen, B. E. (bingshu.chen@queensu.ca)

References

Chollet, F. and Allaire J. J. (2017). Deep learning with R. Manning.

Norman, P., Li, W., Jiang, W. and Chen, B. E. (2024). deepAFT: A non-linear accelerated failure time model with artificial neural network. Statistics in Medicine.

See Also

deepAFT, deepGLM, deepSurv, dnnControl

Examples

## Example for dnnFit with MSE loss function to do a non-linear regression
  set.seed(101)
### define model layers
  model = dNNmodel(units = c(4, 3, 1), activation = c("elu", "sigmoid", "sigmoid"), 
                   input_shape = 3)
  x = matrix(runif(15), nrow = 5, ncol = 3)
  y = exp(x[, 1])
  control = dnnControl(loss='mse')
  fit = dnnFit(x, y, model, control) 

Feed forward and back propagation for dnn Models

Description

{fwdNN} is an R function for feed forward network.

Usage

   fwdNN(X, model)             
#
# to calculate a feed feedward model 
#

Arguments

Details

'cache' is the cache of each input layer, will be used in the bwdNN function.

Value

The function fwdNN return a list containing at least the following components:

Author(s)

Bingshu E. Chen (bingshu.chen@queensu.ca)

See Also

bwdNN, plot.dNNmodel, print.dNNmodel, summary.dNNmodel,

Examples

### define a dnn model, calculate the feed forward network
   model = dNNmodel(units = c(8, 6, 1), activation = c("elu", "sigmoid", "sigmoid"), 
                   input_shape = 3)
  
### feed forward with a dummy x matrix
   x = matrix(runif(15), nrow = 5, ncol = 3)
   cache = fwdNN(x, model)

A function for tuning of the hyper parameters

Description

{ hyperTuning} is a tuning tool to find the optimal hyper parameter for the ANN model.

Usage

   hyperTuning(x, y, model, ER = c("cindex", "mse"), 
          method = c('BuckleyJames', 'ipcw', 'transform', 'deepSurv'), 
          lower = NULL, upper = NULL, node = FALSE,
          K = 5, R = 25)
### additional function used in hyperTuning is cross-validation prediction error
#
#  CVpredErr(x, y, model, control, method)
#

Arguments

Details

The reported prediction error is the mean of the fold scores. The reported SE is their sample standard deviation divided by the square root of the number of folds. This is a nominal standard error of the fold-score mean; it does not correct for dependence caused by overlapping training sets and should not be interpreted as a generalization-error confidence interval. Invalid fold counts or tuning-trial counts are rejected before tuning. Failed cross-validation attempts count toward R. If no candidate is selected after these attempts, tuning stops with an error. When node = TRUE, each candidate is rebuilt with freshly initialized parameter matrices matching its sampled hidden-layer widths. The output-layer width and the supplied model's other architecture settings are preserved. Hidden layers with at least two nodes are sampled from two through their original width; one-node hidden layers remain unchanged. Models without hidden layers retain their architecture. The returned model is the candidate associated with the best cross-validation score and returned control values; it is an initialization, not a model fitted on the full dataset.

A random search method is used to optimal hyper parameter (Bergstra and Bengio, 2012). The function { CVpredErr} will be call to calculate the cross-validation prediction error for the given x and y with the specified method from the input argument.

Value

A list of "model" and "dnnControl" is returned. The list contains at least the following components,

Author(s)

Chen, B. E. (chenbe@queensu.ca)

References

Bergstra, J. and Bengio, Y. (2012). Random search for hyper-parameter optimization. The Journal of Machine Learning Research. 13, page 281-305.

See Also

deepAFT, deepGLM, deepSurv, dnnFit

Examples

### Tuning the hyper parameter for a deepAFT model: 
#### cross-validation take a long time to run.

  set.seed(101)
### define model layers
  model = dNNmodel(units = c(4, 3, 1), activation = c("elu", "sigmoid", "sigmoid"), 
                   input_shape = 3)
  x = matrix(runif(45), nrow = 15, ncol = 3)
  time = exp(x[, 1])
  status = rbinom(15, 1, 0.5)
  y = Surv(time, status)
  ctl = dnnControl(epochs = 30)
  hyperTuning(x, y, model, method = "BuckleyJames", K = 2, R = 2, lower = ctl)

Calculate integrated Brier Score for deepAFT

Description

The function ibs is used to calculate integrated Brier Score for deepAFT.

Usage

### To calculate Brier score for the original fitted data or the new data
### with new outcomes
## S3 method for class 'deepAFT'
ibs(object, newdata=NULL, newy = NULL, ...)

Arguments

Details

Observations may be supplied in any row order. Survival indicators and IPCW weights use comparisons of observed times rather than row positions. At an evaluation time t, subjects with observed time greater than t contribute the survival term; observed events at or before t contribute the event term. Subjects censored at or before t contribute zero. Tied times therefore have identical Brier scores.

The returned bs rows are ordered by increasing observed time, retaining duplicate times. The reported ibs is the unnormalized sum of each Brier score multiplied by the preceding interval width, starting at zero. Duplicate times have zero interval width. The existing censoring-survival convention and its zero-survival replacement of 0.0001 are retained.

ibs is called to calculate integrate Brier score for the deepAFT model deepAFT.

Value

A list contains the integrate Brier score and the Brier score is returned:

Author(s)

Bingshu E. Chen

See Also

deepAFT

Mean Square Error (mse) for a fitted survival Object

Description

Compute Mean Square Error (mse) values for a fitted AFT model survival object using IPCW method.

Usage

## S3 method for 'mseIPCW'
mseIPCW(object, newdata, newy)

Arguments

Details

predict is called to predict object from a deepAFT deepAFT or a survreg model.

IPCW method is used to calcuate the mean square error for censored survival time.

Value

mseIPCW returns the mse for the predicted survival data.

Author(s)

Bingshu E. Chen (bingshu.chen@queensu.ca)

See Also

predict, deepAFT, deepSurv, survfit.deepSurv

Functions to optimize the gradient descent of a cost function

Description

Different type of optimizer functions such as SGD, Momentum, AdamG and NAG.

Usage

  optimizerMomentum(V, dW, W, alpha = 0.63, lr = 1e-4, lambda = 1) 

Arguments

Details

For SGD with momentum, use

V = 0; obj = optimizerMomentum(V, dW, W); V = obj$V; W = obj$W

For SDG with MAG

V = 0; obj = optimizerNAG(V, dW, W); V = obj$V; W = obj$W

Value

return and updated W and other parameters such as V, V1 and V2 that will be used on SGD.

Author(s)

Bingshu E. Chen

See Also

activation, bwdNN, fwdNN, dNNmodel, dnnFit

Plot methods in dnn package

Description

Plot function for plotting of R objects in the dnn package.

Several different type of plots can be produced for the deep learning mdels. Plot method is used to provide a summary of outputs from "deepAFT", "deepGLM", "deepSurv" and "dnn".

Use "methods(plot)" and the documentation for these for other plot methods.

Usage

## S3 method for class 'dNNmodel'
plot(x, ...)
## S3 method for class 'deepAFT'
plot(x, type = c("predicted", "residuals", "baselineKM"), ...)

Arguments

Details

plot.deepAFT is called to plot the fitted deep learning AFT model.

plot.dNNmodel is called to plot fitted dnn model

The default method, plot.default has its own help page. Use methods("plot") to get all the methods for the plot generic.

Value

No return value, called to plot a figure.

Author(s)

Bingshu E. Chen

See Also

The default method for plot plot.default. glm

Predicted Values for a deepAFT or a deepSurv Object

Description

Compute the predicted values for a deepAFT or a deepSurv object

Usage

## S3 method for class 'predict'
## S3 method for class 'dSurv'
predict(object, newdata, newy=NULL, ...)

Arguments

Details

When newy is supplied for a deepSurv model, martingale residuals use \delta - \exp(\eta) H_0(t) at the original observed times. The baseline cumulative hazard is evaluated as a step function, with zero cumulative hazard before the first baseline time. DeepAFT models instead use the AFT time transformation.

predict.dSurv is called to predict object from a deepAFT deepAFT or a deepSurv deepSurv model.

The default method, predict has its own help page. Use methods("predict") to get all the methods for the predict generic.

Value

predict.dSurv returns a list of the predicted values, risk scores and the cumulative hazard function.

Author(s)

Bingshu E. Chen

See Also

The default method for predict predict, deepAFT, deepSurv, survfit.deepSurv

print a summary of fitted deep learning model object

Description

print is used to provide a short summary of outputs from deepAFT, deepSurv, deepGLM, and dNNmodel.

Usage

## S3 method for class 'deepAFT'
print(x, ...)
## S3 method for class 'summary.deepAFT'
print(x, ...)
## S3 method for class 'deepAFT'
summary(object, ...)

## S3 method for class 'dNNmodel'
print(x, ...)
## S3 method for class 'dNNmodel'
summary(object, ...)

Arguments

Details

print.deepAFT is called to print object or summary of object from the deep learning AFT models deepAFT. summary(fit) provides detail summary of ‘deepAFT’ model fit, including predictors, baseline survival function for T0=T/exp(mu), and martingale residuals for the fitted model.

print.dNNmodel is called to print object or summary of object from the dNNmodel.

The default method, print.default has its own help page. Use methods("print") to get all the methods for the print generic.

Value

An object of class "summary.deepAFT" is returned. The object contains the following list components:

Author(s)

Bingshu E. Chen

See Also

The default method for print print.default. Other methods include coxph, survreg, deepAFT, summary

Calculate Residuals for a deepAFT or deepSurv Fit

Description

Calculates martingale, deviance or Cox-Snell residuals for a previously fitted deepAFT or deepSurv model.

Usage

## S3 method for class 'deepAFT'
## S3 method for class 'dSurv'
residuals(object, type = c("martingale", "deviance", "coxSnell"), ...)

Arguments

Details

For a deepSurv model, the Cox-Snell residual is H_i(T_i) = \exp(\eta_i) H_0(T_i), where \eta_i is the neural-network predictor and H_0 is the fitted baseline cumulative hazard. It is evaluated as a step function at the original observed time, with zero cumulative hazard before the first baseline time. The martingale residual is \delta_i - H_i(T_i). AFT time rescaling is not used for deepSurv models.

residuals.deepAFT is called to compute baseline survival function S_T0(t) from the deepAFT model deepAFT, where T0 = T/exp(mu), or log(T) = log(T) - mu.

The default method, residuals has its own help page. Use methods("residuals") to get all the methods for the residuals generic.

Value

Fitted AFT survival estimates are preserved, including the final estimate. When the fitted survival is zero, the Cox-Snell residual is Inf, and the martingale and deviance residuals are -Inf.

For martingale and deviance residuals, the returned object is a vector with one element for each subject. The row order will match the input data for the original fit.

See residuals for more detail about other output values.

Note

For deviance residuals, the status variable may need to be reconstructed.

Author(s)

Bingshu E. Chen

See Also

The default method for residuals residuals, predict.dSurv, survfit.deepSurv, and deepAFT.

The restricted mean survival time (RMST)

Description

Calculate the restricted mean survival time (RMST) for deepSurv survival objects.

Usage

## S3 method for class 'deepSurv'
rmst(object, newdata = NULL, risk = NULL, tau = NULL, ...)

Arguments

Details

The restricted mean survival time (RMST) is the mean of the truncated survival time at some finite value tau. The RMST is defined as,

RMST(tau) = E(min(T, tau)) = int_0 ^tau S(t)dt,

where S(t) = P(T>t) is the survival function of the random variable T.

When risk or newdata is supplied, RMST is calculated by summing interval widths multiplied by the fitted survival probability, S(t) = \exp\{-\mathrm{risk} H_0(t)\}. The baseline cumulative hazard is treated as a step function and is zero before the first baseline time. Thus RMST equals tau when the horizon precedes the first event. Beyond the last baseline time, the final fitted survival probability is held constant. The horizon must be finite and nonnegative, and risk values must be finite and nonnegative.

If both risk and newdata are NULL, the function calculates RMST directly from the response using rmst.

Value

A value or vector of the restricted mean survival time is returned.

Author(s)

Bingshu E. Chen

See Also

rmst, rmst.coxph, coxph, Surv

Examples

  set.seed(29)
  n     = 5
  time  = rexp(n, 1)
  event = rbinom(n, 1, 0.75)
  x     = rnorm(n)
  y     = Surv(time, event)

  ### calculate the restricted mean survival time at tau = 0.5
  rms   = rmst(y, tau = 0.5)

  ### calculate the RMST for deepSurv
  #fit   = deepSurv(y~x, model = model)
  #RMST  = rmst(fit, risk = c(1, 2, 3), tau = 2)

Compute a Survival Curve from a deepAFT or a deepSurv Model

Description

Computes the predicted survival function of a previously fitted deepAFT or deepSurv model.

Usage

## S3 method for class 'deepAFT' or 'deepSurv'
## S3 method for class 'deepAFT'
survfit(formula, se.fit=TRUE, conf.int=.95, ...)
## S3 method for class 'deepSurv'
survfit(formula, se.fit=TRUE, conf.int=.95, ...)

Arguments

Details

survfit.dSurv is called to compuate baseline survival function S0(t) for T0 from the deepAFT model deepAFT, where T0 = T/exp(mu), or log(T) = log(T) - mu.

For the deepSurv model deepSurv, survfit.dSurv evaluates the Nelson-Aalen estimate of the baseline survival function with covariate X = 0.

The default method, survfit has its own help page. Use methods("survfit") to get all the methods for the survfit generic.

Value

survfit.dSurv returns a list of predicted baseline survival function, cumulative hazard function and residuals.

See survfit for more detail about other output values such as upper, lower, conf.type. Confidence interval is based on log-transformation of survival function.

Author(s)

Bingshu E. Chen

See Also

The default method for survfit survfit, predict.dSurv