install.packages(
"openalexSnowball",
repos = c(
"https://openalexpro.r-universe.dev",
"https://cloud.r-project.org"
)
)
## Static plot
install.packages(c("ggplot2", "tidygraph", "ggraph"))
## Interactive plot
install.packages(c("networkD3", "htmlwidgets"))Technical Guideline Series
Snowball Search for Literature Search and Analysis using OpenAlex
In addition to the typical literature search using search terms, one can conduct a snowball search. A snowball search starts from a set of identified key-papers, and the snowball search will identify the publications cited in the key papers as well as the publications citing the key-paper. This search strategy identifies related articles using citation relationships (not keywords), building a citation network based on the key-papers. Here we will demonstrate how a snowball search can be conducted using OpenAlex and R with the openalexPro ecosystem of packages, in particular {openalexSnowball}, with code examples, and discuss some shortcomings and advantages of this approach. Furthermore, we will outline some analysis approaches and possibilities of a citation network without going into too much detail.
Prepared by
- Rainer M. Krug - IPBES Task Force on Knowledge and Data.
Reviewed by
- Aidin Niamir - IPBES Technical Support Unit for Knowledge and Data
- Renske Gudde - IPBES Technical Support Unit for Knowledge and Data
- Yanina V. Sica - IPBES Technical Support Unit for Knowledge and Data
For any inquires please contact Aidin.Niamir@senckenberg.de
Version: 1.0.0
Last updated: 18 November, 2026
Introduction
Snowball search (also known as chain sampling, chain-referral sampling, referral sampling) is in the context of literature search a search which starts with some key-papers and identifies the papers which are referenced in the key-papers (also called backward search) as well as the papers citing one or more key-papers (also called forward search).
These key-papers should cover the range of the topic which should be covered by the resulting literature corpus, while containing the most relevant papers of the topic, and form the core of the search. Consequently, the selection of the key-papers is essential and this selection determines the quality and usability of the resulting corpus for a specific question asked.
Methods
Databases suitable for Snowballing
In principle, snowballing can be done with most (if not all) literature databases. Examples are Web of Science, Scopus or PubMed which provide the possibility to search for papers from their web interface or using API services. When using their web interface, one can only search for one article at the time, so it is very cumbersome to conduct a snowball search for multiple keypapers. Using the provided APIs of these proprietary databases makes automating the search possible, but becomes easily extremely expensive and still laden with restrictions due to high licence fees.
A good alternative is OpenAlex. OpenAlex is an open scholarly data source which provides a free daily usage budget for its API (which is enough for most projects, including the snowball search shown here), and the complete database is also available as a free snapshot for download. Therefore, the snowball search can be scripted. API clients are available for many different programming languages, including R (e.g. {openalexR} and {openalexPro}) and Python (pyalex).
This technical guideline focuses on the use of OpenAlex (the data source for literature recommended by the IPBES Technical Support Unit on Knowledge and Data) through the openalexPro ecosystem of R packages:
{openalexPro}provides the access to the OpenAlex API. In contrast to{openalexR}, which processes all data in memory,{openalexPro}processes the retrieved data on disk and stores it as Apache Parquet files. The size of a search is therefore limited by disk space rather than by memory.{openalexSnowball}builds on{openalexPro}and conducts the snowball search itself. It retrieves the key-papers, the works citing them and the works cited by them, and stores the resulting citation network as nodes (works) and edges (citations) in Parquet.
Further packages in the ecosystem which are useful in this context, but not used in this guideline, are {openalexSnapshot}, which allows to conduct the same snowball search offline against a local copy of the OpenAlex snapshot (see Offline snowball search), and {openalexConvert}, which exports the retrieved works to reference managers (CSL-JSON, BibTeX, Zotero).
Snowballing in R
Installation and loading of the packages
The packages of the openalexPro ecosystem are not on CRAN, but are available from r-universe. Installing {openalexSnowball} also installs {openalexPro}. The packages, plus the additional ones used in this technical guideline for plotting, can be installed using
and loaded using
library(openalexSnowball)OpenAlex API key
OpenAlex can be used without an API key, but much stricter limits apply in this case. It is therefore strongly recommended to obtain a free API key from OpenAlex and to make it available to {openalexPro}. Assuming the key is xxxxxxx, this can be done in one of the following ways, which are evaluated in this order:
- by setting the option using
openalexPro::opt_api_key("xxxxxxx")in the R session, - by setting the environment variable
openalexPro.api_keyto the key, for example in the.Renvironfile, or - by storing the key in the keyring of the operating system using
keyring::key_set("API_openalex"), which asks for the key and stores it encrypted. This is the safest option.
Afterwards, the key and the remaining budget can be checked using
openalexPro::pro_validate_credentials()Testing:
api_key: XXXXXXXXXXXXXXXXXXXXXX
[1] TRUE
openalexPro::pro_rate_limit_status()OpenAlex Rate Limit Status:
Daily budget: $1
Daily used: $0
Daily remaining: $1
Prepaid balance: $0
Prepaid remaining: $0
Resets at: 2026-11-19T00:00:00.000Z
Resets in: 26705 seconds
Snowballing
Let’s assume, we have a list of DOIs of the key papers, which have been identified by experts with knowledge of the field and topic.
dois <- c(
"10.1016/j.marpol.2023.105710",
"10.1007/s13280-014-0582-z",
"10.1016/j.cosust.2022.101160",
"10.1146/annurev-environ-102014-021340"
)The snowball search is done by the function pro_snowball(). The key papers can be provided either as DOIs (argument doi) or as OpenAlex ids (argument identifier), so there is no need to convert the DOIs to OpenAlex ids first. The results are written to the directory given in the argument output. If no output is given, a temporary directory is used, which is deleted at the end of the R session, so a persistent directory should be specified.
It is always a good idea to wrap the snowball search (and other long running calculations) in a construct which only does the snowball search if it has not been conducted before, as especially with many key papers the snowball search can take some time. In addition, resume = TRUE makes pro_snowball() continue an interrupted search (e.g. due to a lost internet connection or an exhausted daily API budget) instead of starting it again.
snowball_dir <- file.path("data", "snowball")
## `edges/` is written last, so its existence marks a completed search
if (!dir.exists(file.path(snowball_dir, "edges"))) {
pro_snowball(
doi = dois,
output = snowball_dir,
resume = TRUE,
verbose = FALSE
)
}The same snowball search can also be done using the OpenAlex ids of the key papers instead of their DOIs, by using the argument identifier. This is useful when the key papers have no DOI, or when they have been identified in OpenAlex itself (the OpenAlex id is part of the URL of a work on OpenAlex, e.g. W2020319093 in https://openalex.org/W2020319093). The OpenAlex ids of the four key papers used here are:
pro_snowball(
identifier = c("W2020319093", "W2204133637", "W4220786370", "W4379647013"),
output = file.path("data", "snowball_ids"),
resume = TRUE,
verbose = FALSE
)When there are many key papers, they should all be passed to a single call of pro_snowball() rather than calling it in a loop for each key paper, as this is much faster. See ?pro_snowball for further arguments, e.g. workers to retrieve the data in parallel.
The results of the snowball search
The results are stored in snowball_dir as Parquet datasets:
data/snowball/
├── nodes/ # the works, partitioned by relation=
├── edges/ # the citations, partitioned by edge_type=
├── snowball_meta.parquet # provenance: key papers, date, package versions
├── _snowball_run.parquet # parameters of the run, used by resume
└── .osb_done/ # markers of the completed stages, used by resume
The results can be read into R using read_snowball(). With return_data = TRUE they are read into memory as tibbles, otherwise they are returned as Arrow Datasets, which can be filtered and summarised (e.g. using {dplyr} or DuckDB) without loading the whole dataset into memory. The latter is useful for large snowball searches. shorten_ids = TRUE removes the https://openalex.org/ prefix from the ids, and meta = TRUE returns in addition the provenance information.
snowball <- read_snowball(
snowball = snowball_dir,
edge_type = "core",
return_data = TRUE,
shorten_ids = TRUE,
meta = TRUE
)The resulting list snowball has three elements:
nodeswhich contains the nodes of the citation network, i.e. the individual publications (orworksin the terminology of OpenAlex), with all fields returned by OpenAlex. Every work is contained only once. As a work can have more than one role in the snowball search (a key paper citing another key paper is both a key paper and a citing work), the roles are given in three independent logical columns:is_keypaper: the work is one of the key papers,is_citing: the work cites at least one key paper (forward search),is_cited: the work is cited by at least one key paper (backward search).
edgeswhich contains the edges of the citation network, i.e. the citations between the works. The columnfromcontains the citing work andtothe cited work.metawhich contains the provenance of the search, i.e. the key papers, the date of the search and the versions of the packages used. This should be reported together with the results, as the content of OpenAlex changes over time and a snowball search conducted at a later time will give different results.
The provenance of the snowball search used in this guideline is:
knitr::kable(
data.frame(
Field = c(
"Date of search",
"Mode",
"Key papers",
"openalexSnowball",
"openalexPro"
),
Value = c(
format(as.POSIXct(snowball$meta$created_at), "%Y-%m-%d"),
snowball$meta$mode,
gsub(
"https://openalex.org/",
"",
gsub(",", ", ", snowball$meta$keypapers)
),
snowball$meta$openalexSnowball,
snowball$meta$openalexPro
)
)
)| Field | Value |
|---|---|
| Date of search | 2026-11-18 |
| Mode | api |
| Key papers | W2020319093, W2204133637, W4220786370, W4379647013 |
| openalexSnowball | 0.15.1 |
| openalexPro | 0.13.0 |
When results of a snowball search are used, the packages should be cited as well. The citations can be obtained using citation("openalexSnowball") and citation("openalexPro").
In this snowball search, we obtained 2918 works, of which 2572 cite and 375 are cited by the 4 key papers.
The edges are of three mutually exclusive types, which can be selected using the argument edge_type of read_snowball():
core: citations from or to a key paper, i.e. the citations identified by the snowball search itself,extended: citations between two works of the snowball search, neither of them being a key paper,outside: citations from or to works which are not part of the snowball search.
By selecting edge_type = "core" above, the citation network does not include any citations between the newly identified works. We will come back to this later. edge_type = c("core", "extended") contains the core as well as the extended citations.
Plotting the network
There are many different packages in R to plot networks ({igraph}, {ggraph} together with {tidygraph} and others).
As we will plot two networks in this guideline, we first define two functions, one for a static and one for an interactive plot, which take the result of read_snowball() as input. Both plots only use a few columns of the nodes.
Static Network Graph
For the static plot, I will only show how to plot the network using {ggraph} and {tidygraph} and not go into details how the plot can be tweaked.
library(ggplot2)
library(tidygraph)
Attaching package: 'tidygraph'
The following object is masked from 'package:stats':
filter
library(ggraph)
plot_snowball_static <- function(snowball, title = "Cited by count") {
graph <- tidygraph::tbl_graph(
nodes = snowball$nodes[, c("id", "is_keypaper", "cited_by_count")],
edges = snowball$edges[, c("from", "to")],
node_key = "id",
directed = TRUE
)
ggraph::ggraph(graph, layout = "stress") +
ggraph::geom_edge_link(
aes(alpha = after_stat(index)),
show.legend = FALSE
) +
ggraph::geom_node_point(
aes(fill = is_keypaper, size = cited_by_count),
shape = 21,
color = "white"
) +
ggraph::geom_node_label(
aes(filter = is_keypaper, label = id),
nudge_y = 0.2,
size = 3
) +
scale_size(range = c(3, 10), guide = "none") +
scale_fill_manual(values = c("#a3ad62", "#d46780"), na.value = "grey") +
ggraph::theme_graph() +
theme(
plot.background = element_rect(fill = "transparent", colour = NA),
panel.background = element_rect(fill = "transparent", colour = NA)
) +
guides(fill = "none") +
ggtitle(title)
}which can now be used to plot the network and to save the plot as pdf and png (saving as svg using the package {svglite} is shown, but commented out, as the resulting files are very large):
fn <- file.path("figures", "cited_by_count")
## only (re-)create the plot if one of the files is missing
if (!all(file.exists(paste0(fn, c(".pdf", ".png"))))) {
p_cb <- plot_snowball_static(snowball)
ggsave(
paste0(fn, ".pdf"),
plot = p_cb,
device = cairo_pdf,
width = 20,
height = 15
)
ggsave(
paste0(fn, ".png"),
plot = p_cb,
width = 20,
height = 15,
bg = "white",
dpi = 300
)
## The plot can also be saved as svg (needs the package svglite). This is
## not done here, as every node and edge becomes an element of the svg and
## the files get very large (45 MB for the core and 413 MB for the
## supplemented network).
# ggsave(
# paste0(fn, ".svg"),
# plot = p_cb,
# device = svglite::svglite,
# width = 20,
# height = 15,
# bg = "white"
# )
}