YFV_Brazil

Code and results for 'Joint epidemiological and phylodynamic inference of sylvatic yellow fever transmission drivers in Southeast Brazil'

Overview

This repository contains the complete analytical pipeline for investigating sylvatic yellow fever virus (YFV) transmission dynamics in Southeast Brazil. The analysis combines:

• Epidemiological and demographic modeling of case sampling rates of infected non-human primates and transmission dynamics
• Joint inference using EpiFusion to reconstruct transmission dynamics from phylogenetic trees and case incidence data
• Environmental driver analysis examining relationships between meteorological variables (temperature, precipitation, NDVI, ENSO) and transmission
• Spillover modeling quantifying the relationship between non-human primate (NHP) prevalence and human spillover events

The analysis focuses on two major YFV clades: SP (São Paulo) and MG/ES/RJ (Minas Gerais, Espírito Santo, Rio de Janeiro).

Repository Structure

YFV_Brazil/
├── Data/                    # All data files (raw, intermediate, clean)
│   ├── Raw/                 # Raw data files
│   ├── Intermediate/        # Intermediate processing outputs
│   ├── Clean/               # Cleaned data ready for analysis
│   └── EpiFusion_XMLs/      # EpiFusion parameter files
├── Scripts/                 # Analysis scripts (run in numerical order)
│   ├── 0-clean_data_fill_nas.R
│   ├── 1-calculate_case_sampling_rate.R
│   ├── 2-model_transmission_dynamics.R
│   ├── 3-model_meteorological_relationships.R
│   ├── 4-model_spillover_relationship.R
│   ├── 5-clean_plotting_data_and_results.R
│   ├── S2-multiple_imputation_sensitivity_analysis.R
│   ├── S4-sampling_rate_interval_sensitivity_analysis.R
│   ├── S7-individual_lagged_environmental_effects.R
│   ├── S8-testing_environmental_interactions.R
│   ├── S9-comparison_infections_vs_cases_environmental_effects.R
│   └── Z-plotting_utilities.R
├── Results/                 # Model outputs and results
│   ├── Case_Sampling_Rate/
│   ├── Dynamics/
│   ├── Meteorological_Drivers/
│   ├── Spillover/
│   └── Supplementary/
├── Plotting/                 # Processed data for figure generation
├── Figs/                     # Generated figures (PDF, PNG, PPTX)
├── Tables/                   # Generated manuscript tables
└── figures_and_tables.Rmd    # R Markdown file to generate all figures

Workflow

The analysis proceeds through six main scripts (numbered 0-5) run sequentially, followed by supplementary sensitivity analyses. See Scripts/README.md for detailed descriptions of each script.

Main pipeline: Data cleaning → Case sampling rate estimation → Joint inference → Environmental driver analysis → Spillover modeling → Plotting data preparation

Figure generation: The figures_and_tables.Rmd file generates all manuscript figures (including supplementary Figures S1-S18) and tables using processed results from the Plotting/ directory.

Dependencies

R Packages

The analysis requires the following R packages:

Core packages:

• dplyr, tidyverse, magrittr - Data manipulation
• ggplot2 - Plotting
• mgcv - Generalized additive models
• mice - Multiple imputation
• ape, ggtree - Phylogenetic tree handling
• sf, raster, geobr - Spatial data processing
• ncdf4, exactextractr - NetCDF data handling

Specialized packages:

• EpiFusionUtilities - EpiFusion joint inference analysis utilities
• survival, pammtools, ggsurvfit - Survival analysis
• hdrcde, HDInterval - Statistical intervals
• MetBrewer - Color palettes
• castor - Phylogenetic utilities
• naniar - Missing data visualization
• lme4 - Mixed effects models
• parallel - Parallel processing

For figure generation:

• knitr, rmarkdown - R Markdown processing
• ggarrange (from ggpubr) - Figure arrangement

External Software

• EpiFusion - Required for YFV dynamics inference (see script 2 for details)
• R (version 4.0+ recommended)
• RStudio (optional but recommended)

External Data Requirements

The following data files are not included in this repository due to file size restrictions or publication embargoes. To fully replicate the analysis, you will need to obtain these data from the sources listed below. Many of the resulting intermediary files from these sources are already included on the repo, however, so it's still possible to run most of the analysis by using those files (albeit it just makes the workflow slightly less straightforward than sourcing each script in order!)

Phylogenetic Tree

• File: Data/Raw/YFV_outbreakClade_HKYG_Skygrid_Uncorr.combined.MCC.tre
• Status: Excluded until publication of Hill et al.
• Source: Hill et al. (2022) - "Phylogeographic reconstruction of yellow fever virus transmission in Brazil"
• Access: Please contact the authors of Hill et al. (medRxiv, 2022) to request access to the phylogenetic tree
• Used in: Script 0 (tree processing), Script 2 (EpiFusion models), Script 5 (plotting)

Non-human Primate Population Rasters

• File: Data/Raw/PRIMATE_DATA_FROM_ARRAN/ (ignored in .gitignore)
• Status: Excluded but available on request from Arran Hamlet
• Source: Hamlet (2020) - "Yellow Fever in South America: The Role of Environment and Host on Transmission Dynamics"
• Access: Please contact the Arran Hamlet to request access
• Used in: Script 0 (primate population calculation)

Meteorological Data

The following large meteorological datasets are excluded due to file size but are publicly available:

ERA5 and ERA5-Land Data

• Files:
  • Data/Raw/Raw_ERA5_TotalPrecipitation/*.nc - Total precipitation
  • Data/Raw/Raw_ERA5Land_Temperature/*.nc - 2-meter air temperature
• Source: Copernicus Climate Change Service (C3S)
• Access:
  • ERA5: Available from the Copernicus Climate Data Store (CDS)
  • ERA5-Land: Available from the Copernicus Climate Data Store (CDS)
• Time period needed: 2014-2018 (study period)
• Variables:
  • ERA5: Total precipitation (tp)
  • ERA5-Land: 2-meter temperature (t2m)
• Used in: Script 0 (data processing)
• Note: You will need to register for a free account on the CDS to download data

NDVI PROBA-V Data

• Files: Data/Raw/NDVI_PROBA-V/*.nc - Normalized Difference Vegetation Index
• Source: PROBA-V satellite (European Space Agency / Copernicus)
• Access: Available from the Copernicus Global Land Service
• Time period needed: 2014-2018 (study period)
• Product: PROBA-V NDVI 1km (V3.0.1)
• Used in: Script 0 (data processing)
• Note: Data are available as NetCDF files

Large Model Outputs

The following directories contain large model outputs that are excluded but processed summaries are included:

• Results/Dynamics/mgesrj_fixedtree_timevaryingsampling/* - Raw EpiFusion posterior samples for MG/ES/RJ clade
• Results/Dynamics/sp_fixedtree_timevaryingsampling/* - Raw EpiFusion posterior samples for SP clade
• Results/Meteorological_Drivers/5_Fold_Cross_Validation_Models/* - Individual cross-validation model files
• Results/Supplementary/S7-Univariate_Lagged_AICs/*/* - Individual lagged model files and variable-specific subdirectories
• Results/Supplementary/S7-Univariate_Lagged_AICs/*posteriors* - Posterior sample files from lag analysis
• Results/Supplementary/S8-Variable_Interactions/models/* - Individual interaction model files
• Results/Supplementary/S8-Variable_Interactions/plots/* - Interaction plot PDF files

Note: Processed summaries of these results are included in the repository (e.g., Results/Dynamics/*.RDS files, summary tables in Supplementary directories), so you can reproduce figures and downstream analyses without the raw outputs. However, to fully replicate Script 2, Script 3, or supplementary scripts, you would need to run the models yourself (which is computationally intensive).

Data Processing Notes

• Script 0 processes the raw meteorological NetCDF files and creates cleaned CSV files in Data/Clean/Meteorological/
• The cleaned meteorological data files are included in the repository, so you can run Scripts 3-5 without the raw data
• To run Script 0 in full, you would need all the raw data listed above

Data Organization

Raw Data (Data/Raw/)

• Phylogenetic tree: YFV_outbreakClade_HKYG_Skygrid_Uncorr.combined.MCC.tre (not included in repository - see .gitignore)
• Primate survival data from empirical studies
• Primate population distribution rasters (Data/Raw/PRIMATE_DATA_FROM_ARRAN/) — not included in the repository; see Non-human Primate Population Rasters under External Data Requirements
• Human case data (fa_casoshumanos_1994-2023.csv)
• Vaccination coverage inputs (cpnibr17374588965.csv, with auxiliary raw RDS files)
• ENSO data (Weekly_ENSO_SSTA3.4.csv)
• Meteorological data (ERA5 temperature and precipitation, NDVI PROBA-V) - stored externally due to size

Clean Data (Data/Clean/)

Organized by data type:

• Epidemiological/ - Case data, occurrence data with imputed missing values
• Phylogenetic/ - Processed trees and metadata for each clade
• Meteorological/ - Processed environmental variables with appropriate lags
• Demographic/ - Primate population estimates and yearly vaccination coverage by clade

Results Organization

Results/

• Case_Sampling_Rate/ - Sampling rate estimates and parametric fits
• Dynamics/ - EpiFusion outputs: R(t) trajectories, infection estimates
• Meteorological_Drivers/ - GAM models, effect sizes, cross-validation results
• Spillover/ - DLNM models and predictions
• Supplementary/ - Results from sensitivity analyses

Plotting/

Contains processed RDS files ready for figure generation:

• dynamics_table.RDS - Transmission dynamics summaries
• sampling_table.RDS - Sampling rate summaries
• environmental_effects_table.RDS - Environmental effect sizes
• spillover_effects_table.RDS - Spillover effect sizes
• Additional files for supplementary figures

Reproducing the Analysis

Disclaimer: There are parts of this analysis that we don't recommend running in their entirety as they took a few weeks to run due to the long duration of the study period (5 years) (e.g. the EpiFusion models)

Quick Start

1. Install R dependencies:

   # Install CRAN packages
   install.packages(c("dplyr", "tidyverse", "mgcv", "mice", "ape", "ggtree", 
                      "ggplot2", "sf", "raster", ...))
   
   # Install EpiFusionUtilities (if available)
   # Note: This may require special installation instructions

2. Prepare data:

   • Ensure all raw data files are in Data/Raw/
   • Note: The phylogenetic tree file is excluded from the repository (see .gitignore)

3. Run analysis scripts in order:

   source("Scripts/0-clean_data_fill_nas.R")
   source("Scripts/1-calculate_case_sampling_rate.R")
   source("Scripts/2-model_transmission_dynamics.R")  # May require pre-computed EpiFusion results
   source("Scripts/3-model_meteorological_relationships.R")
   source("Scripts/4-model_spillover_relationship.R")
   source("Scripts/5-clean_plotting_data_and_results.R")

4. Generate figures:

   rmarkdown::render("figures_and_tables.Rmd")

Important Notes

• EpiFusion runs: The full EpiFusion analysis (script 2) takes 1-2 weeks on HPC. The script can parse pre-computed results if available.
• Large data files: Some raw meteorological data files are excluded from the repository due to size (see .gitignore).
• Phylogenetic tree: The master phylogenetic tree is excluded until publication of Hill et. al (see .gitignore).
• Computational resources: Some analyses (particularly GAM fitting) benefit from parallel processing and may require substantial memory.

Citation

If you use this code or results, please cite this repository for now, but hopefully soon a publication by the following:

Judge, C., Iani, F.C.M., Finch, E., Gaythorpe, K.A.M., Faria, N.R., Hill, S.C., Brady, O.J., Joint epidemiological and phylodynamic inference of sylvatic yellow fever transmission drivers in Southeast Brazil

Authors

• Ciara Judge*
• Felipe C.M. Iani
• Emilie Finch
• Katy A.M. Gaythorpe
• Nuno R. Faria
• Sarah C. Hill
• Oliver J. Brady

*ciara.judge@biology.ox.ac.uk

License

See LICENSE file for details.

Contact

For questions about the code or analysis, please open an issue on the GitHub repository or contact the corresponding author.

Use of AI disclaimer

LLMs such as ChatGPT were used as an assistant debug code during the analysis, and Cursor was used to generate README files for this repository. All outputs from LLMs were examined by a real person before their inclusion in the project.