Package 'CAMeRa'

Description

CAMERA estimates joint causal effect in multiple ancestries and detects pleiotropy via the zero relevance model.

Author(s)

Maintainer: Gibran Hemani g.hemani@bristol.ac.uk (ORCID)

Authors:

• Gibran Hemani g.hemani@bristol.ac.uk (ORCID)

• Yoonsu Cho yoonsu.cho@bristol.ac.uk

• Tom Palmer remlapmot@hotmail.com (ORCID)

Other contributors:

• Amy Mason am2609@medschl.cam.ac.uk (ORCID) [contributor]

• Mercy Kimani [contributor]

See Also

Useful links:

• https://github.com/MRCIEU/CAMERA

• https://mrcieu.github.io/CAMERA/

• Report bugs at https://github.com/MRCIEU/CAMERA/issues/

Description

A simple wrapper function. Using a summary set, identify set of instruments for the traits, and perform SEM MR to test the association across the population.

Public fields

Methods

Public methods

• CAMERA$import()

• CAMERA$assign()

• CAMERA$import_from_local()

• CAMERA$new()

• CAMERA$instrument_heterogeneity()

• CAMERA$estimate_instrument_specificity()

• CAMERA$replication_evaluation()

• CAMERA$check_phenotypes()

• CAMERA$cross_estimate()

• CAMERA$plot_cross_estimate()

• CAMERA$extract_instruments()

• CAMERA$extract_instrument_regions()

• CAMERA$scan_regional_instruments()

• CAMERA$plot_regional_instruments_maxz()

• CAMERA$regional_ld_matrices()

• CAMERA$susie_finemap_regions()

• CAMERA$paintor_finemap_regions()

• CAMERA$MsCAVIAR_finemap_regions()

• CAMERA$fema_regional_instruments()

• CAMERA$plot_regional_instruments()

• CAMERA$get_metadata()

• CAMERA$estimate_instrument_heterogeneity_per_variant()

• CAMERA$mrgxe()

• CAMERA$mrgxe_plot()

• CAMERA$mrgxe_plot_variant()

• CAMERA$make_outcome_data()

• CAMERA$make_outcome_local()

• CAMERA$harmonise()

• CAMERA$set_summary()

• CAMERA$pleiotropy()

• CAMERA$plot_pleiotropy()

• CAMERA$plot_pleiotropy_heterogeneity()

• CAMERA$perform_basic_sem()

• CAMERA$runsem()

• CAMERA$standardise_data()

• CAMERA$clone()

CAMERA$import()

Migrate the results from a previous CAMERA

Usage

CAMERA$import(x)

Arguments

CAMERA$assign()

Assign values to fields of the CAMERA object

Usage

CAMERA$assign(...)

Arguments

CAMERA$import_from_local()

Import instrument and outcome data from local summary statistics, e.g. as organised by CAMERA_local

Usage

CAMERA$import_from_local(
  instrument_raw,
  instrument_outcome,
  instrument_regions,
  instrument_outcome_regions,
  exposure_ids,
  outcome_ids,
  pops,
  ...
)

Arguments

CAMERA$new()

Create a new dataset and initialise an R interface

Usage

CAMERA$new(
  exposure_ids = NULL,
  outcome_ids = NULL,
  pops = NULL,
  bfiles = NULL,
  plink = NULL,
  radius = NULL,
  clump_pop = NULL,
  x = NULL
)

Arguments

CAMERA$instrument_heterogeneity()

The function evaluates heterogeneity in the association of selected instruments and the exposure/outcome between the populations. Heterogeneity (Q statistics) is calcuated based on an IVW or simple MODE MR estimator. The instruments can be identified using "Raw", "MaxZ", or fine-mapping (Susie, PAINTOR) methods.

Usage

CAMERA$instrument_heterogeneity(
  instrument = self$instrument_raw,
  alpha = "bonferroni",
  method = "ivw",
  outlier_removal = FALSE
)

Arguments

Returns

Data frame with one row for each ordered pair of populations, with columns:

• Reference, Replication: IDs of the reference and replication datasets

• nsnp: number of instruments significant in the reference dataset that are also present in the replication dataset

• agreement: slope of the regression of the replication associations on the reference associations

• se, pval: standard error of agreement and p-value for the test of the null hypothesis that the slope is 0 (i.e. no association between the instrument associations in the two populations)

• Q, Q_pval ("ivw" only): Cochran's Q statistic and its p-value for the null hypothesis that all instruments share the same slope, i.e. no heterogeneity in the agreement between populations

• I2 ("ivw" only): the proportion of the variation in the ratio of the associations that is due to heterogeneity rather than chance, calculated as (Q - nsnp) / Q

CAMERA$estimate_instrument_specificity()

The function estimates what fraction of the instuments is expected to be replicated across the populations under the hypothesis that the effect estimates are the same.

Usage

CAMERA$estimate_instrument_specificity(
  instrument,
  alpha = "bonferroni",
  winnerscurse = FALSE
)

Arguments

Details

For each pair of populations, the instruments that are significant (p < alpha) in the discovery population are compared with their associations in the replication population. Following Okbay et al. (2016), under the hypothesis that the instruments have the same effects in both populations, the expected number of instruments with the same sign, and the expected number with p < alpha, in the replication population are calculated taking account of the precision of the replication associations. These are compared with the observed numbers.

Returns

Data frame, also stored in x$instrument_specificity_summary, with columns:

• discovery, replication: IDs of the discovery and replication datasets

• metric: "Sign" (the instrument has the same sign in both populations) or "P-value" (the instrument has p < alpha in the replication population)

• nsnp: number of instruments compared

• datum, value: the "Expected" and "Observed" number of instruments meeting metric

• pdiff: p-value from a binomial test of the null hypothesis that the observed number equals the expected number. A small p-value suggests the instruments replicate less (or more) than expected if their effects were the same in both populations.

Per variant results are stored in x$instrument_specificity, including the expected probabilities of sign agreement (sign) and replication (sig), and distinct, which flags instruments that were expected to replicate but did not (sig > 0.8 and replication p > 0.1), or were expected to have the same sign but did not (sign > 0.8).

CAMERA$replication_evaluation()

The function explains what contributes to the replication of gene-trait association between the populations, considering LD structure.

Usage

CAMERA$replication_evaluation(
  instrument = self$instrument_raw,
  ld = self$ld_matrices
)

Arguments

Returns

Table of the regression result

CAMERA$check_phenotypes()

This function evaluates how competitable genetic associations in population 1 are with those in population 2. The function checks whether 1) the chosen IDs for the exposure or outcome can be used for the further steps and 2) the units for the genetic associations are comparable between populations.

Usage

CAMERA$check_phenotypes(ids = self$exposure_ids)

Arguments

Returns

Table of the result.

CAMERA$cross_estimate()

This method performs a IVW analysis on the harmonised data. It fits two linear models, one considering all populations and another considering each population separately. It then performs a fixed effects meta-analysis to estimate the heterogeneity across different populations. The results are stored in the mrres attribute of the CAMERA object.

Usage

CAMERA$cross_estimate(dat = self$harmonised_dat)

Arguments

Returns

Data frame, also stored in x$mrres, with one row for the estimate across all populations (pops == "All") and one row for each population, with columns:

• pops: population

• Estimate, ⁠Std. Error⁠, ⁠t value⁠, ⁠Pr(>|t|)⁠: the IVW MR estimate, i.e. the weighted regression of the SNP-outcome associations on the SNP-exposure associations through the origin with weights 1 / se.y^2, its standard error, t statistic and p-value

• Qj, Qjpval, Qdf: for each population, the contribution of its estimate to the heterogeneity between populations and its p-value (1 degree of freedom), from a fixed effects meta analysis of the population estimates; a small p-value suggests the estimate in that population differs from the others. For the "All" row these are Cochran's Q statistic across all populations, its p-value (null hypothesis: the same causal effect in all populations) and its degrees of freedom.

CAMERA$plot_cross_estimate()

Plot the results from cross_estimate

Usage

CAMERA$plot_cross_estimate(est = self$mrres, qj_alpha = 0.05)

Arguments

Returns

Plot

CAMERA$extract_instruments()

This function searches for GWAS significant SNPs (P < 5E-8) for a specified set of the exposures. This method is equivalant to the instrumnet extraction method for Multivariable MR. Reference here: https://mrcieu.github.io/TwoSampleMR/reference/mv_extract_exposures.html.

Usage

CAMERA$extract_instruments(
  exposure_ids = self$exposure_ids,
  harmonise_strictness = 1,
  ...
)

Arguments

Returns

Data frame in x$instrument_raw

CAMERA$extract_instrument_regions()

This function extract genomic regions around each instrument (e.g. 50kb) obtained from x$extract_instruments().

Usage

CAMERA$extract_instrument_regions(
  radius = self$radius,
  instrument_raw = self$instrument_raw,
  exposure_ids = self$exposure_ids
)

Arguments

Returns

Data frame in x$instrument_regions

CAMERA$scan_regional_instruments()

The function searches for a SNP that is best associated across the poupulations within the identified regions by using x$extract_instrument_regions().

Usage

CAMERA$scan_regional_instruments(
  instrument_raw = self$instrument_raw,
  instrument_regions = self$instrument_regions
)

Arguments

Returns

List of z scores for the chosen SNPs in x$instrument_region_zscores. Data frame in x$instrument_maxz

CAMERA$plot_regional_instruments_maxz()

The function draws a plot shows how CAMERA selected the instruments for the exposure from the selected genomic regions.

Usage

CAMERA$plot_regional_instruments_maxz(
  instrument_region_zscores = self$instrument_region_zscores,
  instruments = self$instrument_raw,
  region = 1:min(10, nrow(instruments)),
  comparison = FALSE
)

Arguments

Returns

Plot

CAMERA$regional_ld_matrices()

Generate LD matrices for instrument regions. If we want to do fine mapping we need to get an LD matrix for the whole region (for each population) We then need to harmonise the LD matrix to the summary data, and the summary datasets to each other The function obtains an LD matrix for the selected genomic regions.

Usage

CAMERA$regional_ld_matrices(
  instrument_regions = self$instrument_regions,
  bfiles = self$bfiles,
  pops = self$pops,
  plink = self$plink
)

Arguments

Returns

Data frame of LD matrix (x$ld_matrices)

CAMERA$susie_finemap_regions()

Fine-mapping using susieR (https://github.com/stephenslab/susieR) to extract instruments for the exposure for multiple populations. The function identifies credible sets that overlap between the populations and determine the best SNP in a genomic region to be used as instrument.

Usage

CAMERA$susie_finemap_regions(
  dat = self$instrument_regions,
  ld = self$ld_matrices
)

Arguments

Returns

Result from susieR in x$susie_results. Data frame in x$instrument_susie

CAMERA$paintor_finemap_regions()

Fine-mapping using PAINTOR (https://github.com/gkichaev/PAINTOR_V3.0) to extract instruments for the exposure for multiple populations. The function chooses the SNP with highest posterior probability and associations in each exposure.

Usage

CAMERA$paintor_finemap_regions(
  region = self$instrument_regions,
  ld = self$ld_matrices,
  PAINTOR = "PAINTOR",
  workdir = tempdir()
)

Arguments

Returns

Result from PAINTOR in x$paintor_results. Data frame in x$instrument_paintor

CAMERA$MsCAVIAR_finemap_regions()

Fine-mapping using MsCAVIAR (https://github.com/nlapier2/MsCAVIAR) to extract instruments for the exposure for multiple populations.

Usage

CAMERA$MsCAVIAR_finemap_regions(
  region = self$instrument_regions,
  ld = self$ld_matrices,
  MsCAVIAR = "MsCAVIAR",
  workdir = tempdir()
)

Arguments

Returns

Result from MsCAVIAR in x$mscaviar_results. Data frame in x$instrument_mscaviar

CAMERA$fema_regional_instruments()

Identify the best variant for each region by meta-analysing the associations across the populations

Usage

CAMERA$fema_regional_instruments(
  method = "fema",
  instrument_regions = self$instrument_regions,
  instrument_raw = self$instrument_raw,
  n = self$exposure_metadata$sample_size
)

Arguments

Returns

Data frame of the selected instruments, also stored in x$instrument_fema

CAMERA$plot_regional_instruments()

Plot the associations in a region for each population and for the meta-analysis

Usage

CAMERA$plot_regional_instruments(
  region,
  instrument_regions = self$instrument_regions,
  meta_analysis_regions = self$instrument_fema_regions
)

Arguments

Returns

Plot

CAMERA$get_metadata()

Get metadata for the exposures and outcomes from the OpenGWAS API

Usage

CAMERA$get_metadata(
  exposure_ids = self$exposure_ids,
  outcome_ids = self$outcome_ids
)

Arguments

Returns

List of the exposure and outcome metadata, also stored in x$exposure_metadata and x$outcome_metadata

CAMERA$estimate_instrument_heterogeneity_per_variant()

Test for heterogeneity of effect estimates between populations. For each SNP this function will provide a Cochran's Q test statistic - a measure of heterogeneity of effect sizes between populations. A low p-value means high heterogeneity. In addition, for every SNP it gives a per population p-value - this can be interpreted as asking for each SNP is a particular giving an outlier estimate.

Usage

CAMERA$estimate_instrument_heterogeneity_per_variant(dat = self$harmonised_dat)

Arguments

Returns

Data frame of the Q statistic, its p-value and FDR adjusted p-value for each SNP, also stored in x$instrument_heterogeneity_per_variant

CAMERA$mrgxe()

Estimate the pleiotropic effect of each variant using MR GxE across populations, see egger_bootstrap()

Usage

CAMERA$mrgxe(
  dat = self$harmonised_dat,
  variant_list = subset(self$instrument_heterogeneity_per_variant, Qfdr < 0.05)$SNP,
  nboot = 100
)

Arguments

Returns

Data frame of the MR GxE results, also stored in x$mrgxe_res

CAMERA$mrgxe_plot()

Plot the MR GxE pleiotropy estimates for each variant

Usage

CAMERA$mrgxe_plot(mrgxe_res = self$mrgxe_res)

Arguments

Returns

Plot

CAMERA$mrgxe_plot_variant()

Plot the instrument-exposure against instrument-outcome associations across populations for selected variants

Usage

CAMERA$mrgxe_plot_variant(
  variant = self$mrgxe_res %>% dplyr::ungroup() %>% dplyr::filter(p.adjust(a_pval,
    "fdr") < 0.05) %>% {
     .$SNP
 },
  dat = self$harmonised_dat
)

Arguments

Returns

Plot

CAMERA$make_outcome_data()

The function extracts summary statistics of given a list of instruments and the outcomes

Usage

CAMERA$make_outcome_data(exp = self$instrument_raw, p_exp = 0.05/nrow(exp))

Arguments

Returns

Data frame in x$instrument_outcome

CAMERA$make_outcome_local()

The function extracts summary statistics of given a list of instruments and the outcomes from local data

Usage

CAMERA$make_outcome_local(
  exp = self$instrument_raw,
  out = self$instrument_outcome_regions,
  p_exp = 0.05/nrow(exp)
)

Arguments

Returns

Data frame in x$instrument_outcome

CAMERA$harmonise()

This function harmonises the alleles and effects between the exposure and outcome.

Usage

CAMERA$harmonise(exp = self$instrument_raw, out = self$instrument_outcome)

Arguments

Returns

Data frame in x$harmonised_dat_sem

CAMERA$set_summary()

Generate summary of exposure, outcome and population metadata

Usage

CAMERA$set_summary()

Returns

data frame

CAMERA$pleiotropy()

Estimate similarity of horizontal pleiotropy across ancestries. For each ancestry, identify outliers in the MR analysis based on per-variatn Q statistics. Then estimate the deviation from the main estimates for all outliers across all ancestries. Finally, determine if the pleiotropy deviation is consistent across all ancestries

Usage

CAMERA$pleiotropy(harmonised_dat = self$harmonised_dat, mrres = self$mrres)

Arguments

Returns

• data frame of outliers pleiotropy_outliers

• data frame of heterogeneity for each outlier / ancestry combination pleiotropy_Q_outliers

• data frame of agreement of outlier effects pleiotropy_agreement

CAMERA$plot_pleiotropy()

Plot pleiotropy results

Usage

CAMERA$plot_pleiotropy(dat = self$pleiotropy_outliers)

Arguments

Returns

plot

CAMERA$plot_pleiotropy_heterogeneity()

Plot pleiotropy results per variant

Usage

CAMERA$plot_pleiotropy_heterogeneity(
  dat = self$pleiotropy_Q_outliers,
  pthresh = 0.05
)

Arguments

Returns

plot

CAMERA$perform_basic_sem()

Perform basic SEM analysis of the joint estimates in multiple ancestries.

Usage

CAMERA$perform_basic_sem(harmonised_dat = self$harmonised_dat_sem)

Arguments

Returns

Table of the SEM results. Summary of the results available in x$sem_result.

CAMERA$runsem()

Fit an SEM model using lavaan

Usage

CAMERA$runsem(model, data, modname)

Arguments

Returns

Data frame of the SEM estimates for each population

CAMERA$standardise_data()

This function standardises the betas and SEs for the instruments-exposure/outcome associations when unit information is not matched across the populations. In case of large differences in genetic effects observed between the populations (e.g. due to sample size difference), the function scales the betas and SEs.

Usage

CAMERA$standardise_data(
  dat = self$instrument_raw,
  standardise_unit = FALSE,
  standardise_scale = FALSE,
  scaling_method = "simple_mode"
)

Arguments

CAMERA$clone()

The objects of this class are cloneable with this method.

Usage

CAMERA$clone(deep = FALSE)

Arguments

Description

A simple wrapper function for importing data from local files for use with the CAMERA class.

Create the object with CAMERA_local$new() and then call its organise() method. This reads the summary statistics files listed in metadata, finds and clumps the top hits for each dataset, pools them across populations, and extracts the region around each instrument from every dataset. The results are stored in the instrument_raw, instrument_outcome, instrument_regions and instrument_outcome_regions fields, which can be passed to the import_from_local() method of a CAMERA object.

See vignette("import-local", package = "CAMeRa") for a worked example.

Details

metadata must be a data frame with one row per summary statistics file (i.e. per trait and population) and the following columns:

• what: either "exposure" or "outcome"

• trait: name of the trait, the same for all populations of a trait

• pop: population, e.g. "EUR"; must match the pop column of ld_ref

• id: a unique identifier for the dataset

• fn: path to the summary statistics file, which is read with data.table::fread()

• chr_col, pos_col, ea_col, oa_col, eaf_col, beta_col, se_col, pval_col: the name or number of the column in the file containing the chromosome, base pair position, effect allele, other allele, effect allele frequency, effect estimate, standard error, and p-value respectively

Other columns are ignored. Variants are identified by chromosome, position and alleles (as chr:pos_a1_a2, with the alleles in alphabetical order), so all files must use the same genome build.

ld_ref must be a data frame with columns pop and bfile, giving for each population the path to a PLINK binary fileset (without the .bed/.bim/.fam extension) used as the LD reference for clumping.

Top hits are only taken from datasets with at least two variants with p-value below pthresh. Currently organise() uses the first exposure trait and the first outcome trait in metadata.

Public fields

Methods

Public methods

• CAMERA_local$new()

• CAMERA_local$standardise()

• CAMERA_local$read_file()

• CAMERA_local$pool_tophits()

• CAMERA_local$organise_data()

• CAMERA_local$fixed_effects_meta_analysis_fast()

• CAMERA_local$organise()

• CAMERA_local$clone()

CAMERA_local$new()

Create a new CAMERA_local object

Usage

CAMERA_local$new(
  metadata,
  ld_ref,
  plink_bin,
  mc.cores = 1,
  radius = 25000,
  pthresh = 5e-08,
  minmaf = 0.01
)

Arguments

CAMERA_local$standardise()

Standardise the allele coding so that the effect allele is the alphabetically first allele, flipping the effect estimate and allele frequency where needed, and create a variant ID of the form chr:pos_ea_oa

Usage

CAMERA_local$standardise(
  d,
  ea_col = "ea",
  oa_col = "oa",
  beta_col = "beta",
  eaf_col = "eaf",
  chr_col = "chr",
  pos_col = "pos",
  vid_col = "vid"
)

Arguments

Returns

d with standardised alleles and a variant ID column

CAMERA_local$read_file()

Read in the summary statistics file for one dataset, drop variants with minor allele frequency below minmaf, and standardise the alleles

Usage

CAMERA_local$read_file(m, minmaf = self$minmaf)

Arguments

Returns

A tibble with columns chr, pos, eaf, beta, se, pval, ea, oa and vid

CAMERA_local$pool_tophits()

Pool the top hits across datasets. For each trait, the regions within radius of its top hits are merged, and the variants in each region are extracted from every dataset. Within each region the variant with the largest absolute z-score for the trait is selected, considering only variants present in a number of datasets for which at least one such variant has p-value below pthresh

Usage

CAMERA_local$pool_tophits(
  rawdat,
  tophits,
  metadata,
  radius = 250000,
  pthresh = 5e-08,
  mc.cores = 1
)

Arguments

Returns

A list with elements region_list (the merged regions for each trait), region_extract (the extracted variants in each region) and tophit_pool (the selected variant from each region in every dataset)

CAMERA_local$organise_data()

Read in the data (unless rawdat is supplied), find the top hits in each dataset by clumping the variants with p-value below pthresh using ieugwasr::ld_clump(), and pool them with pool_tophits()

Usage

CAMERA_local$organise_data(
  metadata = self$metadata,
  plink_bin = self$plink_bin,
  ld_ref = self$ld_ref,
  pthresh = self$pthresh,
  minmaf = self$minmaf,
  radius = self$radius,
  mc.cores = self$mc.cores,
  rawdat = NULL
)

Arguments

Returns

As for pool_tophits()

CAMERA_local$fixed_effects_meta_analysis_fast()

Fixed effect inverse variance weighted meta-analysis of each row of beta_mat and se_mat

Usage

CAMERA_local$fixed_effects_meta_analysis_fast(beta_mat, se_mat)

Arguments

Returns

A vector of p-values, one per row

CAMERA_local$organise()

Organise the data for the exposure and outcome, populating the instrument_raw, instrument_outcome, instrument_regions and instrument_outcome_regions fields

Usage

CAMERA_local$organise()

CAMERA_local$clone()

The objects of this class are cloneable with this method.

Usage

CAMERA_local$clone(deep = FALSE)

Arguments

See Also

CAMERA, vignette("import-local", package = "CAMeRa")

Description

For a single variant estimated in different sub groups.

Usage

egger_bootstrap(b_gx, se_gx, b_gy, se_gy, nboot = 1000)

Arguments

Details

Estimate the degree of pleiotropy using MR GxE. This method uses a negative control type approach based on an assumption that the instrument-exposure association is uncorrelated with the pleiotropic effect. Therefore, as the instrument-exposure association reduces in magnitude, the effect on the outcome will reduce towards an intercept term which represents the pleiotropic effect.

Standard errors are obtained from parametric bootstrap

Value

List

• a = intercept estimate (pleiotropy)

• b = slope estimate (b_iv effect)

• a_se = standard error of intercept

• b_se = standard error of slope

• a_pval = p-value of intercept estimate

• b_pval = p-value of slope estimate

• a_mean = mean value of intercept from bootstraps

• b_mean = mean value of slope estimates from bootstraps

Description

Perform fixed effects meta analysis for one association

Usage

fixed_effects_meta_analysis(beta_vec, se_vec, infl = 10000)

Arguments

Value

list of results

Description

Assumes effects across studies are all on the same scale

Usage

fixed_effects_meta_analysis_fast(beta_mat, se_mat)

Arguments

Value

list of meta analysis betas and SEs

Description

Sometimes estimates appear unstable. They are likely unreliable and best to not use for heterogeneity analyses etc.

Usage

identify_blownup_estimates(b, se, infl)

Arguments

Value

index of betas to remove

Description

Taken from Okbay et al 2016. Under the assumption that all discovery effects are unbiased, what fraction of associations would replicate in the replication dataset, given the differential power of the discovery and replication datasets. Uses standard error of the replication dataset to account for differences in sample size and distribution of independent variable

Usage

prop_overlap(b_disc, b_rep, se_disc, se_rep, alpha)

Arguments

Value

List of results

• res: aggregate expected replication rate vs observed replication rate

• variants: per variant expected replication rates

Description

Uses weighted Z scores following advice from https://onlinelibrary.wiley.com/doi/full/10.1111/j.1420-9101.2005.00917.x Suggested weights are 1/se^2 However se is scale dependent and it would be ideal to avoid scale issues at this stage So using instead calculate expected se based on n and af. Assumes continuous traits in the way it uses n (i.e. not case control aware at the moment)

Usage

z_meta_analysis(beta_mat, se_mat, n, eaf_mat)

Arguments