diff --git a/DESCRIPTION b/DESCRIPTION index fe7f7e3..0653a98 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: forplot Title: Forest plots -Version: 0.0.1 +Version: 0.0.2 Authors@R: person("Lukas", "Bütikofer", , "lukas.buetikofer@unibe.ch", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-0801-746X")) diff --git a/NEWS.md b/NEWS.md index f5f88df..a533719 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,4 +2,9 @@ forplot 0.0.1 ------------------ add news file -ordering of columns according to input \ No newline at end of file +ordering of columns according to input + +forplot 0.0.2 +------------------ + +bug fix in help file \ No newline at end of file diff --git a/R/forest.R b/R/forest.R index 540cf35..7eb1c4e 100644 --- a/R/forest.R +++ b/R/forest.R @@ -49,15 +49,15 @@ #' x (vector with xpos), y (single y-position), text (character vector with labels), cex (text size), #' the list can be >1 to define more than one header line #' @param ref reference line, list with x (xposition), extend (extension on top), lty (line type), col (line color), lwd (line width) -#' @param bottomline lines at the bottom if not NA -#' @param headline 1 line for header if not NA, 2 lines if 2 -#' @param headline_pos vector with position of lower and upper headline (if applicable), default c(0,1) -#' @param beta2 if not NULL a second forest is generated, needs variables beta2, beta2_lci and beta2_uci in dat +#' @param bottomline line at the bottom if not NA +#' @param headline line for header if not NA, 1 for one line at the bottom, 2 for a line at the bottom and top +#' @param headline_pos vector with position of lower and upper headline (if applicable), default c(0,1) +#' @param beta2 if not NULL a second forest is generated, needs variables beta2, beta_lci2 and beta_uci2 in dat #' @param xlab2 see xlab for 2nd forest #' @param xlab_text2 see xlab_text for 2nd forest #' @param xlim2 see xlim for 2nd forest #' @param xtitle2 see xtitle for 2nd forest -#' @param ... options passed to ff_ci for formatting the effects (if beta_format not goven) +#' @param ... options passed to ff_ci for formatting the effects (if beta_format not given) #' #' @return forest plot #' diff --git a/README.Rmd b/README.Rmd index 4f21c33..fd91cd8 100644 --- a/README.Rmd +++ b/README.Rmd @@ -31,16 +31,16 @@ Note that `remotes` treats any warnings (e.g. that a certain package was built u Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS = "true") ``` -## Overview -`forpplot` and it's main function fplot needs a data frame with specific column names. +## Usage +`forplot` and its main function `fplot` needs a data frame with specific column names. -- vlabel: a chr column with the variable labels printed on the left of the forest plot -- nx: any number of chr or num columns numbered sequentially (i.e. n1, n2, n3, ...). Printed in that seqence after the - column label. May contain the number of observations and/or summary per group. -- beta, beta_lci, beta_uci: three num columns with point estimates and confidence interval to be plotted as forest. -- beta_format: optional chr column with formatted text to be prin§ted along forest, generated from beta if not given. -- px: any number of chr or num columns numbered sequentially (i.e. p1, p2, p3, ...), printed on the very right of the plot. - May contain p-values. +- *vlabel*: a *chr* column with the variable labels. +- *nx*: any number of *chr* or *num* columns numbered sequentially (i.e. *n1*, *n2*, *n3*, ...). Could contain the number of observations and/or summary per group. +- *beta*, *beta_lci*, *beta_uci*: three *num* columns with point estimates and confidence interval to be plotted as forest. +- *beta_format*: optional *chr* column with formatted text to be printed along forest, generated from betas if not given. +- *px*: any number of *chr* or *num* columns numbered sequentially (i.e. *p1*, *p2*, *p3*, ...). Could contain p-values. + +The order of the columns is kept for the plot. The package includes an example dataset with 10 variables: @@ -54,23 +54,24 @@ data(forplotdata) forplotdata ``` -The nx columns included the number of observations and descritpives (mean (sd)) for each group, beta is a mean difference, p1 the p-value. +The *nx* columns include the number of observations and descriptives (mean (sd)) for each group, *beta* is a mean difference, *p1* the p-value. -The minimal plot only includes a label and the forest and needs columns vlabel, beta, beta_lci, beta_uci. +The minimal plot only includes a label and the forest and needs columns *vlabel*, *beta*, *beta_lci*, *beta_uci*. ```{r, fig.height=3.5, fig.width=5} fplot(dat=forplotdata[,c("vlabel","beta","beta_lci","beta_uci")]) ``` -We can add the nx and px columns: +Adding *nx* and *px* columns: ```{r, fig.height=3.5, fig.width=8} fplot(dat=forplotdata) ``` -Set more sensible widths and heights. -The widths has to be the same length as the number of columns for the input - data plus two for the left and right margin. -The length is usually three, header, body and footer. +Set more sensible widths and heights: + +- lwidths has to be the same length as the number of columns for the input + data plus two for the left and right margin +- lheight is usually of length three, for header, body and footer ```{r, fig.height=3.5, fig.width=8} lwidths<-c(0.05,0.5,0.2,0.8,0.2,0.8,1.2,1.2,0.5,0.05) @@ -81,8 +82,7 @@ fplot(dat=forplotdata,lwidths=lwidths,lheights=lheights) ``` A header can be given using a character vector the same - length as the number of columns of the input data, which then - places it above the columns + length as the number of columns of the input data: ```{r, fig.height=3.5, fig.width=8} header<-c("","Group1\nN","Group0\nmean (sd)","Group2\nN","Group2\nmean (sd)", @@ -92,21 +92,22 @@ fplot(dat=forplotdata,lwidths=lwidths,lheights=lheights,header=header) ``` The header can also be placed at any x/y position using a list - with one element per header line. + with one element per header line: ```{r, fig.height=3.5, fig.width=8} -header<-list(list(y=0.7, - text=c("Group1","Group2","Mean difference (95% CI)","P-value"), - x=c(0.10,0.32,0.7,0.98)), - list(y=0.3,text=c("N","mean (sd)","N","mean (sd)"), - x=c(0.07,0.18,0.28,0.38))) +header<-list( + list(y=0.7,text=c("Group1","Group2","Mean difference (95% CI)","P-value"),x=c(0.10,0.32,0.7,0.98)), + list(y=0.3,text=c("N","mean (sd)","N","mean (sd)"),x=c(0.07,0.18,0.28,0.38))) fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights) ``` -A label can be placed below the x-axis using option xtitle. -Option ref adds a vertical reference line and xlim specifies the - limits for the axis. +Further formatting options for the forest plot include: + + - *xtitle*: a label below the x-axis + - *ref*: adds a vertical reference line + - *xlim*: limits for the x-axis + ```{r, fig.height=3.5, fig.width=8} xtitle<-list(x=0.86,y=0.2,textl="Group 1 better ",textr=" Group 2 better") @@ -115,10 +116,10 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, xtitle=xtitle,ref=list(x=0),xlim=c(-1,0.5)) ``` -Note that arrows are shown if the limits of the CIs are not included within xlim. +Note that arrows are shown if the limits of the confidence intervals are not included within *xlim*. There are further options for the reference line and we can shift the x-axis - if the gap at the bottom is too large. + if the gap at the bottom is too large: ```{r, fig.height=3.5, fig.width=8} xtitle<-list(x=0.86,y=0.6,textl="Group 1 better ",textr=" Group 2 better") @@ -129,7 +130,7 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ``` -The points of the forest plots can also be formatted. +The points of the forest plots can also be formatted: ```{r, fig.height=3.5, fig.width=8} set.seed(1345) @@ -142,7 +143,7 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ``` -Lines at the top and bottom can be added. +Lines at the top and bottom can be added: ```{r, fig.height=3.5, fig.width=8} fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, @@ -151,10 +152,9 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, headline=2,bottomline=1) ``` -If effect measures are on the log-scale (e.g. for odds ratios), option lscale can be used to indicate that the text should contain the exponentiated values. Axis ticks and labels have to be adapted by hand. +If effect measures are on the log-scale (e.g. for odds ratios), option *lscale* can be used to indicate that the text should contain the exponentiated values. Axis ticks and labels have to be adapted by hand. ```{r, fig.height=3.5, fig.width=8} - xlab_text<-c(0.3,0.5,0.8,1.0,1.5) xlab<-log(xlab_text) xlim<-log(c(min(xlab_text),max(xlab_text))) @@ -165,14 +165,14 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, xtitle=xtitle,shift_xaxis=0.3,xlab_line=-0.8, xlim=xlim,xlab=xlab, xlab_text=xlab_text, headline=2,bottomline=1) - ``` ## Under development -A feature under development is adding a second forest plot (e.g. to show a risk difference and ratio). -That needs a beta, beta_lci2 and beta_uci2 column in the dataset (just copied over in the example below). -Options xlab2,xlab_text2,xlim2 and xtitle2 are available to format the second plot. +A feature under development is adding a second forest plot (e.g. to show a risk difference and ratio) + by setting *beta2 = TRUE*. +That needs columns *beta2*, *beta_lci2* and *beta_uci2* in the dataset (just copied over in the example below). +Options *xlab2*, *xlab_text2*, *xlim2* and *xtitle2* are available to format the second plot. ```{r, fig.height=3.5, fig.width=8} @@ -186,7 +186,7 @@ forplotdata2$p1<-forplotdata$p1 lwidths<-c(0.05,0.5,0.2,0.8,0.2,0.8,1.2,1.2,1.2,1.2,0.5,0.05) lheights<-c(0.14,1,0.08) -fplot(dat=forplotdata2,beta2 = TRUE, +fplot(dat=forplotdata2, beta2 = TRUE, lwidths=lwidths,lheights=lheights, xlim=c(-1,0.5),xlim2=c(-1,0.5), headline=2,bottomline=1) diff --git a/README.md b/README.md index fc4ec8d..2edcece 100644 --- a/README.md +++ b/README.md @@ -22,23 +22,23 @@ error, run the following line and try again: Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS = "true") ``` -## Overview +## Usage -`forpplot` and it’s main function fplot needs a data frame with specific +`forplot` and its main function `fplot` needs a data frame with specific column names. -- vlabel: a chr column with the variable labels printed on the left of - the forest plot -- nx: any number of chr or num columns numbered sequentially (i.e. n1, - n2, n3, …). Printed in that seqence after the column label. May - contain the number of observations and/or summary per group. -- beta, beta_lci, beta_uci: three num columns with point estimates and - confidence interval to be plotted as forest. -- beta_format: optional chr column with formatted text to be prin§ted - along forest, generated from beta if not given. -- px: any number of chr or num columns numbered sequentially (i.e. p1, - p2, p3, …), printed on the very right of the plot. May contain - p-values. +- *vlabel*: a *chr* column with the variable labels. +- *nx*: any number of *chr* or *num* columns numbered sequentially + (i.e. *n1*, *n2*, *n3*, …). Could contain the number of observations + and/or summary per group. +- *beta*, *beta_lci*, *beta_uci*: three *num* columns with point + estimates and confidence interval to be plotted as forest. +- *beta_format*: optional *chr* column with formatted text to be printed + along forest, generated from betas if not given. +- *px*: any number of *chr* or *num* columns numbered sequentially + (i.e. *p1*, *p2*, *p3*, …). Could contain p-values. + +The order of the columns is kept for the plot. The package includes an example dataset with 10 variables: @@ -63,11 +63,12 @@ forplotdata #> 10 out10 100 5.1 (1.1) 100 5.4 (1.1) -0.28700316 -0.5822050 0.008198722 0.057 ``` -The nx columns included the number of observations and descritpives -(mean (sd)) for each group, beta is a mean difference, p1 the p-value. +The *nx* columns include the number of observations and descriptives +(mean (sd)) for each group, *beta* is a mean difference, *p1* the +p-value. The minimal plot only includes a label and the forest and needs columns -vlabel, beta, beta_lci, beta_uci. +*vlabel*, *beta*, *beta_lci*, *beta_uci*. ``` r fplot(dat=forplotdata[,c("vlabel","beta","beta_lci","beta_uci")]) @@ -75,7 +76,7 @@ fplot(dat=forplotdata[,c("vlabel","beta","beta_lci","beta_uci")]) ![](man/figures/README-unnamed-chunk-3-1.png) -We can add the nx and px columns: +Adding *nx* and *px* columns: ``` r fplot(dat=forplotdata) @@ -83,9 +84,11 @@ fplot(dat=forplotdata) ![](man/figures/README-unnamed-chunk-4-1.png) -Set more sensible widths and heights. The widths has to be the same -length as the number of columns for the input data plus two for the left -and right margin. The length is usually three, header, body and footer. +Set more sensible widths and heights: + +- lwidths has to be the same length as the number of columns for the + input data plus two for the left and right margin +- lheight is usually of length three, for header, body and footer ``` r lwidths<-c(0.05,0.5,0.2,0.8,0.2,0.8,1.2,1.2,0.5,0.05) @@ -98,8 +101,7 @@ fplot(dat=forplotdata,lwidths=lwidths,lheights=lheights) ![](man/figures/README-unnamed-chunk-5-1.png) A header can be given using a character vector the same length as the -number of columns of the input data, which then places it above the -columns +number of columns of the input data: ``` r header<-c("","Group1\nN","Group0\nmean (sd)","Group2\nN","Group2\nmean (sd)", @@ -111,23 +113,23 @@ fplot(dat=forplotdata,lwidths=lwidths,lheights=lheights,header=header) ![](man/figures/README-unnamed-chunk-6-1.png) The header can also be placed at any x/y position using a list with one -element per header line. +element per header line: ``` r -header<-list(list(y=0.7, - text=c("Group1","Group2","Mean difference (95% CI)","P-value"), - x=c(0.10,0.32,0.7,0.98)), - list(y=0.3,text=c("N","mean (sd)","N","mean (sd)"), - x=c(0.07,0.18,0.28,0.38))) +header<-list( + list(y=0.7,text=c("Group1","Group2","Mean difference (95% CI)","P-value"),x=c(0.10,0.32,0.7,0.98)), + list(y=0.3,text=c("N","mean (sd)","N","mean (sd)"),x=c(0.07,0.18,0.28,0.38))) fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights) ``` ![](man/figures/README-unnamed-chunk-7-1.png) -A label can be placed below the x-axis using option xtitle. Option ref -adds a vertical reference line and xlim specifies the limits for the -axis. +Further formatting options for the forest plot include: + +- *xtitle*: a label below the x-axis +- *ref*: adds a vertical reference line +- *xlim*: limits for the x-axis ``` r xtitle<-list(x=0.86,y=0.2,textl="Group 1 better ",textr=" Group 2 better") @@ -138,11 +140,11 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ![](man/figures/README-unnamed-chunk-8-1.png) -Note that arrows are shown if the limits of the CIs are not included -within xlim. +Note that arrows are shown if the limits of the confidence intervals are +not included within *xlim*. There are further options for the reference line and we can shift the -x-axis if the gap at the bottom is too large. +x-axis if the gap at the bottom is too large: ``` r xtitle<-list(x=0.86,y=0.6,textl="Group 1 better ",textr=" Group 2 better") @@ -154,7 +156,7 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ![](man/figures/README-unnamed-chunk-9-1.png) -The points of the forest plots can also be formatted. +The points of the forest plots can also be formatted: ``` r set.seed(1345) @@ -168,7 +170,7 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ![](man/figures/README-unnamed-chunk-10-1.png) -Lines at the top and bottom can be added. +Lines at the top and bottom can be added: ``` r fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, @@ -180,11 +182,10 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ![](man/figures/README-unnamed-chunk-11-1.png) If effect measures are on the log-scale (e.g. for odds ratios), option -lscale can be used to indicate that the text should contain the +*lscale* can be used to indicate that the text should contain the exponentiated values. Axis ticks and labels have to be adapted by hand. ``` r - xlab_text<-c(0.3,0.5,0.8,1.0,1.5) xlab<-log(xlab_text) xlim<-log(c(min(xlab_text),max(xlab_text))) @@ -202,10 +203,10 @@ fplot(dat=forplotdata,header=header,lwidths=lwidths,lheights=lheights, ## Under development A feature under development is adding a second forest plot (e.g. to show -a risk difference and ratio). That needs a beta, beta_lci2 and beta_uci2 -column in the dataset (just copied over in the example below). Options -xlab2,xlab_text2,xlim2 and xtitle2 are available to format the second -plot. +a risk difference and ratio) by setting *beta2 = TRUE*. That needs +columns *beta2*, *beta_lci2* and *beta_uci2* in the dataset (just copied +over in the example below). Options *xlab2*, *xlab_text2*, *xlim2* and +*xtitle2* are available to format the second plot. ``` r @@ -219,7 +220,7 @@ forplotdata2$p1<-forplotdata$p1 lwidths<-c(0.05,0.5,0.2,0.8,0.2,0.8,1.2,1.2,1.2,1.2,0.5,0.05) lheights<-c(0.14,1,0.08) -fplot(dat=forplotdata2,beta2 = TRUE, +fplot(dat=forplotdata2, beta2 = TRUE, lwidths=lwidths,lheights=lheights, xlim=c(-1,0.5),xlim2=c(-1,0.5), headline=2,bottomline=1) diff --git a/man/fplot.Rd b/man/fplot.Rd index 8948217..755d3b4 100644 --- a/man/fplot.Rd +++ b/man/fplot.Rd @@ -117,13 +117,13 @@ the list can be >1 to define more than one header line} \item{ref}{reference line, list with x (xposition), extend (extension on top), lty (line type), col (line color), lwd (line width)} -\item{bottomline}{lines at the bottom if not NA} +\item{bottomline}{line at the bottom if not NA} -\item{headline}{1 line for header if not NA, 2 lines if 2} +\item{headline}{line for header if not NA, 1 for one line at the bottom, 2 for a line at the bottom and top} \item{headline_pos}{vector with position of lower and upper headline (if applicable), default c(0,1)} -\item{beta2}{if not NULL a second forest is generated, needs variables beta2, beta2_lci and beta2_uci in dat} +\item{beta2}{if not NULL a second forest is generated, needs variables beta2, beta_lci2 and beta_uci2 in dat} \item{xlab2}{see xlab for 2nd forest} @@ -133,7 +133,7 @@ the list can be >1 to define more than one header line} \item{xtitle2}{see xtitle for 2nd forest} -\item{...}{options passed to ff_ci for formatting the effects (if beta_format not goven)} +\item{...}{options passed to ff_ci for formatting the effects (if beta_format not given)} } \value{ forest plot