crossfire is a package created to give easier access to the datasets of the project Fogo Cruzado, which is a digital collaboration platform to register gun shootings in the metropolitan areas of Rio de Janeiro and Recife.
The package facilitates data extraction from the project open-data API, developed by Volt Data Lab.
Please note that as of Nov. 2020, due to changes in Fogo Cruzado's API, user's should update crossfire to its' 0.2.0 version. The get_fogocruzado() function from the 0.1.0 version returns errors and cannot be used.
Currently, the crossfire package can be installed directly from its GitHub repository:
if (!require("devtools")) install.packages("devtools")
devtools::install_github("voltdatalab/crossfire")
Once installed, it can be loaded using the library function.
library(crossfire)
crossfire has 3 functions: fogocruzado_signin, get_fogocruzado and get_cities. Below, we explain how they can be used.
To access Fogo Cruzado's API, users should be registered and insert their e-mail and password for authentication. fogocruzado_signin function registers these information on the current R session, so that it can be used to obtain the Bearer token to extract data using the API.
As noted, the function sets the e-mail and password in the current R environment. Thus, users should repeat this operation on every new R session in which they intend to use the crossfire package. We note that user and password are personal. Therefore, users should be careful when writing and saving them in R scripts, in order to avoid sharing these information.
# Registers user and password
fogocruzado_signin(email = "example@account_exeample.com", password = "pass")
crossfire main function is get_fogocruzado. It allows the extraction from slices to the whole dataset of shootings registered by Fogo Cruzado. The function returns a data frame, in which each line corresponds to a shooting registered and its information. The function has the following arguments: city, initial_date, final_date, state, and security_agent.
cityallows to filter the observations by some cities. Their default returns all observations. The complete list of cities can be found using theget_citiesfunction.
# Extract data for all registered shootings
fogocruzado_all <- get_fogocruzado()
# Extract data for shootings in the cities of Rio de Janeiro and Recife
fogocruzado_rj_recife <- get_fogocruzado(city = c("Rio de Janeiro", "Recife"))
initial_dateandfinal_datelet users select observations according to a certain period of time. The default is set to the current date as the final date and considers a 6-month interval to set the initial date. For the new API version, the package limits requests to a maximum of 210 days (roughly 7 months), which can cover any interval from the full dataset. (Fogo Cruzado has been collecting data about Rio de Janeiro's metropolitan area since July 5th, 2016 and Recife's metropolitan area since April 1st, 2018). Initial and final dates should be included ascharacterin the"YYYY-MM-DD"format.
# Extract all data from 2018
fogocruzado_2018 <- get_fogocruzado(initial_date = "2018-07-01", final_date = "2018-12-31")
statelet users filter occurences according to the country's state where they happened. Default returns all observations.
# Get all data from shootings registered in Pernambuco
fogocruzado_pe <- get_fogocruzado(state = "PE")
security_agentallows users to select shootings according to the presence of security agents in the occurrence, assuming the value ofsecurity_agent = 1when they are present, andsecurity_agent = 0- when they're not.
# Extract data from occurents where security agents were present
fogocruzado_security <- get_fogocruzado(security_agent = 1)
get_cities() returns a data.frame with information about all cities from the Rio de Janeiro and Recife metropolitan areas covered by the Fogo Cruzado initiative.
cities <- get_cities()