Package 'cystiSim' reference manual

Package 'cystiSim'

Title:	Agent-Based Model for Taenia_solium Transmission and Control
Description:	The cystiSim package provides an agent-based model for Taenia solium transmission and control. cystiSim was developed within the framework of CYSTINET, the European Network on taeniosis/cysticercosis, COST ACTION TD1302.
Authors:	Brecht Devleesschauwer [aut, cre], Uffe Christian Braae [aut]
Maintainer:	Brecht Devleesschauwer <[email protected]>
License:	GPL (>= 2)
Version:	0.1.2
Built:	2025-03-06 04:48:25 UTC
Source:	https://github.com/brechtdv/cystisim

Title:

Agent-Based Model for Taenia_solium Transmission and Control

Description:

The cystiSim package provides an agent-based model for Taenia solium transmission and control. cystiSim was developed within the framework of CYSTINET, the European Network on taeniosis/cysticercosis, COST ACTION TD1302.

Authors:

Brecht Devleesschauwer [aut, cre], Uffe Christian Braae [aut]

Maintainer:

Brecht Devleesschauwer <[email protected]>

License:

GPL (>= 2)

Version:

0.1.2

Built:

2025-03-06 04:48:25 UTC

Source:

https://github.com/brechtdv/cystisim

Help Index

Agent-based model for Taenia solium transmission and control.

Description

The cystiSim model allows simulating Taenia solium taeniosis/cysticercosis transmission in a virtual population of humans and pigs. It also allows evaluating the possible effects of human mass drug administration, pig mass drug administration, and pig vaccination. cystiSim was developed within the framework of CYSTINET, the European Network on taeniosis/cysticercosis, COST ACTION TD1302 (http://www.cystinet.org/).

Details

Package:	cystiSim
Version:	0.1.2
Date:	2020-02-26
Authors:	Brecht Devleesschauwer, Uffe Christian Braae
Maintainer:	[email protected]
URL:	https://github.com/brechtdv/cystiSim
BugReports:	https://github.com/brechtdv/cystiSim/issues
Depends:	R (>= 3.6.0), ggplot2
Imports:	magrittr, knitr
License:	GPL (>= 2)
LazyLoad:	yes

Available functions in the cystiSim package:

baseline
`random_baseline_man`	Generate a random baseline human population.
`random_baseline_pig`	Generate a random baseline pig population.

model—S3 class '`cystiRun`'
`fit`	Fit parameters of a `cystiRun` model.
`initiate`	Initiate a `cystiRun` model.
`update`	Update a `cystiRun` model.

interventions
`do_man_mda`	Do human mass drug administration.
`do_pig_mda`	Do pig mass drug administration.
`do_pig_vac`	Do pig vaccination.
`do_pig_mda_vac`	Do pig mass drug administration AND vaccination.

simulate—S3 class '`cystiSim`'
`cystiSim`	Simulate multiple `cystiRun` models.
`report`	Generate a PDF report for a `cystiSim` object.
`elim`	Derive when elimination occurred in a `cystiSim` object.

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Random baseline populations

Description

Generate random baseline human and pig populations.

Usage

random_baseline_man(n, p)
random_baseline_pig(n, p, p.high, size, mu)
random_baseline_man(n, p)
random_baseline_pig(n, p, p.high, size, mu)

Arguments

`n`	Number of individuals to simulate.
`p`	Proportion of individuals infected with a mature parasite.
`p.high`	Proportion of infected pigs with high infection intensity.
`size`	Size of Negative Binomial distribution of age-specific slaughter probability.
`mu`	Mean of Negative Binomial distribution of age-specific slaughter probability.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

'cystiRun' object

Description

Functions to initiate, update and explore 'cystiRun' objects. A 'cystiRun' object corresponds to a single run of a cystiSim model.

Usage

initiate(man, pig,
         ph2m, pl2m, m2p, e2p, age.coef = c(0, 0),
         slaughter = slaughter_nbinom,
         slaughter.args = list(min = 6, max = 36, size = 0.70, mu = 80))

## S3 method for class 'cystiRun'
update(object, n = 1200, verbose = TRUE, ...)

## S3 method for class 'cystiRun'
print(x, from = 200, to = NA, ...)

## S3 method for class 'cystiRun'
plot(x, y = NULL, show = c("PC", "PR", "HT", "EN"),
      start = 0, from = 1, to = NA, ...)
      
prevalence(z)
initiate(man, pig,
         ph2m, pl2m, m2p, e2p, age.coef = c(0, 0),
         slaughter = slaughter_nbinom,
         slaughter.args = list(min = 6, max = 36, size = 0.70, mu = 80))

## S3 method for class 'cystiRun'
update(object, n = 1200, verbose = TRUE, ...)

## S3 method for class 'cystiRun'
print(x, from = 200, to = NA, ...)

## S3 method for class 'cystiRun'
plot(x, y = NULL, show = c("PC", "PR", "HT", "EN"),
      start = 0, from = 1, to = NA, ...)
      
prevalence(z)

Arguments

`man`	Human population dataframe.
`pig`	Pig population dataframe.
`ph2m`	Pig (Heavy infection) to Man transmission probability.
`pl2m`	Pig (Light infection) to Man transmission probability.
`m2p`	Man to Pig transmission probability.
`e2p`	Environment to Pig transmission probability.
`age.coef`	Optional intercept and slope for the association between age and taeniosis.
`slaughter`	Function that defines the slaughter probability of pigs.
`slaughter.args`	Arguments to be passed to the slaughter function.
`object`	Object of class 'cystiRun'.
`n`	Number of iterations (months).
`verbose`	If `TRUE`, a progress bar is shown.
`x`	Object of class 'cystiRun'.
`y`	Currently ignored.
`z`	Vector of infection indicators.
`start`	Origin of plot.
`from`	First iteration to be used in output.
`to`	Last iteration to be used in output. The default value `NA` corresponds to the last available iteration.
`show`	Which output should be plotted?
`...`	Arguments to be passed on to generic function.

Value

initiate and update return an object of S3 class 'cystiRun'.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Examples

## we will use the built-in Mbeya dataset
prevalence(pig_mbeya$cysti)
prevalence(man_mbeya$taenia)

## define transmission probabilities
ph2m <- 0.000174918
pl2m <- 0.000149501
m2p  <- 6.85E-05
e2p  <- 0.00022611

## first initiate the 'cystiRun' object
mod <- initiate(man_mbeya, pig_mbeya, ph2m, pl2m, m2p, e2p)

## update the model 240 cycles (=20 years)
## this is a burn-in period, needed to obtain steady state
mod <- update(mod, 240)

## apply human mass drug administration
mod <- do_man_mda(mod, efficacy = 0.70, coverage = 0.80)

## apply pig mass drug administration
mod <- do_pig_mda(mod, efficacy = 0.90, coverage = 0.90)

## update the model 120 more cycles (=10 years)
mod <- update(mod, 120)

## plot the cycles
plot(mod, from = 200, start = 40)
## we will use the built-in Mbeya dataset
prevalence(pig_mbeya$cysti)
prevalence(man_mbeya$taenia)

## define transmission probabilities
ph2m <- 0.000174918
pl2m <- 0.000149501
m2p  <- 6.85E-05
e2p  <- 0.00022611

## first initiate the 'cystiRun' object
mod <- initiate(man_mbeya, pig_mbeya, ph2m, pl2m, m2p, e2p)

## update the model 240 cycles (=20 years)
## this is a burn-in period, needed to obtain steady state
mod <- update(mod, 240)

## apply human mass drug administration
mod <- do_man_mda(mod, efficacy = 0.70, coverage = 0.80)

## apply pig mass drug administration
mod <- do_pig_mda(mod, efficacy = 0.90, coverage = 0.90)

## update the model 120 more cycles (=10 years)
mod <- update(mod, 120)

## plot the cycles
plot(mod, from = 200, start = 40)

'cystiSim' object

Description

Functions to initiate and explore 'cystiSim' objects. A 'cystiSim' object corresponds to multiple runs of a cystiSim model.

Usage

cystiSim(n = 100, mod, main = NULL)

report(x, ...)

## S3 method for class 'cystiSim'
print(x, ...)

## S3 method for class 'cystiSim'
summary(object, round = 3, ...)

## S3 method for class 'cystiSim'
plot(x, y, annotate = TRUE, ...)

## S3 method for class 'cystiSim'
report(x, name = "cystiSim", ...)

## S3 method for class 'cystiSim'
elim(x, show = c("m", "y"), ...)
cystiSim(n = 100, mod, main = NULL)

report(x, ...)

## S3 method for class 'cystiSim'
print(x, ...)

## S3 method for class 'cystiSim'
summary(object, round = 3, ...)

## S3 method for class 'cystiSim'
plot(x, y, annotate = TRUE, ...)

## S3 method for class 'cystiSim'
report(x, name = "cystiSim", ...)

## S3 method for class 'cystiSim'
elim(x, show = c("m", "y"), ...)

Arguments

`n`	Number of iterations (months).
`mod`	cystiSim model.
`main`	cystiSim model label.
`x`	Object of class 'cystiSim'.
`object`	Object of class 'cystiSim'.
`y`	Currently ignored.
`round`	Number of decimal digits to be printed.
`annotate`	Should plot be annotated with summary information?
`name`	Report name.
`show`	Show time till elimination in terms of months or years?
`...`	Other arguments to be passed to generics.

Value

cystiSim returns an object of S3 class 'cystiSim'.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Examples

## Not run: 

## we will use the built-in Mbeya dataset
prevalence(pig_mbeya$cysti)
prevalence(man_mbeya$taenia)

## define transmission probabilities
ph2m <- 0.000174918
pl2m <- 0.000149501
m2p  <- 6.85E-05
e2p  <- 0.00022611

## set seed for reproducibility
set.seed(264)

## need to define coverage and efficacy of all interventions
cov_man_mda <- 0.80
cov_pig_mda <- 0.90
cov_pig_vac <- NULL
eff_man_mda <- 0.70
eff_pig_mda <- 0.90
eff_pig_vac <- NULL

## run the simulations
sim <-
cystiSim(
  n = 10,
  main = "example",
  mod = {
initiate(man_mbeya, pig_mbeya, ph2m, pl2m, m2p, e2p) %>%
  update(240) %>%
  do_man_mda(coverage = cov_man_mda, efficacy = eff_man_mda) %>%
  do_pig_mda(coverage = cov_pig_mda, efficacy = eff_pig_mda) %>%
  update(120)
  }
)

## summarize results
summary(sim)

## plot simulations (mean and uncertainty interval)
plot(sim)

## create PDF report and plot
report(sim)

## End(Not run)
## Not run: 

## we will use the built-in Mbeya dataset
prevalence(pig_mbeya$cysti)
prevalence(man_mbeya$taenia)

## define transmission probabilities
ph2m <- 0.000174918
pl2m <- 0.000149501
m2p  <- 6.85E-05
e2p  <- 0.00022611

## set seed for reproducibility
set.seed(264)

## need to define coverage and efficacy of all interventions
cov_man_mda <- 0.80
cov_pig_mda <- 0.90
cov_pig_vac <- NULL
eff_man_mda <- 0.70
eff_pig_mda <- 0.90
eff_pig_vac <- NULL

## run the simulations
sim <-
cystiSim(
  n = 10,
  main = "example",
  mod = {
initiate(man_mbeya, pig_mbeya, ph2m, pl2m, m2p, e2p) %>%
  update(240) %>%
  do_man_mda(coverage = cov_man_mda, efficacy = eff_man_mda) %>%
  do_pig_mda(coverage = cov_pig_mda, efficacy = eff_pig_mda) %>%
  update(120)
  }
)

## summarize results
summary(sim)

## plot simulations (mean and uncertainty interval)
plot(sim)

## create PDF report and plot
report(sim)

## End(Not run)

Do human mass drug administration(MDA)

Description

Intervention function that mimics the possible effects of human mass drug administration.

Usage

do_man_mda(x, coverage, efficacy, min.age = 0, max.age = Inf)
do_man_mda(x, coverage, efficacy, min.age = 0, max.age = Inf)

Arguments

`x`	`cystiRun` object.
`coverage`	Presumed coverage of drug administration within eligible population, expressed as a decimal value.
`efficacy`	Presumed efficacy of tapeworm treatment, expressed as a decimal value.
`min.age`	Minimum age for MDA, in months. Defaults to `0`, i.e., no lower age limit.
`max.age`	Maximum age for MDA, in months. Defaults to `Inf`, i.e., no upper age limit.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Do pig mass drug administration (MDA)

Description

Intervention function that mimics the possible effects of pig mass drug administration.

Usage

do_pig_mda(x, coverage, efficacy, immunity = 3, min.age = 1, max.age = Inf)
do_pig_mda(x, coverage, efficacy, immunity = 3, min.age = 1, max.age = Inf)

Arguments

`x`	`cystiRun` object.
`coverage`	Presumed coverage of drug treatment within eligible population, expressed as a decimal value.
`efficacy`	Presumed efficacy of drug treatment, expressed as a decimal value.
`immunity`	Presumed duration of immunity following drug treatment of an infected pig. Defaults to 3 months.
`min.age`	Minimum age for drug treatment, in months. Defaults to 1 month.
`max.age`	Maximum age for drug treatment, in months. Defaults to `Inf`, i.e., no upper age limit.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Do pig mass drug administration (MDA) and vaccination

Description

Intervention function that mimics the possible effects of combined pig mass drug administration and vaccination.

Usage

do_pig_mda_vac(x, coverage, efficacy.mda, efficacy.vac,
               immunity.mda = 3, immunity.vac = Inf, interval = 4,
               min.age = 1, max.age = Inf)
do_pig_mda_vac(x, coverage, efficacy.mda, efficacy.vac,
               immunity.mda = 3, immunity.vac = Inf, interval = 4,
               min.age = 1, max.age = Inf)

Arguments

`x`	`cystiRun` object.
`coverage`	Presumed coverage within eligible population, expressed as a decimal value.
`efficacy.mda`	Presumed efficacy of drug treatment, expressed as a decimal value.
`efficacy.vac`	Presumed efficacy of vaccine, expressed as a decimal value.
`immunity.mda`	Presumed duration of immunity following drug treatment of an infected pig. Defaults to 3 months.
`immunity.vac`	Presumed duration of immunity following successful vaccination. Defaults to `Inf`.
`interval`	Maximum interval between two consecutive shots for immunity. Defaults to 4 months.
`min.age`	Minimum age for intervention, in months. Defaults to 1 month.
`max.age`	Maximum age for intervention, in months. Defaults to `Inf`, i.e., no upper age limit.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Do pig vaccination

Description

Intervention function that mimics the possible effects of pig vaccination.

Usage

do_pig_vac(x, coverage, efficacy, immunity = Inf, interval = 4,
           min.age = 1, max.age = Inf)
do_pig_vac(x, coverage, efficacy, immunity = Inf, interval = 4,
           min.age = 1, max.age = Inf)

Arguments

`x`	`cystiRun` object.
`coverage`	Presumed coverage of vaccination within eligible population, expressed as a decimal value.
`efficacy`	Presumed efficacy of vaccine, expressed as a decimal value.
`immunity`	Presumed duration of immunity following successful vaccination. Defaults to `Inf`.
`interval`	Maximum interval between two consecutive shots for immunity. Defaults to 4 months.
`min.age`	Minimum age for vaccination, in months. Defaults to 1 month.
`max.age`	Maximum age for vaccination, in months. Defaults to `Inf`, i.e., no upper age limit.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Fit cystiSim parameters

Description

This function simulates random cystiSim parameters, and return those scenarios that result in a baseline prevalence close to the specified target.

Usage

fit(n.sim, n.update, target, limit,
    man, pig, ph2m, pl2m, m2p, e2p, age.coef = c(0, 0),
    slaughter = slaughter_nbinom,
    slaughter.args = list(min = 6,  max = 36, size = 0.70, mu = 80))
fit(n.sim, n.update, target, limit,
    man, pig, ph2m, pl2m, m2p, e2p, age.coef = c(0, 0),
    slaughter = slaughter_nbinom,
    slaughter.args = list(min = 6,  max = 36, size = 0.70, mu = 80))

Arguments

`n.sim`	Desired number of retained scenarios.
`n.update`	Number of updates of the baseline model.
`target`	Named list of target prevalences for `ht`, `pc` and/or `pi`
`limit`	Maximum tolerated deviance.
`man`	Human population dataframe.
`pig`	Pig population dataframe.
`ph2m`	Pig (Heavy infection) to Man transmission probability.
`pl2m`	Pig (Light infection) to Man transmission probability.
`m2p`	Man to Pig transmission probability.
`e2p`	Environment to Pig transmission probability.
`age.coef`	Optional intercept and slope for the association between age and taeniosis.
`slaughter`	Function that defines the slaughter probability of pigs.
`slaughter.args`	Arguments to be passed to the slaughter function.

Details

The abbreviations used:

ht....Human Taeniosis prevalence
pc....Porcine Cysticercosis prevalence
pi....Pig Intensity proportion (i.e., proportion heavily infection pigs)

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Mbeya human population

Description

Default baseline dataframe.

Usage

data("man_mbeya")data("man_mbeya")

Format

A data frame with 6000 observations on the following 7 variables.

age: a numeric vector
sex: a factor with levels female male
taenia: a numeric vector
taenia_immature: a numeric vector
time_since_infection: a numeric vector
environment: a numeric vector
time_since_contamination: a numeric vector

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Mbozi human population

Description

Default baseline dataframe.

Usage

data("man_mbozi")data("man_mbozi")

Format

A data frame with 6000 observations on the following 7 variables.

age: a numeric vector
sex: a factor with levels female male
taenia: a numeric vector
taenia_immature: a numeric vector
time_since_infection: a numeric vector
environment: a numeric vector
time_since_contamination: a numeric vector

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Mbeya pig population

Description

Default baseline dataframe.

Usage

data("pig_mbeya")data("pig_mbeya")

Format

A data frame with 498 observations on the following 8 variables.

age: a numeric vector
cysti: a numeric vector
cysti_immature: a numeric vector
time_since_infection: a numeric vector
intensity: a factor with levels 0 H L
immunity: a numeric vector
time_since_vaccination: a logical vector
slaughtered: a numeric vector

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Mbozi pig population

Description

Default baseline dataframe.

Usage

data("pig_mbozi")data("pig_mbozi")

Format

A data frame with 498 observations on the following 8 variables.

age: a numeric vector
cysti: a numeric vector
cysti_immature: a numeric vector
time_since_infection: a numeric vector
intensity: a factor with levels 0 H L
immunity: a numeric vector
time_since_vaccination: a logical vector
slaughtered: a numeric vector

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Pig slaughter functions

Description

These functions simulate age-dependent slaughter of pigs. The default function is slaughter_nbinom.

Usage

slaughter_binom(age, min, max, p)
slaughter_nbinom(age, min, max, size, mu)
slaughter_binom(age, min, max, p)
slaughter_nbinom(age, min, max, size, mu)

Arguments

`age`	Age of the pigs.
`min`	Minimum age at slaughter, i.e., Pr(slaughter<min)=0.
`max`	Age at which all pigs are definitely slaughtered, i.e., Pr(slaughter>=max)=1.
`p`	Binomial probability of slaughter.
`size`	Size of Negative Binomial distribution of age-specific slaughter probability.
`mu`	Mean of Negative Binomial distribution of age-specific slaughter probability.

Note

For more details and examples, please visit the cystiSim Wiki pages on https://github.com/brechtdv/cystiSim/wiki.

Author(s)

[email protected]

Package 'cystiSim'

Help Index

Agent-based model for Taenia solium transmission and control.

Description

Details

Random baseline populations

Description

Usage

Arguments

Note

Author(s)

'cystiRun' object

Description

Usage

Arguments

Value

Note

Author(s)

See Also

Examples

'cystiSim' object

Description

Usage

Arguments

Value

Note

Author(s)

See Also

Examples

Do human mass drug administration(MDA)

Description

Usage

Arguments

Note

Author(s)

See Also

Do pig mass drug administration (MDA)

Description

Usage

Arguments

Note

Author(s)

See Also

Do pig mass drug administration (MDA) and vaccination

Description

Usage

Arguments

Note

Author(s)

See Also

Do pig vaccination

Description

Usage

Arguments

Note

Author(s)

See Also

Fit cystiSim parameters

Description

Usage

Arguments

Details

Note

Author(s)

Mbeya human population

Description

Usage

Format

Note

Mbozi human population

Description

Usage

Format

Note

Mbeya pig population

Description

Usage

Format

Note

Mbozi pig population