Data and code from publication: Marine animal diversity across latitudinal and temperature gradients during the Phanerozoic

Data and code from publication: Marine animal diversity across latitudinal and temperature gradients during the Phanerozoic

# Running the analysis for Benson, Close et al. Marine animal diversity across latitudinal and temperature gradients during the Phanerozoic. 2025. Palaeontology. This document drafted on 23 April 2025 by Roger Close and Roger Benson.

## Data description
The occurrence data for marine animals downloaded from the Paleobiology Database (www.paleobiodb.org) in CSV format and used to run this analysis are contained in the folder `./input/marine_inverts/PBDB_CSV_data_downloads/2022-05-23-14-15-24/`. Time intervals downloaded at the same time as occurrence data is in "./input/pbdb_time_int.csv".

## Files and variables

In RStudio, open on the file 'marine-lbg-ms.RProj' to load the project.

To run the analysis, run `run-master-script.R` via Rscript. To run the analysis in Rscript, open a Terminal session (either in the bottom left pane of RStudio, or by opening a command-line session with the container as described above with `docker exec`). Then navigate to the project directory (marine-lbg-ms-code-submission-2025-04-22) and type:
`Rscript --vanilla run-master-script.R &> run-master-script.log &`

This will run the analysis in the background in Rscript. You can monitor the progress of the analysis by typing:
`tail -f run-master-script.log`

This will print the console output in real time to show you what's going on. You can also use `top` or `htop` to monitor CPU and RAM usage.

The file `run-master-script.R` sets up some aspects of the analysis and then runs the script `master-script.R`. `master-script.R` calls subscripts in "./subscripts/" to run each part of the analysis --- descriptions of each subscript are given in comments before they are sourced in `master-script.R`; see that file for details. Plotting scripts are in "./subscripts/plotting-scripts/". Custom functions are in "./functions/" and "./geoMST-functions/".

Most analysis settings are specified in the file `./analysis-settings-files/settings-for-including-almost-everything.R` (ignore this filename --- it is a holdover from earlier drafts of the analysis).

If you set `new_output_folder` to TRUE in `run-master-script.R`, it will create a new date/timestamped folder in `./output/marine_inverts/` to contain the results (the analysis codename is appended to the folder name). Otherwise, it will use the last-used folder (if one exists; saved in `./input/current_datestamped_folder.rda`). 

If a folder containing results already exists, the analysis can be reloaded into an empty RStudio session by navigating to the folder in the file browser, clicking the file `click-to-reload-folder-name.rda` (which loads objects like `folder.name` so the analysis knows what output folder is in use), loading the packages by running the appropriate line in `run-master-script`, and then sourcing `master-script.R`. If the final saved workspace exists in `./output/marine_inverts/<datestamped-results-folder>/saved-workspaces/marine_inverts_spatial_subsampling_results_999.RDataFS`, it will be loaded; otherwise, the highest saved workspace will be loaded (numbered from 1-10 throughout `master-script.R`). This allows loading the most recent point in the analysis (if an error caused it to fail, for example).

Figures used in the study are saved in the output folder, within the associated date/timestamped subfolder.

A record the analysis settings is saved in a datestamped CSV file beginning with `analysis_settings` in the datestamped output folder.

## Code/software
The code described above was run in R version 4.2.1. All of the R packages needed to run the project are contained in the renv library in the main folder (`./renv`). Run the command `renv::restore()` to restore all of the R packages from the lockfile.

## Access information
The occurrence data for marine animals downloaded from the Paleobiology Database (www.paleobiodb.org) on 2022-05-23-14-15-24.

##Summary of file directory 

marine-lbg-ms-code-submission-2025-04-22
    marine-lbg-ms.Rproj
        -In RStudio, open on the file 'marine-lbg-ms.RProj' to load the project.
    run-master-script.R
        -To run the analysis, run `run-master-script.R` via Rscript (see above)
    input
        country-codes.csv  
            -ISO country codes and their translations from https://r2.datahub.io/clt97y5hy0000jz087j66iiuk/main/raw/data/country-codes.csv are provided in "./input/country-codes_csv.csv". Column heads: official_name_en    ISO3166-1-Alpha-2    Continent    `Region Name`    `Region Code` (ISO country codes and names)    
        exclude-terms (names and terms to exclude unsuitable occurrence records, provided by Roger Benson and Richard Butler; self-explanatory)             
            -egg-terms.txt 
            -marine-tetrapod-terms.txt
            -terrestrial_and_freshwater_taxa.R
            -trace-terms.txt
        gcm_data_df.rda    
            -General Circulation Model (GCM) data from Bristol BRIDGE project (provided by Alexander Farnsworth) is contained in "./input/gcm_data_df.rda".
        haq_sealevel_curve.csv    
            -Sea level data from Haq et al. (1987) is contained in "./input/haq_sealevel_curve.csv". Column heads: Age (Ma)    SL (compared to present) (self-explanatory)
        marine_inverts             
            -Subfolder containing data analysed in the study, downloaded from the Paleobiology Database (www.paleobiodb.org) on 23 May 2022. Definitions of column heads can be found at https://paleobiodb.org/data1.2/occs/list_doc.html
        marine_regions.csv   
            -Modern continental regions defined by Roger Close are defined in "./input/marine_regions.csv". Column heads: country_name, country_code, super_region_name, region_name, region_code, subregion, oceanic_island (self-explanatory)
        onshore_environments.csv 
            -Onshore/offshore environments defined by Roger Close for PBDB environment values are defined in "./input/onshore_environments.csv". Column heads: environment, onshore (T/F) (self-explanatory)
        PaleoDEMS netcdf           
            -Scotese PALEOMAP netCDF files from https://www.earthbyte.org/paleodem-resource-scotese-and-wright-2018/ are in "./input/PaleoDEMS netcdf/"
        PaleoReefs DB downloads  
            -Subfolder containing PARED PaleoReefs DB data downloads provided by Wolfgang Kiessling are contained in "./input/PaleoReefs DB downloads/". Only lat (latitude), lng (longitude), max_ma (oldest date) and min_ma (youngest date) are used in the analysis --- contact Wolfgang Kiessling for defintions of other variables).
            -Other column heads are provided to preserve the original context of the data: r_number    name    country    formation    system    series    intervall    max_ma    min_ma    time_slice_text    reliabilit    subsurface_text    type_text    thickness_text    m_thick    width_text    m_width    extension_text    m_ext    ext_belt    belonging    tropical_text    environment_text    subenvironment_text    bathymetry_text    biota_main_t    biota_sec_text    biota_deta_text    alg_type_text    p_lmc    p_arag    p_hmc    upwell_text    control_text    diversity_text    m_spec    guild_text    macro_bor_text    micro_bor_text    vert_zonat_text    hor_zonat_text    micrite_text    sparite_text    debris_text    dolomite_text    reservoir_text    latit    longit    collection    pal_lat_scotese    pal_long_scotese
        pbdb_time_int.csv          
            -Time interval definitions downloaded from the Paleobiology Database (www.paleobiodb.org) on 23 May 2022. Definitions of column heads can be found at https://paleobiodb.org/data1.2/intervals/list_doc.html
        scotese.shapes.RData
            -Scotese PALEOMAP palaeomap shapefiles obtained from Christopher Scotese.
    analysis-settings-files
        settings-for-including-almost-everything.R
            -Most analysis settings are specified in the file `./analysis-settings-files/settings-for-including-almost-everything.R`
    functions
        -Subfolder containing custom functions used by the script
    geoMST-functions
        -Subfolder containing custom functions used by the script

    master-plotting-script.R
    master-script.R
    run-master-plotting-script.R
    renv
    subscripts
        -The above are subsections of the analysis, sourced by master-script.R or subscripts thereof, with descriptions found in those files.