IPBES_TG_Snowballing.qmd

---
title: Technical Guideline Series
subtitle: Snowball Search for Literature Search and Analysis using OpenAlex
date: today
author:
  - name: 
        family: Krug
        given: Rainer M.
    id: rmk
    orcid: 0000-0002-7490-0066
    email: Rainer.Krug@Senckenberg.de, Rainer@Krugs.de
    affiliation: 
      - name: Senckenberg
        city: Frankfurt (Main)
        url: https://www.senckenberg.de/en/institutes/sbik-f/
    roles: [author, editor]
  - name: 
        family: Niamir
        given: Aidin 
    id: an
    orcid: 0000-0003-4511-3407
    email: Aidin.Niamir@Senckenberg.de
    affiliation: 
      - name: Senckenberg
        city: Frankfurt (Main)
        url: https://www.senckenberg.de/en/institutes/sbik-f/
    roles: [editor]
abstract: > 
    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 snowballing search can be conducted using [OpenAlex](https://OpenAlex.org) and R 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 
keyword: "literature search, snowball search, citation network"
license: "CC BY"
citation: 
  type: report
  container-title: IPBES Technical Guidelines on Snowball Search for Literature Search and Analysis using OpenAlex
  doi: 10.5281/zenodo.10257156
doi: 10.5281/zenodo.10257156
version: 0.6.0

format:
    html:
        toc: true
        toc-depth: 4
        toc_expand: true
        embed-resources: true
        code-fold: false
        code-summary: 'Show the code'
---

```{r}
#| label: setup
#| include: false
#| echo: true
#| 

# This is needed to execute the inline code

if (!require("quarto")) {
    install.packages("quarto")
    library(quarto)
}

if (!require("pandoc")) {
    install.packages("pandoc")
    library(pandoc)
}

if (quarto::quarto_version() < as.numeric_version("1.4.358")) {
    stop("Please upgrade your quarto version to at least 1.4.358 as otherwise the rendering will fail, but the code will run\n")
}

if (pandoc::pandoc_version() < as.numeric_version("3.1.9")) {
    stop("Please upgrade your quarto version to at least 3.1.9 as otherwise the rendering will fail, but the code will run\n")
}
```

[![DOI](https://zenodo.org/badge/706159588.svg)](https://zenodo.org/doi/10.5281/zenodo.10257156)
[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)

[![](https://img.shields.io/badge/Github_Repo-Snowballing_TG-orange)](https://github.com/IPBES-Data/IPBES_TG_Snowballing)
[![GitHub release](https://img.shields.io/github/release/IPBES-Data/IPBES_TG_Snowballing.svg)](https://github.com/IPBES-Data/IPBES_TG_Snowballing/releases/latest)
[![GitHub commits since latest release](https://img.shields.io/github/commits-since/IPBES-Data/IPBES_TG_Snowballing/latest)](https://github.com/IPBES-Data/IPBES_TG_Snowballingcommits/main)


Prepared by 

- [Rainer M. Krug](mailto:Rainer@krugs.de) - IPBES Task Force on Knowledge and Data. 

Reviewed by 

- [Aidin Niamir](mailto:Aidin.Niamir@Senckenberg.de) - IPBES Technical Support Unit for Knowledge and Data
- [Renske Gudde](mailto:Renske.Gudde@Senckenberg.de) - IPBES Technical Support Unit for Knowledge and Data
- [Yanina V. Sica](mailto:Yanina.Sica@Senckenberg.de) - IPBES Technical Support Unit for Knowledge and Data

<!-- - IPBES Task Force on Knowledge and Data**  -->

*For any inquires please contact [Aidin.Niamir@senckenberg.de](mailto:aidin.niamir@senckenberg.de)* 

**Version:** `r rmarkdown::metadata$version`

Last updated: `r Sys.Date() |> format("%d %B, %Y")`


## 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 (e.g. https://dev.elsevier.com/sc_apis.html). 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 doe to high licels fees and restrictions.

A good alternative is [OpenAlex](https://openalex.org). [OpenAlex](https://openalex.org) is an open scholary data source, whcich does not charge fees for the basic API usage (which is enough for most projects). Therefore, the snowball search can be scripted. API clients are available for many different programming languages, including R ([openalexR](https://docs.ropensci.org/openalexR/articles/A_Brief_Introduction_to_openalexR.html)) and Python [pyalex](https://pypi.org/project/pyalex/).
This technical guideline will focus particularly on the use of [OpenAlex](https://openalex.org) (the by the data tsu recommended data source for literature) through the R package [openalexR](https://docs.ropensci.org/openalexR/articles/A_Brief_Introduction_to_openalexR.html) which is perfectly suited for this task, in addition to being easy to use.

### Snowballing in R

#### Installation and loading of the package
The package [openalexR](https://docs.ropensci.org/openalexR/articles/A_Brief_Introduction_to_openalexR.html) 
is available from CRAN. The package plus additional ones used in this technical guideline and can be installed using

```{r}
#| eval: false
install.packages("openalexR")
install.packages("ggplot2")
install.packages("tibble")

## Static plot
install.packages("tidygraph")
install.packages("ggraph")

## Interactive plot
install.packages("networkD3")
install.packages("DT")
```

and loaded using

```{r}
#| eval: true
library(openalexR)
```

#### 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.

```{r}
#| eval: true
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"
    # "10.1016/j.eist.2016.09.001", "10.1016/j.cosust.2019.12.004"
)
```

As the snowball search in [OpenAlex](https://openalex.org) is based on internal identifiers (OpenAlex ids), the DOIs need to be converted to these internal ids. This can be done using the function `oa_fetch()` of the package [openalexR](https://docs.ropensci.org/openalexR/articles/A_Brief_Introduction_to_openalexR.html) which can take a list of DOIs and returns a list of works ([Works](https://docs.openalex.org/api-entities/works) are documents in [OpenAlex](https://openalex.org).). The function has many other arguments, but I will only show the use for this ssnowball search. For more information, please refer to the help in R or the [documentation](https://docs.ropensci.org/openalexR/reference/index.html).

```{r}
#| label: fetch_works

key_works <- oa_fetch(
    entity = "works",
    doi = dois,
    verbose = FALSE
)
```

Now we can do the snowball search, by using the function `oa_snowball()` with `key_works$id` as the `identifier`.

It is always a good idea to wrap the snowball search (and other long running calculations) a construct which only does tha snowball search if it has not been conducted before, as expecially with many key papers the snowball search can tike some time.

```{r}
#| label: snowball

fn <- file.path("data", "snowball.rds")
if (file.exists(fn)) {
    snowball <- readRDS(fn)
} else {
    ### Here comes the actual snowball search
    snowball <- oa_snowball(
        identifier = key_works$id,
        verbose = FALSE
    )
    ###
    saveRDS(snowball, fn)
}
```

The resulting list `snowball` has two elements:

- **`nodes`** which contains the nodes of the citation network, i.e. the individual publications (or `works` in the terminology of OpenAlex). This includes the key papers which are identified by the field `oa_input` which is `TRUE` for the key papers.
- **`edges`** which contains the edges of the citation network, i.e. the citations between the works.

The edges only contain the citations from and to the key papers. The citation network **does not** include any citations between the newly identified works. We will come back to this later.

Another useful function is `snowball2df()` which flattens the object returned by `oa_snowball()` into a tibble.
It is usually much easier to work with this flat structure.

```{r}
#| label: snowball2df

flat_snow <- snowball2df(snowball) |>
    tibble::as_tibble()
```

#### Plotting the network

##### Static Network Graph

There ara many different packages in R to plot networks ([igraph](https://r.igraph.org), [ggraph](https://ggraph.data-imaginist.com) together with [tidygraph](https://tidygraph.data-imaginist.com) and others).

For now, I will only show how to plot the network using `ggraph` and `tidygraph` and not go into details how the plot can be tweaked.


```{r}
#| label: plot_network

library(tidygraph)
library(ggraph)

fn <- file.path("figures", "cited_by_count.png")
if (!file.exists(fn)) {
 p_cb <- ggraph::ggraph(tidygraph::as_tbl_graph(snowball), 
        graph = , layout = "stress") + ggraph::geom_edge_link(ggplot2::aes(alpha = ggplot2::after_stat(index)), 
        show.legend = FALSE) + ggraph::geom_node_point(ggplot2::aes(fill = oa_input, 
        size = cited_by_count), shape = 21, color = "white") + 
        ggraph::geom_node_label(ggplot2::aes(filter = oa_input, 
            label = id), nudge_y = 0.2, size = 3) + ggraph::scale_edge_width(range = c(0.1, 
        1.5), guide = "none") + ggplot2::scale_size(range = c(3, 
        10), guide = "none") + ggplot2::scale_fill_manual(values = c("#a3ad62", 
        "#d46780"), na.value = "grey", name = "") + ggraph::theme_graph() + 
        ggplot2::theme(plot.background = ggplot2::element_rect(fill = "transparent", 
            colour = NA), panel.background = ggplot2::element_rect(fill = "transparent", 
            colour = NA), legend.position = "bottom") + ggplot2::guides(fill = "none") + 
        ggplot2::ggtitle(paste0("Cited by count"))
    ggplot2::ggsave(file.path("figures", "cited_by_count.pdf"), 
        plot = p_cb, device = cairo_pdf, width = 20, height = 15)
    ggplot2::ggsave(file.path("figures", "cited_by_count.png"), 
        plot = p_cb, width = 20, height = 15, bg = "white", dpi = 600)
}
```
![](figures/cited_by_count.png)

There are many options on how these plots can be tweaked, but this is beyond the 
scope of this technical guideline to go into details. Please see the 
documentation of [ggraph](https://ggraph.data-imaginist.com) and 
[tidygraph](https://tidygraph.data-imaginist.com) the two packages for more information.

#### Interactive Network Graph

Snowball citation networks can also be plotted as an interactive graph. I use here [networkD3](https://christophergandrud.github.io/networkD3/) to do this and to save the html widget.

As they are dynamic, they need some time to settle in a stable state. The time it needs depens=ds on the umber of edges as well as your computer, but should ba done in less than a  inute (and they are fun to watch).

```{r}
#| label: plot_network_interactive

library(dplyr)
library(networkD3)

networkData <- data.frame(
  src = snowball$edges$from,
  target = snowball$edges$to,
  stringsAsFactors = FALSE
)

nodes <- data.frame(
  name = snowball$nodes$id,
  title = snowball$nodes$display_name,
  doi = snowball$nodes$doi,
  nodesize = snowball$nodes$cited_by_count / (2024 - snowball$nodes$publication_year) * 0.5,
  stringsAsFactors = FALSE
)
nodes$id <- 0:(nrow(nodes) - 1)

# create a data frame of the edges that uses id 0:9 instead of their names
edges <- networkData |>
  left_join(nodes, by = c("src" = "name")) |>
  select(-src, -title) |>
  rename(source = id) |>
  left_join(nodes, by = c("target" = "name")) |>
  select(-target, -title) |>
  rename(target = id) |>
  mutate(width = 1)

# make a grouping variable that will match to colours
nodes$group <- ifelse(
  nodes$name %in% gsub("^https://openalex.org/", "", key_works$id),
  "key_paper",
  "other"
)
nodes$oa_id <- nodes$name
nodes$name <- nodes$title

# control colours with a JS ordinal scale
ColourScale <- 'd3.scaleOrdinal()
                        .domain(["key_paper", "other"])
                     .range(["#FF6900", "#694489"]);'

openDOI <- "window.open(d.doi)"

MyClickScript <- 'alert("You clicked " + d.name + " with the doi " +
             d.doi +  " of your original R data frame");'

nwg <- networkD3::forceNetwork(
  Links = edges,
  Nodes = nodes,
  Source = "source",
  Target = "target",
  NodeID = "name",
  Nodesize = "nodesize",
  Group = "group",
  Value = "width",
  opacity = 0.9,
  zoom = TRUE,
  colourScale = DT::JS(ColourScale),
  fontSize = 20,
  legend = TRUE,
  clickAction = openDOI
)

nwg$x$nodes$doi <- nodes$doi

tmpdir <- tempfile()
dir.create(tmpdir)
# on.exit(unlink(tmpdir, recursive = TRUE))

tmpfile <- file.path(tmpdir, "nwg.html")

networkD3::saveNetwork(
  nwg,
  file = tmpfile,
  selfcontained = TRUE
)

file.copy(
  tmpfile,
  file.path("figures", "cited_by_count_interactive.html")
)

nwg

```

[Open in new window](./figures/cited_by_count_interactive.html)

These interactive graphs have even more options for tweaking then the static plots, see [networkD3](https://christophergandrud.github.io/networkD3/) for more information.


#### Supplementing the citation network

As mentioned above, the citation network does not include any links between the newly 
identified works, as these are included only through citing or cited by the key papers. This can  
easily be changed, as the works returned from OpenAlex contain a field which lists all the ids 
of the works which are citing the work. This field is called `referenced_works` and can be used to 
supplement the citation network. 
We need to filter these works to only include the works in the original citation network, and add the new edges to the `snowball$edges` object:

```{r}
#| label: supplement_citation_network

library(tibble)

fn <- file.path("data", "snowball_supplemented.rds")
if (file.exists(fn)) {
    snowball_supplemented <- readRDS(fn)
} else {
    new_edges <- tibble(
        from = character(0),
        to = character(0)
    )

    ## all the works in the citation network
    works <- snowball$nodes$id

    ## check if the works in the `referenced_works` field are in the citation network
    ## and if yes, add them to new_edges 
    for (i in 1:nrow(snowball$nodes)) {
        from <- works[[i]]
        to <- gsub("https://openalex.org/", "", snowball$nodes$referenced_works[[i]])
        to_in_works <- to[to %in% works]
        if (length(to_in_works) > 0) {
            new_edges <- add_row(
                new_edges,
                tibble(
                    from = from,
                    to = to_in_works
                )
            )
        }
    }

    ## add the new edges to the citation network but only the unique ones
    snowball_supplemented <- snowball
    snowball_supplemented$edges <- add_row(snowball_supplemented$edges, new_edges) |>
        distinct()

    saveRDS(snowball_supplemented, fn)
}
```

Now we can plot the supplemented citation network:

```{r}
#| label: plot_supplemented_network

fn <- file.path("figures", "supplemented_cited_by_count.png")
if (!file.exists(fn)) {
    p_cb <- ggraph::ggraph(tidygraph::as_tbl_graph(snowball_supplemented),
        graph = , layout = "stress"
    ) + ggraph::geom_edge_link(ggplot2::aes(alpha = ggplot2::after_stat(index)),
        show.legend = FALSE
    ) + ggraph::geom_node_point(ggplot2::aes(
        fill = oa_input,
        size = cited_by_count
    ), shape = 21, color = "white") +
        ggraph::geom_node_label(ggplot2::aes(
            filter = oa_input,
            label = id
        ), nudge_y = 0.2, size = 3) + ggraph::scale_edge_width(range = c(
            0.1,
            1.5
        ), guide = "none") + ggplot2::scale_size(range = c(
            3,
            10
        ), guide = "none") + ggplot2::scale_fill_manual(values = c(
            "#a3ad62",
            "#d46780"
        ), na.value = "grey", name = "") + ggraph::theme_graph() +
        ggplot2::theme(plot.background = ggplot2::element_rect(
            fill = "transparent",
            colour = NA
        ), panel.background = ggplot2::element_rect(
            fill = "transparent",
            colour = NA
        ), legend.position = "bottom") + ggplot2::guides(fill = "none") +
        ggplot2::ggtitle(paste0("Cited by count"))
    ggplot2::ggsave(file.path("figures", "supplemented_cited_by_count.pdf"),
        plot = p_cb, device = cairo_pdf, width = 20, height = 15
    )
    ggplot2::ggsave(file.path("figures", "supplemented_cited_by_count.png"),
        plot = p_cb, width = 20, height = 15, bg = "white", dpi = 600
    )
}
```

![](figures/supplemented_cited_by_count.png)

and as an interactive plot

```{r}
#| label: plot_network_interactive_supplemented

library(dplyr)
library(networkD3)

networkData <- data.frame(
  src = snowball_supplemented$edges$from,
  target = snowball_supplemented$edges$to,
  stringsAsFactors = FALSE
)

nodes <- data.frame(
  name = snowball_supplemented$nodes$id,
  title = snowball_supplemented$nodes$display_name,
  doi = snowball_supplemented$nodes$doi,
  nodesize = snowball_supplemented$nodes$cited_by_count / (2024 - snowball_supplemented$nodes$publication_year) * 0.5,
  stringsAsFactors = FALSE
)
nodes$id <- 0:(nrow(nodes) - 1)

# create a data frame of the edges that uses id 0:9 instead of their names
edges <- networkData |>
  left_join(nodes, by = c("src" = "name")) |>
  select(-src, -title) |>
  rename(source = id) |>
  left_join(nodes, by = c("target" = "name")) |>
  select(-target, -title) |>
  rename(target = id) |>
  mutate(width = 1)

# make a grouping variable that will match to colours
nodes$group <- ifelse(
  nodes$name %in% gsub("^https://openalex.org/", "", key_works$id),
  "key_paper",
  "other"
)
nodes$oa_id <- nodes$name
nodes$name <- nodes$title

# control colours with a JS ordinal scale
ColourScale <- 'd3.scaleOrdinal()
                        .domain(["key_paper", "other"])
                     .range(["#FF6900", "#694489"]);'

openDOI <- "window.open(d.doi)"

MyClickScript <- 'alert("You clicked " + d.name + " with the doi " +
             d.doi +  " of your original R data frame");'

nwg <- networkD3::forceNetwork(
  Links = edges,
  Nodes = nodes,
  Source = "source",
  Target = "target",
  NodeID = "name",
  Nodesize = "nodesize",
  Group = "group",
  Value = "width",
  opacity = 0.9,
  zoom = TRUE,
  colourScale = DT::JS(ColourScale),
  fontSize = 20,
  legend = TRUE,
  clickAction = openDOI
)

nwg$x$nodes$doi <- nodes$doi

tmpdir <- tempfile()
dir.create(tmpdir)
# on.exit(unlink(tmpdir, recursive = TRUE))

tmpfile <- file.path(tmpdir, "nwg.html")

networkD3::saveNetwork(
  nwg,
  file = tmpfile,
  selfcontained = TRUE
)

file.copy(
  tmpfile,
  file.path("figures", "cited_by_count_interactive_supplemented.html")
)

nwg
```

[Open in new window](./figures/cited_by_count_interactive_supplemented.html)

As one can easily see, the number of citations (edges) is much higher, 
and the network is much more connected. A visual inspection is therefore not 
possible anymore, and one needs to use other methods to analyse the network. 

## Other things to do with snowball search
Aspect which are not covered in this technical guidaline, but can be done with the results 
from the snowball seaarching are:

- Clustering of the citation network using for example the package `igraph` to identify topical clusters, citation clusters, etc.
- Identify papers linking identified clsters 
- other network analysis approaches to identify patterns in the citation network
- etc.


## Things to keep in mind when using Snowball Search

This is a (non complete) list of points one needs to consider when using snowball search. Not all points appl;y to all questions, and some are more relevant then others. They are listed in no particular order.

1. The selection of the key papers is essential for the resulting literature search. The key papers should cover the range of the topic which should be covered by the literature search, while containing  the most relevant papers of the topic.
2. The snowball search is based on citation relationships and not on keywords. In other words, papers which are not cited by the key papers will not be included in the resulting literature search, even if they are highly relevant for the topic. 
3. The snowball covers (given a solid choice of key papers) the most relevant literature for a topic, but it does not discover topic areas which are relevant but not linked to the key-papers by citations. Consequently, if a topic consists of multiple research areas which are not citing each other, keypapers need to be provided for all of them.
4. Snowball search contains less false positives (works not related to the topic) than a keyword based search, while a snowball search is less likely to find all works related (see 3. above).
5. Grey literature is underrepresented in the snowball results. Nevertheless, it is possible to do additional snowball searche manally and to supplement the corpus, but the effort is relatively high.
6 Snowball search is a very efficient (time saving) way to obtain a list of relevant literature of a topic, as keyword search usually requires rather complex search terms and numerous iterations to get down to a managable number of identified works.



<!-- 

#### Identifying clusters in the citation network

One approach to identify clusters in the citation network is to use the edge.betweenness
which is a measure which ??????.

This clustering is implemented in the [igraph](https://r.igraph.org) package.

HERE I NEED IDEAS!!!!

```{r}
#| eval: false

library(igraph)

g <- igraph::graph_from_data_frame(
  d = snowball$edges, 
  # vertices = snowball$nodes,
  directed = TRUE
)
eb <- cluster_edge_betweenness(g)

layout <- layout.fruchterman.reingold(g)
plot(
  eb, g,
  layout = layout
)
```

#### Interactive network chart
Interactive network graphs are also possible, and mainly useful for smaller networks and for exploring the network.

```{r}
library(networkD3)

p <- simpleNetwork(
  Data = snowball$edges,
  height="50px", width="50px",
  zoom = TRUE
)
p
```


#### And another graph option (have to try it out)

```{r}
#| eval: false

# https://datastorm-open.github.io/visNetwork/
library(visNetwork)

copub_network <-
    visNetwork(snowball$nodes, snowball$edges, width = "100%") |>
    ## set random seed for reproducibility
    visLayout(randomSeed = 123) |>
    visOptions(
        selectedBy = list(variable = "doi", highlight = TRUE),
        highlightNearest = list(enabled = TRUE, algorithm = "all")
    )
``` -->