{"id":19551394,"url":"https://github.com/dcousin3/superb","last_synced_at":"2025-10-07T12:31:50.224Z","repository":{"id":56934330,"uuid":"198099571","full_name":"dcousin3/superb","owner":"dcousin3","description":"Summary plots with adjusted error bars","archived":false,"fork":false,"pushed_at":"2025-01-24T02:48:41.000Z","size":321960,"stargazers_count":19,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T06:18:11.565Z","etag":null,"topics":["error-bars","plotting","r","statistics","summary-plots","summary-statistics","visualization"],"latest_commit_sha":null,"homepage":"https://dcousin3.github.io/superb","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcousin3.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-21T19:59:16.000Z","updated_at":"2025-01-24T02:48:46.000Z","dependencies_parsed_at":"2024-01-18T04:08:10.501Z","dependency_job_id":"9ce2911f-ac75-441e-9170-d49ec1c1d655","html_url":"https://github.com/dcousin3/superb","commit_stats":{"total_commits":121,"total_committers":2,"mean_commits":60.5,"dds":"0.12396694214876036","last_synced_commit":"39105206aa46c7a70d16191e780ff6c4ae7d54c5"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcousin3%2Fsuperb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcousin3%2Fsuperb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcousin3%2Fsuperb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcousin3%2Fsuperb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcousin3","download_url":"https://codeload.github.com/dcousin3/superb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251051368,"owners_count":21528787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-bars","plotting","r","statistics","summary-plots","summary-statistics","visualization"],"created_at":"2024-11-11T04:13:44.426Z","updated_at":"2025-10-07T12:31:50.218Z","avatar_url":"https://github.com/dcousin3.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\nbibliography: \"inst/REFERENCES.bib\"\ncsl: \"inst/apa-6th.csl\"\n---\n\n# superb: Summary plots with adjusted error bars\n \u003cimg src=\"logo.png\" align=\"right\" alt=\"\" width=\"120\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![CRAN Status](https://www.r-pkg.org/badges/version/superb)](https://cran.r-project.org/package=superb)\n\u003c!-- badges: end --\u003e\n\n```{r, echo = FALSE, message = FALSE, results = 'hide', warning = FALSE}\ncat(\"this will be hidden; use for general initializations.\\n\")\nlibrary(superb)\nlibrary(ggplot2)\noptions(\"superb.feedback\" = \"none\") # shut down all information\n```\n\nThe library `superb`  offers two main functionalities. The first and foremost functionnality\nis to obtain plots with adjusted error bars. The main function is `superb()`\nbut you can also use `superbShiny()` for a graphical user interface requiring\nno programming nor scripting.  See the nice tutorial by @w21.\n\nThe purpose of the function `superb()` is to provide a plot with \nsummary statistics and correct\nerror bars. With simple adjustments, the error bar are adjusted\nto the design (within or between), to the purpose (single, i.e., in isolation, or \ndifference, i.e., for pair-wise comparisons),\nto the sampling method (simple randomized samples or cluster\nrandomized samples) and to the population size (infinite or of a specific\n size). The `superb(..., showPlot=FALSE)` argument does not generate the plot but returns the \nsummary statistics and the interval boundaries. These can afterwards\nbe sent to other plotting environments.\n\nThe second, subsidiary, functionality is to *Generate Random Datasets*. The function \n`GRD()` is used to easily generate random data from any design (within or between) using\nany population distribution with any parameters, and with various \neffect sizes. `GRD()` is quite handy to test statistical procedures and plotting procedures \nsuch as `superb()`.\n\n# Installation\n\nThe official **CRAN** version can be installed with \n\n```{r, echo = TRUE, eval = FALSE}\ninstall.packages(\"superb\")\nlibrary(superb)\n```\n\nThe development version `r packageVersion(\"superb\")` can be accessed through GitHub:\n\n```{r, echo = TRUE, eval = FALSE}\ndevtools::install_github(\"dcousin3/superb\")\nlibrary(superb)\n```\n\n```{r, echo = FALSE, eval = FALSE, results = FALSE}\nlibrary(superb)\n```\n\n# Examples\n\nThe easiest is to use the graphical interface which can be \nlaunched with \n\n```{r, echo = TRUE, eval = FALSE}\nsuperbShiny()\n```\n\nThe following examples use the script-based commands.\n\nHere is a simple example illustrating the ``ToothGrowth`` dataset\nof rats  (in which the dependent variable is `len`) \nas a function of the `dose` of \nvitamin and the form of the vitamin supplements `supp` (pills or juice)\n\n```{r, fig.alt=\"mean+-95%CI\", fig.cap=\"**Figure 1**. A simple _superb_ plot\"}\nsuperb(len ~ dose + supp, ToothGrowth )\n```\n\nIn the above, the default summary statistic, the mean, is used. The error\nbars are, by default, the 95% confidence intervals (of the mean). These two choices\ncan be changed with the `statistic` and the `errorbar` arguments.\n\nThis second example explicitly indicates to display the \n`median` instead of the default `mean` summary statistics along with the default 95% confidence interval of the median here (the correct\nfunction is automatically selected):\n\n```{r, fig.alt=\"median+-95%CI\", fig.cap=\"**Figure 2**. A median _superb_ plot\"}\nsuperb(len ~ dose + supp, ToothGrowth,\n    statistic = \"median\")\n```\n\nAs a third example, we illustrate the  harmonic means\n`hmean` along with 99.9% confidence intervals of the harmonic\nmean displayed using bars:\n\n```{r, fig.alt=\"harmonic mean+-95%CI\", fig.cap=\"**Figure 4**. A simple _superb_ plot with 99.9%CI\"}\nsuperb(len ~ dose + supp, ToothGrowth,\n    statistic = \"hmean\", \n    errorbar = \"CI\", gamma = 0.999,\n    plotLayout = \"bar\")\n```\n\nThe second function, `GRD()`, can be used to generate random data\nfrom designs with various within- and between-subject factors.\nThis example generates scores for 30 simulated participants in \na 3 x 6 design with 6 daily repeated-measures on `Day`s. The \nfactor `Day` is modeled as impacting the scores (increasing by 3 points \nper day) whereas difficulty is beneficial for the C level only:\n\n```{r}\nset.seed(663) # for reproducibility\ntestdata \u003c- GRD(\n    RenameDV   = \"score\", \n    SubjectsPerGroup = 10, \n    BSFactors  = \"Difficulty(A,B,C)\", \n    WSFactors  = \"Day(6)\",\n    Population = list(mean = 75,stddev = 10,rho = 0.8),\n    Effects    = list( \"Difficulty\" =  custom(-5,-5,+10), \"Day\" = slope(3) )\n) \nhead(testdata)\n```\n\nThis is here that the full benefits of `superb()` is seen: with\njust a few adjustments, you can obtained decorrelated error bars\nwith the Correlation-adjusted (CA), the Cousineau-Morey (CM) or \nthe Loftus \u0026 Masson (CM) techniques:\n\n```{r, fig.alt=\"mean+-95%CI\", fig.cap=\"**Figure 4**. Multiple _superb_ plots\"}\nlibrary(gridExtra)          # for grid.arrange\nlibrary(RColorBrewer)       # for nicer color palette\n\nplt1 \u003c- superb( crange(score.1, score.6) ~ Difficulty, \n    testdata, WSFactors = \"Day(6)\",\n    plotLayout = \"line\"\n) + ylim(50,100) + labs(title = \"No adjustments\") +\ntheme_bw() + ylab(\"Score\") +\nscale_color_brewer(palette=\"Dark2\")\n    \nplt2 \u003c- superb( crange(score.1, score.6) ~ Difficulty, \n    testdata, WSFactors = \"Day(6)\",\n    adjustments = list(purpose = \"difference\", decorrelation = \"CA\"),\n    plotLayout = \"line\"\n)+ ylim(50,100) + labs(title = \"correlation- and difference-adjusted\") +\ntheme_bw() + ylab(\"Score\") +\nscale_color_brewer(palette=\"Dark2\")\n\ngrid.arrange(plt1,plt2, ncol=2)\n```\n\nEven better, the simulated scores can be illustrated using \nmore elaborate layouts such as the ``pointjitter`` layout which, \nin addition to the mean and confidence interval, shows the raw \ndata using jitter dots:\n\n```{r, fig.alt=\"mean+-95%CI\", fig.cap=\"**Figure 5**. A decorated _superb_ plot\"}\nsuperb( crange(score.1, score.6) ~ Difficulty, \n    testdata, WSFactors = \"Day(6)\",\n    adjustments = list(purpose = \"difference\", decorrelation = \"CM\"),\n    plotLayout = \"pointjitter\",\n    errorbarParams = list(color = \"purple\"),\n    pointParams = list( size = 3, color = \"purple\")\n) +\ntheme_bw() + ylab(\"Score\") +\nscale_color_brewer(palette=\"Dark2\")\n```\n\nIn the above example, optional arguments ``errorbarParams`` and ``pointParams``\nare used to inject specifications in the error bars and the points respectively.\nWhen these arguments are used, they override the defaults from ``superb()``.\n\nLastly, we could aim for a radar (a.k.a. circular) plot with\n\n```{r, fig.alt=\"mean+-95%CI\", fig.cap=\"**Figure 6**. A simple _superb_ plot\"}\nsuperb( crange(score.1, score.6) ~ Difficulty, testdata, \n    WSFactors = \"Day(6)\",\n    adjustments = list(purpose = \"difference\", decorrelation = \"CM\"),\n    plotLayout = \"circularpointlinejitter\",\n    factorOrder = c(\"Day\", \"Difficulty\"),\n    pointParams = list( size = 3 ),\n    jitterParams = list(alpha=0.25),\n    errorbarParams= list(width=0.33, color = \"black\")\n) +\ntheme_bw() + ylab(\"\") +\ntheme(panel.border = element_blank(), text = element_text(size = 16) ) +\nscale_color_brewer(palette=\"Dark2\") +\ntheme(axis.line.y = element_blank(), \naxis.text.y=element_blank(), axis.ticks.y=element_blank())\n```\n\nEvery time, you get error bars for free! no need to compute them on the side, no \nneed to worry about the adjustments (whether you want stand-alone error\nbars or adjusted for purpose or correlation, it is all just one option).\nAlso, keep in mind that it is easy to change the default (mean +- 95%\nconfidence intervals) to any other summary statistics --e.g., median-- and \nany other measure of error --e.g., standard error, standard deviation,\ninter-quartile range, name it--; you can find some responses in the vignettes\nor on stackExchange or just open an issue on the github repository.\n\n# For more\n\n_superb_ is for __summary plot with error bars__, as simple as that.\n\nThe library `superb` makes it easy to illustrate summary statistics \nalong with error bars. Some layouts can be used to visualize additional\ncharacteristics of the raw data. Finally, the resulting appearance can be customized \nin various ways.\n\nThe complete documentation is available on this [site](https://dcousin3.github.io/superb/).\n\nA general introduction to the `superb` framework underlying this \nlibrary is published\nat *Advances in Methods and Practices in Psychological Sciences* [@cgh21]. Also, most of the formulas for confidence intervals when statistics other than the mean are displayed can be found in [@htc14,@htc15].\n\n# References\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcousin3%2Fsuperb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcousin3%2Fsuperb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcousin3%2Fsuperb/lists"}