{"id":14069098,"url":"https://github.com/rubenarslan/codebook","last_synced_at":"2026-02-22T11:10:44.896Z","repository":{"id":56936265,"uuid":"109252375","full_name":"rubenarslan/codebook","owner":"rubenarslan","description":"Cook rmarkdown codebooks from metadata on R data frames","archived":false,"fork":false,"pushed_at":"2024-10-15T19:31:49.000Z","size":100387,"stargazers_count":141,"open_issues_count":21,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-18T02:32:29.134Z","etag":null,"topics":["codebook","documentation","formr","json-ld","metadata","r","spss","webapp"],"latest_commit_sha":null,"homepage":"https://rubenarslan.github.io/codebook/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubenarslan.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-02T10:50:15.000Z","updated_at":"2024-10-15T19:30:37.000Z","dependencies_parsed_at":"2023-01-22T23:46:08.039Z","dependency_job_id":null,"html_url":"https://github.com/rubenarslan/codebook","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenarslan%2Fcodebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenarslan%2Fcodebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenarslan%2Fcodebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenarslan%2Fcodebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubenarslan","download_url":"https://codeload.github.com/rubenarslan/codebook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228092154,"owners_count":17868141,"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":["codebook","documentation","formr","json-ld","metadata","r","spss","webapp"],"created_at":"2024-08-13T07:06:36.343Z","updated_at":"2025-10-22T04:35:36.652Z","avatar_url":"https://github.com/rubenarslan.png","language":"HTML","readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"README-\"\n)\n```\n\n# codebook\n[![Travis-CI Build Status](https://travis-ci.org/rubenarslan/codebook.svg?branch=master)](https://app.travis-ci.com/rubenarslan/codebook) \n[![CRAN status](http://www.r-pkg.org/badges/version-ago/codebook)](https://cran.r-project.org/package=codebook) \n![Downloads](https://cranlogs.r-pkg.org/badges/grand-total/codebook) \n[![codecov](https://codecov.io/gh/rubenarslan/codebook/branch/master/graph/badge.svg)](https://app.codecov.io/gh/rubenarslan/codebook) \n[![DOI](https://zenodo.org/badge/109252375.svg)](https://zenodo.org/badge/latestdoi/109252375)\n\n_Automatic Codebooks from Metadata Encoded in Dataset Attributes_\n\n## Description\n\nEasily automate the following tasks to describe data frames: \n- summarise the distributions, and labelled missings of variables graphically and using descriptive statistics\n-  for surveys, compute and summarise reliabilities (internal consistencies, retest, multilevel) for psychological scales, \n-  combine this information with metadata (such as item labels and labelled values) that is derived from R attributes.\n\nTo do so, the package relies on 'rmarkdown' partials, so you can generate HTML, PDF, and Word documents. Codebooks are also available as tables (CSV, Excel, etc.) and in JSON-LD, so that search engines can find your data and index the metadata.\n\n\n## Generate markdown codebooks from the attributes of the variables in your data frame\n\nRStudio and a few of the tidyverse package already usefully display the information contained in the attributes of the variables in your data frame. The [haven](https://github.com/tidyverse/haven) package also manages to grab variable documentation from SPSS or Stata files.\n\n## RStudio Addin\nIf the RStudio data viewer scrolls slow for your taste, or you'd like to keep the variable labels in view while working, use our RStudio Addins (ideally assigned to a keyboard shortcut) to see and search variable and value labels in the viewer pane. \n\n![Gif of Addin](https://rubenarslan.github.io/codebook/reference/figures/codebook_addin.gif)\n\n## Codebook generation\n\nThe codebook package takes those attributes and the data and tries to produce a good-looking codebook, i.e. a place to get an overview of the variables in a dataset. The codebook processes single items, but also \"scales\", i.e. psychological questionnaires that are aggregated to extract a construct. For scales, the appropriate reliability coefficients (internal consistencies for single measurements, retest reliabilities for repeated measurements, multilevel reliability for multilevel data) are computed.\nFor items and scales, the distributions are summarised graphically and numerically.\n\nThis package integrates tightly with formr ([formr.org](https://formr.org)), an online survey framework and especially the data frames produced and marked up by the [formr R package](https://github.com/rubenarslan/formr). However, codebook is completely independent of it.\n\n## Documentation\nConfer the help or: https://rubenarslan.github.io/codebook/.\nSee the [vignette](https://rubenarslan.github.io/codebook/articles/codebook.html) for a quick example of an HTML document generated using `codebook`, or below for a copy-pastable rmarkdown document to get you started.\n\n## Use as a webapp\n\nIf you don't want to install the codebook package, you can just upload an annotated dataset in a variety of formats (R, SPSS, Stata, ...) here: https://codebook.formr.org\n\n## Use locally\n### Install\n\nRun the following in R.\n```r\ninstall.packages(\"codebook\")\n```\n\nOr to get the latest development version:\n\n```r\ninstall.packages(\"remotes\")\nremotes::install_github(\"rubenarslan/codebook\")\n```\n\nThen run the following to get started:\n\n```r\nlibrary(codebook)\nnew_codebook_rmd()\n```\n\n## Citation\nTo cite the package, you can cite the open access paper, but to make your codebook\ntraceable to the version of the package you used, you might also want to cite\nthe archived package DOI.\n\n### Paper\n\u003e Arslan, R. C. (2019). How to automatically document data with the codebook package to facilitate data re-use. Advances in Methods and Practices in Psychological Science. [doi:10.1177/2515245919838783](https://doi.org/10.1177/2515245919838783)\n\n### Zenodo\n\u003e Arslan, R. C. (2024). Automatic codebooks from survey metadata (2018). URL https://github.com/rubenarslan/codebook. [![DOI](https://zenodo.org/badge/109252375.svg)](https://zenodo.org/badge/latestdoi/109252375)\n\n\n### How to use\nHere's a simple rmarkdown template, that you could use to get started.\nThe resulting codebook will be an HTML file, but you can also choose to generate PDFs or Word files by fiddling with the `output` settings.\n\n````markdown\n---\ntitle: \"Codebook\"\noutput:\n  html_document:\n    toc: true\n    toc_depth: 4\n    toc_float: true\n    code_folding: 'hide'\n    self_contained: true\n  pdf_document:\n    toc: yes\n    toc_depth: 4\n    latex_engine: xelatex\n---\n\n```{r setup}`r ''`\nknitr::opts_chunk$set(\n  warning = TRUE, # show warnings during codebook generation\n  message = TRUE, # show messages during codebook generation\n  error = TRUE, # do not interrupt codebook generation in case of errors,\n                # usually makes debugging easier, and sometimes half a codebook\n                # is better than none\n  echo = FALSE  # don't show the R code\n)\nggplot2::theme_set(ggplot2::theme_bw())\n\n```\n\nHere, we import data from formr\n\n```{r}`r ''`\nlibrary(formr)\nsource(\".passwords.R\")\nformr_connect(email = credentials$email, password = credentials$password)\ncodebook_data \u003c- formr_results(\"s3_daily\")\n```\n\nBut we can also import data from e.g. an SPSS file.\n```{r}`r ''`\ncodebook_data \u003c- rio::import(\"s3_daily.sav\")\n```\n\n\nSometimes, the metadata is not set up in such a way that codebook\ncan leverage it fully. These functions help fix this.\n\n```{r codebook}`r ''`\nlibrary(codebook) # load the package\n# omit the following lines, if your missing values are already properly labelled\ncodebook_data \u003c- detect_missing(codebook_data,\n    only_labelled = TRUE, # only labelled values are autodetected as\n                                   # missing\n    negative_values_are_missing = FALSE, # negative values are NOT missing values\n    ninety_nine_problems = TRUE,   # 99/999 are missing values, if they\n                                   # are more than 5 MAD from the median\n    )\n\n# If you are not using formr, the codebook package needs to guess which items\n# form a scale. The following line finds item aggregates with names like this:\n# scale = scale_1 + scale_2R + scale_3R\n# identifying these aggregates allows the codebook function to\n# automatically compute reliabilities.\n# However, it will not reverse items automatically.\ncodebook_data \u003c- detect_scales(codebook_data)\n```\n\nNow, generating a codebook is as simple as calling codebook from a chunk in an\nrmarkdown document.\n\n```{r}`r ''`\ncodebook(codebook_data)\n```\n````\n\n## [Code of conduct for contributing](https://github.com/rubenarslan/codebook/blob/master/CONDUCT.md)\n","funding_links":[],"categories":["HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubenarslan%2Fcodebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubenarslan%2Fcodebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubenarslan%2Fcodebook/lists"}