{"id":22298127,"url":"https://github.com/jhorzek/tablespan","last_synced_at":"2025-07-29T01:33:23.170Z","repository":{"id":261954464,"uuid":"883393946","full_name":"jhorzek/tablespan","owner":"jhorzek","description":"Create satisficing tables in R.","archived":false,"fork":false,"pushed_at":"2024-11-30T17:30:52.000Z","size":3374,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-30T18:29:22.502Z","etag":null,"topics":["excel","html","latex","r","rtf","tables"],"latest_commit_sha":null,"homepage":"https://jhorzek.github.io/tablespan/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhorzek.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-11-04T22:17:23.000Z","updated_at":"2024-11-30T17:29:05.000Z","dependencies_parsed_at":"2024-11-09T20:19:54.234Z","dependency_job_id":"6cf1748d-131a-4718-9cf2-5996c88d6876","html_url":"https://github.com/jhorzek/tablespan","commit_stats":null,"previous_names":["jhorzek/basictables","jhorzek/tabelle","jhorzek/tablespan"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhorzek%2Ftablespan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhorzek%2Ftablespan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhorzek%2Ftablespan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhorzek%2Ftablespan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhorzek","download_url":"https://codeload.github.com/jhorzek/tablespan/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227971924,"owners_count":17849406,"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":["excel","html","latex","r","rtf","tables"],"created_at":"2024-12-03T17:59:48.726Z","updated_at":"2025-07-29T01:33:23.159Z","avatar_url":"https://github.com/jhorzek.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\nlibrary(dplyr)\nlibrary(tablespan)\n```\n\n# tablespan\n\n\u003c!-- badges: start --\u003e\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n[![CRAN status](https://www.r-pkg.org/badges/version/tablespan)](https://CRAN.R-project.org/package=tablespan)\n[![Total Downloads](https://cranlogs.r-pkg.org/badges/grand-total/tablespan)](https://cranlogs.r-pkg.org/badges/grand-total/tablespan)\n\u003c!-- badges: end --\u003e\n\n\u003e Create satisficing tables in R the formula way.\n\nThe objective of `tablespan` is to provide a \"good enough\" approach to creating tables by \nleveraging R's formulas.\n\n`tablespan` builds on the awesome packages [`openxlsx`](https://ycphs.github.io/openxlsx/) and [`gt`](https://gt.rstudio.com/), which allows tables created with `tablespan`\nto be exported to the following formats:\n\n1. **Excel** (using [`openxlsx`](https://ycphs.github.io/openxlsx/))\n2. **HTML** (using [`gt`](https://gt.rstudio.com/))\n3. **LaTeX** (using [`gt`](https://gt.rstudio.com/))\n4. **RTF** (using [`gt`](https://gt.rstudio.com/))\n\n## Installation\n\nTo install `tablespan` from CRAN use:\n\n```{r, eval=FALSE}\ninstall.packages(\"tablespan\")\n```\n\nThe development version of `tablespan` can be installed from GitHub with:\n\n```{r, eval=FALSE}\nlibrary(remotes)\nremotes::install_github(\"jhorzek/tablespan\")\n```\n\n\n## Introduction\n\nR has a large set of great packages that allow you to create and export tables \nthat look exactly like you envisioned. However, sometimes you may just need a\ngood-enough table that is easy to create and share with others. This is where\n`tablespan` can be of help.\n\nLet's assume that we want to share the following table:\n```{r}\nlibrary(dplyr)\ndata(\"mtcars\")\n\nsummarized_table \u003c- mtcars |\u003e\n  group_by(cyl, vs) |\u003e\n  summarise(N = n(),\n            mean_hp = mean(hp),\n            sd_hp = sd(hp),\n            mean_wt = mean(wt),\n            sd_wt = sd(wt))\n\nprint(summarized_table)\n```\n\nWe don't want to share the table as is - the variable names are all a bit technical\nand the table could need some spanners summarizing columns. So, we want\nto share a table that looks something like this:\n\n```\n|                   | Horse Power |   Weight  |\n| Cylinder | Engine | Mean  |  SD | Mean | SD |\n| -------- | ------ | ----- | --- | ---- | -- |\n|                   |                         |\n```\n\n`tablespan` allows us to create this table with a single formula.\n\n### Creating a Basic Table\n\nIn `tablespan`, the table headers are defined with a formula. For example,\n`cyl ~ mean_hp + sd_hp` defines a table with `cyl` as the\nrow names and `mean_hp` and `sd_hp` as columns:\n\n```{r}\nlibrary(tablespan)\ntablespan(data = summarized_table,\n          formula = cyl ~ mean_hp + sd_hp)\n```\n\nNote that the row names (`cyl`) are in a separate block to the left.\n\n### Adding Spanners\n\nSpanners are defined using braces and spanner names. For example, the \nfollowing defines a spanner for `mean_hp` and `sd_hp` with the name `Horsepower`:\n`cyl ~ (Horsepower = mean_hp + sd_hp)`:\n\n```{r}\ntablespan(data = summarized_table,\n          formula = cyl ~ (Horsepower = mean_hp + sd_hp))\n```\n\nSpanners can also be nested:\n\n```{r}\ntablespan(data = summarized_table,\n          formula = cyl ~ (Horsepower = (Mean = mean_hp) + (SD  = sd_hp)))\n```\n\n### Renaming Columns\n\nVariable names in an R `data.frame` are often very technical (e.g., `mean_hp` and `sd_hp`).\nWhen sharing the table, we may want to replace those names. In the example above, \nwe may want to replace `mean_hp` and `sd_hp` with \"Mean\" and \"SD\". In \n`tablespan` renaming variables is achieved with `new_name:old_name`.\nFor example, `cyl ~ (Horsepower = Mean:mean_hp + SD:sd_hp)` renames `mean_hp` to\n`Mean` and `sd_hp` to `SD`:\n\n```{r}\ntablespan(data = summarized_table,\n          formula = cyl ~ (Horsepower = Mean:mean_hp + SD:sd_hp))\n```\n\n### Creating the Full Table\n\nThe combination of row names, spanners, and renaming of variables allows creating\nthe full table:\n\n```{r}\nlibrary(dplyr)\nlibrary(tablespan)\ndata(\"mtcars\")\n\nsummarized_table \u003c- mtcars |\u003e\n  group_by(cyl, vs) |\u003e\n  summarise(N = n(),\n            mean_hp = mean(hp),\n            sd_hp = sd(hp),\n            mean_wt = mean(wt),\n            sd_wt = sd(wt))\n\ntbl \u003c- tablespan(data = summarized_table,\n                 formula = Cylinder:cyl + Engine:vs ~\n                   N +\n                   (`Horse Power` = Mean:mean_hp + SD:sd_hp) +\n                   (`Weight` = Mean:mean_wt + SD:sd_wt),\n                 title = \"Motor Trend Car Road Tests\",\n                 subtitle = \"A table created with tablespan\",\n                 footnote = \"Data from the infamous mtcars data set.\")\ntbl\n```\n\n## Exporting to Excel\n\nTables created with `tablespan` can now be translated to xlsx tables with [`openxlsx`](https://ycphs.github.io/openxlsx/) using the `as_excel` function:\n\n```{r}\n# as_excel creates an openxlsx workbook\nwb \u003c- as_excel(tbl = tbl)\n\n# Save the workbook as an xlsx file:\n# openxlsx::saveWorkbook(wb,\n#                        file = \"cars.xlsx\", \n#                        overwrite = TRUE)\n```\n\n![](man/figures/tablespan_example_cars.png)\n\n### Styling\n\nWhile `tablespan` provides limited styling options, some elements can be adjusted.\nFor example, we may want to print some elements in bold or format numbers differently.\nIn `tablespan`, styling happens when translating the table to an `openxlsx` workbook\nwith `as_excel`.\nTo this end, `tablespan` provides a `styles` argument.\n\n#### Changing the Overall Look\n\nThe easiest way to customize tables is to change the default color scheme.\nThe function `tbl_styles` provides control over most elements in the table,\nbut in many cases `style_color` may be sufficient. The following creates a \ntable with teal-colored backgrounds for the title, header, and row names:\n\n```{r}\nwb \u003c- as_excel(tbl = tbl, \n               styles = style_color(primary_color = \"#008080\"))\n\n# Save the workbook as an xlsx file:\n# openxlsx::saveWorkbook(wb,\n#                        file = \"cars.xlsx\", \n#                        overwrite = TRUE)\n```\n\n![](man/figures/tablespan_example_cars_color.png)\n\nSimilarly, a dark background can be defined as follows:\n\n```{r}\nwb \u003c- as_excel(tbl = tbl, \n               styles = style_color(primary_color = \"#000000\"))\n\n# Save the workbook as an xlsx file:\n# openxlsx::saveWorkbook(wb,\n#                        file = \"cars.xlsx\", \n#                        overwrite = TRUE)\n```\n\n#### Formatting Cells\n\nLet's assume we want all `mean_hp` values with a value $\\geq 100$ to be printed \nin bold. To this end, we first create a new style object using `openxlsx`:\n\n```{r}\nbold \u003c- openxlsx::createStyle(textDecoration = \"bold\")\n```\n\nNext, we create a cell style with `tablespan`:\n\n```{r}\nhp_ge_100 \u003c- cell_style(rows = which(summarized_table$mean_hp \u003e= 100), \n                        colnames = \"mean_hp\", \n                        style = bold,\n                        gridExpand = FALSE)\n```\nNote that we specify the indices of the rows that we want to be in bold and the\ncolumn name of the item.\n\nFinally, we pass this style as part of a list to `as_excel`:\n\n```{r}\n# as_excel creates an openxlsx workbook\nwb \u003c- as_excel(tbl = tbl, \n               styles = tbl_styles(cell_styles = list(hp_ge_100)))\n\n# Save the workbook as an xlsx file:\n# openxlsx::saveWorkbook(wb,\n#                        file = \"cars.xlsx\", \n#                        overwrite = TRUE)\n```\n\n![](man/figures/tablespan_example_cars_styled.png)\n\n#### Formatting Data Types\n\n`tablespan` also allows formatting specific data types. Let's assume that we want\nto round all doubles to 3 instead of the default 2 digits.\nTo this end, we use the `create_data_styles` function, where we specify (1) a \nfunction that checks for the data type we want to style (here `is.double`) and\n(2) a style for all columns that match that style:\n```{r}\ndouble_style \u003c- create_data_styles(double = list(test = is.double, \n                                                 style = openxlsx::createStyle(numFmt = \"0.000\")))\nwb \u003c- as_excel(tbl = tbl, styles = tbl_styles(data_styles = double_style))\n\n# Save the workbook as an xlsx file:\n# openxlsx::saveWorkbook(wb,\n#                        file = \"cars.xlsx\", \n#                        overwrite = TRUE)\n```\n\n![](man/figures/tablespan_example_cars_styled_data.png)\n\n## Exporting to HTML, LaTeX, and RTF\n\nTables created with `tablespan` can also be exported to `gt` which allows saving as HTML, LaTeX, or RTF file. To this end, we simply have to call `as_gt` on our table:\n\n```{r, include=FALSE}\n# Translate to gt:\ngt_tbl \u003c- as_gt(tbl = tbl)\n```\n```{r, eval=FALSE}\n# Translate to gt:\ngt_tbl \u003c- as_gt(tbl = tbl)\ngt_tbl\n```\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"man/figures/tablespan_example_gt_cars.png\" alt=\"Standard table\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n### Styling Great Tables\n\nThe `gt` package provides a wide range of functions to adapt the style of the \ntable created with `as_gt`. For instance, `opt_stylize` adds a pre-defined style \nto the entire table:\n\n```{r, eval=FALSE}\ngt_tbl |\u003e \n  gt::opt_stylize(style = 6,\n                  color = 'gray')\n```\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"man/figures/tablespan_example_gt_cars_styled.png\" alt=\"Styled table\" width=\"50%\"\u003e\n\u003c/p\u003e\n\nWhen adapting the `gt` object, there is an important detail to keep in mind: To \nensure that each table spanner has a unique ID, `tablespan` will create IDs that\ndiffer from the text shown in the spanner. To demonstrate this, Let's assume\nthat we want to add a spanner above `Horse Power` and `Weight`:\n```{r, error=TRUE}\ngt_tbl |\u003e \n  gt::tab_spanner(label = \"New Spanner\", \n                  spanners = c(\"Horse Power\", \"Weight\"))\n```\n\nThis will throw an error because the spanner IDs are different from the spanner labels.\nTo get the spanner IDs, use `gt::tab_info()`:\n\n```{r, eval = FALSE}\ngt_tbl |\u003e \n  gt::tab_info()\n```\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"man/figures/tablespan_example_tab_info.png\" alt=\"Table spanner IDs\" width=\"50%\"\u003e\n\u003c/p\u003e\n\nThe IDs for the spanners can be found at the very bottom. To add another spanner\nabove `Horse Power` and `Weight`, we have to use these IDs:\n```{r, eval=FALSE}\ngt_tbl |\u003e \n  gt::tab_spanner(label = \"New Spanner\", \n                  spanners = c(\"__BASE_LEVEL__Horse Power\", \n                               \"__BASE_LEVEL__Weight\"))\n```\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"man/figures/tablespan_example_new_spanner.png\" alt=\"Table with additional spanner\" width=\"50%\"\u003e\n\u003c/p\u003e\n\n\n\n## Tables without row names\n\nUsing `1` on the left hand side of the formula creates a table without row names.\nFor example, `1 ~ (Horsepower = Mean:mean_hp + SD:sd_hp)` defines\n\n```{r}\ntablespan(data = summarized_table,\n          formula = 1 ~ (Horsepower = Mean:mean_hp + SD:sd_hp))\n```\n\n\n## References\n\n- gt: Iannone R, Cheng J, Schloerke B, Hughes E, Lauer A, Seo J, Brevoort K, Roy O (2024). gt: Easily Create Presentation-Ready Display Tables. R package version 0.11.1.9000, \u003chttps://github.com/rstudio/gt\u003e, \u003chttps://gt.rstudio.com\u003e.\n- expss: Gregory D et al. (2024). expss: Tables with Labels in R. R package version 0.9.31, \u003chttps://gdemin.github.io/expss/\u003e. \n- tables: Murdoch D (2024). tables: Formula-Driven Table Generation. R package version 0.9.31, \u003chttps://dmurdoch.github.io/tables/\u003e. \n- openxlsx: Schauberger P, Walker A (2023). _openxlsx: Read, Write and Edit xlsx Files_. R package version 4.2.5.2,\n\u003chttps://ycphs.github.io/openxlsx/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhorzek%2Ftablespan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhorzek%2Ftablespan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhorzek%2Ftablespan/lists"}