---
title: "Getting Started"
author: "Peter Baumgartner"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Why This Package?

The Reporters Without Borders (RSF) Press Freedom Index measures press freedom
across countries annually. {pressfreedom.data} automates downloading,
cleaning, and standardizing this data for analysis in R.

The RSF index spans 24 years (2002-2026, with 2011 missing because RSF did not
publish that year) across three methodologically distinct periods:

- **2002-2012:** 16 columns, non-comparable scores
- **2013-2021:** 16 columns, comparable 0-100 scale
- **2022-2026:** 22-25 columns with new dimensions (Political, Economic,
  Legal, Social, Safety)

On top of the structural changes, countries have been renamed or
reclassified over time -- 14 pairs have been consolidated to a single,
current name, including:

- Turkey -> Turkiye (official name change, 2022)
- Ivory Coast -> Cote d'Ivoire (RSF standardization)
- Czech Republic -> Czechia (official name change)

Territorial variants are also resolved: Cyprus and Northern Cyprus are kept
as separate rows (they are distinct political entities), while other
territorial fragments (e.g., U.S. bases in Iraq) are removed. The audit
trail for these decisions -- which rows were consolidated and from what
original name -- is preserved in `data/processed/rwb_standardized.rds`
inside the package source, though it is not part of the exported
`rwb_standardized` dataset described below.

Every row in the exported dataset has a valid ISO 3166-1 alpha-3 country
code, so you can join it with other datasets without extra cleanup. We also
found and fixed a subtle scaling bug in RSF's raw score exports that had
silently inflated many 2013-2026 scores by 100x (see the FAQ below for
details).

This package handles all of the above automatically, providing a single,
clean dataset ready for analysis.

If you haven't installed the package yet, see the
[README's Installation section](https://github.com/petzi53/pressfreedom.data#installation).

## Quick Start

### Load and Explore the Data

```{r load}
library(pressfreedom.data)

data(rwb_standardized)
dplyr::glimpse(rwb_standardized)
```

See `?rwb_standardized` for the full column reference.

### Check Data Availability

```{r availability}
# Years available
unique(sort(rwb_standardized$year_n))

# Number of countries per year
rwb_standardized |>
  dplyr::group_by(year_n) |>
  dplyr::summarise(
    n_countries = dplyr::n_distinct(country_en),
    .groups = "drop"
  )
```

## FAQ & Troubleshooting

### Q: Why is 2011 missing?

**A:** RSF did not publish a Press Freedom Index for 2011. The package
preserves this gap rather than imputing values.

### Q: Are scores comparable across all 24 years?

**A:** No. RSF changed its scoring methodology in 2013, so scores from
2002-2012 are not directly comparable to 2013-2026. When analyzing trends
over time, restrict comparisons to the 2013-2026 period unless you are
specifically studying methodology effects.

### Q: Are dimensions available for all years?

**A:** No. The new dimensions (Political, Economic, Legal, Social, Safety)
are only available from 2022 onward. Earlier years have `NA` values.

### Q: Was there a scaling issue in the raw scores?

**A:** Yes. RSF's source files store percentages as bare digits with implied
decimals (e.g., "9189" means 91.89%) and drop trailing zeros inconsistently,
which had left many 2013-2026 scores up to 100x too large in earlier
cleaning attempts. This is now corrected automatically via
`resolve_percent_scaling()` before export, so the `score` values you see are
already on the correct 0-100 scale.

### Q: Can I use ISO codes to join with other datasets?

**A:** Yes. All rows have valid ISO 3166-1 alpha-3 codes in the `iso`
column. This is the standard for country joins.

### Q: Can I use the data on different platforms?

**A:** Yes. The data is normalized to ASCII, with special characters removed
(e.g., Cote d'Ivoire, Turkiye), so it loads and joins correctly regardless of
your operating system or locale settings.

### Q: Can I use this data in published research?

**A:** Yes. RSF publishes the Press Freedom Index publicly to support
journalism, research, and policy analysis, and does not restrict reuse for
these purposes. See the next entry for citation templates.

### Q: How should I cite this data?

**A:** Please cite the package:

```r
citation("pressfreedom.data")
```

This also includes a pointer to citing RSF's original Press Freedom Index
data, since the package citation does not cover the underlying dataset.

### Q: How do I contribute corrections or suggestions?

**A:** Open an issue on GitHub: <https://github.com/petzi53/pressfreedom.data/issues>

### Q: Where can I learn more about the data?

**A:** There are different places to learn more about the data:

- For background information on the RSF Press Freedom Index itself, visit
<https://rsf.org/en/index>. 
- For chart-based examples using this package,
see the companion vignette `vignette("visualizing-trends", package =
"pressfreedom.data")`. 
- For a full description of the dataset's columns and how it was built, see
`?rwb_standardized` in R.