---
title: "Getting Started with psreplicate"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with psreplicate}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
# Everything below needs to download the live index, which isn't available
# on CRAN's build machines or in an offline R CMD check. Try it once; if it
# fails, every chunk after this is skipped instead of erroring the build.
eval_chunks <- tryCatch(
  {
    psreplicate::refresh_index()
    TRUE
  },
  error = function(e) FALSE
)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = eval_chunks
)

# The file-download section further down needs the (optional) dataverse
# package too, independent of whether the network check above passed.
eval_dataverse <- eval_chunks && requireNamespace("dataverse", quietly = TRUE)
```

```{r setup}
library(psreplicate)
```

psreplicate is an R client for the [Political Science Replication
Index](https://jsakowuah.github.io/polisci-replication/): a searchable,
tagged index of replication packages crawled monthly from 34 flagship
political science journals' Harvard Dataverse collections. This vignette
walks through the package's functions in the order you'd typically reach
for them.

## Don't know where to start? `list_functions()`

```{r}
list_functions()
```

That's every exported function in the package, in one table. The rest of
this vignette just walks through the same list with worked examples.

## Searching everything at once

`search_replications()` is the broad, do-everything search: free text
across title/abstract/authors, plus optional filters for journal, method,
data type, and year, all combined with AND.

```{r}
search_replications(query = "regression discontinuity", journal = "AJPS")
```

```{r}
search_replications(method = "Survey Experiment", year = 2020:2024)
```

## Searching one field at a time

If you already know which field you're searching, the single-field
functions skip the guesswork of what `search_replications()`'s `query`
argument actually matches against:

```{r}
search_by_title("regression discontinuity")   # title only
search_by_abstract("difference-in-differences") # abstract/description only
search_by_author("Wantchekon")                  # author names only
```

And the same idea for the structured fields:

```{r}
search_by_journal(c("AJPS", "APSR"))
search_by_method("Field Experiment")
search_by_data_type("Elections / Voting")
search_by_year(2015:2020)
```

## Finding out what values are even valid

The catch with `search_by_method()`, `search_by_data_type()`, and
`search_by_journal()` is that you have to already know a valid tag or
journal code to pass in. These three functions list exactly what's in the
data right now, most common first:

```{r}
list_journals()
list_methods()
list_data_types()
```

## Looking up and opening a specific dataset

Once you have a `doi` from a search result, `dataset_info()` pulls just
that one record, and `browse_dataset()` does the same but opens the
dataset's page directly in your browser instead of returning a tibble:

```{r}
hit <- search_by_title("Rebel Victory and Authoritarian")
dataset_info(hit$doi[1])
```

```{r, eval = FALSE}
browse_dataset(hit$doi[1])
```

## Downloading the actual data files

Everything so far is metadata - title, abstract, authors, tags, a link.
`list_dataset_files()` and `download_dataset()` get the real files (the
`.dta`/`.csv`/`.R`/etc. that make up the replication package), so you don't
have to leave R to go download them by hand. Both require the
[dataverse](https://cran.r-project.org/package=dataverse) package
(`install.packages("dataverse")`), which does the actual work of talking to
Harvard Dataverse's file API - these are thin convenience wrappers around
it, scoped to this index's DOIs.

```{r, eval = eval_dataverse}
list_dataset_files(hit$doi[1])
```

```{r, eval = FALSE}
# downloads every file into a new temporary directory and returns the paths
paths <- download_dataset(hit$doi[1])

# or into a specific directory, and only specific files
download_dataset(hit$doi[1], dest = "replication_data", files = "README.rtf")
```

If you just want one file's contents, `load_dataset_file()` skips the disk
entirely: a tabular file (`.tab`/`.dta`/`.csv`/etc.) comes back as a tibble,
an `.rds` file is deserialized with `readRDS()` as whatever R object it
holds, a plain-text file (a script, a README) comes back as lines of text,
and anything else (PDFs, images) comes back as raw bytes.

```{r, eval = eval_dataverse}
load_dataset_file(hit$doi[1], "area.tab")
```

## Keeping the index fresh

The index is downloaded once and cached locally (see
`tools::R_user_dir("psreplicate", "cache")`), then auto-refreshed once the
cache is more than a day old. Force an update sooner with:

```{r, eval = FALSE}
refresh_index(force = TRUE)
```

## Caveats worth knowing

- **Method and data-type tags are generated by keyword matching**, not
  hand-coded. A classifier will miss paraphrased methods and can
  over-match on common words - use tags to narrow a search, then verify
  by reading the abstract or the dataset itself.
- **Not every political science journal is indexed.** Only journals with
  a dedicated Harvard Dataverse collection are crawlable; notably, the
  *Journal of Conflict Resolution* and *Journal of Peace Research* are
  not (see the [site's
  README](https://github.com/jsakowuah/polisci-replication#journals-covered)
  for where their replication data actually lives).
- **The index refreshes monthly.** `list_journals()`, `list_methods()`,
  and search results all reflect whatever was live the last time your
  local cache refreshed.