Package {OutbreakR}

Calculate Attack Rate

Description

Calculates the attack rate during an outbreak with an exact binomial confidence interval.

The function supports two modes:

1. Numeric mode, using the number of cases and population at risk.

2. Data mode, using a data frame containing individual-level case status.

Group-specific attack rates can also be calculated when group is specified.

Usage

attack_rate(
  cases = NULL,
  population = NULL,
  data = NULL,
  case = NULL,
  case_value = TRUE,
  group = NULL,
  multiplier = 100,
  conf_level = 0.95,
  na.rm = TRUE
)

Arguments

Details

The attack rate is the proportion of the population at risk that develops disease during a specified outbreak period.

Exact binomial confidence intervals are calculated using stats::binom.test().

The denominator should represent the population genuinely at risk during the outbreak.

Value

An object of class "outbreak_attack_rate".

In numeric mode, the returned object contains:

cases

Number of cases.

population

Population at risk.

attack_rate

Estimated attack rate.

lower_ci

Lower confidence limit.

upper_ci

Upper confidence limit.

conf_level

Confidence level used.

multiplier

Scale used for the attack rate.

In grouped data mode, a data frame containing group-specific attack rates and confidence intervals is returned.

Examples

# Numeric mode
attack_rate(
  cases = 45,
  population = 250
)

# Express per 1,000 population
attack_rate(
  cases = 45,
  population = 250,
  multiplier = 1000
)

# Data mode
outbreak_data <- data.frame(
  case_status = c(
    TRUE, TRUE, FALSE,
    TRUE, FALSE, FALSE
  ),
  village = c(
    "A", "A", "A",
    "B", "B", "B"
  )
)

attack_rate(
  data = outbreak_data,
  case = case_status
)

# Group-specific attack rates
attack_rate(
  data = outbreak_data,
  case = case_status,
  group = village
)

Calculate Attributable Fraction Among the Exposed

Description

attributable_fraction_exposed() provides a comprehensive analysis of the fraction of disease among exposed individuals that can be attributed to a specific exposure. It is suitable for cohort studies, outbreak investigations, clinical epidemiology, veterinary epidemiology and One Health research.

The function supports:

• Aggregate (numeric) data

• 2 x 2 contingency table input

• Individual-level data

• Group-wise analysis

• Confidence intervals

• Chi-square or Fisher's Exact Test

Usage

attributable_fraction_exposed(
  exposed_cases = NULL,
  exposed_total = NULL,
  unexposed_cases = NULL,
  unexposed_total = NULL,
  cases = NULL,
  totals = NULL,
  data = NULL,
  outcome = NULL,
  outcome_value = TRUE,
  exposure = NULL,
  exposed_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  continuity = TRUE,
  fisher = FALSE,
  na.rm = TRUE
)

Arguments

Details

Calculates the Attributable Fraction among the Exposed (AFE), also known as the Attributable Proportion among the Exposed or Etiologic Fraction, using aggregate counts or individual-level epidemiological data. The function estimates the proportion of disease among exposed individuals attributable to the exposure together with relative risk, confidence intervals and statistical significance.

Attributable Fraction among the Exposed is calculated as

AFE= \frac{R_e-R_u} {R_e}

or equivalently

AFE= \frac{RR-1} {RR}

where

R_e= \frac{a}{a+b}

and

R_u= \frac{c}{c+d}

Relative Risk is calculated as

RR= \frac{R_e} {R_u}

Odds Ratio is calculated as

OR= \frac{ad} {bc}

Confidence intervals are obtained from the log-transformed Relative Risk and then transformed to the attributable fraction.

Value

An object of class "outbreak_attributable_fraction_exposed" or "outbreak_attributable_fraction_exposed_grouped".

References

Rothman KJ, Greenland S, Lash TL (2008). Modern Epidemiology. 3rd Edition.

Examples

## Aggregate data
attributable_fraction_exposed(
  exposed_cases = 38,
  exposed_total = 500,
  unexposed_cases = 15,
  unexposed_total = 600
)

## 2 x 2 vectors
attributable_fraction_exposed(
  cases = c(38, 15),
  totals = c(500, 600)
)

## Individual-level data
outbreak_data <- data.frame(
  Disease = c(
    rep(1, 38), rep(0, 462),
    rep(1, 15), rep(0, 585)
  ),
  Smoking = c(
    rep(1, 500),
    rep(0, 600)
  ),
  District = rep(
    c("District_A", "District_B"),
    length.out = 1100
  )
)

attributable_fraction_exposed(
  data = outbreak_data,
  outcome = Disease,
  exposure = Smoking
)

## Group-wise analysis
attributable_fraction_exposed(
  data = outbreak_data,
  outcome = Disease,
  exposure = Smoking,
  group = District
)

Calculate Attributable Risk (Risk Difference)

Description

attributable_risk() provides a comprehensive analysis of the absolute effect of an exposure in cohort studies, outbreak investigations, clinical epidemiology, veterinary epidemiology, and One Health research.

The function supports:

• Aggregate (numeric) data

• 2 x 2 contingency table input

• Individual-level data

• Group-wise analysis

• Confidence intervals

• Chi-square or Fisher's Exact Test

Usage

attributable_risk(
  exposed_cases = NULL,
  exposed_total = NULL,
  unexposed_cases = NULL,
  unexposed_total = NULL,
  cases = NULL,
  totals = NULL,
  data = NULL,
  outcome = NULL,
  outcome_value = TRUE,
  exposure = NULL,
  exposed_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  continuity = TRUE,
  fisher = FALSE,
  na.rm = TRUE
)

Arguments

Details

Calculates the attributable risk (AR), also known as the risk difference (RD), between exposed and unexposed groups using aggregate counts or individual-level epidemiological data. The function estimates attributable risk, attributable risk percent, relative risk, odds ratio, number needed to treat or harm, confidence intervals, and statistical significance.

Attributable Risk (Risk Difference) is calculated as

AR = R_e - R_u

where

R_e = \frac{a}{a+b}

and

R_u = \frac{c}{c+d}

Attributable Risk Percent is

AR\% = \frac{R_e-R_u} {R_e} \times100

Relative Risk is

RR = \frac{R_e}{R_u}

Odds Ratio is

OR = \frac{ad}{bc}

Number Needed to Treat (NNT) or Number Needed to Harm (NNH) is calculated as

NNT = \frac{1}{|AR|}

Confidence intervals for the risk difference are calculated using the normal approximation.

Value

An object of class "outbreak_attributable_risk" or "outbreak_attributable_risk_grouped".

References

Rothman KJ, Greenland S, Lash TL (2008). Modern Epidemiology. 3rd Edition.

Examples

## Aggregate data
attributable_risk(
  exposed_cases = 38,
  exposed_total = 500,
  unexposed_cases = 15,
  unexposed_total = 600
)

## 2 x 2 vectors
attributable_risk(
  cases = c(38, 15),
  totals = c(500, 600)
)

## Individual-level data
outbreak_data <- data.frame(
  Disease = c(
    rep(1, 38), rep(0, 462),
    rep(1, 15), rep(0, 585)
  ),
  Exposure = c(
    rep(1, 500),
    rep(0, 600)
  ),
  District = rep(
    c("District_A", "District_B"),
    length.out = 1100
  )
)

attributable_risk(
  data = outbreak_data,
  outcome = Disease,
  exposure = Exposure
)

## Group-wise analysis
attributable_risk(
  data = outbreak_data,
  outcome = Disease,
  exposure = Exposure,
  group = District
)

Estimate the Basic Reproduction Number (R0)

Description

basic_reproduction_number() estimates the basic reproduction number, commonly denoted R0, which represents the expected number of secondary infections generated by one typical infectious individual introduced into a fully susceptible population under specified model assumptions.

The function supports multiple estimation approaches:

• Exponential-growth approximation

• Doubling-time approximation

• SIR transmission model

• Epidemic final-size relationship

The appropriate method depends on the type of epidemiological information available and the assumptions of the transmission model.

Usage

basic_reproduction_number(
  method = c("exponential_growth", "doubling_time", "sir", "final_size"),
  growth_rate = NULL,
  doubling_time = NULL,
  generation_time = NULL,
  beta = NULL,
  gamma = NULL,
  final_size = NULL,
  susceptible_fraction = 1,
  conf_level = 0.95
)

Arguments

Details

Estimates the basic reproduction number (R0) using several commonly used infectious-disease transmission approaches, including exponential growth, epidemic doubling time, SIR model parameters, and the epidemic final-size relationship.

The basic reproduction number is a central quantity in infectious-disease epidemiology. In general:

R_0 > 1

indicates that transmission can increase during the early phase of an outbreak under the model assumptions, whereas

R_0 < 1

indicates that sustained epidemic growth is not expected.

Exponential-growth approximation

Under a simple approximation using epidemic growth rate r and mean generation time T_g:

R_0 \approx 1 + rT_g

This is a simplified approximation and should not be interpreted as a general generation-interval model.

Doubling-time approximation

Epidemic growth rate may be approximated from doubling time:

r = \frac{\log(2)}{T_d}

giving:

R_0 \approx 1 + \frac{\log(2)T_g}{T_d}

where T_d is epidemic doubling time.

SIR method

For the standard SIR model:

R_0 = \frac{\beta}{\gamma}

where \beta is the transmission rate and \gamma is the recovery/removal rate.

Final-size method

Under the standard homogeneous SIR final-size relationship and an initially fully susceptible population:

R_0 = -\frac{\log(1-z)}{z}

where z is the final epidemic proportion infected.

When the initial susceptible fraction differs from one, the interpretation and final-size equation require additional assumptions. The function therefore validates the supplied susceptible fraction before applying the selected method.

Value

An object of class "outbreak_basic_reproduction_number".

Depending on the selected method, the returned object contains:

• Estimated basic reproduction number (R0)

• Estimation method

• Growth rate

• Doubling time

• Generation time

• Transmission rate

• Recovery rate

• Final epidemic size

• Initial susceptible fraction

• Confidence level

• Epidemiological interpretation

References

Anderson RM, May RM (1991). Infectious Diseases of Humans: Dynamics and Control. Oxford University Press.

Diekmann O, Heesterbeek JAP, Roberts MG (2010). The construction of next-generation matrices for compartmental epidemic models. Journal of the Royal Society Interface, 7, 873-885.

Wallinga J, Lipsitch M (2007). How generation intervals shape the relationship between growth rates and reproductive numbers. Proceedings of the Royal Society B, 274, 599-604.

Examples

## Exponential-growth approximation
basic_reproduction_number(
  method = "exponential_growth",
  growth_rate = 0.15,
  generation_time = 5
)

## Doubling-time approximation
basic_reproduction_number(
  method = "doubling_time",
  doubling_time = 4,
  generation_time = 5
)

## SIR model
basic_reproduction_number(
  method = "sir",
  beta = 0.4,
  gamma = 0.2
)

## Final-size method
basic_reproduction_number(
  method = "final_size",
  final_size = 0.70
)

Calculate Case Fatality Rate

Description

Calculates the case fatality rate (CFR) during an outbreak together with an exact binomial confidence interval.

The function supports two modes:

1. Numeric mode using the number of deaths and total cases.

2. Data mode using an individual-level outbreak line list.

Group-specific case fatality rates can also be calculated using a grouping variable such as village, district, species, age group, sex, ward, farm, production unit, or outbreak.

Usage

case_fatality_rate(
  deaths = NULL,
  cases = NULL,
  data = NULL,
  outcome = NULL,
  death_value = "Dead",
  group = NULL,
  multiplier = 100,
  conf_level = 0.95,
  na.rm = TRUE
)

Arguments

Details

The case fatality rate (CFR) estimates the proportion of diagnosed cases that die from the disease during a specified outbreak.

The denominator should include confirmed (or otherwise eligible) outbreak cases only.

Exact binomial confidence intervals are calculated using stats::binom.test().

Value

Numeric mode returns an object of class "outbreak_case_fatality_rate".

Grouped data mode returns an object of class "outbreak_case_fatality_rate_grouped" and "data.frame".

References

Gordis L. Epidemiology. 6th Edition. Elsevier.

Centers for Disease Control and Prevention (CDC). Principles of Epidemiology in Public Health Practice.

Examples

## Numeric mode

case_fatality_rate(
  deaths = 18,
  cases = 250
)

## Per 1,000 cases

case_fatality_rate(
  deaths = 18,
  cases = 250,
  multiplier = 1000
)

## Data mode

outbreak_data <- data.frame(
  outcome = c(
    "Recovered",
    "Recovered",
    "Dead",
    "Recovered",
    "Dead",
    "Recovered"
  ),
  village = c(
    "A",
    "A",
    "A",
    "B",
    "B",
    "B"
  )
)

case_fatality_rate(
  data = outbreak_data,
  outcome = outcome
)

## Group-specific CFR

case_fatality_rate(
  data = outbreak_data,
  outcome = outcome,
  group = village
)

Estimate the Effective Reproduction Number (Re or Rt)

Description

effective_reproduction_number() estimates the effective reproduction number, commonly denoted Re or Rt, representing the expected number of secondary infections generated by one infectious individual under current population and transmission conditions.

Unlike the basic reproduction number (R0), which assumes a fully susceptible population under baseline transmission conditions, the effective reproduction number accounts for factors such as reduced susceptibility, vaccination, immunity, and changes in transmission rates.

The function supports four estimation methods:

• Susceptible-fraction adjustment

• Vaccination adjustment

• Combined susceptibility and vaccination adjustment

• Time-varying transmission-rate method

Usage

effective_reproduction_number(
  R0 = NULL,
  method = c("susceptible", "vaccination", "combined", "transmission_rate"),
  susceptible_fraction = NULL,
  vaccination_coverage = NULL,
  vaccine_effectiveness = NULL,
  beta_t = NULL,
  gamma = NULL,
  conf_level = 0.95
)

Arguments

Details

Estimates the effective reproduction number under partial population susceptibility, vaccination, combined susceptibility and vaccination, or time-varying transmission conditions.

The effective reproduction number describes transmission under current epidemiological conditions.

In general:

R_e > 1

indicates that infections can increase, whereas:

R_e < 1

indicates that transmission is expected to decline under the assumptions of the selected model.

Susceptible-fraction method

When only a fraction S of the population remains susceptible:

R_e = R_0 S

Vaccination method

Under a simple leaky-vaccine approximation:

R_e = R_0(1-vE)

where v is vaccination coverage and E is vaccine effectiveness for the transmission-relevant outcome.

Combined method

When susceptible_fraction represents susceptibility remaining for reasons other than the vaccination effect represented by v * E:

R_e = R_0 S(1-vE)

This formulation assumes that the susceptibility reduction represented by S does not already include the vaccination effect. Otherwise vaccination may be counted twice.

Transmission-rate method

Under an SIR-type model with current transmission rate \beta_t, recovery/removal rate \gamma, and susceptible fraction S_t:

R_t = \frac{\beta_t}{\gamma}S_t

Herd-immunity threshold

For R_0 > 1, the classical homogeneous herd-immunity threshold is:

HIT = 1-\frac{1}{R_0}

Critical vaccination coverage

Under the simple vaccination model, the vaccination coverage required to reduce the effective reproduction number to one is:

V_c = \frac{1-1/R_0}{E}

A calculated value above 1 indicates that the threshold cannot be achieved through vaccination alone at the supplied vaccine effectiveness under the model assumptions.

Value

An object of class "outbreak_effective_reproduction_number".

Depending on the selected method, the returned object may contain:

• Effective reproduction number (Re)

• Basic reproduction number (R0)

• Susceptible fraction

• Vaccination coverage

• Vaccine effectiveness

• Current transmission rate

• Recovery/removal rate

• Herd-immunity threshold

• Critical vaccination coverage

• Transmission status

• Confidence level

• Epidemiological interpretation

References

Anderson RM, May RM (1991). Infectious Diseases of Humans: Dynamics and Control. Oxford University Press.

Diekmann O, Heesterbeek JAP, Britton T (2013). Mathematical Tools for Understanding Infectious Disease Dynamics. Princeton University Press.

Fine P, Eames K, Heymann DL (2011). Herd immunity: a rough guide. Clinical Infectious Diseases, 52, 911-916.

Examples

## Susceptible-fraction adjustment
effective_reproduction_number(
  R0 = 2.5,
  method = "susceptible",
  susceptible_fraction = 0.60
)

## Vaccination adjustment
effective_reproduction_number(
  R0 = 2.5,
  method = "vaccination",
  vaccination_coverage = 0.70,
  vaccine_effectiveness = 0.90
)

## Combined susceptibility and vaccination
effective_reproduction_number(
  R0 = 2.5,
  method = "combined",
  susceptible_fraction = 0.80,
  vaccination_coverage = 0.60,
  vaccine_effectiveness = 0.90
)

## Time-varying transmission rate
effective_reproduction_number(
  method = "transmission_rate",
  beta_t = 0.30,
  gamma = 0.20,
  susceptible_fraction = 0.75
)

Estimate the Herd Immunity Threshold

Description

herd_immunity_threshold() estimates the theoretical fraction of a population that must be effectively immune for the effective reproduction number to reach or fall below a specified target.

For the classical epidemic-control target of target_Re = 1, the homogeneous herd-immunity threshold is:

HIT = 1 - \frac{1}{R_0}

More generally, for a specified target effective reproduction number R_{e,target}, the required effective immune fraction is:

I_{required} = 1 - \frac{R_{e,target}}{R_0}

The function additionally supports existing immunity and imperfect vaccination to estimate the remaining immunity gap, critical vaccination coverage, additional vaccination requirements, and whether a specified control target is theoretically achievable through vaccination.

Usage

herd_immunity_threshold(
  R0,
  vaccine_effectiveness = NULL,
  target_Re = 1,
  existing_immunity = 0,
  conf_level = 0.95
)

Arguments

Details

Estimates the population-level immunity required to reduce transmission to a specified effective reproduction number. The function can also incorporate existing immunity and imperfect vaccine effectiveness to estimate immunity gaps and vaccination requirements.

The classical herd-immunity threshold assumes homogeneous mixing, homogeneous susceptibility and infectiousness, a closed population, and immunity that completely removes individuals from the susceptible pool.

Classical herd-immunity threshold

For R_0 > 1:

HIT = 1 - \frac{1}{R_0}

When R_0 \leq 1, no positive classical herd-immunity threshold is required to bring transmission to the conventional threshold R_e \leq 1.

General target effective reproduction number

For a specified target R_{e,target}:

I_{required} = 1 - \frac{R_{e,target}}{R_0}

Negative values are truncated to zero because no additional population immunity is required when the baseline reproduction number is already at or below the specified target.

Existing immunity

If a fraction I_0 of the population is already effectively immune, the remaining immunity gap is:

I_{gap} = \max(0, I_{required} - I_0)

Under the simple homogeneous susceptibility model, the effective reproduction number associated with existing immunity is:

R_e = R_0(1-I_0)

Imperfect vaccine

When vaccine effectiveness E is supplied, the vaccination coverage required to generate the target effective immune fraction from an otherwise susceptible population is:

V_c = \frac{I_{required}}{E}

After accounting for existing immunity, the additional vaccination coverage required under the model is:

V_{additional} = \frac{I_{gap}}{E}

These calculations assume that vaccine-derived protection is not already included in existing_immunity. If it is already included, supplying the same vaccine protection again may double-count immunity.

A vaccination requirement greater than 1 indicates that the specified target cannot be achieved through vaccination alone at the supplied vaccine effectiveness under the simple model assumptions.

Value

An object of class "outbreak_herd_immunity_threshold".

The returned object may contain:

• Basic reproduction number (R0)

• Target effective reproduction number

• Classical herd-immunity threshold

• Required effective immunity

• Existing immunity

• Remaining immunity gap

• Current effective reproduction number

• Critical susceptible fraction

• Vaccine effectiveness

• Critical vaccination coverage

• Additional vaccination coverage required

• Target-achievability indicators

• Confidence level

• Epidemiological interpretation

References

Anderson RM, May RM (1991). Infectious Diseases of Humans: Dynamics and Control. Oxford University Press.

Fine P, Eames K, Heymann DL (2011). Herd immunity: a rough guide. Clinical Infectious Diseases, 52, 911-916.

Diekmann O, Heesterbeek JAP, Britton T (2013). Mathematical Tools for Understanding Infectious Disease Dynamics. Princeton University Press.

Examples

## Classical herd-immunity threshold
herd_immunity_threshold(
  R0 = 2.5
)

## Account for existing immunity
herd_immunity_threshold(
  R0 = 2.5,
  existing_immunity = 0.30
)

## Imperfect vaccine
herd_immunity_threshold(
  R0 = 2.5,
  vaccine_effectiveness = 0.90
)

## Existing immunity plus imperfect vaccine
herd_immunity_threshold(
  R0 = 2.5,
  existing_immunity = 0.20,
  vaccine_effectiveness = 0.90
)

## More stringent transmission target
herd_immunity_threshold(
  R0 = 3,
  target_Re = 0.8,
  existing_immunity = 0.25,
  vaccine_effectiveness = 0.85
)

Calculate Incidence Proportion

Description

incidence_proportion() estimates the proportion of an initially disease-free population that develops the outcome of interest during a specified period.

Incidence proportion is a measure of risk and differs from incidence rate, which uses person-time or animal-time in the denominator.

Usage

incidence_proportion(
  cases,
  population_at_risk,
  multiplier = 100,
  conf_level = 0.95,
  ci_method = c("wilson", "exact")
)

Arguments

Details

Calculates the incidence proportion, also known as cumulative incidence or risk, among individuals or animals initially at risk during a specified observation period.

Incidence proportion is calculated as:

IP = \frac{C}{N}

where C is the number of new cases occurring during the observation period and N is the population at risk at the beginning of that period.

The scaled incidence proportion is:

IP_m = \frac{C}{N} \times m

where m is the user-specified multiplier.

For example, with multiplier = 100, the result is expressed as a percentage:

IP_{\%} = \frac{C}{N} \times 100

Incidence proportion represents the probability or risk that an initially susceptible individual or animal develops the outcome during the specified period, under the assumptions required for interpreting cumulative incidence.

Unlike an incidence rate, incidence proportion does not use person-time or animal-time in the denominator.

The number of new cases cannot exceed the population initially at risk.

Confidence intervals can be estimated using either the Wilson score interval or the exact binomial interval.

Value

An object of class "outbreak_incidence_proportion" containing the incidence-proportion estimate, confidence interval, epidemiological quantities, and interpretation.

References

Rothman KJ, Greenland S, Lash TL (2008). Modern Epidemiology. 3rd ed. Lippincott Williams & Wilkins.

Gordis L (2014). Epidemiology. 5th ed. Elsevier Saunders.

Wilson EB (1927). Probable inference, the law of succession, and statistical inference. Journal of the American Statistical Association, 22, 209-212.

Examples

## Incidence proportion expressed as percentage
incidence_proportion(
  cases = 25,
  population_at_risk = 500
)

## Express as a proportion
incidence_proportion(
  cases = 25,
  population_at_risk = 500,
  multiplier = 1
)

## Express per 1,000 population at risk
incidence_proportion(
  cases = 25,
  population_at_risk = 500,
  multiplier = 1000
)

## Exact binomial confidence interval
incidence_proportion(
  cases = 5,
  population_at_risk = 100,
  ci_method = "exact"
)

## 99% confidence interval
incidence_proportion(
  cases = 40,
  population_at_risk = 800,
  conf_level = 0.99
)

Calculate Incidence Rate

Description

incidence_rate() estimates the incidence rate as the number of incident cases divided by the total person-time at risk.

The function supports:

• Numeric (aggregate) analysis

• Individual-level data analysis

• Group-wise incidence rate estimation

• Exact Poisson confidence intervals

• Custom incidence rate multipliers

Usage

incidence_rate(
  cases = NULL,
  person_time = NULL,
  data = NULL,
  event = NULL,
  person_time_var = NULL,
  event_value = TRUE,
  group = NULL,
  multiplier = 1000,
  conf_level = 0.95,
  na.rm = TRUE
)

Arguments

Details

Calculates the incidence rate using either aggregated counts or individual-level outbreak data. The function supports overall and grouped analyses and reports incidence rates with exact Poisson confidence intervals.

The incidence rate is calculated as

Incidence\ Rate = \frac{Cases}{Person\ Time}

Exact Poisson confidence intervals are calculated using the chi-square distribution.

Person-time may represent:

• Animal-years

• Person-years

• Animal-months

• Person-months

• Animal-days

• Follow-up time

The reported incidence rate is multiplied by the specified multiplier.

Value

An object of class "outbreak_incidence_rate" or "outbreak_incidence_rate_grouped" containing:

• Number of incident cases

• Total person-time

• Incidence rate

• Scaled incidence rate

• Exact Poisson confidence interval

• Standard error

• Variance

• Confidence level

• Estimation method

Examples

## Numeric mode
incidence_rate(
  cases = 48,
  person_time = 2450
)

## Data mode
outbreak_data <- data.frame(
  Disease = c(
    1, 0, 1, 0, 0,
    1, 0, 1, 0, 0
  ),
  AnimalYears = c(
    1.2, 1.0, 0.8, 1.5, 1.1,
    0.9, 1.3, 1.0, 1.4, 0.8
  ),
  District = c(
    rep("District_A", 5),
    rep("District_B", 5)
  )
)

incidence_rate(
  data = outbreak_data,
  event = Disease,
  person_time_var = AnimalYears
)

## Group-wise incidence rates
incidence_rate(
  data = outbreak_data,
  event = Disease,
  person_time_var = AnimalYears,
  group = District
)

Calculate Mortality Rate

Description

mortality_rate() estimates mortality using one of two denominators:

• Population at risk (mortality proportion)

• Person-time at risk (mortality incidence rate)

The function supports:

• Numeric (aggregate) analysis

• Individual-level data analysis

• Group-wise analysis

• Population-based mortality

• Person-time mortality rate

• Exact Binomial confidence intervals

• Exact Poisson confidence intervals

Usage

mortality_rate(
  deaths = NULL,
  population = NULL,
  person_time = NULL,
  data = NULL,
  death = NULL,
  death_value = TRUE,
  person_time_var = NULL,
  group = NULL,
  multiplier = 1000,
  conf_level = 0.95,
  ci_method = c("exact", "wilson", "agresti", "wald"),
  na.rm = TRUE
)

Arguments

Details

Calculates mortality measures using either aggregated counts or individual-level epidemiological data. The function supports both mortality proportion (deaths/population) and mortality rate (deaths/person-time), with optional grouped analyses.

Population mortality is calculated as

Mortality = \frac{Deaths}{Population}

Person-time mortality rate is calculated as

Mortality\ Rate = \frac{Deaths}{Person\ Time}

Exact Poisson confidence intervals are used for person-time mortality.

Exact Binomial, Wilson, Agresti-Coull or Wald confidence intervals are used for mortality proportion.

Value

An object of class "outbreak_mortality_rate" or "outbreak_mortality_rate_grouped".

Examples

## Population mortality
mortality_rate(
  deaths = 25,
  population = 850
)

## Person-time mortality
mortality_rate(
  deaths = 25,
  person_time = 4200
)

## Data mode
herd_data <- data.frame(
  Death = c(
    0, 0, 1, 0, 0,
    1, 0, 0, 0, 1,
    0, 0, 1, 0, 0,
    0, 1, 0, 0, 0
  ),
  District = rep(
    c("District_A", "District_B"),
    each = 10
  )
)

mortality_rate(
  data = herd_data,
  death = Death
)

Number Needed to Harm (NNH)

Description

Calculates the Number Needed to Harm (NNH), Absolute Risk Increase (ARI), Relative Risk (RR), Relative Risk Increase (RRI), Odds Ratio (OR), and associated confidence intervals from aggregate counts, vectors, or individual-level data.

Usage

number_needed_to_harm(
  treatment_cases = NULL,
  treatment_total = NULL,
  control_cases = NULL,
  control_total = NULL,
  cases = NULL,
  totals = NULL,
  data = NULL,
  outcome = NULL,
  outcome_value = TRUE,
  treatment = NULL,
  treatment_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  continuity = TRUE,
  fisher = FALSE,
  na.rm = TRUE
)

Arguments

Details

The function supports aggregate (2x2 table), vector, individual-level, and grouped analyses and returns publication-ready epidemiological measures using an S3 object.

Number Needed to Harm is defined as:

NNH = \frac{1}{ARI}

where

ARI = EER - CER

Experimental Event Rate:

EER = \frac{a}{a+b}

Control Event Rate:

CER = \frac{c}{c+d}

Relative Risk:

RR = \frac{EER}{CER}

Relative Risk Increase:

RRI = RR - 1

Odds Ratio:

OR = \frac{ad}{bc}

Value

An object of class "outbreak_number_needed_to_harm" containing:

• Treatment cases

• Treatment population

• Control cases

• Control population

• Experimental Event Rate (EER)

• Control Event Rate (CER)

• Absolute Risk Increase (ARI)

• Absolute Risk Increase (%)

• Number Needed to Harm (NNH)

• Relative Risk (RR)

• Relative Risk Increase (RRI)

• Relative Risk Increase (%)

• Odds Ratio (OR)

• Standard error

• Variance

• Confidence intervals for RR

• Confidence intervals for ARI

• Confidence intervals for NNH

• Z statistic

• P-value

• Pearson Chi-square or Fisher's Exact Test

Grouped analyses return an object of class "outbreak_number_needed_to_harm_grouped".

Examples

## Aggregate analysis
number_needed_to_harm(
  treatment_cases = 28,
  treatment_total = 250,
  control_cases = 15,
  control_total = 250
)

## Vector input
number_needed_to_harm(
  cases = c(28, 15),
  totals = c(250, 250)
)

## Individual-level data
# number_needed_to_harm(
#   data = trial,
#   outcome = adverse_event,
#   treatment = drug
# )

## Grouped analysis
# number_needed_to_harm(
#   data = trial,
#   outcome = adverse_event,
#   treatment = drug,
#   group = hospital
# )

Calculate Number Needed to Treat

Description

number_needed_to_treat() estimates the number of individuals that must receive an intervention to prevent one additional adverse outcome compared with a control group. The function supports aggregate data, 2 x 2 tables, individual-level data and grouped analyses for clinical trials, epidemiological studies, veterinary medicine, public health and One Health research.

The function supports:

• Aggregate (numeric) data

• 2 x 2 contingency table input

• Individual-level data

• Group-wise analysis

• Confidence intervals

• Pearson's Chi-square or Fisher's Exact Test

Usage

number_needed_to_treat(
  treatment_cases = NULL,
  treatment_total = NULL,
  control_cases = NULL,
  control_total = NULL,
  cases = NULL,
  totals = NULL,
  data = NULL,
  outcome = NULL,
  outcome_value = TRUE,
  treatment = NULL,
  treatment_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  continuity = TRUE,
  fisher = FALSE,
  na.rm = TRUE
)

Arguments

Details

Calculates the Number Needed to Treat (NNT), Absolute Risk Reduction (ARR), Relative Risk (RR), Relative Risk Reduction (RRR), Odds Ratio (OR), confidence intervals and statistical significance using aggregate counts or individual-level epidemiological data.

Experimental Event Rate (EER):

EER= \frac{a} {a+b}

Control Event Rate (CER):

CER= \frac{c} {c+d}

Absolute Risk Reduction (ARR):

ARR= CER-EER

Number Needed to Treat:

NNT= \frac{1} {ARR}

Relative Risk:

RR= \frac{EER} {CER}

Relative Risk Reduction:

RRR= 1-RR

Odds Ratio:

OR= \frac{ad} {bc}

Confidence intervals are obtained from the log-transformed Relative Risk. Confidence intervals for ARR and NNT are derived from the ARR confidence limits.

Value

An object of class "outbreak_number_needed_to_treat" or "outbreak_number_needed_to_treat_grouped".

References

Altman DG (1998). Confidence intervals for the number needed to treat. BMJ, 317, 1309-1312.

Rothman KJ, Greenland S, Lash TL (2008). Modern Epidemiology. Third Edition.

Examples

## Aggregate data
number_needed_to_treat(
  treatment_cases = 12,
  treatment_total = 250,
  control_cases = 25,
  control_total = 250
)

## 2 x 2 vectors
number_needed_to_treat(
  cases = c(12, 25),
  totals = c(250, 250)
)

## Individual-level data
trial_data <- data.frame(
  Disease = c(
    rep(1, 12), rep(0, 238),
    rep(1, 25), rep(0, 225)
  ),
  Vaccine = c(
    rep(1, 250),
    rep(0, 250)
  ),
  Hospital = rep(
    c("Hospital_A", "Hospital_B"),
    length.out = 500
  )
)

number_needed_to_treat(
  data = trial_data,
  outcome = Disease,
  treatment = Vaccine
)

Calculate Odds Ratio

Description

Calculates the odds ratio (OR) together with confidence intervals for 2 x 2 contingency tables, case-control studies, cross-sectional studies and outbreak investigations.

The function supports two modes:

1. Numeric mode using a 2 x 2 contingency table.

2. Data mode using individual-level outbreak data.

Group-wise analyses may also be performed using variables such as district, village, farm, herd, flock, species, age group, production unit or outbreak identifier.

Usage

odds_ratio(
  exposed_cases = NULL,
  exposed_total = NULL,
  unexposed_cases = NULL,
  unexposed_total = NULL,
  data = NULL,
  outcome = NULL,
  exposure = NULL,
  outcome_value = TRUE,
  exposure_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  correction = TRUE,
  na.rm = TRUE
)

Arguments

Details

Odds ratio compares the odds of disease among exposed individuals with the odds among unexposed individuals.

OR > 1 indicates increased odds associated with exposure.

OR < 1 indicates a protective exposure.

OR = 1 indicates no association.

Confidence intervals are calculated using the logarithmic (Wald) approximation.

If one or more cells contain zero, the optional Haldane-Anscombe correction (adding 0.5 to each cell) can be applied.

The function additionally reports:

• Odds among exposed

• Odds among unexposed

• Log Odds Ratio

• Standard Error of log(OR)

• Wald Z statistic

• Wald p-value

• Chi-square test

• Fisher's Exact test

Value

Numeric mode returns an object of class "outbreak_odds_ratio".

Grouped analyses return an object of class "outbreak_odds_ratio_grouped" and "data.frame".

References

Rothman KJ, Greenland S, Lash TL. Modern Epidemiology. Fourth Edition.

Gordis L. Epidemiology.

Kleinbaum DG, Klein M. Epidemiologic Research: Principles and Quantitative Methods.

Examples

## Numeric mode

odds_ratio(
  exposed_cases = 45,
  exposed_total = 120,
  unexposed_cases = 10,
  unexposed_total = 140
)

## Data mode

outbreak_data <- data.frame(
  disease = c(
    TRUE, TRUE, FALSE,
    FALSE, TRUE, FALSE
  ),
  exposure = c(
    TRUE, TRUE, TRUE,
    FALSE, FALSE, FALSE
  )
)

odds_ratio(
  data = outbreak_data,
  outcome = disease,
  exposure = exposure
)

## Grouped analysis

outbreak_data$district <-
  c("A","A","A","B","B","B")

odds_ratio(
  data = outbreak_data,
  outcome = disease,
  exposure = exposure,
  group = district
)

Create Publication-Ready Epidemiological Contingency Tables

Description

outbreak_table() creates descriptive contingency tables suitable for epidemiological investigations, outbreak reports, surveillance summaries and scientific publications.

The function supports:

• Two-way contingency tables

• Multi-level contingency tables

• Grouped (stratified) contingency tables

• Publication-ready percentage tables

• Epidemiological effect measures

• Statistical hypothesis tests

Depending on the supplied arguments the function automatically determines whether the analysis is performed from vectors or from an individual-level data frame.

Usage

outbreak_table(
  row,
  column,
  data = NULL,
  strata = NULL,
  row_percent = TRUE,
  column_percent = TRUE,
  total_percent = TRUE,
  statistics = TRUE,
  conf_level = 0.95,
  correction = TRUE,
  na.rm = TRUE
)

Arguments

Details

Constructs 2 x 2 or r x c contingency tables from vectors or individual-level outbreak data and automatically computes row, column and overall percentages together with epidemiological measures and statistical tests. The function is intended to provide a unified table engine for all analytical functions in OutbreakR.

If a grouping variable is supplied, an independent contingency table is produced for every level of the grouping variable.

Epidemiological measures are calculated only for valid 2 x 2 contingency tables.

Expected cell frequencies are computed using Pearson's chi-square assumptions.

Missing observations are removed only when na.rm = TRUE.

Value

An object of class "outbreak_table" or "outbreak_table_grouped" containing:

• Contingency table

• Expected frequencies

• Row percentages

• Column percentages

• Overall percentages

• Chi-square statistics

• Fisher's Exact Test

• Phi coefficient

• Cramer's V

• Odds Ratio (2 x 2)

• Risk Ratio (2 x 2)

• Confidence intervals

Examples

## Vector mode
sex <- c(
  "Male", "Male", "Male", "Male",
  "Female", "Female", "Female", "Female"
)

disease <- c(
  "Case", "Case", "Non-case", "Case",
  "Non-case", "Case", "Non-case", "Non-case"
)

outbreak_table(
  row = sex,
  column = disease
)

## Data mode
outbreak_data <- data.frame(
  Species = c(
    "Cattle", "Cattle", "Cattle", "Cattle",
    "Goat", "Goat", "Goat", "Goat"
  ),
  Outcome = c(
    "Positive", "Positive", "Negative", "Positive",
    "Negative", "Positive", "Negative", "Negative"
  )
)

outbreak_table(
  data = outbreak_data,
  row = Species,
  column = Outcome
)

## Data mode with an additional grouping variable
outbreak_data2 <- data.frame(
  Exposure = c(
    "Exposed", "Exposed", "Exposed", "Exposed",
    "Unexposed", "Unexposed", "Unexposed", "Unexposed"
  ),
  Disease = c(
    "Case", "Case", "Case", "Non-case",
    "Case", "Non-case", "Non-case", "Non-case"
  ),
  District = c(
    "A", "A", "B", "B",
    "A", "A", "B", "B"
  )
)

outbreak_table(
  data = outbreak_data2,
  row = Exposure,
  column = Disease
)

Calculate Population Attributable Fraction

Description

population_attributable_fraction() provides a comprehensive analysis of the proportion of disease in the total population that can be attributed to an exposure. The function is suitable for cohort studies, outbreak investigations, public health, veterinary epidemiology and One Health research.

The function supports:

• Aggregate (numeric) data

• 2 x 2 contingency table input

• Individual-level data

• Group-wise analysis

• Confidence intervals

• Pearson's Chi-square or Fisher's Exact Test

Usage

population_attributable_fraction(
  exposed_cases = NULL,
  exposed_total = NULL,
  unexposed_cases = NULL,
  unexposed_total = NULL,
  cases = NULL,
  totals = NULL,
  data = NULL,
  outcome = NULL,
  outcome_value = TRUE,
  exposure = NULL,
  exposed_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  continuity = TRUE,
  fisher = FALSE,
  na.rm = TRUE
)

Arguments

Details

Calculates the Population Attributable Fraction (PAF), also known as the Population Attributable Risk Percent (PAR%) or Population Etiologic Fraction, using aggregate counts or individual-level epidemiological data. The function estimates the proportion of disease in the entire population attributable to a specific exposure together with relative risk, confidence intervals and statistical significance.

Population risk is calculated as

R_p= \frac{a+c} {a+b+c+d}

Risk among exposed is

R_e= \frac{a} {a+b}

Risk among unexposed is

R_u= \frac{c} {c+d}

Population Attributable Fraction is calculated as

PAF= \frac{R_p-R_u} {R_p}

which is equivalent to

PAF= \frac{P_e(RR-1)} {P_e(RR-1)+1}

where

• P_e is the prevalence of exposure in the population.

• RR is the Relative Risk.

Odds Ratio is calculated as

OR= \frac{ad} {bc}

Confidence intervals are obtained from the log-transformed Relative Risk and converted to Population Attributable Fraction.

Value

An object of class "outbreak_population_attributable_fraction" or "outbreak_population_attributable_fraction_grouped".

References

Rothman KJ, Greenland S, Lash TL (2008). Modern Epidemiology. Third Edition.

Rockhill B, Newman B, Weinberg C (1998). Use and misuse of population attributable fractions. American Journal of Public Health, 88(1), 15-19.

Examples

## Aggregate data
population_attributable_fraction(
  exposed_cases = 38,
  exposed_total = 500,
  unexposed_cases = 15,
  unexposed_total = 600
)

## 2 x 2 vectors
population_attributable_fraction(
  cases = c(38, 15),
  totals = c(500, 600)
)

## Individual-level data
outbreak_data <- data.frame(
  Disease = c(
    rep(1, 38),
    rep(0, 462),
    rep(1, 15),
    rep(0, 585)
  ),
  Smoking = c(
    rep(1, 500),
    rep(0, 600)
  ),
  District = rep(
    c("District_A", "District_B"),
    length.out = 1100
  )
)

population_attributable_fraction(
  data = outbreak_data,
  outcome = Disease,
  exposure = Smoking
)

## Group-wise analysis
population_attributable_fraction(
  data = outbreak_data,
  outcome = Disease,
  exposure = Smoking,
  group = District
)

Calculate Prevalence

Description

prevalence() estimates the prevalence proportion as the number of existing disease cases divided by the total population examined.

The function supports:

• Numeric (aggregate) analysis

• Individual-level data analysis

• Group-wise prevalence estimation

• Exact (Clopper-Pearson) confidence intervals

• Wilson Score confidence intervals

• Agresti-Coull confidence intervals

• Wald confidence intervals

Usage

prevalence(
  cases = NULL,
  population = NULL,
  data = NULL,
  disease = NULL,
  disease_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  ci_method = c("exact", "wilson", "agresti", "wald"),
  na.rm = TRUE
)

Arguments

Details

Calculates disease prevalence using either aggregated counts or individual-level epidemiological data. The function supports overall and grouped analyses and provides several methods for calculating confidence intervals.

Value

An object of class "outbreak_prevalence" or "outbreak_prevalence_grouped".

Examples

prevalence(
  cases = 78,
  population = 1245
)

herd_data <- data.frame(
  Disease = c(
    1, 0, 0, 1, 0,
    1, 0, 0, 0, 1,
    0, 1, 0, 0, 0,
    1, 0, 0, 1, 0
  ),
  District = rep(
    c("District_A", "District_B"),
    each = 10
  )
)

prevalence(
  data = herd_data,
  disease = Disease,
  disease_value = 1
)

Print Attack Rate Results

Description

Print Attack Rate Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Grouped Attack Rate Results

Description

Print Grouped Attack Rate Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Attributable Fraction Among the Exposed Results

Description

Print Attributable Fraction Among the Exposed Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Attributable Fraction Among the Exposed Results

Description

Print Grouped Attributable Fraction Among the Exposed Results

Usage

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

Arguments

Value

The object invisibly.

Print Attributable Risk Results

Description

Print Attributable Risk Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Attributable Risk Results

Description

Print Grouped Attributable Risk Results

Usage

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

Arguments

Value

The object invisibly.

Print Basic Reproduction Number Analysis

Description

Prints results from a basic reproduction number (R0) analysis.

Usage

## S3 method for class 'outbreak_basic_reproduction_number'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Case Fatality Rate Results

Description

Print Case Fatality Rate Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Grouped Case Fatality Rate Results

Description

Print Grouped Case Fatality Rate Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Effective Reproduction Number Analysis

Description

Prints results from an effective reproduction number (Re or Rt) analysis.

Usage

## S3 method for class 'outbreak_effective_reproduction_number'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Incidence Proportion Analysis

Description

Prints results from an incidence proportion analysis.

Usage

## S3 method for class 'outbreak_incidence_proportion'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Incidence Rate Results

Description

Print Incidence Rate Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Incidence Rate Results

Description

Print Grouped Incidence Rate Results

Usage

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

Arguments

Value

The object invisibly.

Print Mortality Rate Results

Description

Print Mortality Rate Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Mortality Results

Description

Print Grouped Mortality Results

Usage

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

Arguments

Value

The object invisibly.

Print Number Needed to Harm Analysis

Description

Print Number Needed to Harm Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_harm'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Grouped Number Needed to Harm Analysis

Description

Print Grouped Number Needed to Harm Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_harm_grouped'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Number Needed to Treat Analysis

Description

Print Number Needed to Treat Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_treat'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Grouped Number Needed to Treat Analysis

Description

Print Grouped Number Needed to Treat Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_treat_grouped'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Odds Ratio Results

Description

Print Odds Ratio Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Grouped Odds Ratio Results

Description

Print Grouped Odds Ratio Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Population Attributable Fraction

Description

Print Population Attributable Fraction

Usage

## S3 method for class 'outbreak_population_attributable_fraction'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Grouped Population Attributable Fraction

Description

Print Grouped Population Attributable Fraction

Usage

## S3 method for class 'outbreak_population_attributable_fraction_grouped'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Prevalence Results

Description

Print Prevalence Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Prevalence Results

Description

Print Grouped Prevalence Results

Usage

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

Arguments

Value

The object invisibly.

Print an OutbreakR Rate Ratio

Description

Prints a formatted summary of an incidence rate ratio analysis produced by rate_ratio().

Usage

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

Arguments

Value

The input object, invisibly.

Print Risk Ratio Results

Description

Print Risk Ratio Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Grouped Risk Ratio Results

Description

Print Grouped Risk Ratio Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Secondary Attack Rate Results

Description

Print Secondary Attack Rate Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Grouped Secondary Attack Rate Results

Description

Print Grouped Secondary Attack Rate Results

Usage

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

Arguments

Value

The object x, invisibly.

Print Contingency Table Results

Description

Print Contingency Table Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Contingency Table Results

Description

Print Grouped Contingency Table Results

Usage

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

Arguments

Value

The object invisibly.

Print Vaccine Effectiveness Results

Description

Print Vaccine Effectiveness Results

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Vaccine Effectiveness Results

Description

Print Grouped Vaccine Effectiveness Results

Usage

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

Arguments

Value

The object invisibly.

Print an Outbreak Validation Result

Description

Print an Outbreak Validation Result

Usage

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

Arguments

Value

The object x, invisibly.

Print Summary of Attributable Fraction Among the Exposed

Description

Print Summary of Attributable Fraction Among the Exposed

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Attributable Fraction Among the Exposed

Description

Print Summary of Grouped Attributable Fraction Among the Exposed

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Attributable Risk

Description

Print Summary of Attributable Risk

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Attributable Risk

Description

Print Summary of Grouped Attributable Risk

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Basic Reproduction Number Analysis

Description

Print Summary of Basic Reproduction Number Analysis

Usage

## S3 method for class 'summary.outbreak_basic_reproduction_number'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Summary of Case Fatality Rate

Description

Print Summary of Case Fatality Rate

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Case Fatality Rates

Description

Print Summary of Grouped Case Fatality Rates

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Effective Reproduction Number Analysis

Description

Print Summary of Effective Reproduction Number Analysis

Usage

## S3 method for class 'summary.outbreak_effective_reproduction_number'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Summary of Incidence Proportion Analysis

Description

Print Summary of Incidence Proportion Analysis

Usage

## S3 method for class 'summary.outbreak_incidence_proportion'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Summary of Incidence Rate Analysis

Description

Print Summary of Incidence Rate Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Incidence Rate Analysis

Description

Print Summary of Grouped Incidence Rate Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Mortality Analysis

Description

Print Summary of Mortality Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Mortality Analysis

Description

Print Summary of Grouped Mortality Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Number Needed to Harm

Description

Print Summary of Number Needed to Harm

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Number Needed to Harm

Description

Print Summary of Grouped Number Needed to Harm

Usage

## S3 method for class 'summary.outbreak_number_needed_to_harm_grouped'
print(x, digits = 4, ...)

Arguments

Value

The object invisibly.

Print Summary of Number Needed to Treat

Description

Print Summary of Number Needed to Treat

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Number Needed to Treat

Description

Print Summary of Grouped Number Needed to Treat

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Odds Ratio Analysis

Description

Print Summary of Odds Ratio Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Odds Ratio Analysis

Description

Print Summary of Grouped Odds Ratio Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Population Attributable Fraction

Description

Print Summary of Population Attributable Fraction

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Population Attributable Fraction

Description

Print Summary of Grouped Population Attributable Fraction

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Prevalence Analysis

Description

Print Summary of Prevalence Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Prevalence Analysis

Description

Print Summary of Grouped Prevalence Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Risk Ratio Analysis

Description

Print Summary of Risk Ratio Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Risk Ratio Analysis

Description

Print Summary of Grouped Risk Ratio Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Contingency Table Analysis

Description

Print Summary of Contingency Table Analysis

Usage

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

Arguments

Value

The object invisibly.

Print Grouped Contingency Table Summary

Description

Print Grouped Contingency Table Summary

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Vaccine Effectiveness

Description

Print Summary of Vaccine Effectiveness

Usage

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

Arguments

Value

The object invisibly.

Print Summary of Grouped Vaccine Effectiveness

Description

Print Summary of Grouped Vaccine Effectiveness

Usage

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

Arguments

Value

The object invisibly.

Print Summary of an OutbreakR Rate Ratio Analysis

Description

Prints the structured summary returned by summary.outbreak_rate_ratio().

Usage

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

Arguments

Value

The input object, invisibly.

Calculate Incidence Rate Ratio

Description

rate_ratio() estimates the relative incidence rate between two groups using event counts and person-time, animal-time, or another appropriate amount of time at risk.

The incidence rate ratio is commonly used in cohort studies, outbreak investigations, surveillance studies, veterinary epidemiology, and other studies where follow-up time differs between individuals or groups.

Usage

rate_ratio(
  exposed_cases,
  exposed_time,
  unexposed_cases,
  unexposed_time,
  multiplier = 1000,
  conf_level = 0.95,
  correction = 0.5
)

Arguments

Details

Calculates the incidence rate ratio (IRR) comparing the incidence rate in an exposed group with the incidence rate in an unexposed or reference group.

The incidence rate in the exposed group is:

IR_E = \frac{C_E}{T_E}

and the incidence rate in the unexposed group is:

IR_U = \frac{C_U}{T_U}

where C_E and C_U are the numbers of events and T_E and T_U are the corresponding amounts of time at risk.

The incidence rate ratio is:

IRR = \frac{IR_E}{IR_U}

which is equivalent to:

IRR = \frac{C_E / T_E} {C_U / T_U}

An incidence rate ratio of 1 indicates equal incidence rates in the two groups. Values greater than 1 indicate a higher incidence rate in the exposed group, whereas values below 1 indicate a lower incidence rate in the exposed group.

Unlike a risk ratio, the incidence rate ratio incorporates person-time or animal-time and therefore compares rates rather than cumulative risks.

Value

An object of class "outbreak_rate_ratio" containing the observed incidence rates, incidence rate ratio, confidence interval, inferential statistics, and epidemiological interpretation.

References

Rothman KJ, Greenland S, Lash TL (2008). Modern Epidemiology. 3rd ed. Lippincott Williams & Wilkins.

Dohoo I, Martin W, Stryhn H (2009). Veterinary Epidemiologic Research. 2nd ed. VER Inc.

Examples

## Basic incidence rate ratio
rate_ratio(
  exposed_cases = 40,
  exposed_time = 5000,
  unexposed_cases = 20,
  unexposed_time = 6000
)

## Rates expressed per 100,000 units of time
rate_ratio(
  exposed_cases = 40,
  exposed_time = 5000,
  unexposed_cases = 20,
  unexposed_time = 6000,
  multiplier = 100000
)

## 99 percent confidence interval
rate_ratio(
  exposed_cases = 25,
  exposed_time = 4000,
  unexposed_cases = 15,
  unexposed_time = 5000,
  conf_level = 0.99
)

## Zero events in one group
rate_ratio(
  exposed_cases = 0,
  exposed_time = 1000,
  unexposed_cases = 5,
  unexposed_time = 1200
)

Calculate Risk Ratio (Relative Risk)

Description

Calculates the risk ratio (relative risk, RR) together with its confidence interval for cohort studies and outbreak investigations.

The function supports two modes:

1. Numeric mode using a 2 x 2 contingency table.

2. Data mode using individual-level outbreak data.

Optional grouped analyses can be performed using variables such as village, district, species, farm, herd, flock, age group, production unit, ward, or outbreak.

Usage

risk_ratio(
  exposed_cases = NULL,
  exposed_total = NULL,
  unexposed_cases = NULL,
  unexposed_total = NULL,
  data = NULL,
  outcome = NULL,
  exposure = NULL,
  outcome_value = TRUE,
  exposure_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  correction = TRUE,
  na.rm = TRUE
)

Arguments

Details

Risk ratio compares the cumulative incidence among exposed individuals with the cumulative incidence among unexposed individuals.

RR > 1 indicates increased risk associated with exposure.

RR < 1 indicates a protective exposure.

RR = 1 indicates no association.

Confidence intervals are calculated using the logarithmic (Wald) approximation.

When any cell equals zero, the Haldane-Anscombe correction (adding 0.5 to every cell) may be applied.

The function also reports:

• Risk among exposed

• Risk among unexposed

• Risk difference (Attributable Risk)

• Chi-square test

• Fisher's exact test

Value

Numeric mode returns an object of class "outbreak_risk_ratio".

Grouped data mode returns an object of class "outbreak_risk_ratio_grouped" and "data.frame".

References

Rothman KJ, Greenland S, Lash TL. Modern Epidemiology. Fourth Edition.

Gordis L. Epidemiology.

Examples

## Numeric mode

risk_ratio(
  exposed_cases = 40,
  exposed_total = 120,
  unexposed_cases = 12,
  unexposed_total = 150
)

## Data mode

outbreak_data <- data.frame(
  disease = c(
    TRUE, TRUE, FALSE,
    FALSE, TRUE, FALSE
  ),
  exposure = c(
    TRUE, TRUE, TRUE,
    FALSE, FALSE, FALSE
  )
)

risk_ratio(
  data = outbreak_data,
  outcome = disease,
  exposure = exposure
)

## Grouped analysis

outbreak_data$village <-
  c("A","A","A","B","B","B")

risk_ratio(
  data = outbreak_data,
  outcome = disease,
  exposure = exposure,
  group = village
)

Calculate Secondary Attack Rate

Description

Calculates the secondary attack rate (SAR) among susceptible contacts exposed to one or more primary cases during an outbreak.

The function supports:

1. Numeric mode using the number of secondary cases and susceptible contacts.

2. Data mode using individual-level contact data.

3. Grouped analysis by variables such as household, village, species, age group, exposure setting, or other epidemiological groups.

Usage

secondary_attack_rate(
  secondary_cases = NULL,
  susceptible_contacts = NULL,
  data = NULL,
  secondary_case = NULL,
  case_value = TRUE,
  group = NULL,
  multiplier = 100,
  conf_level = 0.95,
  na.rm = TRUE
)

Arguments

Details

The secondary attack rate estimates the proportion of susceptible contacts who develop disease following exposure to a primary case or cases.

The denominator should contain susceptible contacts only. Primary cases should not be included in the denominator.

Exact binomial confidence intervals are calculated using stats::binom.test().

Value

In numeric or ungrouped data mode, an object of class "outbreak_secondary_attack_rate".

In grouped data mode, an object of class "outbreak_secondary_attack_rate_grouped" and "data.frame".

Examples

# Numeric mode
secondary_attack_rate(
  secondary_cases = 12,
  susceptible_contacts = 60
)

# Contact-level data
contact_data <- data.frame(
  secondary = c(
    TRUE, FALSE, TRUE,
    FALSE, FALSE, TRUE
  ),
  household = c(
    "H1", "H1", "H1",
    "H2", "H2", "H2"
  )
)

secondary_attack_rate(
  data = contact_data,
  secondary_case = secondary
)

# Household-specific SAR
secondary_attack_rate(
  data = contact_data,
  secondary_case = secondary,
  group = household
)

Summary of Attributable Fraction Among the Exposed Analysis

Description

Summary of Attributable Fraction Among the Exposed Analysis

Usage

## S3 method for class 'outbreak_attributable_fraction_exposed'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_attributable_fraction_exposed".

Summary of Grouped Attributable Fraction Among the Exposed

Description

Summary of Grouped Attributable Fraction Among the Exposed

Usage

## S3 method for class 'outbreak_attributable_fraction_exposed_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_attributable_fraction_exposed_grouped".

Summary of Attributable Risk Analysis

Description

Summary of Attributable Risk Analysis

Usage

## S3 method for class 'outbreak_attributable_risk'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_attributable_risk".

Summary of Grouped Attributable Risk Analysis

Description

Summary of Grouped Attributable Risk Analysis

Usage

## S3 method for class 'outbreak_attributable_risk_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_attributable_risk_grouped".

Summary of Basic Reproduction Number Analysis

Description

Creates a structured summary of an object returned by basic_reproduction_number().

Usage

## S3 method for class 'outbreak_basic_reproduction_number'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_basic_reproduction_number".

Summary of Case Fatality Rate

Description

Summary of Case Fatality Rate

Usage

## S3 method for class 'outbreak_case_fatality_rate'
summary(object, ...)

Arguments

Value

A summary table.

Summary of Grouped Case Fatality Rates

Description

Summary of Grouped Case Fatality Rates

Usage

## S3 method for class 'outbreak_case_fatality_rate_grouped'
summary(object, ...)

Arguments

Value

A data frame.

Summary of Effective Reproduction Number Analysis

Description

Creates a structured summary of an object returned by effective_reproduction_number().

Usage

## S3 method for class 'outbreak_effective_reproduction_number'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_effective_reproduction_number".

Summary of Incidence Proportion Analysis

Description

Creates a structured summary of an incidence proportion analysis.

Usage

## S3 method for class 'outbreak_incidence_proportion'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_incidence_proportion".

Summary of Incidence Rate Analysis

Description

Summary of Incidence Rate Analysis

Usage

## S3 method for class 'outbreak_incidence_rate'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_incidence_rate".

Summary of Grouped Incidence Rate Analysis

Description

Summary of Grouped Incidence Rate Analysis

Usage

## S3 method for class 'outbreak_incidence_rate_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_incidence_rate_grouped".

Summary of Mortality Analysis

Description

Summary of Mortality Analysis

Usage

## S3 method for class 'outbreak_mortality_rate'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_mortality_rate".

Summary of Grouped Mortality Analysis

Description

Summary of Grouped Mortality Analysis

Usage

## S3 method for class 'outbreak_mortality_rate_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_mortality_rate_grouped".

Summary of Number Needed to Harm Analysis

Description

Summary of Number Needed to Harm Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_harm'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_number_needed_to_harm".

Summary of Grouped Number Needed to Harm Analysis

Description

Summary of Grouped Number Needed to Harm Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_harm_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_number_needed_to_harm_grouped".

Summary of Number Needed to Treat Analysis

Description

Summary of Number Needed to Treat Analysis

Usage

## S3 method for class 'outbreak_number_needed_to_treat'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_number_needed_to_treat".

Summary of Grouped Number Needed to Treat

Description

Summary of Grouped Number Needed to Treat

Usage

## S3 method for class 'outbreak_number_needed_to_treat_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_number_needed_to_treat_grouped".

Summary of Odds Ratio Analysis

Description

Summary of Odds Ratio Analysis

Usage

## S3 method for class 'outbreak_odds_ratio'
summary(object, ...)

Arguments

Value

A summary data frame.

Summary of Grouped Odds Ratio Analysis

Description

Summary of Grouped Odds Ratio Analysis

Usage

## S3 method for class 'outbreak_odds_ratio_grouped'
summary(object, ...)

Arguments

Value

A data frame.

Summary of Population Attributable Fraction Analysis

Description

Summary of Population Attributable Fraction Analysis

Usage

## S3 method for class 'outbreak_population_attributable_fraction'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_population_attributable_fraction".

Summary of Grouped Population Attributable Fraction

Description

Summary of Grouped Population Attributable Fraction

Usage

## S3 method for class 'outbreak_population_attributable_fraction_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_population_attributable_fraction_grouped".

Summary of Prevalence Analysis

Description

Summary of Prevalence Analysis

Usage

## S3 method for class 'outbreak_prevalence'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_prevalence".

Summary of Grouped Prevalence Analysis

Description

Summary of Grouped Prevalence Analysis

Usage

## S3 method for class 'outbreak_prevalence_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_prevalence_grouped".

Summarize an OutbreakR Rate Ratio Analysis

Description

Creates a structured summary of an incidence rate ratio analysis produced by rate_ratio().

Usage

## S3 method for class 'outbreak_rate_ratio'
summary(object, ...)

Arguments

Value

An object of class "summary_outbreak_rate_ratio".

Summary of Risk Ratio Analysis

Description

Summary of Risk Ratio Analysis

Usage

## S3 method for class 'outbreak_risk_ratio'
summary(object, ...)

Arguments

Value

A summary data frame.

Summary of Grouped Risk Ratio Analysis

Description

Summary of Grouped Risk Ratio Analysis

Usage

## S3 method for class 'outbreak_risk_ratio_grouped'
summary(object, ...)

Arguments

Value

A data frame.

Summary of Contingency Table Analysis

Description

Summary of Contingency Table Analysis

Usage

## S3 method for class 'outbreak_table'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_table".

Summary of Grouped Contingency Table Analysis

Description

Summary of Grouped Contingency Table Analysis

Usage

## S3 method for class 'outbreak_table_grouped'
summary(object, ...)

Arguments

Value

A summary object.

Summary of Vaccine Effectiveness Analysis

Description

Summary of Vaccine Effectiveness Analysis

Usage

## S3 method for class 'outbreak_vaccine_effectiveness'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_vaccine_effectiveness".

Summary of Grouped Vaccine Effectiveness Analysis

Description

Summary of Grouped Vaccine Effectiveness Analysis

Usage

## S3 method for class 'outbreak_vaccine_effectiveness_grouped'
summary(object, ...)

Arguments

Value

An object of class "summary.outbreak_vaccine_effectiveness_grouped".

Calculate Vaccine Effectiveness

Description

vaccine_effectiveness() provides a comprehensive analysis of vaccine performance for randomized clinical trials, cohort studies, outbreak investigations, field epidemiology, veterinary epidemiology, and One Health surveillance.

The function supports:

• Aggregate (numeric) data

• 2 x 2 contingency table input

• Individual-level data

• Group-wise analysis

• Confidence intervals

• Chi-square or Fisher's exact test

Usage

vaccine_effectiveness(
  vaccinated_cases = NULL,
  vaccinated_total = NULL,
  unvaccinated_cases = NULL,
  unvaccinated_total = NULL,
  cases = NULL,
  totals = NULL,
  data = NULL,
  outcome = NULL,
  outcome_value = TRUE,
  exposure = NULL,
  vaccinated_value = TRUE,
  group = NULL,
  conf_level = 0.95,
  continuity = TRUE,
  fisher = FALSE,
  na.rm = TRUE
)

Arguments

Details

Calculates vaccine effectiveness (VE) from aggregate counts or individual-level epidemiological data. The function estimates attack rates among vaccinated and unvaccinated populations, relative risk, vaccine effectiveness, absolute risk reduction, number needed to vaccinate, confidence intervals, and statistical significance.

Vaccine effectiveness is calculated as

VE=(1-RR)\times100

where

RR= \frac{Risk_{Vaccinated}} {Risk_{Unvaccinated}}

Absolute risk reduction is

ARR= Risk_{Unvaccinated} - Risk_{Vaccinated}

Number Needed to Vaccinate (NNV) is

NNV= \frac{1}{ARR}

Confidence intervals for the Risk Ratio are calculated using the logarithmic method.

Vaccine effectiveness confidence intervals are obtained directly from the Risk Ratio confidence limits.

Value

An object of class "outbreak_vaccine_effectiveness" or "outbreak_vaccine_effectiveness_grouped".

Examples

## Aggregate data
vaccine_effectiveness(
  vaccinated_cases = 12,
  vaccinated_total = 820,
  unvaccinated_cases = 56,
  unvaccinated_total = 760
)

## 2 x 2 vectors
vaccine_effectiveness(
  cases = c(12, 56),
  totals = c(820, 760)
)

## Individual-level data
herd_data <- data.frame(
  Disease = c(
    rep(1, 12),
    rep(0, 808),
    rep(1, 56),
    rep(0, 704)
  ),
  Vaccinated = c(
    rep(1, 820),
    rep(0, 760)
  ),
  District = rep(
    c("District_A", "District_B"),
    length.out = 1580
  )
)

vaccine_effectiveness(
  data = herd_data,
  outcome = Disease,
  exposure = Vaccinated
)

## Group-wise analysis
vaccine_effectiveness(
  data = herd_data,
  outcome = Disease,
  exposure = Vaccinated,
  group = District
)

Validate an Outbreak Line List

Description

Validates the structure and basic epidemiological consistency of an outbreak line-list dataset. The function checks case identifiers, onset dates, duplicate records, missing values, future dates, case classifications, outcomes, and selected logical inconsistencies.

This function is intended as the first step in an OutbreakR analysis workflow before calculating attack rates, case fatality rates, epidemic curves, or other outbreak statistics.

Usage

validate_linelist(
  data,
  id,
  onset_date,
  status = NULL,
  outcome = NULL,
  allowed_status = c("Suspected", "Probable", "Confirmed"),
  allowed_outcome = c("Recovered", "Dead", "Ongoing", "Unknown"),
  future_dates = FALSE,
  verbose = TRUE
)

Arguments

Details

The function performs the following checks:

• Input is a data frame.

• Case IDs are not missing.

• Case IDs are unique.

• Onset dates can be interpreted as dates.

• Onset dates are not missing.

• Onset dates are not in the future.

• Case classifications match allowed values.

• Outcomes match allowed values.

Duplicate IDs and invalid dates are considered critical errors. Missing onset dates and unexpected status or outcome values are reported as warnings.

Value

An object of class "outbreak_validation" containing:

valid

Logical indicating whether critical validation errors were detected.

summary

A data frame summarizing validation checks.

errors

A data frame containing critical validation errors.

warnings

A data frame containing non-critical warnings.

problem_rows

A data frame identifying affected rows.

data

The original input data.

Examples

outbreak_data <- data.frame(
  case_id = c("C001", "C002", "C003"),
  onset = as.Date(c(
    "2026-01-01",
    "2026-01-02",
    "2026-01-03"
  )),
  status = c(
    "Confirmed",
    "Probable",
    "Suspected"
  ),
  outcome = c(
    "Recovered",
    "Recovered",
    "Ongoing"
  )
)

validate_linelist(
  outbreak_data,
  id = case_id,
  onset_date = onset,
  status = status,
  outcome = outcome
)