estimate_multinom_ci {bumblebee}

estimate_multinom_ci Estimates confidence intervals for transmission flows

Description

This function computes simultaneous confidence intervals at the 5% significance level for estimated transmission flows. Available methods for computing confidence intervals are: Goodman, Goodman with a continuity correction, Sison-Glaz and Queensbury-Hurst.

Usage

estimate_multinom_ci(df_theta_hat, ...)

## Default S3 method:
estimate_multinom_ci(df_theta_hat, detailed_report = FALSE, ...)

Arguments

df_theta_hat

A data.frame returned by the function: estimate_theta_hat()

...

Further arguments.

detailed_report

A boolean value to produce detailed output of the analysis. (Default is FALSE)

Value

Returns a data.frame containing:

• H1_group, Name of population group 1

• H2_group, Name of population group 2

• number_hosts_sampled_group_1, Number of individuals sampled from population group 1

• number_hosts_sampled_group_2, Number of individuals sampled from population group 2

• number_hosts_population_group_1, Estimated number of individuals in population group 1

• number_hosts_population_group_2, Estimated number of individuals in population group 2

• max_possible_pairs_in_sample, Number of distinct possible transmission pairs between individuals sampled from population groups 1 and 2

• max_possible_pairs_in_population, Number of distinct possible transmission pairs between individuals in population groups 1 and 2

• num_linked_pairs_observed, Number of observed directed transmission pairs between samples from population groups 1 and 2

• p_hat, Probability that pathogen sequences from two individuals randomly sampled from their respective population groups are linked

• est_linkedpairs_in_population, Estimated transmission pairs between population groups 1 and 2

• theta_hat, Estimated transmission flows or relative probability of transmission within and between population groups 1 and 2 adjusted for sampling heterogeneity. More precisely, the conditional probability that a pair of pathogen sequences is from a specific population group pairing given that the pair is linked.

• obs_trm_pairs_est_goodman, Point estimate, Goodman method Confidence intervals for observed transmission pairs

• obs_trm_pairs_lwr_ci_goodman, Lower bound of Goodman confidence interval

• obs_trm_pairs_upr_ci_goodman, Upper bound of Goodman confidence interval

• est_goodman, Point estimate, Goodman method Confidence intervals for estimated transmission flows

• lwr_ci_goodman, Lower bound of Goodman confidence interval

• upr_ci_goodman, Upper bound of Goodman confidence interval

The following additional fields are returned if the detailed_report flag is set

• est_goodman_cc, Point estimate, Goodman method Confidence intervals with continuity correction

• lwr_ci_goodman_cc, Lower bound of Goodman confidence interval

• upr_ci_goodman_cc, Upper bound of Goodman confidence interval

• est_sisonglaz, Point estimate, Sison-Glaz method Confidence intervals

• lwr_ci_sisonglaz, Lower bound of Sison-Glaz confidence interval

• upr_ci_sisonglaz, Upper bound of Sison-Glaz confidence interval

• est_qhurst_acswr, Point estimate, Queensbury-Hurst method Confidence intervals via ACSWR r package

• lwr_ci_qhurst_acswr, Lower bound of Queensbury-Hurst confidence interval

• upr_ci_qhurst_acswr, Upper bound of Queensbury-Hurst confidence interval

• est_qhurst_coinmind, Point estimate, Queensbury-Hurst method Confidence intervals via CoinMinD r package

• lwr_ci_qhurst_coinmind, Lower bound of Queensbury-Hurst confidence interval

• upr_ci_qhurst_coinmind, Upper bound of Queensbury-Hurst confidence interval

• lwr_ci_qhurst_adj_coinmind, Lower bound of Queensbury-Hurst confidence interval adjusted

• upr_ci_qhurst_adj_coinmind, Upper bound of Queensbury-Hurst confidence interval adjusted

Methods (by class)

• default: Estimates confidence intervals for transmission flows

References

1. Magosi LE, et al., Deep-sequence phylogenetics to quantify patterns of HIV transmission in the context of a universal testing and treatment trial – BCPP/ Ya Tsie trial. To submit for publication, 2021.

2. Goodman, L. A. On Simultaneous Confidence Intervals for Multinomial Proportions Technometrics, 1965. 7, 247-254.

3. Cherry, S., A Comparison of Confidence Interval Methods for Habitat Use-Availability Studies. The Journal of Wildlife Management, 1996. 60(3): p. 653-658.

4. Sison, C.P and Glaz, J. Simultaneous confidence intervals and sample size determination for multinomial proportions. Journal of the American Statistical Association, 1995. 90:366-369.

5. Glaz, J., Sison, C.P. Simultaneous confidence intervals for multinomial proportions. Journal of Statistical Planning and Inference, 1999. 82:251-262.

6. May, W.L., Johnson, W.D. Constructing two-sided simultaneous confidence intervals for multinomial proportions for small counts in a large number of cells. Journal of Statistical Software, 2000. 5(6). Paper and code available at https://www.jstatsoft.org/v05/i06.

7. Carnegie, N.B., et al., Linkage of viral sequences among HIV-infected village residents in Botswana: estimation of linkage rates in the presence of missing data. PLoS Computational Biology, 2014. 10(1): p. e1003430.

8. Ratmann, O., et al., Inferring HIV-1 transmission networks and sources of epidemic spread in Africa with deep-sequence phylogenetic analysis. Nature Communications, 2019. 10(1): p. 1411.

9. Wymant, C., et al., PHYLOSCANNER: Inferring Transmission from Within- and Between-Host Pathogen Genetic Diversity. Molecular Biology and Evolution, 2017. 35(3): p. 719-733.

See Also

See estimate_theta_hat to prepare input data to estimate confidence intervals.

     To learn more about the Goodman and Sison-Glaz confidence interval methods 
     see \code{\link[DescTools]{MultinomCI}}. For Queensbury-Hurst confidence
     intervals see \code{\link[ACSWR]{QH_CI}} and \code{\link[CoinMinD]{QH}}

Examples

library(bumblebee)
library(dplyr)

# Compute confidence intervals for estimated transmission flows

# We shall use the data of HIV transmissions within and between intervention and control
# communities in the BCPP/Ya Tsie HIV prevention trial. To learn more about the data 
# ?counts_hiv_transmission_pairs and ?sampling_frequency


# Load and view data
#
# The data comprises counts of observed directed HIV transmission pairs between individuals 
# sampled from intervention and control communities (i.e. num_linked_pairs_observed); 
# and the estimated HIV transmissions within and between intervention and control 
# communities in the BCPP/Ya Tsie trial population adjusted for sampling heterogneity
# (i.e. \code{est_linkedpairs_in_population}). See ?estimate_theta_hat() for details on 
# computing \code{est_linkedpairs_in_population} and \code{theta_hat}.

results_estimate_theta_hat <- estimated_hiv_transmission_flows[, c(1:13)]
 
results_estimate_theta_hat
 
# Compute Goodman confidence intervals (Default)
results_estimate_multinom_ci <- estimate_multinom_ci(
    df_theta_hat = results_estimate_theta_hat, 
    detailed_report = FALSE)

# View results
results_estimate_multinom_ci

# Compute Goodman, Sison-Glaz and Queensbury-Hurst confidence intervals
results_estimate_multinom_ci_detailed <- estimate_multinom_ci(
    df_theta_hat = results_estimate_theta_hat, 
    detailed_report = TRUE)

# View results
results_estimate_multinom_ci_detailed