Weights calculation

Description

contrib is a function that finds out how much time was contributed for every combination of the incidence covariates, the survival covariates, and follow up time. Using these contibutions makes the calculation of the variance of the expected number of deaths much more efficient than making the calculations on the raw data.

Usage

contrib(start_follow, end_follow, incid_cov, surv_cov, follow_up, increment)

Arguments

Details

If only time independent covariates are used, then all vectors are of dimension n = sample size.

Otherwise, the function contrib needs an augmented dataset, in which each person-time corresponds to one row. Each row contains the values of the time-invariant covariates and the updated values of time-dependent variables. Therefore, the covariates must have a finite number of values (they must be discrete).

For example, if only the covariate “age” is used for incidence and survival, an individual followed for 3.4 years that was 54.6 years at the begining of the study should be entered as follow:

#start_follow, end_follow, incid_cov, surv_cov, follow_up
0 0.4 54 54 3.4
0.4 1.4 55 55 3.4
1.4 2.4 56 56 3.4
2.4 3.4 57 57 3.4

An example of the code required to do such a thing is provided in the screening dataset help page.

Value

The resulting list is directly usable in functions est.expDeath, var.expDeath and inference.SMR. The list contains the following elements :

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

See Also

est.expDeath, var.expDeath, inference.SMR, screening

Covariance between two survival probability estimates.

Description

The function covariance calculates the covariance between two survival probabilty obtained with a Cox proportional hazard model. Follow-up times and covariates may differ for the two survival probabilties. This is mostly an internal function, meant to be used by the function var.expDeath.

Usage

covariance(t_i, delta_i, beta, time1, z1, time2, z2, S0_i, S1_i, S02_i, Omega_1)

Arguments

Details

This function was built to be an internal function, only used by the function var.expDeath.

Value

The covariance between the two estimated survival probability.

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

References

Lin D.Y., Fleming T.R., Wei L.J. (1994) Confidence bands for survival curves under the proportional hazards model, Biometrika, 81 (1): 73-81.

Talbot, D., Duchesne, T., Brisson, J., Vandal, N. (2011) Variance estimation and confidence intervals for the standardized mortality ratio with application to the assessment of a cancer screening program, Statistics in Medicine, 30, 3024-3037.

See Also

var.expDeath, function1

Estimation of the expected number of deaths.

Description

Estimation of the expected number of deaths in a screening program using the method proposed by Sasieni (2003).

Usage

est.expDeath(contribution, incid, cox, fuzz, covnames)

Arguments

Value

Returns the expected number of deaths

Note

A complete example of usage is provided in the help page of the screening dataset.

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

References

Sasieni P. (2003) On the expected number of cancer deaths during follow-up of an initially cancer-free cohort. Epidemiology, 14, 108-110.

See Also

var.expDeath,inference.SMR, screening

Examples

#This example uses pre-built objects and shows the simple usage
#of the est.expDeath function when those objects already exists.
#For an example of how to built those object, refer to the 
#help page of the screening dataset.

data(req.objects);
cox.data = req.objects$cox.data;
#Remove "#" to run example :
#est.expDeath(req.objects$contribution,req.objects$incid,req.objects$cox,fuzz = 0.01, 
#req.objects$covnames);

#[1] 33.44264

Internal function for function var.expDeath

Description

This function was only meant to be used by the function var.expDeath. It provides many objects that are needed for the estimation of the variance of the expected number of deaths.

Usage

function1(x)

Arguments

Value

The function function1 returns a list containing many objects that are used by the function var.expDeath.

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

See Also

var.expDeath

h function as defined by Lin et al. (1994).

Description

An internal function meant only to be used by the covariance function.

Usage

h(t_i, delta_i, beta, time, z, S0_i, S1_i)

Arguments

Details

This is an internal function, only meant to be used by the covariance function.

Value

A numeric value described in Lin et al. (1994).

Author(s)

Denis Talbot, Thierry Duchense, Jacques Brisson, Nathalie Vandal.

References

Lin D.Y., Fleming T.R., Wei L.J. (1994) Confidence bands for survival curves under the proportional hazards model, Biometrika, 81 (1): 73-81.

See Also

covariance

Incidences calculations.

Description

A function to calculate incidence rates for every combination of age and calendar years.

Usage

incidences(age_min, age_max, year_min, year_max, follow_up,
start_age, start_year, case)

Arguments

Details

This function can be used to obtain incidences for the functions est.expDeath, var.expDeath and inference.SMR. A complete example of usage is provided in the help page of the screening dataset.

Value

A matrix whose first column is the number of person-years at risk, the second column is the calendar years, the third column is the ages and the fourth column is the incidence rates.

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

See Also

est.expDeath, var.expDeath, inference.SMR, screening

Inference about the standardized mortality ratio (SMR) when evaltuating the effect of a screening program on survival.

Description

This function estimates the expected number of deaths, its variance, the SMR and confidence intervals about the SMR.

Usage

inference.SMR(obs.death, normal = "log-smr", alpha = 0.05, contribution,
incid, cox, fuzz = 0.01, Poisson = FALSE, covnames)

Arguments

Details

The inference.SMR function estimates the expected number of deaths as in Sasieni (2003), estimates the variance of the expected number of deaths and builds confidence intervals as in Talbot et al. (2011). As suggested in the latter, the variance of the observed number of deaths is estimated by the observed number of deaths.

Value

Note

A complete example of usage is provided in the help page of the screening dataset.

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

References

Sasieni P. (2003) On the expected number of cancer deaths during follow-up of an initially cancer-free cohort. Epidemiology, 14, 108-110.

Talbot, D., Duchesne, T., Brisson, J., Vandal, N. (2011) Variance estimation and confidence intervals for the standardized mortality ratio with application to the assessment of a cancer screening program, Statistics in Medicine, 30, 3024-3037.

See Also

est.expDeath, var.expDeath, screening

Examples

#This example uses pre-built objects and shows the simple usage
#of the est.expDeath function when those objects already exist.
#For an example of how to build those objects, refer to the 
#help page of the screening dataset.

#Estimating the variance can be very long even in this small sample example, e.g. a few hours.
#Remove "#" to run example :
#data(req.objects);
#cox.data = req.objects$cox.data;
#results = inference.SMR(obs.death = sum(screening$deathSCN),
# normal = c("smr", "log-smr", "root-smr"),
#	 alpha = 0.05, req.objects$contribution, req.objects$incid,
#	 cox = req.objects$cox, fuzz = 0.01, Poisson = TRUE, req.objects$covnames);


#********  INFERENCE ABOUT THE SMR  ********* 
#
#Observed =  18  Expected =  33.44264 
#Obs.var. =  18  Exp.var. =  39.38153 
#SMR =  0.5382351 
#
# 95 % Confidence intervals with normality assumption at : 
#
#The SMR level : ( 0.2204119 0.8560583 )
#
#The log-SMR level : ( 0.2982118 0.9714471 )
#
#The root-SMR level : ( 0.2673299 0.9029762 )

#results
#
#$expected
#[1] 33.44264
#
#$obs.death
#[1] 18
#
#$variance
#            2
#[1,] 39.38153
#
#$smr
#[1] 0.5400112
#
#$smr.var
#              2
#[1,] 0.02629511
#
#$smr.ci
#[1] 0.2204119 0.8560583
#
#$logSMR.var
#              2
#[1,] 0.09076763
#
#$logSMR.ci
#[1] 0.2982118 0.9714471
#
#$rootSMR.var
#              2
#[1,] 0.01221358
#
#$rootSMR.ci
#[1] 0.2673299 0.9029762

Required objects to run some examples

Description

Contains pre-built objects used to run some examples. Those items simplify some examples.

Usage

data(req.objects)

Format

The format is: List of 5 $ contribution:List of 4 ..$ :'data.frame': 1022 obs. of 9 variables: .. ..$ Group.1: num [1:1022] 0 0.5 1 1.5 2 2.5 3 0 0.5 1 ... .. ..$ Group.2: num [1:1022] 3 3 3 3 3 3 3 4 4 4 ... .. ..$ Group.3: num [1:1022] 70 70 70 70 70 70 70 70 70 70 ... .. ..$ Group.4: num [1:1022] 0 0 0 0 0 0 0 0 0 0 ... .. ..$ Group.5: num [1:1022] 0 0 0 0 0 0 0 0 0 0 ... .. ..$ Group.6: num [1:1022] 0 0 0 0 0 0 0 0 0 0 ... .. ..$ Group.7: num [1:1022] 0 0 0 0 0 0 0 0 0 0 ... .. ..$ Group.8: num [1:1022] 0 0 0 0 0 0 0 0 0 0 ... .. ..$ x : num [1:1022] 11 16.5 11 11 20 20 11 8 16 34 ... ..$ : int 2 ..$ : int 5 ..$ : num 0.5 $ incid : num [1:156, 1:4] 0.018 0.0171 0.0266 0.0122 0.0183 ... $ cox :List of 18 ..$ coefficients : Named num [1:5] -0.3843 0.3169 0.0076 0.1483 0.1751 .. ..- attr(*, "names")= chr [1:5] "year" "age1" "age2" "age3" ... ..$ var : num [1:5, 1:5] 0.104866 0.003629 -0.003322 -0.000495 -0.004334 ... ..$ loglik : num [1:2] -361 -360 ..$ score : num 2.19 ..$ iter : int 4 ..$ linear.predictors: num [1:697] 0.1638 -0.2281 -0.0798 -0.2281 0.3313 ... ..$ residuals : Named num [1:697] -0.0179 -0.0877 -0.1096 -0.1518 -0.1014 ... .. ..- attr(*, "names")= chr [1:697] "1" "2" "3" "4" ... ..$ means : num [1:5] 0.5968 0.0861 0.1449 0.1578 0.122 ..$ concordance : Named num [1:5] 13077 9278 4675 0 2084 .. ..- attr(*, "names")= chr [1:5] "concordant" "discordant" "tied.risk" "tied.time" ... ..$ method : chr "breslow" ..$ n : int 697 ..$ nevent : num 60 ..$ terms :Classes 'terms', 'formula' length 3 Surv(time = followONS, event = deathBC, type = "right") ~ year + age1 + age2 + age3 + age4 .. .. ..- attr(*, "variables")= language list(Surv(time = followONS, event = deathBC, type = "right"), year, age1, age2, age3, age4) .. .. ..- attr(*, "factors")= int [1:6, 1:5] 0 1 0 0 0 0 0 0 1 0 ... .. .. .. ..- attr(*, "dimnames")=List of 2 .. .. .. .. ..$ : chr [1:6] "Surv(time = followONS, event = deathBC, type = \"right\")" "year" "age1" "age2" ... .. .. .. .. ..$ : chr [1:5] "year" "age1" "age2" "age3" ... .. .. ..- attr(*, "term.labels")= chr [1:5] "year" "age1" "age2" "age3" ... .. .. ..- attr(*, "specials")=Dotted pair list of 3 .. .. .. ..$ strata : NULL .. .. .. ..$ cluster: NULL .. .. .. ..$ tt : NULL .. .. ..- attr(*, "order")= int [1:5] 1 1 1 1 1 .. .. ..- attr(*, "intercept")= int 1 .. .. ..- attr(*, "response")= int 1 .. .. ..- attr(*, ".Environment")=<environment: R_GlobalEnv> .. .. ..- attr(*, "predvars")= language list(Surv(time = followONS, event = deathBC, type = "right"), year, age1, age2, age3, age4) .. .. ..- attr(*, "dataClasses")= Named chr [1:6] "nmatrix.2" "numeric" "numeric" "numeric" ... .. .. .. ..- attr(*, "names")= chr [1:6] "Surv(time = followONS, event = deathBC, type = \"right\")" "year" "age1" "age2" ... ..$ assign :List of 5 .. ..$ year: num 1 .. ..$ age1: num 2 .. ..$ age2: num 3 .. ..$ age3: num 4 .. ..$ age4: num 5 ..$ wald.test : num 2.17 ..$ y : Surv [1:697, 1:2] 0.7957+ 3.4669+ 3.7693+ 5.5679+ 2.0462+ 2.1702 0.7686+ 2.7796+ 3.7853+ 5.2374+ ... .. ..- attr(*, "dimnames")=List of 2 .. .. ..$ : chr [1:697] "1" "2" "3" "4" ... .. .. ..$ : chr [1:2] "time" "status" .. ..- attr(*, "type")= chr "right" ..$ formula :Class 'formula' length 3 Surv(time = followONS, event = deathBC, type = "right") ~ year + age1 + age2 + age3 + age4 .. .. ..- attr(*, ".Environment")=<environment: R_GlobalEnv> ..$ call : language coxph(formula = Surv(time = followONS, event = deathBC, type = "right") ~ year + age1 + age2 + age3 + age4, data = cox.data, control = coxph.control(iter.max = 100), method = "breslow") ..- attr(*, "class")= chr "coxph" $ covnames : chr [1:5] "year" "age1" "age2" "age3" ... $ cox.data :'data.frame': 697 obs. of 7 variables: ..$ followONS: num [1:697] 0.796 3.467 3.769 5.568 2.046 ... ..$ deathBC : num [1:697] 0 0 0 0 0 1 0 0 0 0 ... ..$ year : num [1:697] 0 1 1 1 0 1 0 0 1 1 ... ..$ age1 : num [1:697] 0 0 0 0 0 0 0 0 0 0 ... ..$ age2 : num [1:697] 1 0 0 0 0 0 0 0 0 0 ... ..$ age3 : num [1:697] 0 0 1 0 0 0 0 1 0 1 ... ..$ age4 : num [1:697] 0 0 0 0 1 0 0 0 0 0 ...

A population of size 10,000 for a screening program

Description

This dataset contains a simulated population of size 10,000. The population was simulated as described in Talbot et al (2011).

Usage

data(screening)

Format

A data frame with 10000 observations on the following 12 variables.

yearSCN

Year at which the person would become a participant in the screening program

ageSCN

Age at which the person would become a participant in the screening program

yearONS

Year at which the disease onset would happen for a non-participant

deathBC

Indicator variable that has a value of 1 if the non-participant dies from the screened disease, 0 otherwise.

ageFL

Age at which the person is eligible to the screening program for the first time

yearFL

Year at which the person is eligible to the screening program for the first time

followONS

Follow-up time for a non-participant after the disease onset

followSCN

Follow-up time as participant in the screening program

particip

Indicator variable that has a value of 1 if the individual eventually became a participant in the screening program, 0 otherwise

Onset

Indicator variable that has a value of 1 if the disease onset happens while the person is a non-participant

end

Year at which the follow-up ends

deathSCN

Indicator variable that has a value of 1 if the participants dies from the screened disease, 0 otherwise.

Details

Note that even though there are no missing values in the dataset, some events do not occur. For example, if yearsSCN has a greater value than end, then the inidividual never becomes a participant.

Examples

require(survival); #load survival package;
data(screening);
head(screening); #Data to be used in the example;
NB = nrow(screening); #Sample size

#Be careful with R round function. If it was used to obtain discrete value, then
#fuzz option should be used for expected and expected variance 
i=1:NB
yearSCN<-screening[i,1]; #Year at which the woman started participating
ageSCN<-screening[i,2]; #Age at which the woman started participating
yearONS<-screening[i,3]; #Year of breast cancer diagnosis
deathBC<-screening[i,4]; #Death by breast cancer indicator for non-participating woman.
ageFL<-screening[i,5]; #Age at which the woman became eligible
yearFL<-screening[i,6]; #Year at which the woman became eligible
followONS<-screening[i,7]; #Follow-up time after disease onset for a non-participant
followSCN<-screening[i,8]; #Follow-up time as a participant in the screening program
particip<-screening[i,9]; #Indicator that the woman participated into the screening
                          #program at some point
Onset<-screening[i,10]; #Indicator that the non-participating woman got breast cancer
end<-screening[i,11]; #year of eligibility end.
deathSCN<-screening[i,12]; #Death by breast cancer indicator for participating woman.

nb_onset=length(Onset[Onset==1]); #Number of women with breast cancer

#Objects that will containt covariates for the Cox model
year<-numeric(nb_onset); 
age1<-numeric(nb_onset);
age2<-numeric(nb_onset);
age3<-numeric(nb_onset);
age4<-numeric(nb_onset);
ti<-numeric(nb_onset);

year[yearONS[Onset==1] <= 3] = 1; #Indicator that diagnosis happened before year 3
year[yearONS[Onset==1] > 3] = 0; #Indicator that diagnosis happened before year 3
age1[ageSCN[Onset==1] < 55] = 1; #Indicator that age at diagnosis is smaller than 55
age1[ageSCN[Onset==1] >= 55] = 0; #Indicator that age at diagnosis is smaller than 55
age2[ageSCN[Onset==1] >= 55 & ageSCN[Onset==1] < 60] = 1; #... >= 55 and < 60
age2[ageSCN[Onset==1] < 55 | ageSCN[Onset==1] >= 60] = 0; #... >= 55 and < 60
age3[ageSCN[Onset==1] >= 60 & ageSCN[Onset==1] < 65] = 1; #... >= 60 and < 65
age3[ageSCN[Onset==1] < 60 | ageSCN[Onset==1] >= 65] = 0; #... >= 60 and < 65
age4[ageSCN[Onset==1] >= 65 & ageSCN[Onset==1] < 70] = 1; #... >= 65 and < 70
age4[ageSCN[Onset==1] < 65 | ageSCN[Onset==1] >= 70] = 0; #... >= 65 and < 70
cox.data = data.frame(followONS = followONS[Onset == 1], deathBC = deathBC[Onset == 1],
year, age1, age2, age3, age4);
x<-coxph(Surv(time = followONS, event = deathBC, type = 'right')~ year + age1 + age2 + age3 + age4,
data = cox.data, method="breslow",control=coxph.control(iter.max=100))

#Creating a matrix with many more lines than what will be used
new_data<-matrix(0,nrow=12*sum(particip),ncol=10); 

#Creating a matrix containing data in a new form.
#Each line contains stable covariates, so that a
#given individual might be divided on many lines.
#For example, if only the covariate age is used for incidence and survival, 
#an individual followed for 3.4 years that was 54.6 years at the begining 
#of the study should be entered as follow:

#start_follow, end_follow, incid_cov, surv_cov, follow_up
#0   0.4 54 54 3.4
#0.4 1.4 55 55 3.4
#1.4 2.4 56 56 3.4
#2.4 3.4 57 57 3.4


r=1
for(i in seq(1,length(ageFL))[particip==1])
{
        X = followSCN[i];
        dep_t = yearSCN[i];
        age_t = ageSCN[i];
        while(dep_t - yearSCN[i] < X)
        {
                Y = min(floor(age_t) + 1 - age_t, floor(dep_t) + 1 - dep_t);
                if(dep_t - yearSCN[i] + Y >= X)
                {
                        new_data[r,]<-c(floor(age_t), floor(dep_t), age_t < 55,
                        (age_t >= 55 && age_t < 60),
                        (age_t >= 60 && age_t < 65), (age_t >=65 && age_t <70), 
                        dep_t < 3, dep_t - yearSCN[i], X, followSCN[i]);
                }
                else
                {
                        new_data[r,]<-c(floor(age_t), floor(dep_t), age_t < 55,
                        (age_t >= 55 && age_t < 60),
                        (age_t >= 60 && age_t < 65), (age_t >=65 && age_t <70),
                        dep_t < 3, dep_t - yearSCN[i], dep_t - yearSCN[i] + Y, followSCN[i]);
                }
                dep_t = dep_t + Y;
                age_t = age_t + Y;
                r = r + 1;
        }
}
new_data<-new_data[new_data[,1]!=0,];
new_data[1:10,];

#Calculate incidences with incidences function:
#follow up time as non-participant:
follow_up = apply(cbind(end - yearFL,yearONS - yearFL,yearSCN - yearFL),1,min);
incid = incidences(50,75,0,5,follow_up,ageFL,yearFL,Onset);


#Calculate contributions with contrib function:
start_follow = new_data[,8];
end_follow = new_data[,9];
incid_cov = new_data[,c(2,1)];
surv_cov = data.frame(new_data[,c(7,3,4,5,6)]); 
follow_up = new_data[,10];
increment = 0.5;


#Remove following "#" to run example : 

#contribution = contrib(start_follow, end_follow, incid_cov, surv_cov,
#follow_up, increment);
#est.expDeath(contribution,incid,x,fuzz = 0.01, 
#covnames = c("year", "age1", "age2", "age3", "age4"));

#Estimating the variance can be very long even in this small sample example, e.g. a few hours.
#Remove the "#" to run example:
#var.expDeath(contribution,incid,x,fuzz = 0.01, 
#covnames = c("year", "age1", "age2", "age3", "age4"));

#Estimating the variance can be very long even in this small sample example, e.g. a few hours.
#Remove the "#" to run example:

#results = inference.SMR(obs.death = sum(deathSCN), normal = c("smr", "log-smr", "root-smr"),
#        alpha = 0.05, contribution, incid, cox = x, fuzz = 0.01, Poisson = TRUE,
#  covnames =  c("annees", "age1", "age2", "age3", "age4"));


#********  INFERENCE ABOUT THE SMR  ********* 
#
#Observed =  18  Expected =  33.44264 
#Obs.var. =  18  Exp.var. =  39.38153 
#SMR =  0.5382351 
#
# 95 % Confidence intervals with normality assumption at : 
#
#The SMR level : ( 0.2204119 0.8560583 )
#
#The log-SMR level : ( 0.2982118 0.9714471 )
#
#The root-SMR level : ( 0.2673299 0.9029762 )

#results
#
#$expected
#[1] 33.44264
#
#$obs.death
#[1] 18
#
#$variance
#            2
#[1,] 39.38153
#
#$smr
#[1] 0.5400112
#
#$smr.var
#              2
#[1,] 0.02629511
#
#$smr.ci
#[1] 0.2204119 0.8560583
#
#$logSMR.var
#              2
#[1,] 0.09076763
#
#$logSMR.ci
#[1] 0.2982118 0.9714471
#
#$rootSMR.var
#              2
#[1,] 0.01221358
#
#$rootSMR.ci
#[1] 0.2673299 0.9029762

Variance estimation of the expected number of deaths

Description

This function estimates the variance of the expected number of deaths when the latter is estimated using Sasieni's method.

Usage

var.expDeath(contribution, incid, cox, fuzz, Poisson = FALSE, covnames)

Arguments

Value

The function returns the variance of the expected number of deaths

Note

A complete example of how to use this function is available in the help page of the screening dataset.

Author(s)

Denis Talbot, Thierry Duchesne, Jacques Brisson, Nathalie Vandal.

References

Talbot, D., Duchesne, T., Brisson, J., Vandal, N. (2011) Variance estimation and confidence intervals for the standardized mortality ratio with application to the assessment of a cancer screening program, Statistics in Medicine, 30, 3024-3037.

See Also

est.expDeath, inference.SMR, screening

Examples

#This example uses pre-built objects and shows the simple usage
#of the est.expDeath function when those objects already exists.
#For an example of how to built those object, refer to the 
#help page of the screening dataset.

#Remove "#" to run example. The function can be quite long (a few hours) to run:
#data(req.objects);
#cox.data = req.objects$cox.data;
#var.expDeath(req.objects$contribution,req.objects$incid,req.objects$cox,fuzz = 0.01, 
#req.objects$covnames);


#[1,] 39.31382