# Instructions for Repetition of Study

This file describes how to reproduce the analysis of "Identification of the Mode of Evolution in Incomplete Carbonate Successions"

## Authors

__Niklas Hohmann__  
Utrecht University  
email: n.hohmann [at] uu.nl  
Web page: [uu.nl/staff/NHohmann](uu.nl/staff/NHohmann)  
Orcid: [0000-0003-1559-1838](https://orcid.org/0000-0003-1559-1838)

## Reproducibility

There are multiple ways to reproduce and repeat the study:

1. Full reproduction, where all data is generated anew from scratch
2. Inspection of the provided data
3. Reproduction of figures alone

Each point is described separately, and can be performed independent of the others.

## 1. Full reproduction of data

### 1.1 Simulate carbonate platform in CarboCATLite

1. Clone the "scenarioA" branch of the CarboCATLite repository from [here](https://github.com/MindTheGap-ERC/CarboCATLite/tree/scenarioA).
2. Run the file "carbocatGUI.m" in Matlab.
3. Click initialize in the GUI. The GUI after initialization is saved under "figs/matlab/scenarioA_initial_conditions.pdf".
4. Click "Run CA model". This will start the model run, progress is displayed in the console.
5. Once the console outputs indicates the run is finished, save the _glob_ variable in your workspace. The generated data is identical to the data saved under "data/matlab_outputs/scenarioA_glob_matlab_outputs.mat". It constains all the raw data generated by CarboCAT.
6. Click "Plot run" to generate the chronostratigraphic chart and dip section. This figure is saved under "data/matlab_outputs/figs/scenarioA_dip_section_and_chronostrat.pdf". This might take a while.

Repeat for the branch _scenarioB_, which is available [here](https://github.com/MindTheGap-ERC/CarboCATLite/tree/scenarioB). The generated data is available in "data/matlab_outputs/scenarioB_glob_matlab_outputs.mat", the figures are "data/matlab_outputs/figs/scenarioB_initial_conditions.pdf" and "data/matlab_outputs/figs/scenarioB_dip_section_and_chronostrat.pdf"

For a description of the data generated by Matlab, see _codebook.md_ in the _data/matlab_outputs/_ folder.

### 1.2 Extract age-depth models from CarboCATLite

Run _data/matlab_outputs/get_adm_from_carbocat_outputs.m" in Matlab. This extracts age-depth information from the CarboCATLite outputs and generates the file "scenarioA_and_B_matlab_to_R.mat", which can be read into R.

### 1.3 Run analyses in R

Open the R Project in Rstudio as described in _README_. Then run

```r
source("code/process_adm_from_matlab.R")
```

in R. This imports the age-depth models into R, calculates hiatus durations and (in)completeness, and saves the results in "data/R_outputs/ageDepthModelsScenariosAandB.Rdata". See _codebook.md_ in the same folder for a description of the data saved.

Next, run

```r
source("code/parameters_for_tests.R")
```

to load the parameters for the sets, and save them under "data/R_outputs/parameters_for_tests.Rdata". See _codebook.md_ in the same folder for a description of the data saved.

Last, run

```r
source("code/simulate_and_test_modes_of_evolution.R")
```

to run the tests based on the specified parameters and age-depth models. Runtime is multiple hours! The results are saved under under "data/R_outputs/results_modes_of_evolution.Rdata". See _codebook.md_ in the same folder for a description of the data saved.

From here, you can continue to inspect the generated data or generate the plots as described below.

## 2. Inspection of provided data

All data is in the folder _/data/_. For a detailed description of the data structure and contents see the file _/data/R_outputs/codebook.md_ (for outputs from R) and _/data/matlab_outputs/codebook.md_ (for outputs from matlab).

R outputs can be visualized using the scripts in _code/visualize_data.R_.

## 3. Reproduction of figures

To reproduce the figures in the main test and supplementary material, open the R project ad described in the _README_, download the data as described in the section above, and run

```r
source("code/make_plots.R")
```

This will use the data in _/data/R_outputs/_ to generate summary figures in the folder _/figs/R/_

NOTE: Only the figures displaying AIC weights make use of the test results stored in _/data/R_outputs/results_modes_of_evolution.Rdata_. All lineages are simulated anew when _make_plots_ is run. To make the plots reproducible, they can be seeded via the parameter _plot_seed_ for each figure.  
This is a result of the study design. The tests simulate lineages at a specific basin position. Because trait values are random, this makes it impossible to compare __identical__ simulated lineages across multiple basin positions. This problem is circumvented in the functions used for plotting, see _/code/make_plots.R_ for details.