Readme.Rmd

---
title: 'README-file to template paper titled ''Foreign-born population in European Countries'' by Ruben Dewitte'
author: "Ruben Dewitte"
date: "`r Sys.Date()`"
output:
  md_document:
    variant: gfm
  word_document:
    toc: yes
  pdf_document: 
    toc: yes
  html_document:
    number_sections: yes
    toc: yes
    toc_float: yes
bibliography: bibliography.bib  
csl: chicago-author-date-withnotes.csl
---

```{r setup, include=FALSE}
library(knitr)
```

# Overview

The code in this replication package performs analysis using two data sources (@oecd2022foreign; @duncalfe2022countries) using R. A Master file runs all of the code to generate the data for the 1 figures in the paper. The replicator should expect the code to run for about 1 min.

# Data Availability and Provenance Statements

The data relied on in this paper can be found in the './input' folder of the repository and is described in the Table below:

```{r,echo = FALSE}


data_descr = rbind.data.frame(
              oecd = c("./input/foreign_born_OECD.csv", "[@oecd2022foreign]", "yes", "The foreign-born population covers all people who have ever migrated from their country of birth to their current country of residence. The foreign-born population data shown here include people born abroad as nationals of their current country of residence. The difference across countries between the size of the foreign-born population and that of the foreign population depends on the rules governing the acquisition of citizenship in each country. This indicator is measured as a percentage of population."),
              country_codes = c("./input/country_codes.csv", "[@duncalfe2022countries]", "yes", "ISO-3166 Country and Dependent Territories Lists with UN Regional Codes")
)
colnames(data_descr) = c("Data File", "Source", "Provided", "Additional information")


kable(data_descr)
```

# Computing environment

This code was run on a `r R.version$platform` platform of a `r Sys.info()["sysname"]` `r Sys.info()["release"]` (`r Sys.info()["version"]`) computer. 

The analysis is conducted in the R programming environment. R is free, open-source and available for download [here](https://www.r-project.org/). The code has been tested against R version `r R.version$version.string`.

Once R is successfully set up on your system, you will need to install a number of external R libraries. I have used renv to snapshot the project’s R environment. To install all of the necessary R libraries, simply open R at the project root (e.g. by clicking on the .Rproj file) and run the following commands:

```r
## Run these commands in R

# install.packages("renv") ## Only necessary if the renv package is not yet installed on your computer
# renv::init()  ## Only necessary if you didn't open the repo as an RStudio project
renv::restore(confirm = FALSE)
```

# Instructions to replicators

All code files in this repository are referred to through the package here(). This package finds the root as the place where the '.Rproj' file is located. For this repository, the .Rproj file is located in the root folder, referred to as './'. 

The structure of replication package is indicated in the `./code/00_MASTER.R' file. Running this Master file will reproduce all the results of this analysis and assign these results to their respective output folders.


## Mapping of Tables and Figures to programs

A mapping of the Figures displayed in the paper to the respective programs can be found below: 

```{r,echo = FALSE}
fig_descr = rbind.data.frame(
              fig1 = c(NA,"./code/02_analysis.R", "./output/figures/foreign_born.png"," ")
)
fig_descr[,1] = 1:nrow(fig_descr)
colnames(fig_descr) = c("Nr.", "Program", "Output", "Note")


kable(fig_descr)
```

A mapping of the Tables displayed in the paper to the respective programs can be found below: 

```{r,echo = FALSE}
tab_descr = rbind.data.frame(
              tab1a = c(NA,"./code/02_analysis.R", "./output/tables/foreign_born.tex"," "),
              tab1b = c(NA,"./code/02_analysis.R", "./output/tables/foreign_born.docx"," ")

)
tab_descr[,1] = 1:nrow(tab_descr)
colnames(tab_descr) = c("Nr.", "Program", "Output", "Note")


kable(tab_descr)
```

# References