#################################################################################
#################################################################################

README file for the replication code of

"Factoring in the micro: a transaction level dynamic factor approach to the decomposition of export volatility"

##################################################################################
##################################################################################

The folder FitM_code contains all the scripts to replicate all the results and other associated analysis presented in the paper.

This README file provides the instruction to run all the steps of the code, including inforamtion on the input needed and the output produced.

The folder "data_raw" contains a demo dataset and other auxiliary data. These are provided as an example of the inputs that are needed to run
all the scripts, giving information on the required format, and they can be used to test the scripts using the instructions provided.

##################################################################################
##################################################################################

Proceed with the following steps.
NOTE: always run the R scripts in an Rstudio session opening the project FitM_code.Rproj

##################################################################################
1. Dataset preparation and statistics. Folder: "~/FitM_code/data_preparation"
##################################################################################

 1.1 Copy the input files into the folder "data_raw" 
     i) a dataset of the series of export levels for each firm-destination cell: "export_val_country_quart_dataset_1993_2017.csv"
     ii) a dataset associating the firm SIREN (i.e. the firm id): "siren_sec.RData"

 1.2 Run the script "main_data_preparation.R". This script has the following scopes: 
     i) provide summary statisics and plots of the data; 
     ii) filtering the destinations as outlined in Section 3; 
     iii) subsampling the dataset to run the estimate on the block Dynamic Factor models on the subdatasets.
     Inputs: files at the points 1.1.1 and 1.1.2
     Outputs: i) Tables and Figures for the summary statistics. Saved in "~/FitM_code/data_preparation/data_summary/"
              ii) A set of csv files associated to the dataset subsamples, containing the export growth rates of each firm-destination cell.
                  Saved in a folder of the form "~/FitM_code/estimation_scripts/Input/results_samples_CC_Yk"
		  The name of the folder depends on the parameters of the filtering and subsampling. CC is the number of destinations, Yk is the number of firms 
                  selected in each sample.

##################################################################################
2. Estimation of the model. Folder: "~/FitM_code/estimation_scripts"
##################################################################################

 2.1 Open MATLAB and add to path the folder FitM_code and its subfolders. Set the folder "~/FitM_code/estimation_scripts" as working directory.
     Install the "Statistical and Machine Learning toolbox" if not installed.
     Run the script "main_estimation.m".
     Inputs: Folder with csv files associated to the subsamples contained in a folder of the form "~/FitM_code/estimation_scripts/Input/results_samples_CC_Yk"
     Outputs: Estimates of the parameters and latent factors defined by the block DFM
	      Saved in: "~/FitM_code/results_analysis/Input/results_samples_CC_Yk"
	      File names. Factors -> results_h_F.csv; 
                          Loadings -> results_h_C.csv; 
                          Series means -> results_h_M.csv; 
                          Series variances -> results_h_W.csv

##################################################################################
3. Replication of the results by Di Giovanni et al. 2014 
##################################################################################

 3.1 Prepare the data
     Open in R, possibly in RStudio, the rstudio project FitM_code.Rproj.
     Open and run the R script "prepare_data_for_replication.R" in the folder "~/FitM_code/DiGiovanni_et_al_replication".
     Input: i)  a dataset of the series of export levels for each firm-destination cell: "export_val_country_quart_dataset_1993_2017.csv"
     	    ii) a dataset associating the firm SIREN (i.e. the firm id): "sirens_sec.csv"
            iii) the list of the destinations selected at the filtering step (1.2.ii): "countries.RData"
     Output: Two datasets of export growth rates at a quarterly and yearly freuqency with the variable name used in the original scripts.
	     Quarterly frequency: "long_panel_quarterly.dta". Saved in: "~/FitM_code/DiGiovanni_et_al_replication/Input/"
             Yearly frequency: "long_panel_yearly.dta". Saved in: "~/FitM_code/DiGiovanni_et_al_replication/Input/"

 3.2 Estimate a static orthogonal decomposition model à la Di Giovanni et al. 2014
     Open STATA and run the script "main.do" in the folder "~/FitM_code/DiGiovanni_et_al_replication"
     Input:  Two datasets of export growth rates at a quarterly and yearly freuqency as produced in step 3.1.
	     Quarterly frequency: "long_panel_quarterly.dta". Saved in: "~/FitM_code/DiGiovanni_et_al_replication/Input/"
             Yearly frequency: "long_panel_yearly.dta". Saved in: "~/FitM_code/DiGiovanni_et_al_replication/Input/"
     Output: Dataset of the models components for two specification (destination and sector effects and destination effects only) and two frequencies.
	     Saved in: "~/FitM_code/DiGiovanni_et_al_replication/Output/"
	     File names. Components estimated using destination and sector effects at a quarterly freq. -> growth_regs_capays_destsec_quarterly.csv
                         Components estimated using destination effects only at a quarterly freq. -> growth_regs_capays_quarterly.csv
                         Components estimated using destination and sector effects at a yearly freq. -> growth_regs_capays_destsec_yearly.csv
                         Components estimated using destination effects only at a quarterly freq. -> growth_regs_capays_yearly.csv
    Notice: auxiliary STATA and MATLAB scripts are preserved in the folder and can be used to complete the analysis of Di Giovanni et al., 
            yet they are not used to produce the outputs of our paper. All the results are produced in the next step using the four outputs above.

##################################################################################
4. Produce the ouput results of the paper. Figures and tables.
##################################################################################

 4.1 Run the analysis of the results at the aggregate level
     Open in R, possibly in RStudio, the rstudio project FitM_code.Rproj.
     Open and run the R script "results_analysis_aggregate.R" in the folder "~/FitM_code/results_analysis".
   
 4.2 Run the analysis of the results at the firm level
     Open in R, possibly in RStudio, the rstudio project FitM_code.Rproj.
     Open and run the R script "results_analysis_firm.R" in the folder "~/FitM_code/results_analysis".
   

 
