Skip to contents

Changelog

Source: NEWS.md

pviem 0.2.3

Breaking changes

  • Administrative identifiers created by joining multiple configured columns now use ::: as the separator instead of __. This separator is used mainly for internal purposes, so most users do not need to take any action.

New features

  • Added a pkgdown documentation website with an automated deployment workflow.

Documentation

  • Clarified the output columns and statistical interpretation of summarize_immunity_samples(). The .lower and .upper columns are empirical quantiles across imputation samples, whereas .ci95l and .ci95u are confidence limits for the sample mean. README and vignette plots now use the empirical intervals, and examples advise using enough samples to obtain stable uncertainty estimates.
  • Clarified that rho represents assumptions about overlap in vaccine uptake when combining vaccine-specific immunity estimates by immunity type.
  • Expanded the data-requirements guidance, including required and conditional inputs, missing-value handling, administrative boundary data, birth seasonality, and the current provenance limitations of bundled efficacy estimates.
  • Clarified function arguments and return values, including that immunity estimation functions return data.table objects and that deterministic imputation always produces minimum, mean, and maximum samples regardless of n_samples.
  • Reorganized and renamed the introductory vignettes for clearer website navigation, moved vignette illustrations into their source directory, and added responsive figure styling.
  • Improved package metadata, including contributor and repository information, and removed internal functions from the public website reference index.

Internal improvements

  • Added a reusable GitHub release-notes template.
  • Updated the package’s roxygen2 version and regenerated the reference documentation.

pviem 0.2.2

Bug fixes

  • #23: Link to “vignettes” in readme is broken. The link has just been removed.
  • #26: shift_doses() now issues a descriptive warning instead of an error when the admin unit time range is shorter than the dose age, allowing execution to continue.
  • #25: compute_shift_prop() no longer incorrectly requires admin_info or birth_seasonality arguments when monthly = TRUE in config_pviem() setup.

pviem 0.2.1

Bug fixes

  • Monthly RI data validation: Fixed issue #21 where validation incorrectly failed for datasets containing only one year with incomplete but consecutive months (e.g., months 1-6 only, months 7-12 only, or any consecutive sequence within 1-12). The validation now properly allows single-year data to start and end at any month as long as the sequence is consecutive.

Documentation improvements

Vignettes

  • Removed unnecessary code blocks across all vignettes (setup, data-requirements, get-started, and workflow) for a cleaner reading experience.
  • Fixed warnings throughout vignettes, particularly those related to using external variables in tidyverse functions without wrapping them in dplyr::all_of().

Migration guide

  • Enhanced the migration guide in the workflow vignette with:
    • Clearer instructions for upgrading old code
    • More detailed explanations of key changes (named arguments, R version requirement, config_pviem() setup, etc.)

pviem 0.2.0

Breaking changes

  • R Version Requirement: The package now requires R >= 4.4.0 to leverage the built-in %||% (NULL coalescing) operator.
  • Strict Argument Naming: All optional arguments across all functions are now strictly required to be named.
  • Function Signatures & Arguments:
    • In impute_missing_doses(), ri_data is now the only positional argument; all other arguments must be explicitly named.
    • In get_default_sample_pair(), ri_data is now a required positional argument (signature changed to ri_data, ..., dose_names = NULL). It returns an empty list if no missing values are found among the specified (or all) dose columns.
  • Default Values: The default value for rho in compute_immunity_by_type(), compute_immunity_sample(), and compute_immunity_samples() has been changed from 0.5 to 0.
  • Output Modifications: summarize_immunity_samples() output no longer contains the birth column.
  • Data Requirements: The birth column in the birth seasonality data must now be renamed to strictly match the birth argument specified in config_pviem().

New features & capabilities

  • Global Configuration (#13): Introduced the config_pviem() function for initial setup. This major feature gives users centralized control over data column configurations (Admin, time, birth) and allows toggling between monthly or yearly computations at various administrative levels.
  • Scoped Configuration: Added with_config() and local_config() (inspired by withr) to temporarily alter configuration settings for specific code blocks without affecting the global environment. Also added get_pviem_config() to easily retrieve the active configuration.
  • Enhanced Aggregation: summarize_immunity_samples() now supports aggregating immunity samples across different administrative levels and time periods.
  • Streamlined Workflow: shift_doses() now accepts vs_info and birth_seasonality arguments directly, eliminating the need to separately pre-compute shift proportions with compute_shift_prop().
  • New Vignettes: Added three new comprehensive guides to assist users: setup, data-requirements, and get-started, alongside updates to the existing workflow vignette.

Deprecations & API changes

  • Live Births Data: Standalone live births data (including dummy_live_births) is now deprecated. Live births must be included directly in the routine immunization data (ri_data), with the column named according to config_pviem(). Consequently, validate_live_births() has been updated to reflect and enforce this new data structure requirement.
  • Deprecated Functions & Arguments:
    • compute_doses_ratio() and its dose_ratios argument are deprecated. Imputations and ratio calculations are now handled internally by impute_missing_doses().
    • In get_neighbors(), dcolname and level are deprecated and replaced by admin_cols and max_level respectively. The admin_cols provided must be the actual administrative column names in the spatial data, corresponding element-wise to the admin columns configured globally via the admin argument in config_pviem() (as used in related datasets like RI and birth seasonality data). The number of columns in admin_cols must strictly match the length of the admin configuration, otherwise an error is raised.
    • In compute_shift_prop(), dist_codes is deprecated in favor of admin_info.
  • Internal Datasets Updated: dummy_ri_data is deprecated and replaced by dummy_monthly_ri_data and dummy_yearly_ri_data (which include live births). prep_efficacy_default has been renamed to prep_dummy_efficacy.

Bug fixes

  • #18: Fixed an out-of-bounds error in handle_extra_doses() that occurred when max_level exceeded the available administrative unit levels.
  • #15: compute_doses_ratio() now exclusively outputs the ratio for doses defined in sample_pair, resulting in a much cleaner output.
  • #14: Fixed incorrect shift proportion calculations for doses involving fractional ages < 1 month.

Performance & internal polish

  • Performance: Significant speed optimizations achieved by utilizing data.table features and removing unnecessary data conversions and computations.
  • Documentation: Improved overall package documentation for clarity and consistency.
  • Testing: Updated and expanded unit tests to account for the new configuration system and API changes.
  • Various other minor internal improvements.

pviem 0.1.2

Bug fixes

  • Fixed numeric validation that incorrectly rejected scientific notation and large numbers
  • Improved integer validation to accept double values with zero decimal part (e.g., 5.0, 10.00)
  • Enhanced unit interval checking to properly handle boundary values (0 and 1)

Internal changes

  • Replaced regex-based type validation with functional approach
  • Added check_type() function for unified validation logic
  • Expanded test coverage for numeric edge cases and validation scenarios

pviem 0.1.1

Bug fixes

  • Corrected join logic for data.table operations. (Fixes #8) The package now uses inner join where appropriate to prevent the accidental introduction of NA values. This corrects an issue where left join was used incorrectly in some areas, leading to inaccurate data integration.

Improvements

  • Improved data validation. All validation tests have been updated to reflect new, stricter data validation rules. The error messages for validation failures, particularly those related to the complex structure of efficacy data, are now more informative and user-friendly.
  • All internal tests have been updated to align with the new data validation standards.
  • The package’s overall stability and robustness have been enhanced through these changes.

pviem 0.1.0

Major features

This first public release provides a comprehensive pipeline for polio immunity estimation from routine immunization data.

Core immunity estimation pipeline

The package implements a complete workflow for immunity estimation:

Comprehensive data validation framework

Complete data validation system with validate_*() functions:

Flexible modeling assumptions

Key parameters allow users to specify different methodological assumptions:

  • Data Imputation:
    • imputation_mode: Strategies for handling missing dose data (‘stochastic’, ‘deterministic’, ‘custom’)
    • sample_mode: Sampling behavior within each imputation mode
  • Dose Management:
    • hed_assumption: Approaches for handling extra doses (‘redistribute’, ‘discard’, ‘scale’)
    • dd_assumption: Dose receipt patterns (‘organised’, ‘random’)
  • Immunity Modeling:
    • vax_imm_type & rho: Vaccine immunity types and correlation structures

New functions

Main pipeline functions

Supporting functions

Data validation suite

Data resources

  • Example Datasets:
    • dummy_ri_data - Example routine immunization data
    • dummy_vs_info - Vaccination schedule information
    • dummy_live_births - Birth count data
    • dummy_birth_seasonality - Monthly birth distributions
    • fakeland - Complete fake country dataset for demonstration
  • Default Efficacy Estimates:
    • efficacy_default - Default vaccine efficacy estimates for when country-specific data is unavailable
  • Preprocessed Data:
    • prep_dummy_vs_info - Preprocessed vaccination schedule
    • prep_efficacy_default - Preprocessed default efficacy data

Technical implementation

  • Performance: All core functions use data.table for efficient data manipulation
  • Documentation: Comprehensive vignettes demonstrating complete workflows
  • Testing: Full test coverage ensuring method consistency
  • User Experience: Sensible defaults with flexible parameterization
  • Data Integrity: Robust validation system ensures input data quality

Key methodological features

  • Birth Cohort Alignment: Dose shifting ensures children receiving specific doses are properly assigned to their birth cohorts
  • Flexible Imputation: Multiple strategies for handling missing data with customizable sampling
  • Uncertainty Propagation: Full quantification of uncertainty through multiple sampling approaches
  • Real-world Adaptability: Handles common data issues like extra doses and missing values
  • Beyond Polio: Framework designed for adaptability to other vaccine-preventable diseases

Notes for users

This initial release (0.1.0) provides a stable foundation for polio immunity estimation. The API is well-tested but may evolve based on user feedback. Please report any issues at the package repository whether you use it for polio or other vaccine-preventable diseases.