GLM {brainGraph}

Fit General Linear Models at each vertex of a graph

Description

brainGraph_GLM specifies and fits a General Linear Model (GLM) at each vertex for a given vertex measure (e.g. degree) or at the graph-level (e.g., global efficiency). Given a contrast matrix or list of contrast(s), and contrast type (for t- or F-contrast(s), respectively) it will calculate the associated statistic(s) for the given contrast(s).

The summary method prints the results, only for which p < \alpha, where alpha comes from the bg_GLM object. “Simple” P-values are used by default, but you may change this to the FDR-adjusted or permutation P-values via the function argument p.sig. You may also choose to subset by contrast.

The plot method plots the GLM diagnostics (similar to that of plot.lm). There are a total of 6 possible plots, specified by the which argument; the behavior is the same as in plot.lm. Please see the help for that function.

The [ method allows you to select observations (i.e., rows of X and y) and independent variables (i.e., columns of X) from a bg_GLM object.

Usage

brainGraph_GLM(g.list, covars, measure, contrasts, con.type = c("t",
  "f"), outcome = NULL, X = NULL, con.name = NULL,
  alternative = c("two.sided", "less", "greater"), alpha = 0.05,
  level = c("vertex", "graph"), permute = FALSE,
  perm.method = c("freedmanLane", "terBraak", "smith", "draperStoneman",
  "manly", "stillWhite"), part.method = c("beckmann", "guttman",
  "ridgway"), N = 5000, perms = NULL, long = FALSE, ...)

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

## S3 method for class 'bg_GLM'
summary(object, p.sig = c("p", "p.fdr", "p.perm"),
  contrast = NULL, alpha = object$alpha, digits = max(3L,
  getOption("digits") - 2L), print.head = TRUE, ...)

## S3 method for class 'bg_GLM'
plot(x, region = NULL, which = c(1L:3L, 5L),
  ids = TRUE, ...)

## S3 method for class 'bg_GLM'
x[i, j]

Arguments

g.list

A brainGraphList object

covars

A data.table of covariates

measure

Character string of the graph measure of interest

contrasts

Numeric matrix (for T statistics) or list of matrices (for F statistics) specifying the contrast(s) of interest; if only one contrast is desired, you can supply a vector (for T statistics)

con.type

Character string; either 't' or 'f' (for t or F-statistics). Default: 't'

outcome

Character string specifying the name of the outcome variable, if it differs from the graph metric (measure)

X

Numeric matrix, if you wish to supply your own design matrix. Ignored if outcome != measure.

con.name

Character vector of the contrast name(s); if contrasts has row/list names, those will be used for reporting results

alternative

Character string, whether to do a two- or one-sided test. Default: 'two.sided'

alpha

Numeric; the significance level. Default: 0.05

level

Character string; either vertex (default) or graph

permute

Logical indicating whether or not to permute group labels. Default: FALSE

perm.method

Character string indicating the permutation method. Default: 'freedmanLane'

part.method

Character string; the method of partitioning the design matrix into covariates of interest and nuisance. Default: 'beckmann'

N

Integer; number of permutations to create. Default: 5e3

perms

Matrix of permutations, if you would like to provide your own. Default: NULL

long

Logical indicating whether or not to return all permutation results. Default: FALSE

...

Arguments passed to brainGraph_GLM_design

object, x

A bg_GLM object

p.sig

Character string specifying which P-value to use for displaying significant results (default: p)

contrast

Integer specifying the contrast to plot/summarize; defaults to showing results for all contrasts

digits

Integer specifying the number of digits to display for P-values

print.head

Logical indicating whether or not to print only the first and last 5 rows of the statistics tables (default: TRUE)

region

Character string specifying which region's results to plot; only relevant if level='vertex'. Default: NULL

which

Integer vector indicating which of the 6 plots to print to the plot device. Default: c(1:3, 5)

ids

Logical indicating whether to plot subject ID's for outliers. Otherwise plots the integer index

i

Integer/character vector; the observation number(s) or row names to select or remove

j

Integer/character vector; the design matrix column number(s) or names to select or remove

Details

The measure argument will be the graph- or vertex-level measure of interest. Often, this will serve as the model's outcome (or dependent, or response) variable; i.e., the variable typically denoted by y in GLMs. In other cases, you may wish to choose some other variable as the outcome; e.g., IQ, age, etc. Then you could test for a direct association between the network measure and outcome of interest, or test for another association while adjusting for the network metric. For these applications, you must provide the variable name via the outcome argument. This is analogous to -evperdat in FSL's PALM and to --pvr in FreeSurfer.

Value

An object of class bg_GLM containing some input-specific variables (level, outcome, measure, con.type, contrasts, con.name, alt, alpha, permute, perm.method, part.method, N) in addition to:

DT.Xy

A data table from which the design matrices are created and the outcome variable, for all regions.

X

A named numeric matrix or a 3D array of the design matrix. Rownames are subject IDs, column names are predictor variables, and dimnames along the 3rd dimension are region names (if applicable). This is a 3D array only if outcome != measure and level == 'vertex'.

y

A named numeric matrix of the outcome variable. Rownames are Study IDs and column names are regions. There will be multiple columns only if outcome == measure and level == 'vertex'.

DT

A data table with an entry for each vertex (region) containing statistics of interest

removed.subs

A named integer vector in which the names are subject ID's of those removed due to incomplete data (if any). The integers correspond to the row number in the input covars table.

runX

If outcome != measure and level == 'vertex', this will be a character vector of the regions for which the design matrix is invertible. Otherwise, it is NULL.

runY

Character vector of the regions for which the outcome variable has 0 variability. For example, if level='vertex' and measure='degree', some regions may be disconnected or have the same degree for all subjects.

atlas

Character string of the atlas used (guessed based on the vertex count).

perm

A list containing: null.dist (the null distribution of maximum statistics), thresh (the statistic value corresponding to the 100 \times (1 - \alpha)th% percentile of the null distribution)

The plot method returns a list of ggplot objects (if installed) or writes the plots to a PDF in the current directory named bg_GLM_diagnostics.pdf

A bg_GLM object with the specified row(s) selected or removed from both X and y, and column(s) selected/removed from X

Design matrix

The GLM's design matrix will often be identical to the model matrix associated with lm objects (if “dummy” coding, the default, is used) and is created from the input data.table and arguments passed to brainGraph_GLM_design. The first column should have the name of getOption('bg.subject_id') and its values must match the name graph-level attribute of the input graphs. The covariates table must be supplied even if you provide your own design matrix X. If level='vertex' and outcome == measure, there will be a single design for all regions but a separate model for each region (since the graph measure varies by region). If level='vertex' and outcome != measure, there will be a separate design (and, therefore, a separate model) for each region even though the outcome is the same in all models.

Contrasts and statistics

Either t- or F-contrasts can be calculated (specified by con.type). Multiple t-contrasts can be specified by passing a multi-row matrix to contrasts. Multiple F-contrasts can be specified by passing a list of matrices; all matrices must have the same number of columns. All F-contrasts are necessarily two-sided; t-contrasts can be any direction, but only one can be chosen per function call. If you choose con.type="f", the calculated effect size is represented by the ESS (“extra sum of squares”), the additional variance explained for by the model parameters of interest (as determined by the contrast matrix). The standard error for F-contrasts is the sum of squared errors of the full model.

Non-parametric permutation tests

You can calculate permutations of the data to build a null distribution of the maximum statistic which corrects for multiple testing. To account for complex designs, the design matrix must be partitioned into covariates of interest and nuisance; the default method is the Beckmann method. The default permutation strategy is that of Freedman & Lane (1983), and is the same as that in FSL's randomise. See randomise.

Note

The [ method is used when calculating studentized residuals and other “leave-one-out” diagnostics, and typically should not be called directly by the user.

Author(s)

Christopher G. Watson, [e-mail]

See Also

plot.lm

Other GLM functions: GLM design, GLM fits, mtpc

Other Group analysis functions: Bootstrapping, Mediation, NBS, brainGraph_permute, mtpc

Examples

## Not run: 
conmat <- matrix(c(0, 0, 0, 1), nrow=1)
rownames(conmat) <- 'Control > Patient'

res.lm <- brainGraph_GLM(g[[6]], covars=covars.all[tract == 1],
  measure='strength', contrasts=conmat, alt='greater', permute=TRUE, long=TRUE)

## End(Not run)
## Not run: 
## Save objects and then to multipage PDF
lmPlots <- plot(x)
ggsave('lmPlots.pdf', lmPlots)

## Save all the GLM sub-objects from MTPC analysis
res.mtpc <- mtpc(...)
glmPlots <- lapply(res.mtpc$res.glm, plot, which=1:6)
ml <- marrangeGrob(glmPlots, nrow=1, ncol=1)
ggsave('glmPlots.pdf', ml, width=8.5, height=11)

## End(Not run)