Package 'psc'

Description

Function to accept (or not) a proposed solution used as part of the MCMC procedure

Usage

acc(old, new)

Arguments

Details

A function for the evaluation of two likelihoods as part of the MCMC procedure

Value

returns the an evaluation of old/new > U where U is a draw from the uniform distribution

Description

A generated model with a binary endpoint and a logistic link function. Data for the model were synthetically generated and are based on a dataset to evaulate the use of Sorafenib in HCC akin to the PROSASH model (see ?psc::surv.mod for more details)

Usage

bin.mod

Format

A model of class 'glm':

vi

vascular invasion

ecog

ECOG performance Status

logafp

AFP - log scale

alb

albumin

logcreat

Creatinine - log scale

allmets

metastesis

Source

simulated

Description

A function to estimate the linear predictor - used in bootstrapping CFM for CIs

Usage

boot_lp(i, pscOb, resp = resp, rest = NULL)

Arguments

Value

A simulated set of responses

Description

A function to estimate the survival function based on parameter estimates - used in ootstrapping CFM for CIs

Usage

boot_sest(
  i,
  pscOb = pscOb,
  lam = lam,
  kn = kn,
  k = k,
  cov = cov,
  tm = tm,
  rest = rest,
  beta = beta
)

Arguments

Value

A set of survival estimates

Description

The pscCFM creates a model object which is stripped of identifiable information. The cfmDataSumm function supplies a tabulated form of the dataset used in the CFM for summary information. Information returned in the form of a table

Usage

cfmDataSumm(cfm)

Arguments

Value

a summary table

Description

The pscCFM creates a model object which is stripped of identifiable information. The cfmDataVis function supplies a visualised form of the dataset for summary information

Usage

cfmDataVis(cfm)

Arguments

Value

a list of grobs for each model covariate

Description

A function which summarises categorical data using a bar plot. A sub-function of cfmDataVis

Usage

cfmDataVis_fac(x, nm)

Arguments

Value

a ggplot object

Description

A function which summarises categorical data using density plots. A sub-function of cfmDataVis

Usage

cfmDataVis_num(x, nm)

Arguments

Value

a ggplot object

Description

A generic function to provide a summary of a Counter factual model of class 'glm'

Usage

cfmSumm.flexsurvreg(pscOb, bootCI = TRUE, nboot = 1000)

Arguments

Value

A summary of a cfm object

Description

A generic function to provide a summary of a Counter factual model of class 'glm'

Usage

cfmSumm.glm(pscOb, bootCI = TRUE, nboot = 1000, resp = TRUE)

Arguments

Value

A summary of a cfm object

Description

Returns basic measures of the posterior distribution obtained from the psc object

Usage

## S3 method for class 'psc'
coef(object, ...)

Arguments

Value

The summary of the posterior distribution for the efficacy parameter in terms of the median and 95

Description

A generated model with a continuous data endpoint and a identity link function. Data for the model were synthetically generated and are based on a dataset to evaulate the use of Sorafenib in HCC akin to the PROSASH model (see ?psc::surv.mod for more details)

Usage

cont.mod

Format

A model of class 'glm':

ecog

ECOG performance Status

logafp

AFP - log scale

alb

albumin

logcreat

Creatinine - log scale

Source

simulated

Description

A generated model with a count data endpoint and a log link function. Data for the model were synthetically generated and are based on a dataset to evaulate the use of Sorafenib in HCC akin to the PROSASH model (see ?psc::surv.mod for more details)

Usage

count.mod

Format

A model of class 'glm':

ecog

ECOG performance Status

logafp

AFP - log scale

alb

albumin

logcreat

Creatinine - log scale

Source

simulated

Description

A dataset containing 100 simulated patients. Data are based on the data used to generate PROSASH survival model -see ?psc::surv.mod for more detials.

Usage

data

Format

A model of class 'flezsurvreg':

gamma

cumulative baseline hazard parameters

vi

vascular invasion

age60

patient age (centred at 60)

ecog

ECOG performance Status

logafp

AFP - log scale

alb

albumin

logcreat

Creatinine - log scale

allmets

metastesis

ageVasInv

centred age nested within vascular invasion

time

survival time

cen

censoring indicator

os

survival time

count

exapmple outcome for count data

trt

exapmple identifier for mulitple treatment comparisons

aet

Aetiology

Source

simulated

Description

A dataset containing 346 simulated patients. Data are based on the patietns randomised to revceive GemCap in the ESPAC-4 trial

Usage

e4_data

Format

A model of class 'flezsurvreg':

time

survival time

cen

censoring indicator

nodes

negative (n=1) or positive (n=2) lymph nodes

grade

tumour grade (1,2 or 3)

lca199

log transformed ca19.9

t

T-stage (1,2 or 3)

Source

simulated

Description

A function which compares visually a new categorical covariate against equivalent data from a CFM

Usage

facVisComp(p, x)

Arguments

Value

a ggplot object

Description

A generated model with a survival endpoint and a cuymulative hazard function estimated using flexible parametric splines. Data for the model were obtained from the ESPAC-3 trials

Usage

gemCFM

Format

A model of class 'pscCFM' containg a 'flexsurvreg' model:

gamma

cumulative baseline hazard parameters

nodes

negative (n=1) or positive (n=2) lymph nodes

grade

tumour grade (1,2 or 3)

lca199

log transformed ca19.9

ResecM

Resection Margins)

Source

simulated

Description

Function for estimating initial parameter values

Usage

init(pscOb)

Arguments

Details

This function takes the likelihood and data structures provided by the pscData() strucutres and fits the likelihood to provide starting values for MCMC estimation

Value

Parameter Estimates and standard error for the efficacy parameter

Description

A function which defines the likelihood for a PSC model where the Counter Factual Model (CFM) takes the form of a 'flexsurvreg' object and an efficacy parameter ($\beta$) is being estimated. For more details on fitting please see ?pscfit and ?pscEst

Usage

lik.flexsurvreg(beta, pscOb)

Arguments

Details

A likelihood function for use by pscfit for a model of class 'flexsurvreg'

Value

the results of a likelihood functions

Description

A function which defines the likelihood for a PSC model where the Counter Factual Model (CFM) takes the form of a 'glm' object and an efficacy parameter ($\beta$) is being estimated. For more details on fitting please see ?pscfit and ?pscEst

Usage

lik.glm(beta, pscOb)

Arguments

Details

A likelihood function for use by pscfit for a model of class 'glm'

Value

the results of a likelihood functions

Description

A generic function for extracting model information

Usage

modelExtract(CFM)

Arguments

Details

A function for extracting the model information required for using pscfit

Value

a list of extracted model components

Description

A generic function for extracting model information

Usage

## S3 method for class 'flexsurvreg'
modelExtract(CFM)

Arguments

Details

A function for extracting the model information required for using pscfit

Value

a list of extracted model components

Description

A generic function for extracting model information

Usage

## S3 method for class 'glm'
modelExtract(CFM)

Arguments

Details

A function for extracting the model information required for using pscfit

Value

a list of extracted model components

Description

A generic function for extracting model information

Usage

## S3 method for class 'lmerMod'
modelExtract(CFM)

Arguments

Details

A function for extracting the model information required for using pscfit

Value

a list of extracted model components

Description

A function which rrturns either the input value (if positive) or zero (if negative)

Usage

modp(x)

Arguments

Details

A fucntion which returns a version of x with negative values replacd with 0

Value

a numeric vector with negative values replaced with 0

Description

A function which summarises numerical data using a density plots

Usage

numVisComp(p, x)

Arguments

Value

a ggplot object

Description

A function which illsutrates the predicted response under the Counter Factual Model (CFM) and the observed response under the experimental treatment(s). Form of the output will depend on the form of the CFM used

Usage

## S3 method for class 'psc'
plot(x, ...)

Arguments

Details

This function plots the expected response of the control treatment along with the observe response rates of the experimental arms

Value

a survival plot corresponding to the psc fit

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
psc <- pscfit(gemCFM,e4_data,nsim=1500,nchain=1)
plot(psc)

Description

A function which illsutrates the predicted response under the counter factual model and the observed response under the experimental treatment(s).

Usage

## S3 method for class 'psc.binary'
plot(pscOb, ...)

Arguments

Details

This function plots the expected response of the control treatment along with the observe response rates of the experimental arms

Value

a survival plot corresponding to the psc fit

Description

A function which illsutrates the predicted response under the counter factual model and the observed response under the experimental treatment(s).

Usage

## S3 method for class 'psc.cont'
plot(x, ...)

Arguments

Details

This function plots the expected response of the control treatment along with the observe response rates of the experimental arms

Value

a survival plot corresponding to the psc fit

Description

Function for Plotting PSC objects #' A function which illsutrates the predicted response under the counter factual model and the observed response under the experimental treatment(s).

Usage

## S3 method for class 'psc.count'
plot(x, ...)

Arguments

Details

This function plots the expected response of the control treatment along with the observe response rates of the experimental arms

Value

a survival plot corresponding to the psc fit

Description

Function for Plotting PSC objects

Usage

## S3 method for class 'psc.flexsurvreg'
plot(pscOb, addFit = T, ...)

Arguments

Details

making use of 'ggsurvplot' in the survminer package, this function plots the expected survival funtion for the 'control' treatment estimated from the CFM along with the Kaplan Meier estimates of the observed events

Value

a survival plot corresponding to the psc fit

Description

A function which visualises the data of a CFM or the combined CFM and DC data for a 'psc' obecjec

Usage

plotCFM(x, ...)

Arguments

Details

This function returns either density plots (continuous data) or bar plots (categroical data) to describe the data in the CFM. If an object is supplied which has combied the CFM and DC (e.g. a psc object or an object which has been passed through pscData()) then a comparison of the CFM and DC will be supplied

Value

a plot to describe the data included in the models

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
plotCFM(gemCFM)
psc <- pscfit(gemCFM,e4_data,nsim=2000,nchain=1)
plotCFM(psc)

Description

A function that provides a summary of the posterior distributions obtained from a pscEst() procedures

Usage

postSummary(pscOb, thin = 2, burn = 1000, par = "beta")

Arguments

Details

This function makes use of the 'posterior' package to pull together each of the 'draw' matrices included in the psc object and produce posterior summaries

Value

Returns a summary of a 'psc' object including details on the original Counter Factual Model, a summary of the Data Cohort, the predicted responses from the CFM and details on the model fit.

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
pscOb <- pscData(gemCFM,e4_data)
pscOb <- init(pscOb)
pscOb <- pscEst(pscOb)
pscOb <- postSummary(pscOb)

Description

Personalised Synthetic Controls - print

Usage

## S3 method for class 'psc'
print(x, ...)

Arguments

Value

printing psc results

Description

Ensuring a quiet list of the grobs data are supplied to cfmDataVis

Usage

## S3 method for class 'quiet_gglist'
print(x, ...)

Arguments

Value

A quiet list

Description

Ensuring a quiet list of the grobs data are supplied to cfmDataVis

Usage

## S3 method for class 'quiet_gtsumm'
print(x, ...)

Arguments

Value

A quiet list

Description

Ensuring a quiet list of the grobs data are supplied to cfmDataVis

Usage

## S3 method for class 'quiet_list'
print(x, ...)

Arguments

Value

A quiet list

Description

An object returned by the pscfit function, inheriting from class psc and representing a fitted personalised synthetic control model.

Usage

psc.object

Format

An object of class NULL of length 0.

Author(s)

Richard Jasckson ([email protected])

Description

Standard R model objects contain within them the datasets used to create the model and as such care is needed when sharing these objects for research. The psc.cfm function creates an object with all identifiable information retracted and includes only the information required to use the models within the psc package

Usage

pscCFM(CFM, dataSumm = T, dataVis = T)

Arguments

Value

a list containing objects which specify the required exported components of the model.

Description

This function allows the combination of estimation where mulitple treatment comparisons are being made and one of the treatment levels relates to the control level. Note here it is assumed that the control level is coded trt=0. This function then combines the two efficacy estimates for the treatment effect (concurrent and synhtetic) whilst accounting for the correlation inherent in these two estimates.

Usage

pscComb(x)

Arguments

Description

This function ensures the data are supplied in a structure which allows for estimation. This is performed by re-fitting the original CFM with the DC and extracting the appropriate structures. Data are returned in terms of "Y" for model outcomes, "X" for data and "Z" for random effects where mixed models are supplied.

Usage

pscData(CFM, DC, id = NULL, trt = NULL)

Arguments

Value

A set of structures for use with estimation procedures

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
pscOb <- pscData(gemCFM,e4_data)

Description

The purpose of this function is to include the appropriate likelihood to the psc object for estimation procedures

Usage

pscData_addLik(CFM)

Arguments

Value

a likelihood function

Description

The purpose of this function is to organise a treatment indicator where multiple treatment comparisons are being evaluated. This acts as a sub-function to the pscData.R function.

Usage

pscData_addtrt(DC, trt)

Arguments

Value

a dataset which is checked and compatible with the CFM

Description

The purpose of this function is check that terms included in the Data Cohort match those used within the Counter Factual Model. This acts as a sub-function to the pscData.R function.

Usage

pscData_error(term.nm, DC)

Arguments

Value

a 'stop' command when errors are detected

Description

The purpose of this function is to run a series of checks to ensure that the data included in the data cohort is comparable to the counter-factual model. This matches the data classes and checks the levels in the DC match those used in the CFM. This acts as a sub-function to the pscData.R function.

Usage

pscData_match(cls, lev, DC)

Arguments

Value

a dataset which is checked and compatible with the CFM

Description

Currently the psc package works only on complete-case datasets. This function removes rows with missing data and returns a warning to inform the user. This acts as a sub-function to the pscData.R function.

Usage

pscData_miss(DC)

Arguments

Value

a dataset with missing data removed

Description

This function ensures the data are supplied in a structure which allows for estimation. This is performed by re-fitting the original CFM with the DC and extracting the appropriate structures. Data are returned in terms of "Y" for model outcomes, "X" for data and "Z" for random effects where mixed models are supplied.

Usage

pscData_structure(CFM, DC)

Arguments

Value

A set of structures for use with estimation procedures re-export Surv from survival

Description

Function for performing Bayesian MCMC estimation procedures in 'pscfit'

Usage

pscEst(pscOb, nsim = 1000, nchain = 1)

Arguments

Details

Define the set of model parameters $B$ to contain $\Gamma$ which summarize the parameters of the CFM. Prior distributions are defined for B using a multivariate normal distribution $\pi (B) \sim MVN(\mu ,\Sigma)$ where $\mu|$ is the vector of coefficient estimates from the validated model and $\Sigma$ is the variance-covariance matrix. This information is taken directly from the outputs of the parametric model and no further elicitation is required. The prior distirbution for the efficacy parameter ($\pi{(\beta)}$) is set as an uniformative $N(0,1000)$.

Ultimately the aim is to estimate the posterior distribution for $\beta$ conditional on the distribution of B and the observed data. A full form for the posterior distribution is then given as

$P(\beta \vert B,D) \propto L(D \vert B,\beta) \pi(B) \pi(\beta)$

Please see 'pscfit' for more details on liklihood formation.

For each iteration of the MCMC procedure, the following algorithm is performed

1. Set and indicator s=1, and define an initial state based on prior hyperparameters for $\pi(B)$ and $\pi(\beta)$ such that $b_s = \mu and \tau_s=0$

2. Update $s = s+1$ and draw model parameters $b_s$ from $\pi(B)$ and an draw a proposal estimate of $\beta$ from some target distribution

3. Estimate $\Gamma_(i,S)=\nu^T x_i$ where $\nu$ is the subset of parameters from $b_s$ which relate to the model covariates and define 2 new likelihood functions $\Theta_(s,1)=L(D \vert B=b_s,\beta=\tau_(s-1) )$ & $\Theta_(s,2)= L(D \vert B=b_s,\beta=\tau_s)$

4. Draw a single value $\psi$ from a Uniform (0,1) distribution and estimate the condition $\omega= \Theta_(s,1)/\Theta_(s,2)$. If $\omega > \psi$ then accept $\tau_s$ as belonging to the posterior distribution $P(\beta \vert B,D)$ otherwise retain $\tau_(s-1)$

5. Repeat steps 2 – 4 for the required number of iterations

The result of the algorithm is a posterior distribution for the log hazard ratio, $\beta$, captures the variability in B through the defined priors $\pi{(\beta)}$. @examples e4_data <- psc::e4_data gemCFM <- psc::gemCFM pscOb <- pscData(gemCFM,e4_data) pscOb <- init(pscOb) pscOb <- pscEst(pscOb,nsim=1500,nchain=1) importFrom survival Surv survfit

Value

A matrix containing the draws form the posterior distribution

Description

Running the Bayesian MCMC routine A procedure which runs the MCMC estimation routine

Usage

pscEst_run(pscOb, nsim, nchain)

Arguments

Value

An updated set of attributes for the pscOb which includes

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
pscOb <- pscData(gemCFM,e4_data)
pscOb <- init(pscOb)
pscOb <- pscEst_start(pscOb,nsim=1000,nchain=2)
pscOb <- pscEst_run(pscOb,nsim=1000,nchain=2)

Description

Starting conditions for Bayesian MCMC estimation procedures in 'pscfit' A procedure which runs the sampling process for MCMC estimation

Usage

pscEst_samp(pscOb, nsim)

Arguments

Value

An updated set of attributes for the pscOb which includes

Description

Starting conditions for Bayesian MCMC estimation procedures in 'pscfit' A procedure which sets the starting conditions for MCMC estimation

Usage

pscEst_start(pscOb, nsim, nchain)

Arguments

Details

A procedure which sets the starting conditions for MCMC estimation including defining starting estimates, setting a matrix for draws to be save in and defining, target and prior distributions and deifnign the posterior desitribution from the CFM. This also sets the number of cores to be used for estimation where parallel computing is applied.

Value

An updated set of attributes for the pscOb which includes

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
pscOb <- pscData(gemCFM,e4_data)
pscOb <- init(pscOb)
pscOb <- pscEst_start(pscOb,nsim=1000,nchain=2)

Description

Updating the posterior distribution as part of the MCMC estimation process A procedure which performs a single update of the posterior distribution

Usage

pscEst_update(i, draws, pscOb)

Arguments

Value

An updated set of posterior draws

Description

Function which allows comparison of a data cohort against a parametric Counter Factual Model (CFM). The function allows models of the type 'flexsurvreg' and 'glm' to be supplied. The function performs by calculating the linear predictor as a combination of the CFM and the dataset supplied and then selects a likelihood based on the type of model specified. Likelihood is estimated using a Baysian MCMC procedure wherebey the parameters of the CFM acts as informative priors.

Usage

pscfit(
  CFM,
  DC,
  nsim = 2000,
  id = NULL,
  trt = NULL,
  nchain = 1,
  thin = 2,
  burn = 500
)

Arguments

Details

Model currently supports estimation of more than one treatment (using the 'trt') option and esitmation restricted to sub-groups of the data cohort (using the 'id' option.

the pscfit function compares a dataset ('DC') against a parametric model. This is done by selecting a likelihood which is identified by the type of CFM that is supplied. At present, two types of model are supported, a flexible parmaeteric survival model of type 'flexsurvreg' and a geleneralised linear model of type 'glm'.

Where the CFM is of type 'flexsurvreg' the likeihood supplied is of the form:

$L(D \vert \Lambda, \Gamma_i) = \prod^{n}_{i=1} f(t_i \vert \Lambda, \Gamma_i)^{c_i} S(t_i|\Lambda, \Gamma_i)^{(1-c_i)}$

Where $\Lambda$ defines the cumulative baseline hazard function, $\Gamma$ is the linear predictor and $t$ and $c$ are the event time and indicator variables.

Where the CFM is of the type 'glm' the likelihood supplied is of the form:

$L(x \vert \Gamma_i) = \prod^{n}_{i=1} b(x \vert \Gamma_i) \exp{\{\Gamma_i^T t(x) - c(\Gamma_i)\} }$

Where $b(.)$, $t(.)$ and $c(.)$ represent the functions of the exponential family. In both cases, $\Gamma$ is defined as:

$\Gamma = \gamma x + \beta$

Where $\gamma$ are the model coefficients supplied by the CFM and $\beta$ is the parameter set to measure the difference between the CFM and the DC.

Estimation is performed using a Bayesian MCMC procedure. Prior distributions for $\Gamma$ (& $\Lambda$) are derived directly from the model coefficients (mean and variance covariance matrix) or the CFM. A bespoke MCMC routine is performed to estimate $\beta$. Please see '?mcmc' for more detials.

For the standard example where the DC contains information from only a single treatment, trt need not be specified. Where comparisons between the CFM and multiple treatments are require, a covariate of treamtne allocations must be specified sperately (using the 'trt' option).

Value

a object of class 'psc' with attributes model.type, the cleaned Dataset and the posterior distribution of the fitted model

Attributes include

• A 'cleaned' dataset including extracted components of the CFM and the cleaned DC included in the procedure

• An object defining the class of model (and therefore the procedure applied - see above)

• A matrix containing the draws of the posterior distributions

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
psc <- pscfit(gemCFM,e4_data,nsim=1500,nchain=1)
print(psc)

Description

A function to estimate the survival function based on parameter estimates - used in ootstrapping CFM for CIs

Usage

spline_surv_est(lam, kn, k, haz_co, cov_co, cov = cov, tm = tm, beta = 0)

Arguments

Value

A data frame containing survival estimates for a give time

Description

A generic function to provide a summary of a 'psc' object obtained from pscfit.R

Usage

## S3 method for class 'psc'
summary(object, ...)

Arguments

Value

A summary of a psc object obtained using pscSumm and a copy of the pscfit object

Examples

e4_data <- psc::e4_data
gemCFM <- psc::gemCFM
psc <- pscfit(gemCFM,e4_data,nsim=1500,nchain=1)
summary(psc)

Description

A generated model with a survival endpoint and a cuymulative hazard function estimated using flexible parametric splines. Data for the model were synthetically generated and are based on a dataset to evaulate the use of Sorafenib in HCC akin to the PROSASH model

Usage

surv.mod

Format

A model of class 'flezsurvreg':

gamma

cumulative baseline hazard parameters

vi

vascular invasion

age60

patient age (centred at 60)

ecog

ECOG performance Status

logafp

AFP - log scale

alb

albumin

logcreat

Creatinine - log scale

allmets

metastesis

ageVasInv

centred age nested within vascular invasion

time

survival time

cen

censoring indicator

os

survival time

de

count

exapmple outcome for count data

trt

exapmple identifier for mulitple treatment comparisons

aet

Aetiology

Source

simulated

References

Using prognostic and predictive clinical features to make personalised survival prediction in advanced hepatocellular carcinoma patients undergoing sorafenib treatment. Berhane S, et al., Br J Cancer. 2019 Jul;121(2):117-124

Description

The visComp function takes the data visualisations supplied as part of the CFM model and appends summaries of the equivalent datapoints from the Data Cohort.

Usage

visComp(CFM, DC, id = NULL)

Arguments

Value

a list of grobs for each model covariate