Package 'eppasm'

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.7.6
Built: 2024-10-23 05:30:52 UTC
Source: https://github.com/mrc-ide/eppasm

Help Index


Age-specific mortality

Description

Calculate all-cause mortality rate by single year of age and sex from a spec object.

Usage

## S3 method for class 'spec'
agemx(mod, nonhiv = FALSE)

Arguments

mod

output of simmod of class spec.

Details

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.

Value

3-dimensional array of mortality by age, sex, and year.


Age-specific ART coverage among pregnant women

Description

Age-specific ART coverage among pregnant women

Usage

agepregartcov(
  mod,
  fp,
  aidx = 3:9 * 5 - fp$ss$AGE_START + 1L,
  yidx = 1:fp$ss$PROJ_YEARS,
  agspan = 5,
  expand = FALSE
)

Arguments

expand

whether to expand aidx, yidx, sidx, and agspan


Age-specific prevalence among pregnant women

Description

Age-specific prevalence among pregnant women

Usage

agepregprev(
  mod,
  fp,
  aidx = 3:9 * 5 - fp$ss$AGE_START + 1L,
  yidx = 1:fp$ss$PROJ_YEARS,
  agspan = 5,
  expand = FALSE
)

Arguments

expand

whether to expand aidx, yidx, sidx, and agspan


Prevalence by arbitrary age groups

Description

Prevalence by arbitrary age groups

Usage

ageprev(
  mod,
  aidx = NULL,
  sidx = NULL,
  yidx = NULL,
  agspan = 5,
  expand = FALSE,
  VERSION = "C"
)

Arguments

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

Description

Prepare design matrix indices for ANC prevalence predictions

Usage

ancsite_pred_df(ancsite_df, fp)

Arguments

ancsite_df

data.frame of site-level ANC design for predictions

fp

fixed parameter input list

Examples

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

Description

Annualized number of new infections

Usage

calc_infections_eppspectrum(fp, pop, hivpop, artpop, i, ii, r_ts)

Create simulation inputs fixed parameters

Description

Create simulation inputs fixed parameters

Usage

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
)

Details

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

Description

Get vector of years spanned by projections

Usage

get_proj_years(ss)

Convert aggregate HIV population to single year

Description

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.

Usage

hivpop_singleage(mod, ss)

Arguments

mod

EPP-ASM model output of class 'spec'

ss

Model state space inputs

Details

'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.

Examples

pjnz <- system.file("extdata/testpjnz", "Botswana2018.PJNZ", package="eppasm")
fp <- prepare_directincid(pjnz)
mod <- simmod(fp)
hivp1 <- hivpop_singleage(mod, fp$ss)

Incremental Mixture Importance Sampling (IMIS)

Description

Implements IMIS algorithm with optional optimization step (Raftery and Bao 2010).

Usage

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
)

Arguments

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

Value

list with items resample, stat, and center


Incidence rate among adults age 15-49 years

Description

Incidence rate among adults age 15-49 years

Usage

incid(mod, ...)

Arguments

mod

model output

Details

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.


Incidence rate age 15-49 using previous-year susceptible population

Description

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.

Usage

incid15to49_eppinput_specres(x)

Arguments

x

'specres' object created by 'read_hivproj_output()'.


Pointwise likelihood for site-level ANC observations given site-level effects

Description

Pointwise likelihood for site-level ANC observations given site-level effects

Usage

ll_ancsite_conditional(mod, fp, newdata, b_site)

Log likelihood for age-specific household survey prevalence

Description

Log likelihood for age-specific household survey prevalence

Usage

ll_hhsage(mod, fp, dat, pointwise = FALSE)

Log likelihood for age-specific household survey prevalence using binomial approximation

Description

Log likelihood for age-specific household survey prevalence using binomial approximation

Usage

ll_hhsage_binom(mod, fp, dat, pointwise = FALSE)

Log likelihood for age-specific household survey prevalence

Description

Log likelihood for age-specific household survey prevalence

Usage

ll_hhsartcov(mod, fp, dat, pointwise = FALSE)

Log-likelhood for direct incidence estimate from household survey

Description

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.

Usage

ll_hhsincid(mod, fp, hhsincid.dat)

Arguments

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

Description

Melt ANC-SS and site-level ANC-RT to long dataset

Usage

melt_ancsite_data(eppd)

Add dimnames to spec model output

Description

'mod_dimnames' assigns dimnames to spec model outputs.

Usage

mod_dimnames(mod, ss)

Arguments

mod

EPP-ASM model output of class 'spec'

ss

Model state space inputs

Value

EPP-ASM model output with labelled dimensions

Examples

pjnz <- system.file("extdata/testpjnz", "Botswana2018.PJNZ", package="eppasm")
fp <- prepare_directincid(pjnz)
mod <- simmod(fp)

Non-HIV age-specific mortality

Description

Calculate all-cause mortality rate by single year of age and sex from a spec object.

Usage

## S3 method for class 'spec'
natagemx(mod)

Arguments

mod

output of simmod of class spec.

Details

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.

Value

3-dimensional array of mortality by age, sex, and year.


Prepare site-level ANC prevalence data for EPP random-effects likelihood

Description

Prepare site-level ANC prevalence data for EPP random-effects likelihood

Usage

prepare_ancsite_likdat(ancsitedat, fp)

Arguments

ancsitedat

data.frame of site-level ANC data

fp

fixed parameter input list, including state space


Prepare direct incidence input EPP simulation

Description

Prepare direct incidence input EPP simulation

Usage

prepare_directincid(pjnz, method = "directincid_hts")

Arguments

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

Description

Prepare age-specific HH survey prevalence likelihood data

Usage

prepare_hhsageprev_likdat(hhsage, fp)

## Household survey ART coverage likelihood

Description

## Household survey ART coverage likelihood

Usage

prepare_hhsartcov_likdat(hhsartcov, fp)

Prepare household survey incidence likelihood data

Description

Prepare household survey incidence likelihood data

Usage

prepare_hhsincid_likdat(hhsincid, fp)

Setup the r-hybrid model

Description

Setup the r-hybrid model

Usage

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
)

Arguments

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

Description

Prepare fit by EPP regions

Usage

prepare_spec_fit(
  pjnz,
  proj.end = 2016.5,
  popadjust = NULL,
  popupdate = TRUE,
  use_ep5 = FALSE
)

Arguments

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

Description

Read CSAVR input data

Usage

read_csavr_data(pjnz)

Arguments

pjnz

file path to Spectrum PJNZ file.


Read Spectrum internal files file from PJNZ

Description

Read Spectrum internal files file from PJNZ

Usage

read_dp(pjnz, use_ep5 = FALSE)

Arguments

pjnz

file path to Spectrum PJNZ file.


Read annual incidence input

Description

Read annual incidence input

Usage

read_incid_input(pjnz)

Arguments

pjnz

file path to Spectrum PJNZ file.


Read Spectrum _pop1.xlsx export file

Description

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.

Usage

read_pop1(pop1file, country, years = 2000:2021)

Arguments

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

Details

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.

Value

A data.frame consisting of pop1 file in long format


Sample posterior predictions for site-level ANC observations

Description

Sample posterior predictions for site-level ANC observations

Usage

sample_ancsite_pred(mod, fp, newdata, b_site)

Sample from posterior ditribution for ANC site level random effects

Description

Sample from posterior ditribution for ANC site level random effects

Usage

sample_b_site(mod, fp, dat, resid = TRUE)

Sample from conditional posterior distribution for variance parameter

Description

Sample from conditional posterior distribution for variance parameter

Usage

sample_invgamma_post(x, prior_shape, prior_rate)

Simulate model

Description

Simulate model

Usage

simmod(fp, ...)

Arguments

fp

fixed parameter input object

...

Arguments to be passed to methods


Add dimnames to EPP-ASM model output

Description

Add dimnames to EPP-ASM model output

Usage

spec_add_dimnames(mod, fp)

Arguments

mod

output from 'simmod()'

fp

fixed parameters input to 'simmod()'

Value

Input 'mod' object with dimnames applied to arrays.