Getting Started with anumaan

What is anumaan?

anumaan is an R package for preprocessing antimicrobial resistance (AMR) surveillance data and estimating disease burden using GBD methodology. It is structured around three sequential pipelines that can be used together or separately.

Pipeline 1 — Preprocessing

Vignette: Preprocessing Workflow

The preprocessing pipeline standardises raw hospital or surveillance data into an analysis-ready format. It covers:

• Column name standardisation and schema alignment
• Date parsing and chronological validation
• Organism, specimen, antibiotic, and AST value cleaning, including the 0.1.0.9021 specimen reference additions and collapsed sterile-site classes
• Demographic derivations (age, HAI/CAI, LOS)
• Event creation, deduplication, and readmission classification
• Contaminant detection and polymicrobial weighting
• Attrition tracking and analysis-readiness filtering

All functions start with prep_. The pipeline entry point is run_preprocess() for automated runs or the modular prep_* functions for staged, inspectable workflows.

library(anumaan)

# Full automated pipeline
result <- run_preprocess(
  data   = your_ast_data,
  config = amr_config(hai_cutoff = 3, event_gap_days = 14)
)

# Or modular
data <- prep_standardize_organisms(data, organism_col = "organism_name")
data <- prep_harmonize_ast(data, ast_col = "antibiotic_value")
data <- prep_create_event_ids(data, patient_col = "patient_id",
                               date_col = "date_of_culture")

See the full step-by-step walkthrough in the Preprocessing Workflow vignette.

Pipeline 2 — Exploratory Data Analysis

Vignette: Exploratory Data Analysis

The EDA pipeline visualises preprocessed data before it moves on to burden estimation. It does not transform data – it is the review step a stewardship team runs on Pipeline 1’s output to catch data-quality issues and characterise the cohort. It covers:

• Organism and antibiotic-susceptibility overviews (top organisms, R/S patterns, resistance heatmaps)
• Outcome distributions, including outcome by organism/resistance status, by age bin, and by year
• Case-mix and facility patterns (HAI/CAI, ICU vs. ward, polymicrobial share, syndrome distribution)
• Length-of-stay and age distributions

All functions start with plot_, plus the shared eda_theme() styling helper – deliberately distinct from the prep_ (Pipeline 1) and daly_ (Pipeline 3) naming.

library(anumaan)

plot_top_organisms(data, n = 10, mode = "faceted")
plot_abx_heatmap(data, mode = "all")
plot_outcome_distribution(data, mode = "overall")
plot_los_ridge(data, mode = "all")

See the full walkthrough in the Exploratory Data Analysis vignette.

Pipeline 3 — DALY Burden Estimation

Vignette: DALY Burden Estimation

The DALY pipeline takes analysis-ready preprocessed data and produces resistance-profile probability distributions and GBD-style burden estimates. It covers:

• Resistance profile estimation via convex optimisation (Pathway 1) — works from either facility line-list data or pre-computed aggregate marginals (GBD ST-GPR, GLASS, national surveillance networks)
• Marginal and pairwise co-resistance computation with Pearson back-calculation
• Profile probability estimation solving a simplex-constrained QP
• Bootstrap uncertainty intervals for profile probabilities
• Years of Life Lost (YLL) — associated and attributable
• Years Lived with Disability (YLD) — associated and attributable
• Total DALY burden per pathogen, hospital, and organism group

All estimation functions start with daly_. Profile-specific functions are compute_*, estimate_*, enumerate_*, build_*, validate_*, check_*, and bootstrap_*.

# From aggregate marginals (GBD / GLASS / national surveillance)
profiles <- estimate_profiles_convex(
  marginals = your_marginals_table,
  panel_map = list(
    "Klebsiella pneumoniae" = c("Carbapenems", "3GC", "Fluoroquinolones")
  )
)

# Assign LOS relative risk and compute fatal resistance prevalence
profiles_rr <- daly_assign_rr_to_profiles(profiles, rr_table)
R_k         <- daly_calc_resistance_prevalence_fatal(profiles_rr)

See the full walkthrough in the DALY Burden Estimation vignette.

fit <- fit_bayesian_multivariate_probit(
  event_class_data = event_level_ast,
  class_cols = c("3GC", "Carbapenems", "Fluoroquinolones"),
  fixed_effects = c("Age_normalised", "gender", "location"),
  random_effects = list(
    list(name = "hospital", group_col = "center_name", terms = "intercept")
  ),
  pathogen = "klebsiella pneumoniae",
  residual_structure = "correlated",
  compute = list(
    backend = "cpu"
  )
)

fit_opencl <- fit_bayesian_multivariate_probit(
  event_class_data = event_level_ast,
  class_cols = c("3GC", "Carbapenems", "Fluoroquinolones"),
  fixed_effects = c("Age_normalised", "gender", "location"),
  random_effects = list(
    list(name = "hospital", group_col = "center_name", terms = "intercept")
  ),
  pathogen = "klebsiella pneumoniae",
  residual_structure = "correlated",
  compute = list(
    backend = "opencl",
    opencl_platform_id = 0L,
    opencl_device_id = 0L
  )
)

Installation

# From GitHub
remotes::install_github("saketlab/anumaan")

# Build vignettes locally when you want the full article set
remotes::install_github("saketlab/anumaan", build_vignettes = TRUE)

Data Format

All three pipelines expect long format input — one row per isolate × antibiotic combination:

Optional but used when present: date_of_admission, date_of_final_outcome, DOB, Age, gender, final_outcome, infection_type, state.

prep_standardize_specimens() now returns sterile_classification collapsed to Sterile, Non-Sterile, or Others/Ambiguous. The 0.1.0.9021 reference also adds stewardship specimen labels such as Brain abscess, Instrument, Lung aspirate, Lymph node, Hair, and Superficial Biopsy.

Package Reference

Full function documentation is at the Reference page.

# Search all functions
help(package = "anumaan")

# Common entry points
?run_preprocess
?amr_config
?estimate_profiles_convex
?compute_resistance_profiles

Report bugs at https://github.com/saketlab/anumaan/issues.