| Title: | Age-structured EPP Model for HIV Epidemic Estimates |
|---|---|
| Description: | What the package does (one paragraph). |
| Authors: | Jeff Eaton [aut, cre] |
| Maintainer: | Jeff Eaton <[email protected]> |
| License: | GPL-3 |
| Version: | 0.8.4 |
| Built: | 2024-12-06 16:27:08 UTC |
| Source: | https://github.com/mrc-ide/eppasm |
Calculate all-cause mortality rate by single year of age and sex from a
spec object.
## S3 method for class 'spec' agemx(mod, nonhiv = FALSE)## S3 method for class 'spec' agemx(mod, nonhiv = FALSE)
mod |
output of simmod of class |
Mortality in year Y is calculated as the number of deaths occurring from the mid-year of year Y-1 to mid-year Y, divided by the population size at the mid-year of year Y-1. !!! NOTE: This might be different from the calculation in Spectrum. Should confirm this with John Stover.
3-dimensional array of mortality by age, sex, and year.
Age-specific ART coverage among pregnant women
agepregartcov( mod, fp, aidx = 3:9 * 5 - fp$ss$AGE_START + 1L, yidx = 1:fp$ss$PROJ_YEARS, agspan = 5, expand = FALSE )agepregartcov( mod, fp, aidx = 3:9 * 5 - fp$ss$AGE_START + 1L, yidx = 1:fp$ss$PROJ_YEARS, agspan = 5, expand = FALSE )
expand |
whether to expand aidx, yidx, sidx, and agspan |
Age-specific prevalence among pregnant women
agepregprev( mod, fp, aidx = 3:9 * 5 - fp$ss$AGE_START + 1L, yidx = 1:fp$ss$PROJ_YEARS, agspan = 5, expand = FALSE )agepregprev( mod, fp, aidx = 3:9 * 5 - fp$ss$AGE_START + 1L, yidx = 1:fp$ss$PROJ_YEARS, agspan = 5, expand = FALSE )
expand |
whether to expand aidx, yidx, sidx, and agspan |
Prevalence by arbitrary age groups
ageprev( mod, aidx = NULL, sidx = NULL, yidx = NULL, agspan = 5, expand = FALSE, VERSION = "C" )ageprev( mod, aidx = NULL, sidx = NULL, yidx = NULL, agspan = 5, expand = FALSE, VERSION = "C" )
sidx |
sex (1 = Male, 2 = Female, 0 = Both) Notes: Assumes that AGE_START is 15 and single year of age. |
Prepare design matrix indices for ANC prevalence predictions
ancsite_pred_df(ancsite_df, fp)ancsite_pred_df(ancsite_df, fp)
ancsite_df |
data.frame of site-level ANC design for predictions |
fp |
fixed parameter input list |
pjnz <- system.file("extdata/testpjnz", "Botswana2017.PJNZ", package="eppasm") bw <- prepare_spec_fit(pjnz, proj.end=2021.5) bw_u_ancsite <- attr(bw$Urban, "eppd")$ancsitedat fp <- attr(bw$Urban, "specfp") ancsite_pred_df(bw_u_ancsite, fp)pjnz <- system.file("extdata/testpjnz", "Botswana2017.PJNZ", package="eppasm") bw <- prepare_spec_fit(pjnz, proj.end=2021.5) bw_u_ancsite <- attr(bw$Urban, "eppd")$ancsitedat fp <- attr(bw$Urban, "specfp") ancsite_pred_df(bw_u_ancsite, fp)
Annualized number of new infections
calc_infections_eppspectrum(fp, pop, hivpop, artpop, i, ii, r_ts)calc_infections_eppspectrum(fp, pop, hivpop, artpop, i, ii, r_ts)
Create simulation inputs fixed parameters
create_spectrum_fixpar( projp, demp, hiv_steps_per_year = 10L, proj_start = projp$yr_start, proj_end = projp$yr_end, AGE_START = 15L, relinfectART = projp$relinfectART, time_epi_start = projp$t0, popadjust = FALSE, targetpop = demp$basepop, artelig200adj = TRUE, who34percelig = 0, frr_art6mos = projp$frr_art6mos, frr_art1yr = projp$frr_art6mos, projection_period = NULL, art_dropout_recover_cd4 = NULL )create_spectrum_fixpar( projp, demp, hiv_steps_per_year = 10L, proj_start = projp$yr_start, proj_end = projp$yr_end, AGE_START = 15L, relinfectART = projp$relinfectART, time_epi_start = projp$t0, popadjust = FALSE, targetpop = demp$basepop, artelig200adj = TRUE, who34percelig = 0, frr_art6mos = projp$frr_art6mos, frr_art1yr = projp$frr_art6mos, projection_period = NULL, art_dropout_recover_cd4 = NULL )
If argument 'projection_period = NULL', R determines the projection period based on the Spectrum version number. For version <= 6.19, projection period is '"midyear"', and for version >= 6.20, projection period is '"calendar"'.
Get vector of years spanned by projections
get_proj_years(ss)get_proj_years(ss)
EPP-ASM tracks the CD4 distribution and ART duration of the HIV population by coarse age groups '15-16, 17-19, 20-24, ..., 45-49, 50+' for computational efficiency.
hivpop_singleage(mod, ss)hivpop_singleage(mod, ss)
mod |
EPP-ASM model output of class 'spec' |
ss |
Model state space inputs |
'hivpop_singleage' converts the coarse age group CD4 distribution and ART coverage to single year of age counts assuming uniform proportions in each category within coarse age groups.
pjnz <- system.file("extdata/testpjnz", "Botswana2018.PJNZ", package="eppasm") fp <- prepare_directincid(pjnz) mod <- simmod(fp) hivp1 <- hivpop_singleage(mod, fp$ss)pjnz <- system.file("extdata/testpjnz", "Botswana2018.PJNZ", package="eppasm") fp <- prepare_directincid(pjnz) mod <- simmod(fp) hivp1 <- hivpop_singleage(mod, fp$ss)
Implements IMIS algorithm with optional optimization step (Raftery and Bao 2010).
imis( B0, B, B_re, number_k, opt_k = NULL, fp, likdat, prior = eppasm::prior, likelihood = eppasm::likelihood, sample_prior = eppasm::sample.prior, dsamp = eppasm::dsamp, save_all = FALSE )imis( B0, B, B_re, number_k, opt_k = NULL, fp, likdat, prior = eppasm::prior, likelihood = eppasm::likelihood, sample_prior = eppasm::sample.prior, dsamp = eppasm::dsamp, save_all = FALSE )
B0 |
number of initial samples to draw |
B |
number of samples at each IMIS iteration |
B_re |
number of resamples |
number_k |
maximum number of iterations |
opt_k |
vector of iterations at which to use optimization step to identify new mixture component |
fp |
fixed model parameters |
likdat |
likeihood data |
prior |
function to calculate prior density for matrix of parameter inputs |
likelihood |
function to calculate likelihood for matrix of parameter inputs |
sample_prior |
function to draw an initial sample of parameter inputs |
dsamp |
function to calculate density for initial sampling distribution (may be equal to prior) |
save_all |
logical whether to save all sampled parameters |
list with items resample, stat, and center
Incidence rate among adults age 15-49 years
incid(mod, ...)incid(mod, ...)
mod |
model output |
This returns incidence rate calculated as the number of infections during the projection period divded by the number susceptible at the mid-point of the projection period. This is the default incidence calculation for Spectrum version >=6.2 For Spectrum versions <=6.19 incidence was calculated as number of infections divided by susceptible population at the start of the projection year.
Return HIV incidence calculated as number of infections among age 15-49 population divided by susceptible population at the start of the projection year. This was the standard HIV incidence calculation reported by Spectrum up to version <=6.19. From Spectrum version >=6.2, the incidence rate is reported divided by the projection period population.
incid15to49_eppinput_specres(x)incid15to49_eppinput_specres(x)
x |
'specres' object created by 'read_hivproj_output()'. |
Pointwise likelihood for site-level ANC observations given site-level effects
ll_ancsite_conditional(mod, fp, newdata, b_site)ll_ancsite_conditional(mod, fp, newdata, b_site)
Log likelihood for age-specific household survey prevalence
ll_hhsage(mod, fp, dat, pointwise = FALSE)ll_hhsage(mod, fp, dat, pointwise = FALSE)
Log likelihood for age-specific household survey prevalence using binomial approximation
ll_hhsage_binom(mod, fp, dat, pointwise = FALSE)ll_hhsage_binom(mod, fp, dat, pointwise = FALSE)
Log likelihood for age-specific household survey prevalence
ll_hhsartcov(mod, fp, dat, pointwise = FALSE)ll_hhsartcov(mod, fp, dat, pointwise = FALSE)
Calculate log-likelihood for nationally representative incidence estimates from a household survey. Currently implements likelihood for a log-transformed direct incidence estimate and standard error. Needs to be updated to handle incidence assay outputs.
ll_hhsincid(mod, fp, hhsincid.dat)ll_hhsincid(mod, fp, hhsincid.dat)
mod |
model output, object of class 'spec'. |
hhsincid.dat |
prepared houshold survey incidence estimates (see perp |
Melt ANC-SS and site-level ANC-RT to long dataset
melt_ancsite_data(eppd)melt_ancsite_data(eppd)
'mod_dimnames' assigns dimnames to spec model outputs.
mod_dimnames(mod, ss)mod_dimnames(mod, ss)
mod |
EPP-ASM model output of class 'spec' |
ss |
Model state space inputs |
EPP-ASM model output with labelled dimensions
pjnz <- system.file("extdata/testpjnz", "Botswana2018.PJNZ", package="eppasm") fp <- prepare_directincid(pjnz) mod <- simmod(fp)pjnz <- system.file("extdata/testpjnz", "Botswana2018.PJNZ", package="eppasm") fp <- prepare_directincid(pjnz) mod <- simmod(fp)
Calculate all-cause mortality rate by single year of age and sex from a
spec object.
## S3 method for class 'spec' natagemx(mod)## S3 method for class 'spec' natagemx(mod)
mod |
output of simmod of class |
Mortality in year Y is calculated as the number of non-HIV deaths occurring from the mid-year of year Y-1 to mid-year Y, divided by the population size at the mid-year of year Y-1. !!! NOTE: This might be different from the calculation in Spectrum. Should confirm this with John Stover.
3-dimensional array of mortality by age, sex, and year.
Prepare site-level ANC prevalence data for EPP random-effects likelihood
prepare_ancsite_likdat(ancsitedat, fp)prepare_ancsite_likdat(ancsitedat, fp)
ancsitedat |
data.frame of site-level ANC data |
fp |
fixed parameter input list, including state space |
Prepare direct incidence input EPP simulation
prepare_directincid(pjnz, method = "directincid_hts")prepare_directincid(pjnz, method = "directincid_hts")
method |
Method for intercalating new infections. Either "directincid_ann" for annual new infections or "directincid_hts" for new infections each HIV time step. |
Prepare age-specific HH survey prevalence likelihood data
prepare_hhsageprev_likdat(hhsage, fp)prepare_hhsageprev_likdat(hhsage, fp)
## Household survey ART coverage likelihood
prepare_hhsartcov_likdat(hhsartcov, fp)prepare_hhsartcov_likdat(hhsartcov, fp)
Prepare household survey incidence likelihood data
prepare_hhsincid_likdat(hhsincid, fp)prepare_hhsincid_likdat(hhsincid, fp)
Setup the r-hybrid model
prepare_rhybrid( fp, tsEpidemicStart = fp$ss$time_epi_start + 0.5, rw_start = fp$rw_start, rw_trans = fp$rw_trans, rw_dk = fp$rw_dk )prepare_rhybrid( fp, tsEpidemicStart = fp$ss$time_epi_start + 0.5, rw_start = fp$rw_start, rw_trans = fp$rw_trans, rw_dk = fp$rw_dk )
fp |
model parameters object |
tsEpidemicStart |
time step at which epidemic is seeded |
rw_start |
time when random walk starts |
rw_trans |
number of years to transition from logistic differences to RW differences. If NULL, defaults to 5 steps |
Prepare fit by EPP regions
prepare_spec_fit( pjnz, proj.end = 2016.5, popadjust = NULL, popupdate = TRUE, use_ep5 = FALSE )prepare_spec_fit( pjnz, proj.end = 2016.5, popadjust = NULL, popupdate = TRUE, use_ep5 = FALSE )
pjnz |
file path to Spectrum PJNZ file. |
proj.end |
end year for projection. |
popupdate |
logical should target population be updated to match age-specific population size from DP file and %Urban from EPP XML. |
Read CSAVR input data
read_csavr_data(pjnz)read_csavr_data(pjnz)
pjnz |
file path to Spectrum PJNZ file. |
Read Spectrum internal files file from PJNZ
read_dp(pjnz, use_ep5 = FALSE)read_dp(pjnz, use_ep5 = FALSE)
pjnz |
file path to Spectrum PJNZ file. |
Read annual incidence input
read_incid_input(pjnz)read_incid_input(pjnz)
pjnz |
file path to Spectrum PJNZ file. |
Spectrum has a debug mode option to output a file recording the entire state space when a model simulation is computed. This function parse the *_pop1.xlsx file into long-format data.frame.
read_pop1(pop1file, country, years = 2000:2021)read_pop1(pop1file, country, years = 2000:2021)
pop1file |
path to *_pop1.xlsx export file |
country |
string giving the identifying country / region name to be added as a column in the output file |
years |
integer vector of years to extract |
TODO: tidy up the dependencies in this function: reshape, pryr, readxl.
TODO: Insert instructions for how to enter Spectrum debug mode.
'years' must be in the file as sheets, but this is not currently checked. It will fail hard. Inserting a check for this would make it fail softer.
A data.frame consisting of pop1 file in long format
Sample posterior predictions for site-level ANC observations
sample_ancsite_pred(mod, fp, newdata, b_site)sample_ancsite_pred(mod, fp, newdata, b_site)
Sample from posterior ditribution for ANC site level random effects
sample_b_site(mod, fp, dat, resid = TRUE)sample_b_site(mod, fp, dat, resid = TRUE)
Sample from conditional posterior distribution for variance parameter
sample_invgamma_post(x, prior_shape, prior_rate)sample_invgamma_post(x, prior_shape, prior_rate)
Simulate model
simmod(fp, ...)simmod(fp, ...)
fp |
fixed parameter input object |
... |
Arguments to be passed to methods |
Add dimnames to EPP-ASM model output
spec_add_dimnames(mod, fp)spec_add_dimnames(mod, fp)
mod |
output from 'simmod()' |
fp |
fixed parameters input to 'simmod()' |
Input 'mod' object with dimnames applied to arrays.