spanishoddata: Get Spanish Origin-Destination Data <a href="https://rOpenSpain.github.io/spanishoddata/"><img src="man/figures/logo.png" align="right" width="200" alt="spanishoddata website" /></a>

<!-- badges: start -->

<a href="https://lifecycle.r-lib.org/articles/stages.html#stable" target="_blank"><img src="https://img.shields.io/badge/lifecycle-stable-brightgreen.svg" alt="Lifecycle: stable" /></a> <a href="https://CRAN.R-project.org/package=spanishoddata" target="_blank"><img src="https://www.r-pkg.org/badges/version/spanishoddata" alt="CRAN status" /></a> <a href="https://CRAN.R-project.org/package=spanishoddata" target="_blank"><img src="https://cranlogs.r-pkg.org/badges/grand-total/spanishoddata?color=blue" alt="CRAN/METACRAN Total downloads" /></a> <a href="https://CRAN.R-project.org/package=spanishoddata" target="_blank"><img src="https://cranlogs.r-pkg.org/badges/spanishoddata?color=blue" alt="CRAN/METACRAN Downloads per month" /></a>

<!-- 10.5281/zenodo.14516104 --> <!-- badges: end -->

spanishoddata is an R package that provides functions for downloading and formatting Spanish open mobility data released by the Spanish government (Ministerio de Transportes y Movilidad Sostenible (MITMS) 2024).

It supports the two versions of the Spanish mobility data. The first version (2020 to 2021), covering the period of the COVID-19 pandemic, contains tables detailing trip numbers and distances, broken down by origin, destination, activity, residence province, time interval, distance interval, and date. It also provides tables of individual counts by location and trip frequency. The second version (2022 onwards) improves spatial resolution, adds trips to and from Portugal and France, and introduces new fields for study-related activities and sociodemographic factors (income, age, and sex) in the origin-destination tables, along with additional tables showing individual counts by overnight stay location, residence, and date. See the package website and vignettes for v1 and v2 data for more details.

spanishoddata is designed to save time by providing the data in analysis-ready formats. Automating the process of downloading, cleaning, and importing the data can also reduce the risk of errors in the laborious process of data preparation. It also reduces computational resources by using computationally efficient packages behind the scenes. To effectively work with multiple data files, it’s recommended you set up a data directory where the package can search for the data and download only the files that are not already present.

Under the hood, spanishoddata uses the efficient DuckDB database engine via <a href="https://r.duckdb.org/" target="_blank"><code>{duckdb}</code></a> R package and is featured in the <a href="https://duckdb.org/library/spanishoddata-r-package/" target="_blank">DuckDB Library</a>.

Examples of available data

<div id="fig-barcelona-flows">

<img src="vignettes/media/flows_plot_barcelona.svg" style="width:100.0%" />

Figure 1: Example of the data available through the package: daily flows in Barcelona on 7 April 2021

</div>

To create static maps like that see our vignette here.

---

<div id="fig-spain-flows">

Figure 2: Example of the data available through the package: interactive daily flows in Spain

</div> <div id="fig-spain-flows">

Figure 3: Example of the data available through the package: interactive daily flows in Barcelona with time filter

</div>

To create interactive maps see our vignette here.

Install the package

Install from CRAN:

install.packages("spanishoddata")

<details> <summary>

Alternative installation and developemnt

</summary>

You can also install the latest development version of the package from rOpenSpain R universe:

install.packages("spanishoddata",
  repos = c("https://ropenspain.r-universe.dev",
    "https://cloud.r-project.org"))

Alternative way to install the development version from GitHub:

if (!require("remotes")) install.packages("remotes")

remotes::install_github("rOpenSpain/spanishoddata",
  force = TRUE, dependencies = TRUE)

For Developers

To load the package locally, clone it and navigate to the root of the package in the terminal, e.g. with the following:

gh repo clone rOpenSpain/spanishoddata
code spanishoddata
# with rstudio:
rstudio spanishoddata/spanishoddata.Rproj

Then run the following command from the R console:

devtools::load_all()

</details>

You can also explore the package and the data in an interactive RStudio container right in your web browser thanks to Binder, just click the link or the button: . Note that the session will be limited by memory and you will only be able to work with one full day of data.

Load it as follows:

library(spanishoddata)

Set the data directory

Choose where {spanishoddata} should download (and convert) the data by setting the data directory following command:

spod_set_data_dir(data_dir = "~/spanish_od_data")

The function above will also ensure that the directory is created and that you have sufficient permissions to write to it.

<details> <summary>

Setting data directory for advanced users

</summary>

You can also set the data directory with an environment variable:

Sys.setenv(SPANISH_OD_DATA_DIR = "~/spanish_od_data")

The package will create this directory if it does not exist on the first run of any function that downloads the data.

To permanently set the directory for all projects, you can specify the data directory globally by setting the SPANISH_OD_DATA_DIR environment variable, e.g. with the following command:

usethis::edit_r_environ()
# Then set the data directory globally, by typing this line in the file:

SPANISH_OD_DATA_DIR = "~/spanish_od_data"

You can also set the data directory locally, just for the current project. Set the ‘envar’ in the working directory by editing .Renviron file in the root of the project:

file.edit(".Renviron")

</details>

Overall approach to accessing the data

If you only need flows data aggregated by day at municipal level, you can use the spod_quick_get_od() function. This will download the data directly from the web API and let you analyse it in-memory. More on this in the Quickly get daily data vignette.

If you only want to analyse the data for a few days, you can use the spod_get() function. It will download the raw data in CSV format and let you analyse it in-memory. This is what we cover in the steps on this page.

If you need longer periods (several months or years), you should use the spod_convert() and spod_connect() functions, which will convert the data into special format which is much faster for analysis, for this see the Download and convert OD datasets vignette. spod_get_zones() will give you spatial data with zones that can be matched with the origin-destination flows from the functions above using zones ’id’s. Please see a simple example below, and also consult the vignettes with detailed data description and instructions in the package vignettes with spod_codebook(ver = 1) and spod_codebook(ver = 2), or simply visit the package website at https://ropenspain.github.io/spanishoddata/. The <a href="#fig-overall-flow" class="quarto-xref">Figure 4</a> presents the overall approach to accessing the data in the spanishoddata package.

<div id="fig-overall-flow">

<img src="man/figures/package-functions-overview.svg" style="width:78.0%" />

Figure 4: The overview of package functions to get the data

</div>

Showcase

To run the code in this README we will use the following setup:

library(tidyverse)
theme_set(theme_minimal())
sf::sf_use_s2(FALSE)

Get metadata for the datasets as follows (we are using version 2 data covering years 2022 and onwards):

metadata <- spod_available_data(ver = 2) # for version 2 of the data
metadata

# A tibble: 9,442 × 6
   target_url           pub_ts              file_extension data_ym data_ymd  
   <chr>                <dttm>              <chr>          <date>  <date>    
 1 https://movilidad-o… 2024-07-30 10:54:08 gz