Package 'phylosamp'

Description

This function calculates the expected number of observed pairs in the sample that are linked by the linkage criteria. The function requires the sensitivity $\eta$ and specificity $\chi$ of the linkage criteria, and sample size $M$. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

exp_links(eta, chi, rho, M, R = NULL, assumption = "mtml")

Arguments

Value

scalar or vector giving the expected number of observed links in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other obs_pairs: obs_pairs_mtml(), obs_pairs_mtsl(), obs_pairs_stsl()

Examples

# The simplest case: single-transmission, single-linkage, and perfect sensitivity
exp_links(eta=1, chi=0.9, rho=0.5, M=100, assumption='stsl')

# Multiple-transmission and imperfect sensitivity
exp_links(eta=0.99, chi=0.9, rho=1, M=50, R=1, assumption='mtsl')

# Small outbreak, larger sampling proportion
exp_links(eta=0.99, chi=0.95, rho=1, M=50, R=1, assumption='mtml')

# Large outbreak, small sampling proportion
exp_links(eta=0.99, chi=0.95, rho=0.05, M=1000, R=1, assumption='mtml')

Description

This function calculates the false discovery rate (proportion of linked pairs that are false positives) in a sample given the sensitivity $\eta$ and specificity $\chi$ of the linkage criteria, and sample size $M$. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

falsediscoveryrate(eta, chi, rho, M, R = NULL, assumption = "mtml")

Arguments

Value

scalar or vector giving the true discovery rate

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other discovery_rate: truediscoveryrate()

Examples

# The simplest case: single-transmission, single-linkage, and perfect sensitivity
falsediscoveryrate(eta=1, chi=0.9, rho=0.5, M=100, assumption='stsl')

# Multiple-transmission and imperfect sensitivity
falsediscoveryrate(eta=0.99, chi=0.9, rho=1, M=50, R=1, assumption='mtsl')

# Small outbreak, larger sampling proportion
falsediscoveryrate(eta=0.99, chi=0.95, rho=1, M=50, R=1, assumption='mtml')

# Large outbreak, small sampling proportion
falsediscoveryrate(eta=0.99, chi=0.95, rho=0.5, M=1000, R=1, assumption='mtml')

Description

Function calculates the distribution of genetic distances in a population of viruses with the given parameters

Usage

gen_dists(
  mut_rate,
  mean_gens_pdf,
  max_link_gens = 1,
  max_gens = NULL,
  max_dist = NULL
)

Arguments

Value

a data frame with distances and probabilities

Author(s)

Shirlee Wohl and Justin Lessler

See Also

Other mutrate_functions: get_optim_roc(), sens_spec_calc(), sens_spec_roc()

Examples

# ebola-like pathogen
R <- 1.5
mut_rate <- 1

# use simulated generation distributions from the provided 'genDistSim' data object
data('genDistSim')
mean_gens_pdf <- as.numeric(genDistSim[genDistSim$R == R, -(1:2)])

# get theoretical genetic distance dist based on mutation rate and generation parameters
gen_dists(mut_rate = mut_rate,
          mean_gens_pdf = mean_gens_pdf,
          max_link_gens = 1)

Description

Function calculates the distribution of genetic distances in a population of viruses with the given parameters

Usage

gendist_distribution(
  mut_rate,
  mean_gens_pdf,
  max_link_gens = 1,
  max_gens = NULL,
  max_dist = NULL
)

Arguments

Value

a data frame with distances and probabilities

Author(s)

Shirlee Wohl and Justin Lessler

See Also

Other genetic distance functions: gendist_roc_format(), gendist_sensspec_cutoff()

Examples

# ebola-like pathogen
R <- 1.5
mut_rate <- 1

# use simulated generation distributions from the provided 'genDistSim' data object
data('genDistSim')
mean_gens_pdf <- as.numeric(genDistSim[genDistSim$R == R, -(1:2)])

# get theoretical genetic distance dist based on mutation rate and generation parameters
gendist_distribution(mut_rate = mut_rate,
                     mean_gens_pdf = mean_gens_pdf,
                     max_link_gens = 1)

Description

This is a wrapper function that takes output from the gendist_sensspec_cutoff() function and constructs values for the Receiver Operating Characteristic (ROC) curve

Usage

gendist_roc_format(
  cutoff,
  mut_rate,
  mean_gens_pdf,
  max_link_gens = 1,
  max_gens = NULL,
  max_dist = NULL
)

Arguments

Value

data frame with cutoff, sensitivity, and 1-specificity

Author(s)

Shirlee Wohl and Justin Lessler

See Also

Other genetic distance functions: gendist_distribution(), gendist_sensspec_cutoff()

Other ROC functions: optim_roc_threshold()

Examples

# ebola-like pathogen
R <- 1.5
mut_rate <- 1

# use simulated generation distributions
data('genDistSim')
mean_gens_pdf <- as.numeric(genDistSim[genDistSim$R == R, -(1:2)])

# get theoretical genetic distance dist based on mutation rate and generation parameters
dists <- as.data.frame(gendist_distribution(mut_rate = mut_rate,
                       mean_gens_pdf = mean_gens_pdf,
                       max_link_gens = 1))

dists <- reshape2::melt(dists,
                        id.vars = 'dist',
                        variable.name = 'status',
                        value.name = 'prob')

# get sensitivity and specificity using the same paramters
roc_calc <- gendist_roc_format(cutoff = 1:(max(dists$dist)-1),
                               mut_rate = mut_rate,
                               mean_gens_pdf = mean_gens_pdf)

Description

Function to calculate the sensitivity and specificity of a genetic distance cutoff given an underlying mutation rate and mean number of generations between cases

Usage

gendist_sensspec_cutoff(
  cutoff,
  mut_rate,
  mean_gens_pdf,
  max_link_gens = 1,
  max_gens = NULL,
  max_dist = NULL
)

Arguments

Value

a data frame with the sensitivity and specificity for a particular genetic distance cutoff

Author(s)

Shirlee Wohl and Justin Lessler

See Also

Other genetic distance functions: gendist_distribution(), gendist_roc_format()

Examples

# calculate the sensitivity and specificity for a specific genetic distance threshold of 2 mutations
gendist_sensspec_cutoff(cutoff=2,
                        mut_rate=1,
                        mean_gens_pdf=c(0.02,0.08,0.15,0.75),
                        max_link_gens=1)

# calculate the sensitivity and specificity for a a range of genetic distance thresholds
gendist_sensspec_cutoff(cutoff=1:10,
                        mut_rate=1,
                        mean_gens_pdf=c(0.02,0.08,0.15,0.75),
                        max_link_gens=1)

Description

This data object contains the genetic distance distributions for 168 values of $R$ between 1.3 and 18. The distributions represent the the average of 1000 simulations for each value, which can be used as a reasonable proxy for the generation distribution for large outbreaks.

Usage

genDistSim

Format

dataframe

Author(s)

Shirlee Wohl, John Giles, and Justin Lessler

Examples

data(genDistSim)

Description

This function takes the dataframe output of the sens_spec_roc() function and finds the optimal threshold of sensitivity and specificity by minimizing the distance to the top left corner of the Receiver Operating Characteristic (ROC) curve

Usage

get_optim_roc(roc)

Arguments

Value

vector containing optimal thresholds of sensitivity and specificity

Author(s)

Shirlee Wohl, John Giles, and Justin Lessler

See Also

Other mutrate_functions: gen_dists(), sens_spec_calc(), sens_spec_roc()

Examples

# ebola-like pathogen
R <- 1.5
mut_rate <- 1

# use simulated generation distributions
data(genDistSim)
mean_gens_pdf <- as.numeric(genDistSim[genDistSim$R == R, -(1:2)])

# get theoretical genetic distance dist based on mutation rate and generation parameters
dists <- as.data.frame(gen_dists(mut_rate = mut_rate,
                                 mean_gens_pdf = mean_gens_pdf,
                                 max_link_gens = 1))

# reshape dataframe for plotting
dists <- reshape2::melt(dists,
                        id.vars = 'dist',
                        variable.name = 'status',
                        value.name = 'prob')

# get sensitivity and specificity using the same paramters
roc_calc <- sens_spec_roc(cutoff = 1:(max(dists$dist)-1),
                          mut_rate = mut_rate,
                          mean_gens_pdf = mean_gens_pdf)

# get the optimal value for the ROC plot
optim_point <- get_optim_roc(roc_calc)

Description

This function calculates the expected number of pairs observed in a sample of size M. The multiple-transmission and multiple-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to multiple cases $j$ in the sampled population ($M$).

3. Linkage events are independent of one another (i.e, linkage of case $i$ to case $j$ has no bearing on linkage of case $i$ to any other sample).

Usage

obs_pairs_mtml(chi, eta, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of linked pairs observed in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other obs_pairs: exp_links(), obs_pairs_mtsl(), obs_pairs_stsl()

Examples

# Perfect sensitivity and specificity
obs_pairs_mtml(eta=1, chi=1, rho=0.5, M=100, R=1)

obs_pairs_mtml(eta=0.99, chi=0.9, rho=1, M=50, R=1)

obs_pairs_mtml(eta=0.99, chi=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the expected number of pairs observed in a sample of size M. The multiple-transmission and single-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

obs_pairs_mtsl(chi, eta, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of linked pairs observed in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other obs_pairs: exp_links(), obs_pairs_mtml(), obs_pairs_stsl()

Examples

# Perfect sensitivity and specificity
obs_pairs_mtsl(eta=1, chi=1, rho=0.5, M=100, R=1)

obs_pairs_mtsl(eta=0.99, chi=0.9, rho=1, M=50, R=1)

obs_pairs_mtsl(eta=0.99, chi=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the expected number of link pairs observed in a sample of size M. The single-transmission and single-linkage method assumes the following:

1. Each case $i$ is linked by transmission to only one other case $j$ in the population ($N$).

2. Each case $i$ is linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

obs_pairs_stsl(eta, chi, rho, M)

Arguments

Value

scalar or vector giving the expected number of linked pairs observed in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other obs_pairs: exp_links(), obs_pairs_mtml(), obs_pairs_mtsl()

Examples

# perfect sensitivity and specificity
obs_pairs_stsl(eta=1, chi=1, rho=0.5, M=100)

obs_pairs_stsl(eta=0.99, chi=0.9, rho=1, M=50)

obs_pairs_stsl(eta=0.99, chi=0.9, rho=0.5, M=100)

Description

This function takes the dataframe output of the gendist_roc_format() function and finds the optimal threshold of sensitivity and specificity by minimizing the distance to the top left corner of the Receiver Operating Characteristic (ROC) curve

Usage

optim_roc_threshold(roc)

Arguments

Value

vector containing optimal thresholds of sensitivity and specificity

Author(s)

Shirlee Wohl, John Giles, and Justin Lessler

See Also

Other ROC functions: gendist_roc_format()

Examples

# ebola-like pathogen
R <- 1.5
mut_rate <- 1

# use simulated generation distributions
data("genDistSim")
mean_gens_pdf <- as.numeric(genDistSim[genDistSim$R == R, -(1:2)])

# get theoretical genetic distance dist based on mutation rate and generation parameters
dists <- as.data.frame(gendist_distribution(mut_rate = mut_rate,
                       mean_gens_pdf = mean_gens_pdf,
                       max_link_gens = 1))

# reshape dataframe for plotting
dists <- reshape2::melt(dists,
                        id.vars = "dist",
                        variable.name = "status",
                        value.name = "prob")

# get sensitivity and specificity using the same paramters
roc_calc <- gendist_roc_format(cutoff = 1:(max(dists$dist)-1),
                          mut_rate = mut_rate,
                          mean_gens_pdf = mean_gens_pdf)

# get the optimal value for the ROC plot
optim_point <- optim_roc_threshold(roc_calc)

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. The multiple-transmission and multiple-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to multiple cases $j$ in the sampled population ($M$).

3. Linkage events are independent of one another (i.e, linkage of case $i$ to case $j$ has no bearing on linkage of case $i$ to any other sample).

Usage

prob_trans_mtml(eta, chi, rho, M, R)

Arguments

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other prob_trans: prob_trans_mtsl(), prob_trans_stsl()

Examples

# Perfect sensitivity and specificity
prob_trans_mtml(eta=1, chi=1, rho=0.5, M=100, R=1)

prob_trans_mtml(eta=0.99, chi=0.9, rho=1, M=50, R=1)

prob_trans_mtml(eta=0.99, chi=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. The multiple-transmission and single-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

prob_trans_mtsl(chi, eta, rho, M, R)

Arguments

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other prob_trans: prob_trans_mtml(), prob_trans_stsl()

Examples

# Perfect sensitivity and specificity
prob_trans_mtsl(eta=1, chi=1, rho=0.5, M=100, R=1)

prob_trans_mtsl(eta=0.99, chi=0.9, rho=1, M=50, R=1)

prob_trans_mtsl(eta=0.99, chi=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. The single-transmission and single-linkage method assumes the following:

1. Each case $i$ is linked by transmission to only one other case $j$ in the population ($N$).

2. Each case $i$ is linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

For perfect sensitivity, set eta = 1.

Usage

prob_trans_stsl(eta, chi, rho, M)

Arguments

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other prob_trans: prob_trans_mtml(), prob_trans_mtsl()

Examples

# perfect sensitivity and specificity
prob_trans_stsl(eta=1, chi=1, rho=0.2, M=100)

# perfect sensitivity only
prob_trans_stsl(eta=1, chi=0.95, rho=0.2, M=100)

prob_trans_stsl(eta=0.99, chi=0.95, rho=0.9, M=50)

prob_trans_stsl(eta=0.99, chi=0.95, rho=0.05, M=100)

Description

Function to calculate the power given a sample size. This is the top level function to be called to calculate power given a sample size m and a proportion sampled.

Usage

relR_power(
  m,
  R_a,
  R_b,
  p_a,
  N = NULL,
  rho = NULL,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL
)

Arguments

Value

The power given m

Description

Simulate power for detecting differential transmission

Usage

relR_power_simulated(
  m,
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL,
  nsims = 1e+05
)

Arguments

Value

Simulated power

Description

Function for calculating sample size given a set of assumptions. This is the high level wrapper function that users should call directly.

Usage

relR_samplesize(
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  power = 0.8,
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL,
  correct_for_imbalance = FALSE
)

Arguments

Value

Sample size needed achieve desired type I and II error rates under assumptions. Will return NA and throw a warning if impossible.

Examples

## Calculate sample size needed to detect a difference between groups where 
## group A has a reproductive value of 2, group B has a reproductive 
## value of 2.5, the groups are balanced, and the total outbreak size is 
## 1,000

relR_samplesize(R_a = 2, 
                R_b = 2.5, 
                p_a = 0.5,
                N = 1000)

## Update the above calculation to account for imperfect sensitivity = 0.7
relR_samplesize(R_a = 2, 
                R_b = 2.5, 
                p_a = 0.5,
                N = 1000,
                sensitivity = 0.7)

## Update the above calculation to allow for overdispersion
relR_samplesize(R_a = 2, 
                R_b = 2.5, 
                p_a = 0.5,
                N = 1000,
                sensitivity = 0.7,
                overdispersion = 2000)

Description

Function that does the simple derived sample size calculation with no corrections. I.e., directly applies the math as if sensitivity and specificity are perfect.

Usage

relR_samplesize_basic(
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  power = 0.8,
  overdispersion = NULL,
  allow_impossible_m = FALSE
)

Arguments

Value

The required sample size. NA if larger than N.

Description

This function assumes you want to correct for imbalance, if not there is a closed form solution for the estimated sample size that does not include uncertainty bounds. (see relR_samplesize).

Usage

relR_samplesize_ci(
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  power = 0.8,
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL,
  nsims = 1000,
  uncertainty_percent = 0.95,
  B = 1000
)

Arguments

Value

A vector with three quantities:

• sample size: Sample size needed achieve desired type I and II error rates under assumptions. Will return NA and throw a warning if impossible.

• lower bound: The lower bound of an uncertainty interval

• upper bound: The upper bound of an uncertainty interval

Description

Function to run the sample size calculation correcting for imperfect sensitivity and specificity, but not doing any simulation based corrections.

Usage

relR_samplesize_linkerr(
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  power = 0.8,
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL,
  allow_impossible_m = FALSE
)

Arguments

Value

Sample size needed achieve desired type I and II error rates under assumptions. Will return NA and throw a warning if impossible.

Description

Function to calculate the error in estimated sample size for use in optimize function

Usage

relR_samplesize_opterr(
  m,
  R_a,
  R_b,
  p_a,
  N,
  alpha,
  alternative,
  power,
  sensitivity,
  specificity,
  overdispersion
)

Arguments

Value

Squared error between the input sample size and estimated sample size

Description

Function to calculate optimized sample size by solving the transcendental equation that occurs when you replace the R values with ones that account for sensitivity and specificity.

Usage

relR_samplesize_simsolve(
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  power = 0.8,
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL,
  epsilon = 0.01,
  nsims = 1e+05,
  tolerance = 10
)

Arguments

Value

Simulated sample size needed achieve desired type I and II error rates under assumptions. Will return NA and throw a warning if impossible.

Description

Function to solve for optimal sample size when the specificity isn't 1

Usage

relR_samplesize_solve(
  R_a,
  R_b,
  p_a,
  N,
  alpha = 0.05,
  alternative = c("two_sided", "less", "greater"),
  power = 0.8,
  sensitivity = 1,
  specificity = 1,
  overdispersion = NULL,
  allow_impossible_m = FALSE
)

Arguments

Value

The sample size

Description

This function calculates the sample size needed to obtain at least a defined false discovery rate given a final outbreak size $N$.

Usage

samplesize(eta, chi, N, R = NULL, phi, min_pairs = 1, assumption = "mtml")

Arguments

Value

scalar or vector giving the sample size needed to meet the given conditions

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

Examples

samplesize(eta=0.99, chi=0.995, N=100, R=1, phi=0.75)

Description

Function to calculate the sensitivity and specificity of a genetic distance cutoff given an underlying mutation rate and mean number of generations between cases

Usage

sens_spec_calc(
  cutoff,
  mut_rate,
  mean_gens_pdf,
  max_link_gens = 1,
  max_gens = NULL,
  max_dist = NULL
)

Arguments

Value

a data frame with the sensitivity and specificity for a particular genetic distance cutoff

Author(s)

Shirlee Wohl and Justin Lessler

See Also

Other mutrate_functions: gen_dists(), get_optim_roc(), sens_spec_roc()

Examples

# calculate the sensitivity and specificity for a specific genetic distance threshold of 2 mutations
sens_spec_calc(cutoff=2,
               mut_rate=1,
               mean_gens_pdf=c(0.02,0.08,0.15,0.75),
               max_link_gens=1)

# calculate the sensitivity and specificity for a a range of genetic distance thresholds
sens_spec_calc(cutoff=1:10,
               mut_rate=1,
               mean_gens_pdf=c(0.02,0.08,0.15,0.75),
               max_link_gens=1)

Description

This is a wrapper function that takes output from the sens_spec_calc() function and constructs values for the Receiver Operating Characteristic (ROC) curve

Usage

sens_spec_roc(
  cutoff,
  mut_rate,
  mean_gens_pdf,
  max_link_gens = 1,
  max_gens = NULL,
  max_dist = NULL
)

Arguments

Value

data frame with cutoff, sensitivity, and 1-specificity

Author(s)

Shirlee Wohl and Justin Lessler

See Also

Other mutrate_functions: gen_dists(), get_optim_roc(), sens_spec_calc()

Examples

# ebola-like pathogen
R <- 1.5
mut_rate <- 1

# use simulated generation distributions
data('genDistSim')
mean_gens_pdf <- as.numeric(genDistSim[genDistSim$R == R, -(1:2)])

# get theoretical genetic distance dist based on mutation rate and generation parameters
dists <- as.data.frame(gen_dists(mut_rate = mut_rate,
                                 mean_gens_pdf = mean_gens_pdf,
                                 max_link_gens = 1))

dists <- reshape2::melt(dists,
                        id.vars = 'dist',
                        variable.name = 'status',
                        value.name = 'prob')

# get sensitivity and specificity using the same paramters
roc_calc <- sens_spec_roc(cutoff = 1:(max(dists$dist)-1),
                          mut_rate = mut_rate,
                          mean_gens_pdf = mean_gens_pdf)

Description

This function calculates the expected number of observed pairs in the sample that are linked by the linkage criteria. The function requires the sensitivity and specificity of the linkage criteria, and sample size $M$. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

translink_expected_links_obs(
  sensitivity,
  specificity,
  rho,
  M,
  R = NULL,
  assumption = "mtml"
)

Arguments

Value

scalar or vector giving the expected number of observed links in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# The simplest case: single-transmission, single-linkage, and perfect sensitivity
translink_expected_links_obs(sensitivity=1, specificity=0.9, rho=0.5, M=100, assumption='stsl')

# Multiple-transmission and imperfect sensitivity
translink_expected_links_obs(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1, assumption='mtsl')

# Small outbreak, larger sampling proportion
translink_expected_links_obs(sensitivity=0.99, specificity=0.95, rho=1, M=50, 
R=1, assumption='mtml')

# Large outbreak, small sampling proportion
translink_expected_links_obs(sensitivity=0.99, specificity=0.95, 
rho=0.05, M=1000, R=1, assumption='mtml')

Description

This function calculates the expected number of pairs observed in a sample of size M. The multiple-transmission and multiple-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to multiple cases $j$ in the sampled population ($M$).

3. Linkage events are independent of one another (i.e, linkage of case $i$ to case $j$ has no bearing on linkage of case $i$ to any other sample).

Usage

translink_expected_links_obs_mtml(specificity, sensitivity, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of linked pairs observed in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# Perfect sensitivity and specificity
translink_expected_links_obs_mtml(sensitivity=1, specificity=1, rho=0.5, M=100, R=1)

translink_expected_links_obs_mtml(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1)

translink_expected_links_obs_mtml(sensitivity=0.99, specificity=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the expected number of pairs observed in a sample of size M. The multiple-transmission and single-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

translink_expected_links_obs_mtsl(specificity, sensitivity, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of linked pairs observed in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# Perfect sensitivity and specificity
translink_expected_links_obs_mtsl(sensitivity=1, specificity=1, rho=0.5, M=100, R=1)

translink_expected_links_obs_mtsl(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1)

translink_expected_links_obs_mtsl(sensitivity=0.99, specificity=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the expected number of link pairs observed in a sample of size M. The single-transmission and single-linkage method assumes the following:

1. Each case $i$ is linked by transmission to only one other case $j$ in the population ($N$).

2. Each case $i$ is linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

translink_expected_links_obs_stsl(sensitivity, specificity, rho, M)

Arguments

Value

scalar or vector giving the expected number of linked pairs observed in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# perfect sensitivity and specificity
translink_expected_links_obs_stsl(sensitivity=1, specificity=1, rho=0.5, M=100)

translink_expected_links_obs_stsl(sensitivity=0.99, specificity=0.9, rho=1, M=50)

translink_expected_links_obs_stsl(sensitivity=0.99, specificity=0.9, rho=0.5, M=100)

Description

This function calculates the expected number true transmission pairs in a sample of size M. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

translink_expected_links_true(
  sensitivity,
  rho,
  M,
  R = NULL,
  assumption = "mtml"
)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

translink_expected_links_true(sensitivity=0.99, rho=0.75, M=100, R=1)

Description

This function calculates the expected number of true transmission pairs in a sample of size M. The multiple-transmission and multiple-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to multiple cases $j$ in the sampled population ($M$).

3. Linkage events are independent of one another (i.e, linkage of case $i$ to case $j$ has no bearing on linkage of case $i$ to any other sample).

Usage

translink_expected_links_true_mtml(sensitivity, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

translink_expected_links_true_mtml(sensitivity=0.95, rho=0.2, M=1000, R=1)

Description

This function calculates the expected number true transmission pairs in a sample of size M. The multiple-transmission and single-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

translink_expected_links_true_mtsl(sensitivity, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

translink_expected_links_true_mtsl(sensitivity=0.95, rho=0.2, M=200, R=1)

Description

This function calculates the expected number of true transmission pairs in a sample of size M. The single-transmission and single-linkage method assumes the following:

1. Each case $i$ is linked by transmission to only one other case $j$ in the population ($N$).

2. Each case $i$ is linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

translink_expected_links_true_stsl(sensitivity, rho, M)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

translink_expected_links_true_stsl(sensitivity=0.95, rho=0.2, M=200)

Description

This function calculates the false discovery rate (proportion of linked pairs that are false positives) in a sample given the sensitivity and specificity of the linkage criteria, and sample size $M$. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

translink_fdr(sensitivity, specificity, rho, M, R = NULL, assumption = "mtml")

Arguments

Value

scalar or vector giving the true discovery rate

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# The simplest case: single-transmission, single-linkage, and perfect sensitivity
translink_fdr(sensitivity=1, specificity=0.9, rho=0.5, M=100, assumption='stsl')

# Multiple-transmission and imperfect sensitivity
translink_fdr(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1, assumption='mtsl')

# Small outbreak, larger sampling proportion
translink_fdr(sensitivity=0.99, specificity=0.95, rho=1, M=50, R=1, assumption='mtml')

# Large outbreak, small sampling proportion
translink_fdr(sensitivity=0.99, specificity=0.95, rho=0.5, M=1000, R=1, assumption='mtml')

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

translink_prob_transmit(
  sensitivity,
  specificity,
  rho,
  M,
  R,
  assumption = "mtml"
)

Arguments

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_samplesize(), translink_tdr()

Examples

translink_prob_transmit(sensitivity=0.99, specificity=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. The multiple-transmission and multiple-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to multiple cases $j$ in the sampled population ($M$).

3. Linkage events are independent of one another (i.e, linkage of case $i$ to case $j$ has no bearing on linkage of case $i$ to any other sample).

Usage

translink_prob_transmit_mtml(sensitivity, specificity, rho, M, R)

Arguments

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# Perfect sensitivity and specificity
translink_prob_transmit_mtml(sensitivity=1, specificity=1, rho=0.5, M=100, R=1)

translink_prob_transmit_mtml(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1)

translink_prob_transmit_mtml(sensitivity=0.99, specificity=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. The multiple-transmission and single-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

translink_prob_transmit_mtsl(specificity, sensitivity, rho, M, R)

Arguments

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# Perfect sensitivity and specificity
translink_prob_transmit_mtsl(sensitivity=1, specificity=1, rho=0.5, M=100, R=1)

translink_prob_transmit_mtsl(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1)

translink_prob_transmit_mtsl(sensitivity=0.99, specificity=0.9, rho=0.5, M=100, R=1)

Description

This function calculates the probability that two cases are linked by direct transmission given that they have been linked by phylogenetic criteria. The single-transmission and single-linkage method assumes the following:

1. Each case $i$ is linked by transmission to only one other case $j$ in the population ($N$).

2. Each case $i$ is linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

translink_prob_transmit_stsl(sensitivity, specificity, rho, M)

Arguments

Details

For perfect sensitivity, set sensitivity = 1.

Value

scalar or vector giving the probability of transmission between two cases given linkage by phylogenetic criteria

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit(), translink_samplesize(), translink_tdr()

Examples

# perfect sensitivity and specificity
translink_prob_transmit_stsl(sensitivity=1, specificity=1, rho=0.2, M=100)

# perfect sensitivity only
translink_prob_transmit_stsl(sensitivity=1, specificity=0.95, rho=0.2, M=100)

translink_prob_transmit_stsl(sensitivity=0.99, specificity=0.95, rho=0.9, M=50)

translink_prob_transmit_stsl(sensitivity=0.99, specificity=0.95, rho=0.05, M=100)

Description

This function calculates the sample size needed to identify transmission links at a predefined false discovery rate, given a final outbreak size $N$.

Usage

translink_samplesize(
  sensitivity,
  specificity,
  N,
  R = NULL,
  tdr,
  min_pairs = 1,
  assumption = "mtml"
)

Arguments

Value

scalar or vector giving the sample size needed to meet the given conditions

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_tdr()

Examples

translink_samplesize(sensitivity=0.99, specificity=0.995, N=100, R=1, tdr=0.75)

Description

This function calculates the true discovery rate (proportion of true transmission pairs) in a sample given the sensitivity and specificity of the linkage criteria, and sample size $M$. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

translink_tdr(sensitivity, specificity, rho, M, R = NULL, assumption = "mtml")

Arguments

Value

scalar or vector giving the true discovery rate

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other transmission linkage functions: translink_expected_links_obs_mtml(), translink_expected_links_obs_mtsl(), translink_expected_links_obs_stsl(), translink_expected_links_obs(), translink_expected_links_true_mtml(), translink_expected_links_true_mtsl(), translink_expected_links_true_stsl(), translink_expected_links_true(), translink_fdr(), translink_prob_transmit_mtml(), translink_prob_transmit_mtsl(), translink_prob_transmit_stsl(), translink_prob_transmit(), translink_samplesize()

Examples

# The simplest case: single-transmission, single-linkage, and perfect sensitivity
translink_tdr(sensitivity=1, specificity=0.9, rho=0.5, M=100, assumption='stsl')

# Multiple-transmission and imperfect sensitivity
translink_tdr(sensitivity=0.99, specificity=0.9, rho=1, M=50, R=1, assumption='mtsl')

# Small outbreak, larger sampling proportion
translink_tdr(sensitivity=0.99, specificity=0.95, rho=1, M=50, R=1, assumption='mtml')

# Large outbreak, small sampling proportion
translink_tdr(sensitivity=0.99, specificity=0.95, rho=0.5, M=1000, R=1, assumption='mtml')

Description

This function calculates the expected number true transmission pairs in a sample of size M. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

true_pairs(eta, rho, M, R = NULL, assumption = "mtml")

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other true_pairs: true_pairs_mtml(), true_pairs_mtsl(), true_pairs_stsl()

Examples

true_pairs(eta=0.99, rho=0.75, M=100, R=1)

Description

This function calculates the expected number of true transmission pairs in a sample of size M. The multiple-transmission and multiple-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to multiple cases $j$ in the sampled population ($M$).

3. Linkage events are independent of one another (i.e, linkage of case $i$ to case $j$ has no bearing on linkage of case $i$ to any other sample).

Usage

true_pairs_mtml(eta, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other true_pairs: true_pairs_mtsl(), true_pairs_stsl(), true_pairs()

Examples

true_pairs_mtml(eta=0.95, rho=0.2, M=1000, R=1)

Description

This function calculates the expected number true transmission pairs in a sample of size M. The multiple-transmission and single-linkage method assumes the following:

1. Each case $i$ is, on average, the infector of R cases in the population ($N$)

2. Each case $i$ is allowed to be linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

true_pairs_mtsl(eta, rho, M, R)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl and Justin Lessler

See Also

Other true_pairs: true_pairs_mtml(), true_pairs_stsl(), true_pairs()

Examples

true_pairs_mtsl(eta=0.95, rho=0.2, M=200, R=1)

Description

This function calculates the expected number of true transmission pairs in a sample of size M. The single-transmission and single-linkage method assumes the following:

1. Each case $i$ is linked by transmission to only one other case $j$ in the population ($N$).

2. Each case $i$ is linked by the linkage criteria to only one other case $j$ in the sampled population ($M$).

Usage

true_pairs_stsl(eta, rho, M)

Arguments

Value

scalar or vector giving the expected number of true transmission pairs in the sample

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other true_pairs: true_pairs_mtml(), true_pairs_mtsl(), true_pairs()

Examples

true_pairs_stsl(eta=0.95, rho=0.2, M=200)

Description

This function calculates the true discovery rate (proportion of true transmission pairs) in a sample given the sensitivity $\eta$ and specificity $\chi$ of the linkage criteria, and sample size $M$. Assumptions about transmission and linkage (single or multiple) can be specified.

Usage

truediscoveryrate(eta, chi, rho, M, R = NULL, assumption = "mtml")

Arguments

Value

scalar or vector giving the true discovery rate

Author(s)

John Giles, Shirlee Wohl, and Justin Lessler

See Also

Other discovery_rate: falsediscoveryrate()

Examples

# The simplest case: single-transmission, single-linkage, and perfect sensitivity
truediscoveryrate(eta=1, chi=0.9, rho=0.5, M=100, assumption='stsl')

# Multiple-transmission and imperfect sensitivity
truediscoveryrate(eta=0.99, chi=0.9, rho=1, M=50, R=1, assumption='mtsl')

# Small outbreak, larger sampling proportion
truediscoveryrate(eta=0.99, chi=0.95, rho=1, M=50, R=1, assumption='mtml')

# Large outbreak, small sampling proportion
truediscoveryrate(eta=0.99, chi=0.95, rho=0.5, M=1000, R=1, assumption='mtml')

Description

This function calculates the cumulative observed variant prevalence after t time steps (e.g., days) given a logistic growth rate and initial variant prevalence.

Usage

varfreq_cdf_logistic(t, p0_v1, r_v1, c_ratio = 1)

Arguments

Value

scalar giving the cdf of variant prevalence at time t

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other logistic growth functions: varfreq_freq_logistic()

Other variant frequency functions: varfreq_expected_mbias(), varfreq_freq_logistic(), varfreq_obs_freq()

Examples

varfreq_cdf_logistic(t = 30, p0_v1 = 1/10000, r_v1 = 0.1, c_ratio = 1)

Description

This function calculates the multiplicative bias of the observed variant proportion relative to the actual variant proportion. This function assumes that variant 1 is the variant of concern. This function is specific to the two-variant system.

Usage

varfreq_expected_mbias(p_v1, c_ratio)

Arguments

Value

scalar giving the multiplicative bias of variant 1

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant frequency functions: varfreq_cdf_logistic(), varfreq_freq_logistic(), varfreq_obs_freq()

Examples

varfreq_expected_mbias(p_v1 = 0.1, c_ratio = 1.1)

Description

This function calculates the observed variant prevalence after t time steps (e.g., days) given a logistic growth rate and initial variant prevalence.

Usage

varfreq_freq_logistic(t, p0_v1, r_v1, c_ratio = 1)

Arguments

Value

scalar giving the variant prevalence at time t

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other logistic growth functions: varfreq_cdf_logistic()

Other variant frequency functions: varfreq_cdf_logistic(), varfreq_expected_mbias(), varfreq_obs_freq()

Examples

varfreq_freq_logistic(t = 30, p0_v1 = 1/10000, r_v1 = 0.1, c_ratio = 1)

Description

This function calculates the observed variant prevalence from the coefficient of detection ratio and the actual variant prevalence. This function assumes that variant 1 is the variant of concern. This function is specific to the two-variant system.

Usage

varfreq_obs_freq(p_v1, c_ratio)

Arguments

Value

scalar of observed prevalence of variant 1

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant frequency functions: varfreq_cdf_logistic(), varfreq_expected_mbias(), varfreq_freq_logistic()

Examples

varfreq_obs_freq(p_v1 = 0.1, c_ratio = 1.1)

Description

This function calculates the coefficient of detection ratio $C_{V_1}/C_{V_2}$ for two variants. This function assumes that variant 1 is the variant of concern. This function is specific to the two-variant system. Parameters not provided are assumed to be equivalent between the two variants.

Usage

vartrack_cod_ratio(
  phi_v1 = 1,
  phi_v2 = 1,
  gamma_v1 = 1,
  gamma_v2 = 1,
  psi_v1 = 1,
  psi_v2 = 1,
  tau_a = 1,
  tau_s = 1
)

Arguments

Value

scalar giving the multiplicative bias of variant 1

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant tracking functions: vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_prob_prev_xsect(), vartrack_prob_prev(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

vartrack_cod_ratio(phi_v1=0.975, phi_v2=0.95, gamma_v1=0.8, gamma_v2=0.6)

Description

This function calculates the probability of detecting the presence of a variant given a sample size and sampling strategy.

Usage

vartrack_prob_detect(
  n,
  t = NA,
  p_v1 = NA,
  omega,
  p0_v1 = NA,
  r_v1 = NA,
  c_ratio = 1,
  sampling_freq
)

Arguments

Value

scalar of detection probability

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant detection functions: vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect()

Other variant tracking functions: vartrack_cod_ratio(), vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_prob_prev_xsect(), vartrack_prob_prev(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

# Cross-sectional sampling
vartrack_prob_detect(p_v1 = 0.02, n = 100, omega = 0.8, c_ratio = 1, sampling_freq = 'xsect')

# Periodic sampling
vartrack_prob_detect(n = 158, t = 30, omega = 0.8, p0_v1 = 1/10000, 
r_v1 = 0.1, c_ratio = 1, sampling_freq = 'cont')

Description

This function calculates the probability of detecting the presence of a variant given a sample size and either a desired maximum time until detection or a desired prevalence by which to detect the variant by. It assumes a periodic sampling strategy, where samples are collected at regular intervals (time steps).

Usage

vartrack_prob_detect_cont(
  n,
  t = NA,
  p_v1 = NA,
  omega,
  p0_v1,
  r_v1,
  c_ratio = 1
)

Arguments

Value

scalar of detection probability

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant detection functions: vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect()

Other variant tracking functions: vartrack_cod_ratio(), vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_prob_prev_xsect(), vartrack_prob_prev(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

vartrack_prob_detect_cont(n = 158, t = 30, omega = 0.8, p0_v1 = 1/10000, r_v1 = 0.1, c_ratio = 1)

Description

This function calculates the probability of detecting the presence of a variant given a sample size and assuming a single, cross-sectional sample of detected infections.

Usage

vartrack_prob_detect_xsect(p_v1, n, omega, c_ratio = 1)

Arguments

Value

scalar of expected sample size

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant detection functions: vartrack_prob_detect_cont(), vartrack_prob_detect(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect()

Other variant tracking functions: vartrack_cod_ratio(), vartrack_prob_detect_cont(), vartrack_prob_detect(), vartrack_prob_prev_xsect(), vartrack_prob_prev(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

vartrack_prob_detect_xsect(p_v1 = 0.02, n = 100, omega = 0.8, c_ratio = 1)

Description

This function calculates the probability of accurately estimating variant prevalence given a sample size and desired precision in the variant prevalence estimate. Currently, only cross-sectional sampling is supported.

Usage

vartrack_prob_prev(p_v1, n, omega, precision, c_ratio = 1, sampling_freq)

Arguments

Value

scalar of expected sample size

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant prevalence estimation functions: vartrack_prob_prev_xsect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Other variant tracking functions: vartrack_cod_ratio(), vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_prob_prev_xsect(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

vartrack_prob_prev(p_v1 = 0.1, n = 200, omega = 0.8, precision = 0.1, 
c_ratio = 1, sampling_freq = 'xsect')

Description

This function calculates the probability of accurately estimating variant prevalence given a given a sample size and desired precision in the variant prevalence estimate, and assuming a single, cross-sectional sample of detected infections.

Usage

vartrack_prob_prev_xsect(p_v1, n, omega, precision, c_ratio = 1)

Arguments

Value

scalar of expected sample size

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant prevalence estimation functions: vartrack_prob_prev(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Other variant tracking functions: vartrack_cod_ratio(), vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_prob_prev(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_detect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

vartrack_prob_prev_xsect(p_v1 = 0.1, n = 200, precision = 0.1, omega = 0.8, c_ratio = 1)

Description

This function calculates the sample size needed for detecting the presence of a variant given a desired probability of detection and sampling strategy.

Usage

vartrack_samplesize_detect(
  prob,
  t = NA,
  p_v1 = NA,
  omega,
  p0_v1 = NA,
  r_v1 = NA,
  c_ratio = 1,
  sampling_freq
)

Arguments

Value

scalar of expected sample size

Author(s)

Shirlee Wohl, Elizabeth C. Lee, Bethany L. DiPrete, and Justin Lessler

See Also

Other variant detection functions: vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect()

Other variant tracking functions: vartrack_cod_ratio(), vartrack_prob_detect_cont(), vartrack_prob_detect_xsect(), vartrack_prob_detect(), vartrack_prob_prev_xsect(), vartrack_prob_prev(), vartrack_samplesize_detect_cont(), vartrack_samplesize_detect_xsect(), vartrack_samplesize_prev_xsect(), vartrack_samplesize_prev()

Examples

# Cross-sectional sampling
vartrack_samplesize_detect(p_v1 = 0.1, prob = 0.95, omega = 0.8,
                           c_ratio = 1, sampling_freq = 'xsect')

# Periodic sampling
vartrack_samplesize_detect(prob = 0.95, t = 30, omega = 0.8, p0_v1 = 1/10000,
                           r_v1 = 0.1, c_ratio = 1, sampling_freq = 'cont')