prisonbrief

prisonbrief: An R package that returns tidy data from the World Prison Brief website - Published in JOSS (2018)

https://github.com/danilofreire/prisonbrief

Keywords

Repository

An R package that returns tidy data from the World Prison Brief website.

README.Rmd

---
output: github_document
---



```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```
[![DOI](http://joss.theoj.org/papers/10.21105/joss.00361/status.svg)](https://doi.org/10.21105/joss.00361) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1165514.svg)](https://doi.org/10.5281/zenodo.1165514) [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/prisonbrief)](https://cran.r-project.org/package=prisonbrief) [![Travis-CI Build Status](https://travis-ci.org/danilofreire/prisonbrief.svg?branch=master)](https://travis-ci.org/danilofreire/prisonbrief) ![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/danilofreire/prisonbrief?branch=master&svg=true) [![CRAN_Download_Badge](http://cranlogs.r-pkg.org/badges/grand-total/prisonbrief)](https://CRAN.R-project.org/package=prisonbrief)

# prisonbrief: An R package that returns tidy data from the World Prison Brief website

The goal of `prisonbrief` is to download, clean and return data from the [World Prison Brief website](http://www.prisonstudies.org/). The World Prison Brief is an online database compiled by the [Institute for Criminal Policy Research](http://www.icpr.org.uk/) with information on prison systems around the world. Data currently cover 223 jurisdictions and have been collected from public sources. The `prisonbrief` package provides easy-to-use functions to convert WPB data into a format convenient for statistical analysis.

## Installation

The stable version of `prisonbrief` is available on [CRAN](https://cran.r-project.org/package=prisonbrief). To install it, just type:

```{r cran, eval = FALSE}
install.packages("prisonbrief")
```

You can install the most recent development version of `prisonbrief` using the `remotes` package. First, you need to install the `remotes` package with the following code:

```{r remotes-installation, eval = FALSE}
if(!require(remotes)) install.packages("remotes")
```

Then you can install `prisonbrief` from [its GitHub repository](https://github.com/danilofreire/prisonbrief):

```{r gh-installation, eval = FALSE}
remotes::install_github("danilofreire/prisonbrief")
```

If you are using Linux, you may need to type the following command before installing `prisonbrief`:

```{bash linux-dependency, eval = FALSE}
sudo apt-get install libudunits2-dev
```

`prisonbrief` relies on some spatial-data packages in order to return data as simple features dataframes. You may need to install packages such as `rgeos` if you do not already have them installed.  

## Usage

`prisonbrief` is quite simple to use. The package contains only three functions, all of them starting with `wpb`, a mnemonic for World Prison Brief.

The first is a convenience function named `wpb_list()`. It prints a list of available countries to the console.

```{r wpb-list}
library(prisonbrief)

wpb_list()
```

The second function is `wpb_table()`. This function returns a series of variables about the prison systems of the world, of a particular region, or of a specific country. For instance, the code below downloads prison data for Africa:

```{r africa}
africa <- wpb_table(region = "Africa")
names(africa)
```

The region choices are "Africa", "Asia", "Caribbean", "Central America", "Europe", "Middle East", "North America", "Oceania", "South America" and "All".

`wpb_table()` also provides geometric shapes for maps. For instance, you can download and plot the prison population rate in South America with only a few lines of code:

```{r ggpplot-map, eval = FALSE}
south_america <- wpb_table(region = "South America")

library(ggplot2)
ggplot(south_america, aes(fill = prison_population_rate)) +
        geom_sf() +
        scale_fill_distiller(palette = "YlOrRd", trans = "reverse") +
        theme_minimal()
```

![](http://i.imgur.com/JxO0wCr.png)

The function can also be used to retrieve data for a single country. The data returned are parsed from the single country tables, however, and are not ready for quantitative analysis without further cleaning (removing parentheses etc.). Since some of this information may be relevant, we have chosen to leave it in. Data from regions instead of a single country are fully prepared for automated analysis.

Finally, we have added the `wpb_series()` function to the package. The function downloads and tidies the tables describing the trends in the prison population total and the prison population rate for every jurisdiction included in the project. Below is an example taken from [Germany's country profile](http://www.prisonstudies.org/country/germany):

![](http://i.imgur.com/vtbrtg1.png)

You can retrieve the same information with the following code:

```{r germany}
germany <- wpb_series(country = "Germany")
germany
```

`wpb_series()` can also be combined with `wpb_list()` to make interesting time series graphs. The code below downloads data for all countries then plots the prison population rate for Brazil, Germany, Russia and the United States:

```{r for-loop, warning = FALSE, error = FALSE, eval = FALSE}
library(dplyr)

x <- list()
countries <- wpb_list()
for(i in 1:nrow(countries)){
  y <- try(wpb_series(country = countries$country_url[i]), silent = FALSE)
  if(class(y) != 'try-error'){
    x[[i]] <- y
  } else{
    next
  }
}
X <- data.table::rbindlist(x, fill = TRUE) %>%
  dplyr::full_join(countries, by = c("Country" = "country_url"))

X %>% dplyr::filter(country_name %in% c("Brazil",
                                        "Germany",
                                        "Russian Federation",
                                        "United States of America")) %>%
        ggplot(aes(x = Year, y = `Prison population rate`,
                   group = country_name, colour = country_name)) +
        geom_line() +
        theme_minimal()
```

![](http://i.imgur.com/lIUhO5E.png)

## Contributions

`prisonbrief` was written by [Danilo Freire](http://danilofreire.github.io/) and [Robert Myles McDonnell](https://www.robertmylesmcdonnell.com/). Feedback and comments are most welcome. If you have any suggestions on how to improve this package feel free to [open an issue on GitHub](https://github.com/danilofreire/prisonbrief/issues).

## Citation

You can cite the `prisonbrief` package with:

```{r citation}
citation("prisonbrief")
```

Please also cite the source as [World Prison Brief, Institute for Criminal Policy Research](http://www.prisonstudies.org/about-us).

Owner

JOSS Publication

prisonbrief: An R package that returns tidy data from the World Prison Brief website

Published

February 05, 2018

DOI

10.21105/joss.00361

Volume 3, Issue 22, Page 361

Authors

Danilo Freire
Department of Political Economy, King's College London

Robert Myles McDonnell
Avanade

Editor

Karthik Ram

Tags

data prison rstats world prison data

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages