A while ago we[onboarded](https://github.com/ropensci/software-review/issues/130) anexciting package, [`codemetar`](https://github.com/ropensci/codemetar/)by [Carl Boettiger](/about/#team). `codemetar` is an R specificinformation collector and parser for the [CodeMetaproject](https://github.com/codemeta). In particular, `codemetar` candigest metadata about an R package in order to fill [the termsrecognized by CodeMeta](https://codemeta.github.io/terms/). This meansextracting information from DESCRIPTION but also from e.g. continuousintegration^[1](#fn:1){.footnote-ref role="doc-noteref"}^ badges in the README! In this note, we'll take advantageof `codemetar::extract_badges` function to explore the diversity ofbadges worn by the READMEs of CRAN packages. ## Why codemetar::extract_badges(), and how CodeMeta recognized terms include information we've been getting frombadges: - "contIntegration", URLs to continuous integration services such asTravis, Appveyor, Codecov; - "review", information about review of the software if there was one.`codemetar` recognizes information from the peer-review badge we addto the README of onboarded packages thanks to work by [KarthikRam](/about/#team). The list might get longer, so instead of using regular expressions onthe README text, we extract and memoize^[2](#fn:2){.footnote-ref role="doc-noteref"}^ all badges at once to adata.frame that we then query. The badges extraction is based on (in thedev branch of `codemetar`): - conversion to XML using `commonmark` (see [my recent technote](/technotes/2018/09/05/commonmark/)) which works well for theMarkdown badges e.g.`[![Travis-CI Build Status](https://travis-ci.org/ropensci/codemetar.svg?branch=master)](https://travis-ci.org/ropensci/codemetar)`. - extraction and parsing on the first HTML table there is if there'sany, which is necessary for [badges in table, which we've beendiscussing for ourguidelines](https://github.com/ropensci/software-review-meta/issues/56). Note that the CRAN version of `codemetar` already features`extract_badges`, but with a badges table creation based on regularexpressions only (and a small encoding bug). Here is `codemetar::extract_badges` in action [on theREADME of the `drake` package](https://github.com/ropensci/drake): ::: {.highlight} ``` {.chroma tabindex="0"} library("magrittr")codemetar::extract_badges("https://raw.githubusercontent.com/ropensci/drake/master/README.md") %>% knitr::kable() ``` ::: | text | link | image_link | |:----------------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--------------------------------------------------------------------------------------| | ropensci_footer | | \ | | JOSS | | | | Licence | | | | AppVeyor | | | | rOpenSci | | | | minimal R version | | | | Travis | | | | CRAN | | | | downloads | | | | Codecov | | | | Zenodo | | | | Project Status: Active -- The project has reached a stable, usable state and is being actively developed. | | | Quite handy for our metadata collection! Read the source for `extract_badges`[here](https://github.com/ropensci/codemetar/blob/dev/R/extract_badges.R)and see how it's used in [thisscript](https://github.com/ropensci/codemetar/blob/77fc0943a379d27915bb6a8cb9b37cb3349c05da/R/codemeta_readme.R).You can also compare [`codemetar`'sREADME](https://github.com/ropensci/codemetar/blob/master/README.md)with its[codemeta.json](https://github.com/ropensci/codemetar/blob/master/codemeta.json)e.g. [the lines for"contIntegration"](https://github.com/ropensci/codemetar/blob/master/codemeta.json#L445). Now since, `codemetar::extract_badges` exports a nice data.frame for anyREADME with badges, and is exported, it'd be too bad not to use it togain insights from many, many READMEs! ## Extract badges from CRAN packages In this exploration we shall concentrate on CRAN packages that indicatea GitHub repo link under the URL field of DESCRIPTION. By the way, ifyou don't indicate such links in DESCRIPTION of your package yet, youcan (and should) run[`usethis::use_github_links`](https://usethis.r-lib.org/reference/use_github_links.html). ### Get links to GitHub repos from CRAN information I reckon that I could have also used BugReports like Steven M Mortimerdid [in his great analysis of CRAN downloads and GitHubstars](https://stevenmortimer.com/most-starred-r-packages-on-github/). Iam unsure of how one can get the link to and the content of the READMEof packages that don't Rbuildignore their README, such as[`codemetar`](https://cran.r-project.org/web/packages/codemetar/index.html)(see under Material). The imperfect sample I collected will do for thisnote. Here's how I got all the repo owners and names: ::: {.highlight} ``` {.chroma tabindex="0"} cran_db <- tools::CRAN_package_db()# only packages that have a GitHub repogithub_cran <- dplyr::filter(cran_db[, c("Package", "URL")], stringr::str_detect(URL, "github\\.com"))# will need to keep only the URL to the reposelect_github_repo <- function(URL){ URLs <- stringr::str_split(URL, pattern = ",", simplify = TRUE) github_repo <- URLs[stringr::str_detect(URLs, "github\\.com")][1] github_repo <- stringr::str_remove(github_repo, "\\#.*$") github_repo <- stringr::str_remove(github_repo, "\\#.*[ \$.*\$]") github_repo <- stringr::str_remove(github_repo, "/$") stringr::str_replace(github_repo,".*\\.com\\/", "")}github_cran <- dplyr::group_by(github_cran, Package)github_cran <- dplyr::mutate(github_cran, github = select_github_repo(URL))github_cran <- tidyr::separate(github_cran, github, "\\/", into = c("owner", "repo"))github_cran <- dplyr::ungroup(github_cran)# Not very generalgithub_cran$repo[which(github_cran$Package == "webp")] <- "webp" ``` ::: I needed a bit of string cleaning mostly to deal with the URLs of[Jeroen Ooms](/about/#team)' packages, see e.g. [thisone](https://cran.r-project.org/web/packages/antiword/index.html). Iguess I could have cleaned even more, but it was good enough for thisexploration. ### Get all badges Then for each repo I queried the download URL of the [preferredREADME](https://developer.github.com/v3/repos/contents/#get-the-readme)via GitHub's V3 API, using [the `gh`package](https://github.com/r-lib/gh). The preferred README is the oneGitHub displays on the repo landing page. I used`codemetar::extract_badges`, of course. I rate-limited the basicfunction using [`ratelimitr`](https://github.com/tarakc02/ratelimitr). ::: {.highlight} ``` {.chroma tabindex="0"} library("magrittr")github_cran <- readr::read_csv("data/github_cran_links.csv").get_badges <- function(owner, repo){ message(paste(owner, repo, sep = "/")) readme <- try(gh::gh("GET /repos/:owner/:repo/readme", owner = owner, repo = repo), silent = TRUE) if(inherits(readme, "try-error")){ return(NULL) }else{ badges <- codemetar::extract_badges(readme$download_url) if(nrow(badges)>0){ badges$owner <- owner badges$repo <- repo } return(badges) } }.get_badges %>% ratelimitr::limit_rate(ratelimitr::rate(1, 1)) -> get_badgespurrr::map2_df(github_cran$owner, github_cran$repo, get_badges) -> badges ``` ::: ### Remove non badges from the sample The way badges are recognized by `codemetar::extract_badges` is notspecific enough, it can include images formatted like badges that aren'tbadges but instead either local images or images whose credit is shownas URL. To remove them from the sample, I used a strategy in two steps: - I first had a look at the most common domains. For the 17 mostcommon of them, I accepted the images except for one, ropensci.org,included because the *footer* our packages get is formatted as aMarkdown badge. - For the remaining images, a bit more than 200, I used `magick` toobtain their width and height, and filtered actual badges based ontheir width/height ratio. Sometimes the link to the image wasn'teven valid, which was also a reason for exclusion, since it revealedthe image was a local one. ::: {.highlight} ``` {.chroma tabindex="0"} # extract and parse URLsbadges %>% dplyr::pull(image_link) %>% purrr::map_df(urltools::url_parse) -> parsed_image_links# count hits by domainparsed_image_links %>% dplyr::count(domain, sort = TRUE) -> domain_count# these were manually inspected# as legit badge providersok_domain <- domain_count$domain[1:17]# keep the badges needing a checktbd <- dplyr::filter(parsed_image_links, ! domain %in% ok_domain) # get their size ratioget_size <- function(url){ img <- try(magick::image_read(url), silent = TRUE) if(inherits(img, "try-error")){ tibble::tibble(error = TRUE, image_link = url) }else{ info <- magick::image_info(img) info$error <- FALSE info$image_link <- url info } }img_info <- purrr::map_df(urltools::url_compose(tbd), get_size)img_info <- dplyr::mutate(img_info, ratio = width/height)# filter badges from imagesimg_info <- dplyr::filter(img_info, ratio < 3|error)# it'd have been wiser to use a row-wise workflow!badges <- dplyr::filter(badges, !image_link %in% img_info$image_link, !image_link %in% stringr::str_remove(img_info$image_link, "/$"), !tolower(image_link) %in% img_info$image_link, !tolower(image_link) %in% stringr::str_remove(img_info$image_link, "/$"), !stringr::str_detect(image_link, "ropensci\\.org\\/public\\_images\\/"))readr::write_csv(badges, "data/aaall_badges.csv") ``` ::: Don't judge me by my filenaming skills. I was *maybe* a bit tooenthusiastic! ## Analyze badges from CRAN packages I wanted to answer several questions about the badges of CRAN packages,beyond being just happy to have been able to collect so many of them. ### How many repos have at least one badge? ::: {.highlight} ``` {.chroma tabindex="0"} github_cran <- readr::read_csv("data/github_cran_links.csv")# the same repo can have been used by several packages!badges <- readr::read_csv("data/aaall_badges.csv")badges <- dplyr::distinct(badges)nobadges <- dplyr::anti_join(github_cran, badges, by = c("owner", "repo")) ``` ::: There are 1277 packages without any badge (or rather said, without anybadge that we identified) out of a sample of 3541 packages. That means64% have at least one badge. As a reminder, there are more than 13,000packages on CRAN so we're only looking at a subset. ### Among the repos with badges, how many badges? ::: {.highlight} ``` {.chroma tabindex="0"} library("magrittr")badges %>% dplyr::count(repo, owner, sort = TRUE) -> badges_countbadges_count %>% dplyr::summarise(median = median(n)) ``` ::: ## # A tibble: 1 x 1## median## ## 1 4 ::: {.highlight} ``` {.chroma tabindex="0"} library("ggplot2")badges_count %>% ggplot() + geom_histogram(aes(n))+ hrbrthemes::theme_ipsum(base_size = 12, axis_title_size = 12, axis_text_size = 12) + ggtitle("Number of badges per repo", subtitle = "Among repos with at least one badge") ``` ::: ![number of badges for READMEs with at least one(histogram)](/img/blog-images/2018-09-10-github-badges/unnamed-chunk-2-1.png) The median number of badges is 4, which corresponds to my gut feelingthat the answer would be "a few". I have a new question, what are therepos with the most badges? ::: {.highlight} ``` {.chroma tabindex="0"} most_badges <- dplyr::filter(badges_count, n == max(n)) most_badges ``` ::: ## # A tibble: 2 x 3## repo owner n## ## 1 gpuR cdeterman 13## 2 psycho.R neuropsychology 13 You can browse them at ,. ### How many unique badges are there? For counting types of badges, I'll use the domain of `image_link`. Thisis an approximation, since e.g. www.r-pkg.org offers several badges. ::: {.highlight} ``` {.chroma tabindex="0"} badges %>% dplyr::pull(image_link) %>% purrr::map_df(urltools::url_parse) -> parsed_image_linksparsed_image_links %>% dplyr::pull(domain) %>% unique() %>% sort() -> unique_domainslength(unique_domains) ``` ::: ## [1] 50 Not *that* many after all, so I'll print all of them! A special mentionto maintained under ourGitHub organization by [Scott Chamberlain](/about/#team), to show theCRAN check status of your package! Unique badge domains collapsed by `glue::glue_collapse(unique_domains, sep = ", ", last = " and ")`: anaconda.org, api.codacy.com, api.travis-ci.org, app.wercker.com,assets.bcdevexchange.org, awesome.re, badge.fury.io,badges.frapsoft.com, badges.gitter.im, badges.herokuapp.com,badges.ropensci.org, bestpractices.coreinfrastructure.org,ci.appveyor.com, circleci.com, codeclimate.com, codecov.io,coveralls.io, cranchecks.info, cranlogs.r-pkg.org, depsy.org,dmlc.github.io, eddelbuettel.github.io, githubbadges.com,githubbadges.herokuapp.com, gitlab.com, hits.dwyl.io, i.imgur.com,img.shields.io, jhudatascience.org, joss.theoj.org, mybinder.org,popmodels.cancercontrol.cancer.gov, pro-pulsar-193905.appspot.com,raw.githubusercontent.com, readthedocs.org, saucelabs.com,semaphoreci.com, travis-ci.com, travis-ci.org,user-images.githubusercontent.com, usgs-r.github.io, [www.nceas.ucsb.edu](https://www.nceas.ucsb.edu),[www.ohloh.net](https://www.ohloh.net), [www.openhub.net](https://www.openhub.net), [www.paypal.com](https://www.paypal.com), [www.r-pkg.org](https://www.r-pkg.org),[www.rdocumentation.org](https://www.rdocumentation.org), [www.repostatus.org](https://www.repostatus.org), [www.rpackages.io](https://www.rpackages.io) andzenodo.org. ### What are the most common badges? Note that this doesn't take into account the fact that one domain canappear several times in a single README (Travis status for differentbranches for instance). ::: {.highlight} ``` {.chroma tabindex="0"} parsed_image_links %>% dplyr::count(domain, sort = TRUE) %>% head(n = 10) %>% knitr::kable() ``` ::: | domain | n | |:---------------------------------------------------------|-----:| | travis-ci.org | 1880 | | [www.r-pkg.org](https://www.r-pkg.org) | 1804 | | cranlogs.r-pkg.org | 1286 | | img.shields.io | 882 | | ci.appveyor.com | 698 | | codecov.io | 656 | | [www.repostatus.org](https://www.repostatus.org) | 240 | | zenodo.org | 197 | | coveralls.io | 157 | | [www.rdocumentation.org](https://www.rdocumentation.org) | 86 | The most common badges are Travis-CI badges, and METACRAN badges from[www.r-pkg.org](https://www.r-pkg.org/) and[cranlogs.r-pkg.org](https://cranlogs.r-pkg.org/). Now, "img.shields.io"is a service for badges of other things... which? ::: {.highlight} ``` {.chroma tabindex="0"} badges %>% dplyr::filter(stringr::str_detect(image_link, "img\\.shields\\.io")) %>% dplyr::count(text, sort = TRUE) ``` ::: ## # A tibble: 135 x 2## text n## ## 1 Coverage Status 196## 2 License 91## 3 lifecycle 62## 4 CoverageStatus 54## 5 38## 6 packageversion 37## 7 Last-changedate 32## 8 Licence 28## 9 minimal R version 28## 10 Github Stars 19## # ... with 125 more rows Diverse things, in particular the [Tidyverse lifecyclebadges](https://www.tidyverse.org/lifecycle/). After some discussion, weat rOpenSci have adopted the repostatus.org status badges in ourguidelines... but are actually open to repos using both types of badgessince their nomenclature can complement each other! ## Conclusion In this tech note I presented and used one of `codemetar`'s tools for Rpackage metadata munging, `extract_badges`. I extracted and analyzedbadges information from the READMEs of all CRAN packages that indicate aGitHub repo in the URL field of DESCRIPTION. README badges are a way toshow development status, test results, code coverage, peer-review merit,etc.; but can also be used as a machine-readable source of informationabout these same things. Explore more of `codemetar` [in its GitHubrepo](https://github.com/ropensci/codemetar/), and check out the[CodeMeta project itself](https://github.com/codemeta). Read ourguidelines for package development and maintenance [in thisgitbook](https://devguide.ropensci.org/). And have fun ~~addingpretty badges to your own package repos~~ upping your packagedevelopment & maintenance game! ::: {.footnotes role="doc-endnotes"} ------------------------------------------------------------------------ 1. ::: {#fn:1} If you're new to continuous integration I'd recommend reading [thisgreat post of JuliaSilge's](https://juliasilge.com/blog/beginners-guide-to-travis/), and[this chapter of our guide for packagedevelopment](https://devguide.ropensci.org/ci.html). [↩︎](#fnref:1){.footnote-backref role="doc-backlink"} ::: 2. ::: {#fn:2} Memoizing a function means that when called again during the same Rsession with the same parameters, a cached answer is used. See [thevignette of the `memoise`package](https://cran.r-project.org/web/packages/memoise/README.html). [↩︎](#fnref:2){.footnote-backref role="doc-backlink"} ::: :::

Postagens de Rogue Scholar

All the Badges One Can Earn: Parsing Badges of CRAN Packages READMEs