---
title: "Getting started"
output: html_document
---

```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  progress = FALSE,
  error = FALSE, 
  message = FALSE
)

options(digits = 2)
```

1. The first step is to open up a session with the WoS API. `auth()` will authenticate your credentials with the the API's server and return a session ID (SID).

```{r, eval = FALSE}
library(wosr)
sid <- auth(username = "your_username", password = "your_password")
```

```{r, echo = FALSE}
library(wosr)
sid <- auth()
```

2. Now we can query the Web of Science to see how many records match our query string.

```{r}
# Find all publications that contain "animal welfare" in their titles (TI tag)
# and have the words "dog" and "welfare" somewhere in their titles, abstracts, or
# list of keywords (TS tag).
query <- 'TI = ("animal welfare") AND TS = (dog welfare)'
query_wos(query, sid = sid)
```

3. Pull the data.

```{r}
data <- pull_wos(query, sid = sid)
data
```

4. `pull_wos()` returns a series of data frames that are like tables in a relational database. You an link these data frames together as needed, to answer whatever questions you have. For example:

- What are the top 5 journal subject categories (JSCs) in this set of publications and which publications are classified into these JSCs?

```{r}
library(dplyr)

top_jscs <- 
  data$jsc %>% 
    group_by(jsc) %>% 
    count() %>% 
    arrange(desc(n)) %>% 
    head()

top_jscs
```

```{r}
data$jsc %>% 
  inner_join(top_jscs, by = "jsc") %>% 
  inner_join(data$publication, by = "ut") %>% 
  select(title) %>% 
  distinct() %>% 
  head()
```

- Which publications have "cat" in their abstracts, who are the authors on those publications, and which organizations are those authors from?

```{r}
cat_pubs <- 
  data$publication %>% 
    filter(grepl("\\bcat\\b", abstract, ignore.case = TRUE)) %>% 
    select(ut)

cat_pubs
```

```{r}
cat_authors <- 
  data$author %>% 
    semi_join(cat_pubs, by = "ut") %>% 
    select(ut, author_no, display_name)

cat_authors
```

```{r}
cat_authors %>% 
  inner_join(data$author_address, by = c("ut", "author_no")) %>% 
  inner_join(data$address, by = c("ut", "addr_no")) %>% 
  select(ut, author_no, display_name, org)
```

- Which funding organizations were responsible for funding top-cited publications?

```{r}
data$grant %>% 
  inner_join(data$publication, by = "ut") %>% 
  select(grant_agency, ut, tot_cites) %>% 
  distinct() %>% 
  arrange(desc(tot_cites)) %>% 
  head()
```

5. Download more detailed citation data (from the InCites API) for the top-cited publications

```{r, eval = FALSE}
top_100_pubs <- 
  data$publication %>% 
    arrange(desc(tot_cites)) %>% 
    slice(1:100) %>% 
    .$ut

head(pull_incites(top_100_pubs, key = "your_incites_key"))
```

```{r, echo = FALSE}
top_100_pubs <- 
  data$publication %>% 
    arrange(desc(tot_cites)) %>% 
    slice(1:100) %>% 
    .$ut

head(pull_incites(top_100_pubs))
```
