Run mashr Across Multi-Context QTL or GWAS Summary Statistics

End-to-end driver: from `(strong, random, null)` sumstats collections, builds the variant x context Bhat / Shat matrices, estimates the residual correlation (Vhat), and fits the mash model with canonical + PCA + flash + ED covariance components, returning the fitted covariance list and the estimated mixture weights.

Usage

mashPipeline(
  sumStatsList,
  alpha,
  residualCorrelation = NULL,
  residualCorrelationMethod = c("identity", "simple", "simpleSpecific", "corshrink",
    "mle"),
  prior = MashPriorParam(),
  inputScale = c("auto", "beta", "z"),
  mashDataArgs = MashDataOptions(),
  mashArgs = MashOptions(),
  setSeed = 999
)

Arguments

sumStatsList

Named list (or SimpleList) of QtlSumStats or GwasSumStats objects. Required names: "strong" (discovery variants), "random" (random background, the partition the mixture weights are fit on). Optional: "null" (null variants), needed only by the residualCorrelationMethod values that estimate \(\hat V\) from them.

alpha

Numeric (length 1). Variance-stabilising-transform exponent forwarded to mashr::mash_set_data(). Use alpha = 0 on the BETA scale, alpha = 1 on the Z scale.

residualCorrelation

Optional pre-computed residual correlation matrix (Vhat). When supplied, it is used as-is: residualCorrelationMethod is not consulted, and the "random" slot of sumStatsList becomes optional (the function does not need it for anything else). Useful when Vhat was estimated previously on a larger reference and shipped as a static artefact (the legacy MWE pattern).

residualCorrelationMethod

How to estimate \(\hat V\) when residualCorrelation is not supplied; forwarded to mashResidualCorrelation, which is where each estimator is described.

"identity" (the default) takes the residual correlation to be the identity, needs no extra partition, and never depends on which partitions were supplied. It is the safe default rather than the best one: it assumes conditions share no residual correlation, which overlapping-sample designs – the usual multi-context QTL case, where the same donors are measured in every context – violate. Supplying a "null" partition while leaving this at "identity" reports that the partition is unused, since that combination is more often an oversight than an intent.

The estimators differ in what they require: "simple", "simpleSpecific" and "corshrink" need a "null" entry; "mle" needs "random" plus a supplied priorCovariances to refine against. A named method whose requirement is unmet is a hard error, not a silent fallback.

prior

How the prior covariance matrices are obtained, built with MashPriorParam: priorCovariances supplies them outright (short-circuiting the rest), otherwise components chooses which to build, engine how the data-driven ones are refined, and nPcs parametrises the pca component. Forwarded whole to mashPriorCovariances.

inputScale

One of "auto" (default), "beta", "z". Controls which (Bhat, Shat) pair is extracted from each sumstats entry:

"beta": Bhat = BETA, Shat = SE – the standard effect-size scale mashr was designed around. Requires every entry to carry BETA + SE mcols.
"z": Bhat = Z, Shat = 1 – z-score scale. Requires Z.
"auto": Use BETA + SE when every entry carries both; otherwise fall back to (Z, 1) when every entry carries Z. Mixed inputs (some entries missing BETA, others missing Z) are a hard error.

alpha should be chosen consistently with the resolved scale: typically alpha = 0 for beta, alpha = 1 for z.

mashDataArgs

Extra arguments for mashr::mash_set_data(), built with MashDataOptions – for example zero_Bhat_Shat_reset or zero_Shat_reset. Bhat, Shat, alpha and V are supplied by pecotmr and are refused by the constructor.

mashArgs

Extra arguments for mashr::mash(), built with MashOptions – for example nullweight, optmethod or verbose. data, Ulist, outputlevel and seed are owned by pecotmr and are refused by the constructor.

setSeed

Integer. RNG seed for reproducibility of mashr::cov_flash and mashr::cov_ed. Default 999.

Value

A list with elements U (the combined covariance list: canonical + PCA + flash + ED) and w (the estimated mixture weights).

Examples

data(qtlSumStatsMulticontextExample)
ss <- qtlSumStatsMulticontextExample
sumStatsList <- list(strong = ss, random = ss)
mashPipeline(sumStatsList, alpha = 0, prior = MashPriorParam(nPcs = 2L))
#> Adding factor 1 to flash object...
#> Adding factor 2 to flash object...
#> Adding factor 3 to flash object...
#> Factor doesn't significantly increase objective and won't be added.
#> Wrapping up...
#> Done.
#> Backfitting 2 factors (tolerance: 8.94e-06)...
#>   Difference between iterations is within 1.0e+00...
#>   Difference between iterations is within 1.0e-01...
#>   Difference between iterations is within 1.0e-02...
#>   Difference between iterations is within 1.0e-03...
#>   Difference between iterations is within 1.0e-04...
#> Wrapping up...
#> Done.
#> Adding factor 1 to flash object...
#> Adding factor 2 to flash object...
#> Adding factor 3 to flash object...
#> Factor doesn't significantly increase objective and won't be added.
#> Wrapping up...
#> Done.
#> Backfitting 2 factors (tolerance: 8.94e-06)...
#>   Difference between iterations is within 1.0e+00...
#>   Difference between iterations is within 1.0e-01...
#>   Difference between iterations is within 1.0e-02...
#>   Difference between iterations is within 1.0e-03...
#> Wrapping up...
#> Done.
#>  - Computing 200 x 273 likelihood matrix.
#>  - Likelihood calculations took 0.02 seconds.
#>  - Fitting model with 273 mixture components.
#>  - Model fitting took 0.41 seconds.
#> $U
#> $U$ED_PCA_1
#>             brain     blood     muscle
#> brain  0.15289673 0.1351045 0.09075052
#> blood  0.13510450 0.2928071 0.14918350
#> muscle 0.09075052 0.1491835 0.17091815
#> 
#> $U$ED_PCA_2
#>                brain         blood        muscle
#> brain   7.071112e-02  3.869435e-06 -6.163860e-06
#> blood   3.869435e-06  7.074430e-02 -5.356393e-05
#> muscle -6.163860e-06 -5.356393e-05  7.079600e-02
#> 
#> $U$ED_tPCA
#>              brain       blood      muscle
#> brain  0.072756163 0.003235763 0.002527583
#> blood  0.003235763 0.075853371 0.003947439
#> muscle 0.002527583 0.003947439 0.073942083
#> 
#> $U$ED_tFLASH_default
#>              brain       blood      muscle
#> brain  0.071877036 0.001950940 0.002284472
#> blood  0.001950940 0.073990396 0.003889138
#> muscle 0.002284472 0.003889138 0.075466277
#> 
#> $U$ED_FLASH_default_1
#>            brain     blood    muscle
#> brain  0.1684507 0.1420732 0.1028400
#> blood  0.1420732 0.2772258 0.1494864
#> muscle 0.1028400 0.1494864 0.1789167
#> 
#> $U$ED_FLASH_default_2
#>                brain         blood        muscle
#> brain   7.072856e-02  1.459131e-05 -2.837483e-05
#> blood   1.459131e-05  7.072258e-02 -2.314856e-05
#> muscle -2.837483e-05 -2.314856e-05  7.075569e-02
#> 
#> $U$ED_tFLASH_nonneg
#>              brain       blood      muscle
#> brain  0.072149086 0.002133816 0.002382316
#> blood  0.002133816 0.073876114 0.003535475
#> muscle 0.002382316 0.003535475 0.074867554
#> 
#> $U$ED_FLASH_nonneg_1
#>             brain     blood     muscle
#> brain  0.16797922 0.1438778 0.09877292
#> blood  0.14387777 0.2835319 0.14610302
#> muscle 0.09877292 0.1461030 0.17101125
#> 
#> $U$ED_FLASH_nonneg_2
#>               brain        blood       muscle
#> brain  7.071068e-02 2.264767e-09 2.813069e-07
#> blood  2.264767e-09 7.071070e-02 2.422564e-06
#> muscle 2.813069e-07 2.422564e-06 7.101158e-02
#> 
#> $U$identity
#>      [,1] [,2] [,3]
#> [1,]    1    0    0
#> [2,]    0    1    0
#> [3,]    0    0    1
#> 
#> $U$brain
#>      [,1] [,2] [,3]
#> [1,]    1    0    0
#> [2,]    0    0    0
#> [3,]    0    0    0
#> 
#> $U$blood
#>      [,1] [,2] [,3]
#> [1,]    0    0    0
#> [2,]    0    1    0
#> [3,]    0    0    0
#> 
#> $U$muscle
#>      [,1] [,2] [,3]
#> [1,]    0    0    0
#> [2,]    0    0    0
#> [3,]    0    0    1
#> 
#> $U$equal_effects
#>      [,1] [,2] [,3]
#> [1,]    1    1    1
#> [2,]    1    1    1
#> [3,]    1    1    1
#> 
#> $U$simple_het_1
#>      [,1] [,2] [,3]
#> [1,] 1.00 0.25 0.25
#> [2,] 0.25 1.00 0.25
#> [3,] 0.25 0.25 1.00
#> 
#> $U$simple_het_2
#>      [,1] [,2] [,3]
#> [1,]  1.0  0.5  0.5
#> [2,]  0.5  1.0  0.5
#> [3,]  0.5  0.5  1.0
#> 
#> $U$simple_het_3
#>      [,1] [,2] [,3]
#> [1,] 1.00 0.75 0.75
#> [2,] 0.75 1.00 0.75
#> [3,] 0.75 0.75 1.00
#> 
#> 
#> $w
#>               null           ED_PCA_1           ED_PCA_2            ED_tPCA 
#>         0.67084039         0.00000000         0.00000000         0.00000000 
#>  ED_tFLASH_default ED_FLASH_default_1 ED_FLASH_default_2   ED_tFLASH_nonneg 
#>         0.00000000         0.00000000         0.00000000         0.00000000 
#>  ED_FLASH_nonneg_1  ED_FLASH_nonneg_2           identity              brain 
#>         0.00000000         0.00000000         0.00000000         0.00000000 
#>              blood             muscle      equal_effects       simple_het_1 
#>         0.00000000         0.01470376         0.31445585         0.00000000 
#>       simple_het_2       simple_het_3 
#>         0.00000000         0.00000000 
#>