Learning TWAS weights with pecotmr

Overview

TWAS weights are per-variant coefficients that predict a molecular phenotype (gene expression, splicing, protein abundance) from genotype. Once learned, the weights are combined with GWAS summary statistics to compute per-gene TWAS Z-scores (covered in the TWAS Z-score + causal inference vignette).

twasWeightsPipeline() is a single that accepts multiple input types. The output is always a TwasWeights collection (DFrame subclass keyed by (study, context, trait, method) with per-tuple TwasWeightsEntry payloads).

Input class	Methods supported
`QtlDataset`	Univariate: LASSO, elastic net, mr.ash, MCP, SCAD, L0Learn, Bayesian alphabet, DPR. Multivariate: mr.mash, mvsusie
`MultiStudyQtlDataset`	Iterates over embedded studies; same methods as `QtlDataset`
`QtlSumStats`	RSS-only: LASSO, mr.ash, MCP, SCAD, L0Learn, DPR, PRS-CS, P+T. Multivariate: mr.mash, mvsusie

library(pecotmr)

Bundled inputs

data(qtl_dataset_example,
     qtl_sumstats_example,
     multi_study_qtl_dataset_example)

Individual-level weights

The simplest individual-level call learns a single regression-based weight set from a QtlDataset. Cross-validation is enabled by default (cvFolds = 5). Like fineMappingPipeline(), you need to tell it which genotype window to extract — cisWindow (per trait) is the most common choice.

Fine-mapping methods (susie, susieInf, susieAsh, mvsusie, fsusie) are not re-fit by twasWeightsPipeline() - instead run fine-mapping models with fineMappingPipeline() first and pass the result via fineMappingResult = … (see the next section).

tw <- twasWeightsPipeline(qtl_dataset_example,
                           methods   = "lasso",
                           cisWindow = 1e6)
tw

## TwasWeights: 1 entries
##   1 studies, 1 contexts, 1 traits, 1 methods
##   LD sketch: NULL (individual-level fit)

Extract the per-variant weights for one tuple:

entry <- getTwasWeights(tw, study = "study1", context = "brain",
                         trait = "ENSG_example", method = "lasso")
head(getWeights(entry))

## chr22:14850625:T:G chr22:14870204:T:C chr22:14878387:G:A chr22:14880040:A:G 
##                  0                  0                  0                  0 
## chr22:14884399:T:C chr22:15063831:A:G 
##                  0                  0

CV performance:

getCvResult(entry)

## $samplePartition
##      Sample Fold
## 1   NA12005    1
## 2   NA11919    1
## 3   NA12842    1
## 4   NA12843    1
## 5   NA10836    1
## 6   NA10831    1
## 7   NA12145    1
## 8   NA12761    1
## 9   NA12286    1
## 10  NA07349    1
## 11  NA12718    1
## 12  NA12344    1
## 13  NA12146    1
## 14  NA07029    1
## 15  NA12760    1
## 16  NA11917    1
## 17  NA11893    1
## 18  NA10853    1
## 19  NA12546    1
## 20  NA07000    1
## 21  NA12751    1
## 22  NA11881    1
## 23  NA10863    1
## 24  NA12814    1
## 25  NA07022    1
## 26  NA12872    1
## 27  NA12818    1
## 28  NA10861    1
## 29  NA12282    1
## 30  NA12336    1
## 31  NA11930    1
## 32  NA10837    1
## 33  NA12045    1
## 34  NA12044    2
## 35  NA12239    2
## 36  NA12890    2
## 37  NA10839    2
## 38  NA11882    2
## 39  NA07045    2
## 40  NA10859    2
## 41  NA11831    2
## 42  NA12347    2
## 43  NA07051    2
## 44  NA12489    2
## 45  NA12287    2
## 46  NA12234    2
## 47  NA12400    2
## 48  NA12753    2
## 49  NA06993    2
## 50  NA11830    2
## 51  NA11892    2
## 52  NA12828    2
## 53  NA12707    2
## 54  NA07347    2
## 55  NA12740    2
## 56  NA12043    2
## 57  NA12283    2
## 58  NA12057    2
## 59  NA12873    2
## 60  NA11829    2
## 61  NA12812    2
## 62  NA12817    2
## 63  NA12801    2
## 64  NA12864    2
## 65  NA12249    2
## 66  NA12889    2
## 67  NA10838    3
## 68  NA06997    3
## 69  NA10835    3
## 70  NA11843    3
## 71  NA12777    3
## 72  NA12248    3
## 73  NA10856    3
## 74  NA12778    3
## 75  NA12750    3
## 76  NA12763    3
## 77  NA12056    3
## 78  NA06994    3
## 79  NA12413    3
## 80  NA10845    3
## 81  NA12827    3
## 82  NA12273    3
## 83  NA07037    3
## 84  NA12383    3
## 85  NA12341    3
## 86  NA12830    3
## 87  NA12708    3
## 88  NA12340    3
## 89  NA12343    3
## 90  NA12144    3
## 91  NA12348    3
## 92  NA12716    3
## 93  NA12386    3
## 94  NA10843    3
## 95  NA06984    3
## 96  NA12264    3
## 97  NA10850    3
## 98  NA12739    3
## 99  NA10846    3
## 100 NA12877    4
## 101 NA12272    4
## 102 NA12815    4
## 103 NA06985    4
## 104 NA12155    4
## 105 NA12762    4
## 106 NA06986    4
## 107 NA12376    4
## 108 NA10854    4
## 109 NA12802    4
## 110 NA06995    4
## 111 NA12829    4
## 112 NA12875    4
## 113 NA12399    4
## 114 NA10847    4
## 115 NA12813    4
## 116 NA07014    4
## 117 NA07357    4
## 118 NA07435    4
## 119 NA12775    4
## 120 NA12878    4
## 121 NA11995    4
## 122 NA12749    4
## 123 NA11839    4
## 124 NA07031    4
## 125 NA11994    4
## 126 NA11840    4
## 127 NA12752    4
## 128 NA06991    4
## 129 NA10864    4
## 130 NA12156    4
## 131 NA12006    4
## 132 NA10830    4
## 133 NA07346    5
## 134 NA12865    5
## 135 NA12275    5
## 136 NA11894    5
## 137 NA12767    5
## 138 NA07056    5
## 139 NA07348    5
## 140 NA12832    5
## 141 NA07055    5
## 142 NA12335    5
## 143 NA11891    5
## 144 NA12375    5
## 145 NA11920    5
## 146 NA12748    5
## 147 NA12776    5
## 148 NA10852    5
## 149 NA11832    5
## 150 NA12892    5
## 151 NA10840    5
## 152 NA07345    5
## 153 NA10855    5
## 154 NA11931    5
## 155 NA11918    5
## 156 NA11993    5
## 157 NA12874    5
## 158 NA12891    5
## 159 NA06989    5
## 160 NA12154    5
## 161 NA12003    5
## 162 NA11992    5
## 163 NA12342    5
## 164 NA12766    5
## 165 NA10865    5
## 
## $predictions
##      NA06989      NA11891      NA11843      NA12341      NA12739      NA10850 
## -0.049846523  0.071101616  0.000000000  0.000000000  0.000000000  0.000000000 
##      NA06984      NA12877      NA12275      NA06986      NA12272      NA10845 
##  0.000000000 -0.173111627  0.055076902  0.153867473 -0.011121075  0.000000000 
##      NA10852      NA07051      NA12400      NA12344      NA12777      NA12287 
## -0.050745478 -0.067440733  0.142604947  0.369153869  0.000000000 -0.045874154 
##      NA10837      NA12383      NA12340      NA12708      NA12273      NA11892 
##  0.025284031  0.000000000  0.000000000  0.000000000  0.000000000 -0.069997549 
##      NA12546      NA12843      NA12766      NA12348      NA12817      NA10840 
## -0.146018540 -0.241263924 -0.049865421  0.000000000 -0.082630013 -0.035957498 
##      NA06997      NA11917      NA12718      NA12282      NA11920      NA12776 
##  0.000000000 -0.117916165 -0.050317441 -0.253274971  0.056337923 -0.035570735 
##      NA12283      NA07435      NA12828      NA07045      NA07031      NA12336 
## -0.084527847 -0.030963247 -0.083894490 -0.051725971 -0.048466511 -0.261175909 
##      NA07349      NA12827      NA12375      NA12343      NA12335      NA12778 
## -0.284366433  0.000000000 -0.049903000  0.000000000  0.057216412  0.000000000 
##      NA12832      NA11930      NA12890      NA07037      NA07347      NA12829 
##  0.056966310  0.034463620  0.133021411  0.000000000 -0.074719952 -0.203697418 
##      NA12749      NA11894      NA12286      NA10865      NA10864      NA10853 
## -0.230264107 -0.034478174 -0.300843685  0.071803864 -0.091158897  0.376585622 
##      NA11918      NA12830      NA12818      NA10836      NA11893      NA11919 
##  0.055161238  0.000000000 -0.242491863  0.118303283  0.572821006  0.148243677 
##      NA12489      NA12399      NA12413      NA10843      NA12842      NA12347 
## -0.077314964  0.049445481  0.000000000  0.000000000  0.062382803  0.369890590 
##      NA07346      NA12775      NA07014      NA12767      NA12889      NA12386 
## -0.048693439 -0.010530936 -0.250633007 -0.033740477  0.143913300  0.000000000 
##      NA06995      NA12376      NA12342      NA12748      NA11931      NA12045 
## -0.081141571  0.050337080  0.161343431  0.072509753 -0.050462020  0.048452362 
##      NA12750      NA11831      NA12146      NA11882      NA07056      NA12707 
##  0.000000000 -0.061883388  0.333170268  0.156807277  0.056531721 -0.067586148 
##      NA12154      NA12753      NA11839      NA10859      NA12875      NA07348 
##  0.055500400 -0.055547196 -0.052454445  0.160684270 -0.019321064 -0.034752152 
##      NA12156      NA12044      NA11992      NA11829      NA12239      NA12762 
## -0.255985044 -0.071319524 -0.050392820 -0.057446110 -0.064590106  0.145925671 
##      NA12716      NA12878      NA10856      NA12874      NA12760      NA06985 
##  0.000000000 -0.229220988  0.000000000 -0.034969029  0.274506212 -0.157753584 
##      NA12003      NA10835      NA07022      NA12813      NA10839      NA07055 
## -0.050512630  0.000000000 -0.104197463  0.132423240  0.139063582  0.070882514 
##      NA12056      NA10863      NA12145      NA12814      NA10847      NA12006 
##  0.000000000  0.112059304 -0.041282450  0.323978451  0.116310179  0.298310330 
##      NA12763      NA07357      NA12144      NA10831      NA07000      NA11832 
##  0.000000000 -0.172491997  0.000000000 -0.044011218 -0.035746359 -0.036139064 
##      NA06991      NA11840      NA12802      NA12761      NA10830      NA10855 
## -0.228693356 -0.146148277  0.240825549 -0.245041556 -0.263423707 -0.035585131 
##      NA06994      NA11993      NA11995      NA12891      NA12864      NA12751 
##  0.000000000 -0.034642781 -0.072197205  0.071112478 -0.079599677 -0.094899456 
##      NA10861      NA12005      NA12234      NA07345      NA07029      NA12892 
## -0.296682755 -0.256612254 -0.054552829 -0.034484954  0.537202025 -0.036115202 
##      NA12248      NA10846      NA12801      NA12872      NA12155      NA06993 
##  0.000000000  0.000000000 -0.073877474 -0.004869147 -0.009002766 -0.069321802 
##      NA11830      NA10838      NA12249      NA12057      NA12812      NA11881 
## -0.053694877  0.000000000  0.104125173 -0.066953967 -0.084943961 -0.254625615 
##      NA11994      NA12873      NA12815      NA12740      NA12752      NA12043 
## -0.124120295 -0.072020180  0.273167259 -0.069612209 -0.220653149 -0.057500318 
##      NA12264      NA10854      NA12865 
##  0.000000000  0.020780484 -0.049812528 
## 
## $metrics
##         corr          rsq      adj_rsq         pval         RMSE          MAE 
##  0.051390763  0.002641010 -0.003477756  0.512119380  0.999951442  0.790754739 
## 
## $foldFits
## NULL

The entry’s variantIds slot lists the LD-aligned variant set the weights are defined on:

length(getVariantIds(entry))

## [1] 198

Including a fine-mapping susie fit in the TWAS ensemble

The posterior effect estimates of SuSiE fine-mapping models are themselves a set of per-variant weight estimates. When you pass an existing FineMappingResult to twasWeightsPipeline(), the trimmed susie fit for each matching (study, context, trait) tuple is added to the ensemble as an additional weights row instead of being re-fit.

fmr <- fineMappingPipeline(qtl_dataset_example, methods = "susie",
                            cisWindow = 1e6)
tw2 <- twasWeightsPipeline(qtl_dataset_example,
                            methods            = c("susie", "lasso"),
                            cisWindow          = 1e6,
                            fineMappingResult  = fmr)

Multi-study weights

msTw <- twasWeightsPipeline(multi_study_qtl_dataset_example,
                             methods   = "lasso",
                             cisWindow = 1e6)
table(msTw$study)

## 
## study1 study2 
##      1      1

The call for iterating over the studies of a MultiStudyQtlDataset is identical to the call for a single QtlDataset.

Multiple weight methods at once

Pass a character vector to fit several methods on the same fold split and return them as separate (method) rows in the collection. Fine-mapping methods (susie, susieInf, susieAsh, mvsusie) can only be included if their results are present in the object passed to the fineMappingResult argument:

# TWAS-regression only — no fineMappingResult needed.
twasWeightsPipeline(
  qtl_dataset_example,
  methods = c("lasso", "enet", "ridge", "mrash"))

# Add a fine-mapping susie row by providing the FineMappingResult.
fmr <- fineMappingPipeline(qtl_dataset_example, methods = "susie",
                            cisWindow = 1e6)
twasWeightsPipeline(
  qtl_dataset_example,
  methods           = c("susie", "lasso", "enet", "ridge", "mrash"),
  cisWindow         = 1e6,
  fineMappingResult = fmr)

RSS / sumstats weights

twSs <- twasWeightsPipeline(qtl_sumstats_example, methods = "lasso")
twSs

## TwasWeights: 1 entries
##   1 studies, 1 contexts, 1 traits, 1 methods
##   LD sketch: plink1 @ pecotmr://extdata/toy_canonical

The RSS path uses the ldSketch GenotypeHandle inside the QtlSumStats collection to compute LD as needed. The same

Multivariate (multi-context) weights

When you have multiple contexts for the same trait (e.g. multi-tissue expression), pass methods = "mrmash" to do a joint multivariate fit:

twasWeightsPipeline(
  qtl_dataset_example,
  methods  = "mrmash",
  contexts = c("brain", "liver"))

For an explicit cross-context joint fit driven by a jointSpecification:

twasWeightsPipeline(
  multi_study_qtl_dataset_example,
  methods            = "mrmash",
  jointSpecification = list(axis = "context",
                             contexts = c("brain", "liver")))

Common parameters

twasWeightsPipeline(
  qtl_dataset_example,
  methods             = "susie",
  contexts            = "brain",
  traitId             = "ENSG_example",
  region              = "chr22:25000000-26000000",
  cisWindow           = 5e5,
  cvFolds             = 5,
  samplePartition     = NULL,
  maxCvVariants       = -1,
  cvThreads           = 1,
  ensemble            = TRUE,
  ensembleR2Threshold = 0.01,
  ensembleSolver      = "quadprog",
  estimatePi          = TRUE,
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize  = NULL,
  dataType            = NULL,
  naAction            = "drop")

ensemble = TRUE adds an additional ensembleWeights row to the collection — a weighted combination of the individual methods’ CV predictions filterd by ensembleR2Threshold.
naAction is forwarded to getResidualizedPhenotypes() (see the fine-mapping vignette for semantics).

Reading the result

TwasWeights is a DFrame subclass keyed by the 4-tuple (study, context, trait, method). The per-tuple payload is a TwasWeightsEntry:

entry <- tw$entry[[1L]]
class(entry)

## [1] "TwasWeightsEntry"
## attr(,"package")
## [1] "pecotmr"

slotNames(entry)

## [1] "variantIds"   "weights"      "fits"         "cvResult"     "standardized"
## [6] "dataType"

Each entry exposes:

weights — per-variant coefficients (named numeric vector or matrix for multivariate methods)
variantIds — variant IDs the weights are aligned to
cvResult — list with rsq, r, predicted values, etc. (access with getCvResult())
standardized — whether weights are on the standardized (y ~ scale(X)) or original scale
dataType — string tag carried through for reporting (e.g. "expression", "splicing")
fit — the full fit object when the user requested retainFit = TRUE

Next steps

Combine the learned weights with a GWAS via causalInferencePipeline to compute per-gene TWAS Z-scores.

pecotmr authors

2026-07-30