*********************************************************************************************
*********************************************************************************************
Guide to Reproduce the Analyses and Results Presented in the Paper and Supplementary Material 
*********************************************************************************************
*********************************************************************************************

Paper: Acosta, E., van Raalte, A.A. (2019) APC Curvature Plots: Displaying Nonlinear Age-Period-Cohort Patterns on Lexis Plots. 
Demographic Research 
acosta@mpg.demogr.de

This guide presents the material required to fully reproduce the analyses and results presented in the paper. 
All the scripts were performed using R version: 3.6.1 (R Core Team 2019). 
Data inputs, scripts, and this document, are all available in the OSF link: https://osf.io/5bmyz/


*********************************
Procedure for reproducing results
*********************************

Open the master script (00_master.R) in a new R session. This script will execute all scripts required for reproducing the 
analyses and plots of the paper. 

Before executing this master script, make sure to introduce within the quotation marks in lines 21-28 your username and password 
for the Human Mortality Database (HMD) and the Human Fertility Database (HFD). This information is required for constructing the 
APC curvature plots 6, 7, A2, and A3.

If you are not yet registered in these databases, you can do it in the respective websites
https://www.mortality.org/
https://www.humanfertility.org/

Our scripts assume that the current working directory is the folder in which the master script (00_master.R) lives.  
If you open a new R session by double-clicking on the master file (00_master.R) then the current working directory should be 
set correctly.

You can also set the working directory to the folder where the master script (00_master.R) lives by typing a setwd()command in the 
R console. For example, on a Windows system you might type
* setwd(C:/Users/Jane/apc_curvature_plots_rep_material/)
whereas on a Mac you might type
* setwd(/Users/Jane/apc_curvature_plots_rep_material/)


*****************************************************
Description of the files contained in the ZIP archive
*****************************************************

The zip. file contains 1 data file and 12 scripts


FOLDER: "data"
**************
* db_drugs_deaths_exposures_race.csv
Contains all drug-related male deaths and exposure-to-risk in the United States for the period 1990-2016, 
by single years of age, and race/ethnicity.

The mortality counts (456.776 deaths) were obtained from the micro-data files of the U.S. National Vital Statistics System. 
Here, we define drug-related mortality as deaths involving drug use registered in the categories of accidental and undetermined 
intent overdoses, or in the categories of mental or behavioral causes (i.e., ICD 10 codes F11-19, F55, X40-44, Y10-14).
The raw files are available in http://www.nber.org/data/vital-statistics-mortality-data-multiple-cause-of-death.html

The exposure to death data come from the HMD and the proportion by race and ethnicity was estimated from the Bridged-Race 
Population Estimates. The raw files are available in https://www.cdc.gov/nchs/nvss/bridged_race/data_documentation.htm


FOLDER: "scripts"
*****************
These are the R-files for generating the main results described in the paper. 
All these scripts are called from the master script 

* aa00_preparing_R_session.R
Script for preparing the R session: Installing and loading required packages for running the scripts

* an01_smooth_US_mort_by_race_1990_2016.R
Estimation of smoothed, interpolated, and excess death rates of drug mortality in the US, by race

* an02_excess_from_dAPC_Carstensen_function.R
Script for estimating of excess death rates of drug mortality in the US, by race, as the difference between the smoothed mortality 
rates and a baseline obtained from a dAPC model with the cohort terms set at zero

* fg01_obs_&_smth_drugs.R
Script for plotting Figure 1: Lexis surface of observed and smoothed drug-related mortality rates for Hispanic males in the United 
States

* fg02_drugs_cohort_effects.R
Script for plotting Figure 2: Relative risks of drug-related mortality for cohorts of Hispanic males in the United States

* fg03_surfaces_change.R
Script for plotting Figure 3: Lexis surfaces of changes in drug-related mortality rates over age/cohort and over period/cohort for 
Hispanic males in the United States

* fg04a_excess_from_interpolation.R
Script for plotting Figure 4a: Lexis surfaces of the excess drug-related mortality rates for male Hispanic boomers in the United 
States during 1990-2016, ages 15-75. Excess mortality rates (/100k) estimated as the difference between the smoothed mortality rates 
and an interpolated baseline that omits the 1940-1970 cohorts from the Lexis mortality surface. 

* fg04b_excess_from_dAPC_curvatures.R
Script for plotting Figure 4a: Lexis surfaces of the excess drug-related mortality rates for male Hispanic boomers in the United 
States during 1990-2016, ages 15-75. Excess mortality rates (/100k) estimated as the difference between the smoothed mortality rates 
and a baseline obtained from a dAPC model with the cohort terms set at zero; i.e., centered at the linear trend component of the 
cohort effects.

* fg05_APC_curvatures_plot_boomers.R
Script for plotting Figures 5 and A1: APC curvature plot of the features of excess drug-related mortality among four racial/ethnic 
groups of boomer males in the United States 

* fg06_APC_curvatures_plot_young_hump.R
Script for plotting Figures 6 and A2: APC curvature plot of the features of excess mortality in young adult males in four countries

* fg07_APC_curvatures_plot_cohort_fertility.R
Script for plotting Figures 7 and A3: APC curvature plot of cohort fertility rate peaks in three countries


FOLDER: "figures"
*****************
All figures (1 to 7, and A1 to A3) will be stored in this folder