plotspres: 'plotspres' generates forest plots showing _SPRE_ statistics.
In magosil86/getspres: SPRE Statistics for Exploring Heterogeneity in Meta-Analysis
Description
Usage
Arguments
Details
Value
Methods (by class)
See Also
Examples
View source: R/driver_generate_forestplot_incl_spres.R
Description
Forest plots showing SPRE (standardised predicted random-effects) statistics
can be useful in highlighting overly influential outlier studies with the potential
to inflate summary effect estimates in genetic association meta-analyses.
Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
plotspres(beta_in, se_in, study_names_in, variant_names_in, spres_in, ...)
## Default S3 method:
plotspres(
beta_in,
se_in,
study_names_in,
variant_names_in,
spres_in,
spre_colour_palette = c("mono_colour", "black"),
set_studyNOs_as_studyIDs = FALSE,
set_study_field_width = "%02.0f",
set_cex = 0.66,
set_xlim,
set_ylim,
set_at,
tau2_method = "DL",
adjust_labels = 1,
save_plot = TRUE,
verbose_output = FALSE,
...
)
Arguments
beta_in
A numeric vector of observed study effects e.g. log odds-ratios.
se_in
A numeric vector of standard errors, genomically corrected at study-level.
study_names_in
A character vector of study names.
variant_names_in
A character vector of variant names e.g. rsIDs.
spres_in
A numeric vector of SPRE statistics.
...
other arguments.
spre_colour_palette
An optional character vector specifying the colour palette that should be used for observed study effects. There are 3 types of colour palettes available, namely: "mono_colour", "dual_colour" and "multi_colour"; with the "dual_colour" palette, observed study effects with negative SPRE statistics are coloured differently from those with positive SPRE statistics, and with the "multi_colour" palette observed study effects are colored in a gradient according to the SPRE statistic values. Default palette option is spre_colour_palette = c("mono_colour", "black").
set_studyNOs_as_studyIDs
An optional boolean specifying whether study numbers should be used as study IDs in the forest plot. Default is FALSE.
set_study_field_width
An optional character vector of format strings, akin to the fmt character vector in the sprintf function. (Default is set_study_field_width = "%02.0f").
set_cex
An optional character scalar and symbol expansion factor indicating the percentage by which text and symbols should be scaled relative to the reference; e.g. 1=reference, 1.3 is 30% larger, 0.3 is 30% smaller. (Default is cex = 0.66).
set_xlim
An optional numeric vector of length 2 indicating the horizontal limits of the plot region.
set_ylim
An optional numeric vector of length 2 indicating the y-axis limits of the plot.
set_at
An optional numeric vector indicating position of the x-axis tick marks and corresponding labels.
tau2_method
An optional character scalar, specifying the method that should be used to estimate heterogeneity either through DerSimonian and Laird's moment-based estimate "DL" or restricted maximum likelihood "REML". Note: The REML method uses the iterative Fisher scoring algorithm (step length = 0.5, maximum iterations = 10000) to estimate tau2. Default is "DL".
adjust_labels
An optional numeric scalar value that tweaks label (column header) positions. (Default is adjust_labels = 1).
save_plot
An optional boolean to save forestplot as a tiff file. Default is TRUE.
verbose_output
An optional boolean to display intermediate output. (Default is FALSE).
Details
plotspres takes as input SPRE statistics, observed study effects
and corresponding standard errors (i.e. summary data). The observed study effects
(i.e. study effect-size estimates) could be association statistics from either
quantitative or binary trait meta-analyses, for instance, linear regression coefficients
might be employed for quantitative traits and log-transformed logistic regression
coefficients (per-allele log odds ratios) used for case-control meta-analyses.
SPRE statistics can be calculated using the getspres function.
plotspres uses inverse-variance weighted fixed and random-effects
meta-analysis models in the metafor R package to generate forestplots.
Value
Returns a list containing:
number_variants A numeric scalar indicating the number of variants
number_studies A numeric scalar indicating the number of studies
fixed_effect_results A list of fixed-effect meta-analysis results for each variant examined
random_effects_results A list of random-effects meta-analysis results for each variant examined
spre_forestplot_dataset A dataframe of the data provided by the user for analysis which contains the following fields:
beta , study effect-size estimates
se , corresponding standard errors of study effect-size estimates
variant_names , variant names
study_names , study names
spre , SPRE (standardised predicted random-effects) statistics
study_numbers , study numbers
variant_numbers , variant numbers
Methods (by class)
-
default: Generates forest plots showing SPRE statistics
See Also
getspres to calculate SPRE statistics and the
metafor package to explore implementations of fixed and
random-effects meta-analysis models in R. To access more information and examples
visit the getspres website at: https://magosil86.github.io/getspres/.
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
library(getspres)
# Generate a forest plot showing SPRE statistics for variants in heartgenes214.
# heartgenes214 is a case-control GWAS meta-analysis of coronary artery disease.
# To learn more about the heartgenes214 dataset ?heartgenes214
# Calculating SPRE statistics for 3 variants in heartgenes214
heartgenes3 <- subset(heartgenes214,
variants %in% c("rs10139550", "rs10168194", "rs11191416"))
getspres_results <- getspres(beta_in = heartgenes3$beta_flipped,
se_in = heartgenes3$gcse,
study_names_in = heartgenes3$studies,
variant_names_in = heartgenes3$variants)
# Explore results generated by the getspres function
str(getspres_results)
# Retrieve number of studies and variants
getspres_results$number_variants
getspres_results$number_studies
# Retrieve SPRE dataset
df_spres <- getspres_results$spre_dataset
head(df_spres)
# Extract SPREs from SPRE dataset
head(spres <- df_spres[, "spre"])
# Generating forest plots showing SPREs for variants in heartgenes3
# Forest plot with default settings
# Tip: To store plots set save_plot = TRUE (useful when generating multiple plots)
plotspres_res <- plotspres(beta_in = df_spres$beta,
se_in = df_spres$se,
study_names_in = as.character(df_spres$study_names),
variant_names_in = as.character(df_spres$variant_names),
spres_in = df_spres$spre,
save_plot = FALSE)
# Explore results generated by the plotspres function
# Retrieve number of studies and variants
plotspres_res$number_variants
plotspres_res$number_studies
# Retrieve fixed and random-effects meta-analysis results
fixed_effect_res <- plotspres_res$fixed_effect_results
random_effects_res <- plotspres_res$random_effects_results
# Retrieve dataset that was used to generate forest plots
df_plotspres <- plotspres_res$spre_forestplot_dataset
# Retrieve more detailed meta-analysis output
str(plotspres_res)
# Explore available options for plotspres forest plots:
# 1. Colorize study-effect estimates according to SPRE statistic values
# 2. Label studies by study number instead of study names
# 3. Format study labels (useful when using study numbers as study labels)
# 4. Change text size
# 5. Adjust x and y axes limits
# 6. Change method used to estimate amount of heterogeneity from "DL" to "REML"
# 7. Run verbosely to show intermediate results
# 8. Adjust label (i.e. column header) positions
# 9. Save plot as a tiff file (useful when generating multiple plots)
# Colorize study-effect estimates according to SPRE statistic values
# Use a dual colour palette for observed study effects so that study effect estimates
# with negative SPRE statistics are coloured differently from those with positive
# SPRE statistics.
plotspres_res <- plotspres(beta_in = df_spres$beta,
se_in = df_spres$se,
study_names_in = as.character(df_spres$study_names),
variant_names_in = as.character(df_spres$variant_names),
spres_in = df_spres$spre,
spre_colour_palette = c("dual_colour", c("blue","black")),
save_plot = FALSE)
# Use a multi-colour palette for observed study effects so that study effects estimates
# are colored in a gradient according to SPRE statistic values.
# Available multi-colour palettes:
#
# gr_devices_palettes: "rainbow", "cm.colors", "topo.colors", "terrain.colors"
# and "heat.colors"
#
# colorspace_hcl_hsv_palettes: "rainbow_hcl", "diverge_hcl", "terrain_hcl",
# "sequential_hcl" and "diverge_hsl"
#
# color_ramps_palettes: "matlab.like", "matlab.like2", "magenta2green",
# "cyan2yellow", "blue2yellow", "green2red",
# "blue2green" and "blue2red"
plotspres_res <- plotspres(beta_in = df_spres$beta,
se_in = df_spres$se,
study_names_in = as.character(df_spres$study_names),
variant_names_in = as.character(df_spres$variant_names),
spres_in = df_spres$spre,
spre_colour_palette = c("multi_colour", "rainbow"),
save_plot = FALSE)
# Exploring other options in the plotspres function.
# Label studies by study number instead of study names (option: set_studyNOs_as_studyIDs)
# Format study labels (option: set_study_field_width)
# Adjust text size (option: set_cex)
# Adjust x and y axes limits (options: set_xlim, set_ylim)
# Change method used to estimate heterogeneity from "DL" to "REML" (option: tau2_method)
# Adjust position of x-axis tick marks (option: set_at)
# Run verbosely (option: verbose_output)
df_rs10139550 <- subset(df_spres, variant_names == "rs10139550")
plotspres_res <- plotspres(beta_in = df_rs10139550$beta,
se_in = df_rs10139550$se,
study_names_in = as.character(df_rs10139550$study_names),
variant_names_in = as.character(df_rs10139550$variant_names),
spres_in = df_rs10139550$spre,
spre_colour_palette = c("multi_colour", "matlab.like"),
set_studyNOs_as_studyIDs = TRUE,
set_study_field_width = "%03.0f",
set_cex = 0.75, set_xlim = c(-2,2), set_ylim = c(-1.5,51),
set_at = c(-0.6, -0.4, -0.2, 0.0, 0.2, 0.4, 0.6),
tau2_method = "REML", verbose_output = TRUE,
save_plot = FALSE)
# Adjust label (i.e. column header) position, also keep plot in graphics window rather
# than save as tiff file
df_rs10139550_3studies <- subset(df_rs10139550, as.numeric(df_rs10139550$study_names) <= 3)
# Before adjusting label positions
plotspres_res <- plotspres(beta_in = df_rs10139550_3studies$beta,
se_in = df_rs10139550_3studies$se,
study_names_in = as.character(df_rs10139550_3studies$study_names),
variant_names_in = as.character(df_rs10139550_3studies$variant_names),
spres_in = df_rs10139550_3studies$spre,
spre_colour_palette = c("dual_colour", c("blue","black")),
save_plot = FALSE)
# After adjusting label positions
plotspres_res <- plotspres(beta_in = df_rs10139550_3studies$beta,
se_in = df_rs10139550_3studies$se,
study_names_in = as.character(df_rs10139550_3studies$study_names),
variant_names_in = as.character(df_rs10139550_3studies$variant_names),
spres_in = df_rs10139550_3studies$spre,
spre_colour_palette = c("dual_colour", c("blue","black")),
adjust_labels = 1.7, save_plot = FALSE)
magosil86/getspres documentation built on May 14, 2021, 10:03 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Methods (by class) See Also Examples
View source: R/driver_generate_forestplot_incl_spres.R
Description
Forest plots showing SPRE (standardised predicted random-effects) statistics can be useful in highlighting overly influential outlier studies with the potential to inflate summary effect estimates in genetic association meta-analyses.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | plotspres(beta_in, se_in, study_names_in, variant_names_in, spres_in, ...)
## Default S3 method:
plotspres(
beta_in,
se_in,
study_names_in,
variant_names_in,
spres_in,
spre_colour_palette = c("mono_colour", "black"),
set_studyNOs_as_studyIDs = FALSE,
set_study_field_width = "%02.0f",
set_cex = 0.66,
set_xlim,
set_ylim,
set_at,
tau2_method = "DL",
adjust_labels = 1,
save_plot = TRUE,
verbose_output = FALSE,
...
)
|
Arguments
beta_in |
A numeric vector of observed study effects e.g. log odds-ratios. |
se_in |
A numeric vector of standard errors, genomically corrected at study-level. |
study_names_in |
A character vector of study names. |
variant_names_in |
A character vector of variant names e.g. rsIDs. |
spres_in |
A numeric vector of SPRE statistics. |
... |
other arguments. |
spre_colour_palette |
An optional character vector specifying the colour palette that should be used for observed study effects. There are 3 types of colour palettes available, namely: "mono_colour", "dual_colour" and "multi_colour"; with the "dual_colour" palette, observed study effects with negative SPRE statistics are coloured differently from those with positive SPRE statistics, and with the "multi_colour" palette observed study effects are colored in a gradient according to the SPRE statistic values. Default palette option is |
set_studyNOs_as_studyIDs |
An optional boolean specifying whether study numbers should be used as study IDs in the forest plot. Default is |
set_study_field_width |
An optional character vector of format strings, akin to the fmt character vector in the sprintf function. (Default is |
set_cex |
An optional character scalar and symbol expansion factor indicating the percentage by which text and symbols should be scaled relative to the reference; e.g. 1=reference, 1.3 is 30% larger, 0.3 is 30% smaller. (Default is |
set_xlim |
An optional numeric vector of length 2 indicating the horizontal limits of the plot region. |
set_ylim |
An optional numeric vector of length 2 indicating the y-axis limits of the plot. |
set_at |
An optional numeric vector indicating position of the x-axis tick marks and corresponding labels. |
tau2_method |
An optional character scalar, specifying the method that should be used to estimate heterogeneity either through DerSimonian and Laird's moment-based estimate "DL" or restricted maximum likelihood "REML". Note: The REML method uses the iterative Fisher scoring algorithm (step length = 0.5, maximum iterations = 10000) to estimate tau2. Default is "DL". |
adjust_labels |
An optional numeric scalar value that tweaks label (column header) positions. (Default is |
save_plot |
An optional boolean to save forestplot as a tiff file. Default is |
verbose_output |
An optional boolean to display intermediate output. (Default is |
Details
plotspres takes as input SPRE statistics, observed study effects
and corresponding standard errors (i.e. summary data). The observed study effects
(i.e. study effect-size estimates) could be association statistics from either
quantitative or binary trait meta-analyses, for instance, linear regression coefficients
might be employed for quantitative traits and log-transformed logistic regression
coefficients (per-allele log odds ratios) used for case-control meta-analyses.
SPRE statistics can be calculated using the getspres function.
plotspres uses inverse-variance weighted fixed and random-effects
meta-analysis models in the metafor R package to generate forestplots.
Value
Returns a list containing:
number_variants A numeric scalar indicating the number of variants
number_studies A numeric scalar indicating the number of studies
fixed_effect_results A list of fixed-effect meta-analysis results for each variant examined
random_effects_results A list of random-effects meta-analysis results for each variant examined
spre_forestplot_dataset A dataframe of the data provided by the user for analysis which contains the following fields:
beta , study effect-size estimates
se , corresponding standard errors of study effect-size estimates
variant_names , variant names
study_names , study names
spre , SPRE (standardised predicted random-effects) statistics
study_numbers , study numbers
variant_numbers , variant numbers
Methods (by class)
-
default: Generates forest plots showing SPRE statistics
See Also
getspres to calculate SPRE statistics and the
metafor package to explore implementations of fixed and
random-effects meta-analysis models in R. To access more information and examples
visit the getspres website at: https://magosil86.github.io/getspres/.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | library(getspres)
# Generate a forest plot showing SPRE statistics for variants in heartgenes214.
# heartgenes214 is a case-control GWAS meta-analysis of coronary artery disease.
# To learn more about the heartgenes214 dataset ?heartgenes214
# Calculating SPRE statistics for 3 variants in heartgenes214
heartgenes3 <- subset(heartgenes214,
variants %in% c("rs10139550", "rs10168194", "rs11191416"))
getspres_results <- getspres(beta_in = heartgenes3$beta_flipped,
se_in = heartgenes3$gcse,
study_names_in = heartgenes3$studies,
variant_names_in = heartgenes3$variants)
# Explore results generated by the getspres function
str(getspres_results)
# Retrieve number of studies and variants
getspres_results$number_variants
getspres_results$number_studies
# Retrieve SPRE dataset
df_spres <- getspres_results$spre_dataset
head(df_spres)
# Extract SPREs from SPRE dataset
head(spres <- df_spres[, "spre"])
# Generating forest plots showing SPREs for variants in heartgenes3
# Forest plot with default settings
# Tip: To store plots set save_plot = TRUE (useful when generating multiple plots)
plotspres_res <- plotspres(beta_in = df_spres$beta,
se_in = df_spres$se,
study_names_in = as.character(df_spres$study_names),
variant_names_in = as.character(df_spres$variant_names),
spres_in = df_spres$spre,
save_plot = FALSE)
# Explore results generated by the plotspres function
# Retrieve number of studies and variants
plotspres_res$number_variants
plotspres_res$number_studies
# Retrieve fixed and random-effects meta-analysis results
fixed_effect_res <- plotspres_res$fixed_effect_results
random_effects_res <- plotspres_res$random_effects_results
# Retrieve dataset that was used to generate forest plots
df_plotspres <- plotspres_res$spre_forestplot_dataset
# Retrieve more detailed meta-analysis output
str(plotspres_res)
# Explore available options for plotspres forest plots:
# 1. Colorize study-effect estimates according to SPRE statistic values
# 2. Label studies by study number instead of study names
# 3. Format study labels (useful when using study numbers as study labels)
# 4. Change text size
# 5. Adjust x and y axes limits
# 6. Change method used to estimate amount of heterogeneity from "DL" to "REML"
# 7. Run verbosely to show intermediate results
# 8. Adjust label (i.e. column header) positions
# 9. Save plot as a tiff file (useful when generating multiple plots)
# Colorize study-effect estimates according to SPRE statistic values
# Use a dual colour palette for observed study effects so that study effect estimates
# with negative SPRE statistics are coloured differently from those with positive
# SPRE statistics.
plotspres_res <- plotspres(beta_in = df_spres$beta,
se_in = df_spres$se,
study_names_in = as.character(df_spres$study_names),
variant_names_in = as.character(df_spres$variant_names),
spres_in = df_spres$spre,
spre_colour_palette = c("dual_colour", c("blue","black")),
save_plot = FALSE)
# Use a multi-colour palette for observed study effects so that study effects estimates
# are colored in a gradient according to SPRE statistic values.
# Available multi-colour palettes:
#
# gr_devices_palettes: "rainbow", "cm.colors", "topo.colors", "terrain.colors"
# and "heat.colors"
#
# colorspace_hcl_hsv_palettes: "rainbow_hcl", "diverge_hcl", "terrain_hcl",
# "sequential_hcl" and "diverge_hsl"
#
# color_ramps_palettes: "matlab.like", "matlab.like2", "magenta2green",
# "cyan2yellow", "blue2yellow", "green2red",
# "blue2green" and "blue2red"
plotspres_res <- plotspres(beta_in = df_spres$beta,
se_in = df_spres$se,
study_names_in = as.character(df_spres$study_names),
variant_names_in = as.character(df_spres$variant_names),
spres_in = df_spres$spre,
spre_colour_palette = c("multi_colour", "rainbow"),
save_plot = FALSE)
# Exploring other options in the plotspres function.
# Label studies by study number instead of study names (option: set_studyNOs_as_studyIDs)
# Format study labels (option: set_study_field_width)
# Adjust text size (option: set_cex)
# Adjust x and y axes limits (options: set_xlim, set_ylim)
# Change method used to estimate heterogeneity from "DL" to "REML" (option: tau2_method)
# Adjust position of x-axis tick marks (option: set_at)
# Run verbosely (option: verbose_output)
df_rs10139550 <- subset(df_spres, variant_names == "rs10139550")
plotspres_res <- plotspres(beta_in = df_rs10139550$beta,
se_in = df_rs10139550$se,
study_names_in = as.character(df_rs10139550$study_names),
variant_names_in = as.character(df_rs10139550$variant_names),
spres_in = df_rs10139550$spre,
spre_colour_palette = c("multi_colour", "matlab.like"),
set_studyNOs_as_studyIDs = TRUE,
set_study_field_width = "%03.0f",
set_cex = 0.75, set_xlim = c(-2,2), set_ylim = c(-1.5,51),
set_at = c(-0.6, -0.4, -0.2, 0.0, 0.2, 0.4, 0.6),
tau2_method = "REML", verbose_output = TRUE,
save_plot = FALSE)
# Adjust label (i.e. column header) position, also keep plot in graphics window rather
# than save as tiff file
df_rs10139550_3studies <- subset(df_rs10139550, as.numeric(df_rs10139550$study_names) <= 3)
# Before adjusting label positions
plotspres_res <- plotspres(beta_in = df_rs10139550_3studies$beta,
se_in = df_rs10139550_3studies$se,
study_names_in = as.character(df_rs10139550_3studies$study_names),
variant_names_in = as.character(df_rs10139550_3studies$variant_names),
spres_in = df_rs10139550_3studies$spre,
spre_colour_palette = c("dual_colour", c("blue","black")),
save_plot = FALSE)
# After adjusting label positions
plotspres_res <- plotspres(beta_in = df_rs10139550_3studies$beta,
se_in = df_rs10139550_3studies$se,
study_names_in = as.character(df_rs10139550_3studies$study_names),
variant_names_in = as.character(df_rs10139550_3studies$variant_names),
spres_in = df_rs10139550_3studies$spre,
spre_colour_palette = c("dual_colour", c("blue","black")),
adjust_labels = 1.7, save_plot = FALSE)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.