FAStdIncidenceRateResults: Familial Standardized Incidence Rate

In jotsetung/FamAgg: Pedigree Analysis and Familial Aggregation

Familial Standardized Incidence Rate

Description

The FAStdIncidenceRateResults object contains the results from a familial standardized incidence rate (FSIR) calculation employing in addition Monte Carlo simulations to assess significance levels for the individuals' FSIRs.

The FSIR weights the disease status of relatives based on their degree of relatedness with the proband (Kerber, 1995). Formally, the FSIR is defined as the standardized incidence ratio (SIR) or standardized morality ratio in epidemiology, i.e. as the ratio between the observed and expected number of cases, only that both are in addition also weighted by the degree of relatedness (i.e. kinship value) between individuals in the pedigree.

Usage

## S4 method for signature 'FAStdIncidenceRateResults'
fsir(object, trait=NULL, lambda=NULL,
                                           timeInStrata=NULL,
                                           ...)

## S4 method for signature 'FAStdIncidenceRateResults'
lambda(object, ...)

## S4 method for signature 'FAStdIncidenceRateResults'
plotPed(object, id=NULL, family=NULL,
                                              filename=NULL, device="plot",
                                              only.phenotyped=FALSE, ...)

## S4 method for signature 'FAStdIncidenceRateResults'
plotRes(object, id=NULL, family=NULL,
                                              addLegend=TRUE, type="density", ...)

## S4 method for signature 'FAStdIncidenceRateResults'
result(object, method="BH")

## S4 method for signature 'FAStdIncidenceRateResults'
resultForId(object, id=NULL)

## S4 method for signature 'FAStdIncidenceRateResults'
runSimulation(object, nsim=50000,
                                                    lambda=NULL,
                                                    timeInStrata=NULL,
                                                    strata=NULL,
                                                    ...)

## S4 method for signature 'FAStdIncidenceRateResults'
timeInStrata(object)

## S4 replacement method for signature 'FAStdIncidenceRateResults'
trait(object) <- value

Arguments

(in alphabetic order)

addLegend	For plotRes: if a legend should be added to the plot.
device	For plotPed: see plotPed for more details.
family	For plotPed: the family for which the pedigree should be plotted. For plotRes: not supported.
filename	For plotPed: the file name to which the pedigree plot should be exported. See plotPed for more details.
id	For plotPed and plotRes: the id of the indiviual for which the pedigree or the simulation result should be plotted. Note: id can be a numeric or a character. Numeric ids will be internally converted to character. For resultForId: the ID of the individual from which the result should be returned.
lambda	Numeric vector with the incidence rates per stratum from the population. The length of this vector has to match the number of columns of argument timeInStrata. For fsir: not used.
method	The multiple hypothesis testing method. All methods supported by p.adjust are allowed.
nsim	Number of simulations.
object	The FAStdIncidenceRateResults object.
only.phenotyped	For plotPed: Wheter only phenotyped individuals, i.e. individuals with a non-NA value in column affected (the trait information). If TRUE, the function removes all non-phenotyped individuals, keeping only those that are required for the pedigree to be complete.
strata	For runSimulation: a numeric, character of factor characterizing each individual in the pedigree. The length of this vector and the ordering has to match the pedigree. This vector allows to perform stratified random sampling. See details on the PedigreeAnalysis help page or examples for more information.
timeInStrata	For runSimulation: a numeric matrix specifying the time at risk for each individual in each strata. Columns represent the strata, rows the individuals, each cell the time at risk for the individual in the respective strata. See example below. The factor2matrix could be useful in generating such a table. For fsir: not used.
trait	For fsir: not used.
type	For plotRes: at present only "density" is supported.
value	For trait<-: can be a named numeric, character or factor vector. The names (at least some of them) have to match the ids in the pedigree of the object.
...	For plotPed: additional arguments to be submitted to the internal buildPed call and to plotPed. For runSimulation: additional arguments prune and lowMem. See below for details.

Details

Monte Carlo simulation and empirical p-value estimation: see details of FAIncidenceRateResults as the concept and calculation is essentially identical.

Calling the runSimulation method on a FAStdIncidenceRateResults object is the same as calling the fsirTest on a FAData object. In the first case the simulation is performed using the trait information data stored internally in the object, while in the latter case the trait information have to be submitted to the function call.

By providing argument strata, the stratified random sampling is performed. See example below and the details section in PedigreeAnalysis for more details.

The FSIR can also be directly calculated, without simulation, using the fsir method of a FAData object.

A call to the setter methods trait<- resets any simulation results present in the sim slot, thus, the object can be re-used to perform a simulation analysis using the new trait data.

By default the Monte Carlo p-value estimation in the runSimulation method is quite memory demanding. For very large pedigrees the optional argument lowMem=TRUE might be passed to the method which results in faster and less memory demanding calculations. This will however disable the plotRes method on the resulting FAStdIncidenceRateResults as the distribution of FSIR from the simulation runs is no longer reported.

Note: the FIR for singletons and individuals that do not share kinship with at least one other phenotyped individual that has also a valid value in argument timeAtRisk (and eventually strata) will be NA.

Value

Refer to the method and function description above for detailed information on the returned result object.

Objects from the Class

FAStdIncidenceRateResults objects are created by the fsirTest method on a FAData object.

Extends

Class FAData directly.

Slots

nsim

Number of simulations.

sim

The result of the simulation. This slot should not be accessed directly, use the result method to extract result information.

timeInStrata

Numeric matrix specifying the time at risk in each strata (represented by the columns) of each individual (rows). Use the accessor method timeInStrata to extract this data.

lambda

Numeric vector with the incidence rates per stratum from the population.

Methods and Functions

object$name

Access various results and data stored in the object. name can be fsir, pvalue, lambda or timeInStrata to access the FSIR, the (raw) p-value from the simulation analysis, the lambda or the time in strata.

fsir

Returns the FSIR values calculated by a call to the runSimulation method or fsir method on a FAData object. In contrast to that latter method, which directly calculates the values, this method returns the values from a calculation stored inside the FAStdIncidenceRateResults object.

The method returns a named numeric vector with the familial incidence rates, the names being the ID of the individuals. Singletons as well as individuals that, after removing not phenotyped individuals or individuals without time at risk, do not share kinship with any other individual in the pedigree have a value of NA.

plotPed

Plots a pedigree for one of the affected individuals in the simulation results. The id of the selected affected individual (specified with argument id) is highlighted in red. The FSIR value for each individual is drawn below the individual's id. See plotPed for more details.

plotRes

Plots the distribution of expected FSIR calculated for the selected individuals from Monte Carlo simulations along with the actually observed FSIR.

result

Returns the result from the simulation as a data.frame with columns:

"trait_name": the name of the trait.

"total_phenotyped": total number of phenotyped individuals in the trait.

"total_affected": total number of affected individuals in the trait.

"total_tested": the number of individuals in the pedigree considered for the simulation. This corresponds to all individuals with valid, non-NA, values in trait, timeAtRisk and eventually strata.

"id": the id of the individual.

"family": the family id.

"fsir": the familial standardized incidence rate. Note that this will be

NA for all non-phenotyped individuals and singletons in the pedigree as well as for individuals that do not share kinship with at least one other phenotyped individual with valid time at risk (or valid value in parameter strata).

"pvalue": the p-value for the significance of the familial standardized incidence rate assessed by Monte Carlo simulations.

"padj": the p-value adjusted for multiple hypothesis testing (with the method specified with argument method).

The returned data.frame is sorted by column "pvalue", its row names correspond to column "id".

resultForId

Extracts results information for a given individual. The method returns a list with elements "id", "fsir", "pvalue", "timeInStrata" and "lambda" with the ID of the individual, the FSIR and corresponding p-value estimated by the simulation, the row from the timeInStrata matrix of the individual and the lambda (incidence rates from the population).

runSimulation

Performs the simulation analysis based on the pedigree and trait information stored in the object as well as the time at risk provided with argument timeAtRisk. Returns a FAStdIncidenceRateResults object with the results from the simulation.

trait<-

Set the trait information. This method will reset all simulation results saved in the sim slot.

Note

Subsetting (using the [ operator) is not supported.

Author(s)

Johannes Rainer

References

Kerber, R.A. (1995) Method for calculating risk associated with family history of a disease. Genet Epidemiol, pp 291–301.

See Also

FAData, kinship, trait, probabilityTest, kinshipGroupTest, kinshipSumTest, genealogicalIndexTest, familialIncidenceRateTest, fsirTest, plotPed, estimateTimeAtRisk

Examples

##########################
##
##  Perform the simulation analysis
##
## Load the test data.
data(minnbreast)

## Subset to some families and generate a pedigree data.frame.
mbsub <- minnbreast[minnbreast$famid == 4 | minnbreast$famid == 5 |
                    minnbreast$famid == 6 | minnbreast$famid == 7 |
                    minnbreast$famid == 411, ]
PedDf <- mbsub[, c("famid", "id", "fatherid", "motherid", "sex")]
colnames(PedDf) <- c("family", "id", "father", "mother", "sex")

## Generate the FAData.
fad <- FAData(pedigree=PedDf)

## Specify the trait.
tcancer <- mbsub$cancer
names(tcancer) <- mbsub$id

## Next we have to specify lambda and the timeInStrata matrix.
## For lambda we use information from Cancer Research UK:
## New breast cancer cases in females per year and 100000: 155.3
## New breast cancer cases in males per year and 100000:     1.1
## New prostate cancer cases in females per year and 100000: 0
## New prostate cancer cases in males per year and 100000: 134.3
lbda <- c(M=(1.1+134.4)/100000, F=155.3/100000)

## Next we need the time at risk of each individual in each strata.
## For strata we use male and females, for the time at risk we use
## column "endage":
stratMat <- factor2matrix(fad$sex)
## Next we have to multiply that with the endage, since each person
## spent that time "at risk" to get cancer.
stratMat <- stratMat * mbsub$endage

## Running the simulation
fsirs <- fsirTest(fad, trait=tcancer, traitName="cancer", lambda=lbda,
                  timeInStrata=stratMat, nsim=500)

## Showing some of the results
head(result(fsirs))

## Extract the FSIR
head(fsirs$fsir)

## We can also directly access the p-values from the simulation,
## these are however the raw, unadjusted p-values.
head(fsirs$pvalue)

## Get the time in strata for each individual
head(fsirs$timeInStrata)

## Plot the pedigree for a family with significant FSIRs.
## The numbers below the IDs of the individuals represent the actual
## FSIR values.
plotPed(fsirs, family=result(fsirs)$family[1])

## Plot also the result from the simulation run.
plotRes(fsirs, id=result(fsirs)$id[1])

## Extract the data and result for an individual
resultForId(fsirs, id="16424")

jotsetung/FamAgg documentation built on March 15, 2023, 3:48 a.m.