Sample Size and Simulation for Negative Binomial Outcomes
Overview
Provides tools for planning and simulating recurrent event trials with overdispersed count endpoints analyzed using negative binomial (or Poisson) rate models. Implements sample size and power calculations for fixed designs with variable accrual, dropout, maximum follow-up, and event gaps, including methods of Zhu and Lakkis (2014) doi:10.1002/sim.5947 and Friede and Schmidli (2010) doi:10.3414/ME09-02-0060 as well as extensions for score-test sizing and gaps between events. Supports group sequential monitoring by building on the 'gsDesign' package. Includes recurrent-event simulation utilities (including seasonal rates), interim data truncation, Wald and score-test inference for rate ratios, and information estimation and sample size re-estimation with or without treatment-group labels.
Score-test sizing and inference guidance
- Expanded the paper, sample-size vignette, and score-vs-Wald simulation vignette with recommendations for when the Zhu-Lakkis / Friede-Schmidli / Mutze Wald sample-size formula is appropriate and when to use score-test sizing with separate null and alternative variance factors.
- Added an
ai-skillsvignette demonstrating how the agent skills under.agents/skills/can guide package-native score-test and simulation workflows without replacing statistical review. - Added a published sample-size examples vignette showing how the package-specific AI skill translates literature and protocol descriptions into transparent
sample_size_nbinom()calls, including dropout, event-gap, non-inferiority, and group sequential parameterization checks.
Show all changes in 0.3.2Hide the rest of the changes in 0.3.2
- Refined score-test recommendations to distinguish the final analysis test from the sample-size formula: Wald/Zhu-Lakkis sizing remains a useful practical baseline and may provide a power margin when paired with the score test in fixed-design superiority settings, while SSR designs should verify any starting-size margin inside the planned adaptation rule.
- Added a targeted SSR starting-size sensitivity cache comparing Wald- and score-sized starting designs under the score final test in a low-event stress setting. Both starts preserved near-nominal score-test Type I error, and the larger Wald-sized start did not produce a clear SSR power advantage.
- Documented the cached score-vs-Wald simulation results: the Wald test was mildly anti-conservative in several finite-sample scenarios, while the score test preserved Type I error more conservatively and should be paired with simulation-based power checks.
- Corrected the reported
variance_nullfield fromsample_size_nbinom()so it is on the same final-analysis scale asvariance; the score sample-size calculation itself was already using the null variance factor correctly.
Group sequential simulation vignette
- Corrected the group sequential simulation vignette and cached results so that simulations use the rounded final group sequential sample size, monthly dropout hazard, and helper functions for boundary checking and summary.
toInteger.gsNB()now preserves calendar-time enrollment quantities at interim analyses and recomputes expected events, exposures, and information after rounding the final sample size.toInteger.gsNB()now preserves the shape of piecewise accrual schedules when rescaling calendar-time designs after final sample-size rounding.gsNBCalendar(),update_gsNB(), and simulation boundary checks now support harm-bound group sequential designs available ingsDesign3.10.0 (test.type = 7or8,sfharm,sfharmparam, andtestHarm).summarize_gs_sim()now reports optional sample-size and exposure summaries when available and uses finite trimmed means for information estimates.- Updated SSR simulation reporting in the manuscript and SSR simulation article to use the production score-test cache: 3,600 replicates per power scenario, 20,000 per RR = 1 main-grid scenario, 1,000 per RR > 1 scenario, and 20,000 per dispersion/test-statistic cell for the non-binding Type I tables.
- Replaced the CRAN-bundled SSR trial-level simulation cache with compact precomputed summaries for tables and figures, while leaving full raw simulation caches available for local development or external archival.
- Converted the score-vs-Wald simulation article from interactive widget output to static vignette tables and figures backed by compact precomputed summaries, reducing the CRAN package size while leaving the full simulation cache available outside the CRAN build.
- Updated the SSR simulation study to compare Wald and score tests at the same nominal one-sided alpha of 0.025, and aligned the SSR power simulations with the score final-analysis recommendation.
- Added a checkpointed production generator for the SSR score-test cache so the long-running power and Type I simulations can be resumed from saved chunks.
- Updated the blinded-information diagnostics article to distinguish historical raw ML pathologies from the current MoM fallback behavior.
Missing data and imputation documentation
- Added documentation clarifying that the primary recurrent-event analysis is an observed-exposure negative binomial likelihood analysis. Under ignorable censoring / MAR assumptions, partially followed subjects contribute their observed events and exposure, and multiple imputation is not required simply because follow-up is censored.
- Expanded MNAR sensitivity-analysis guidance for recurrent-event endpoints, including the need to preserve censoring reason and planned remaining follow-up before post-dropout outcomes can be imputed.
- Added Keene, Roger, Hartley, and Kenward (2014) as the recurrent-event controlled-imputation reference for de facto / reference-based sensitivity analyses, and aligned the manuscript, slides, and simulation vignette around that framing.
- Updated the paper and slide materials to cite package articles as executable supplementary material for the fuller simulation grids and reporting.
Manuscript
- Converted the paper to the Quarto Journal of Statistical Software template, added a semi-real recurrent-event group sequential design example with tables and a figure, added formal R package citations, and simplified the Jensen correction grid table so the formula-heavy entries no longer break the PDF.
From NEWS.md in the release
Install
Health
- OK13 OK2026-08-05
- NOTE12 OK, 1 NOTE2026-08-01
- OK13 OK2026-06-09
- ERROR12 OK, 1 ERROR2026-06-08
- OK14 OK2026-03-10
Documentation
- Help pages
- 37 (3 internal)
- Examples that run
- 82%28 run in a plain check · 6 never run
- Exported functions with examples
- 97%
- Documented parameters
- 98%
- Return-value docs
- 97%
- Help pages citing references
- 14%
- AI-assisted gsDesignNB workflows HTML
- Diagnosing Blinded Information Calculation Issues HTML
- Group sequential design and simulation HTML
- Group sequential simulation with completers analysis HTML
- Multiple imputation for longitudinal negative binomial counts HTML
- Non-inferiority and super-superiority designs HTML
- Published sample-size examples with the gsDesignNB AI skill HTML
- Sample size calculation for negative binomial outcomes HTML
- Sample size re-estimation example HTML
- Score vs Wald tests and sample-size recommendations HTML
Show 4 moreHide 4 vignettes
Downloads
Repository
- PRs merged (all time)
- 89%
- Median days to close, 50 most recently updated closed issues
- 4
- Median days to close, 50 most recently updated closed PRs
- 0
Stars over time
Forks over time
Releases over time
Issues over time
PRs over time
Commits over time
Commit identities over time
9 development-tooling and community-health practices detected across 6 families in the upstream repository
Checks run against github.com/keaven/gsdesignnb on 2026-10-18.
The R CMD check workflow runs on Linux, macOS and Windows, and on R-devel
GitHub Pages site last deployed 2026-10-17 · The repository has a site deploy workflow
pkgdown site last built 2026-10-17
Show all practicesHide 2 practices
This repository shows signs of AI coding tools.
- GitHub Copilotfirst seen 2026-01-12Pull request: opened by its own accountCommits: 7 by its own account · at least 1 crediting it in the message
- Cursorfirst seen 2026-02-14Commits: at least 8 crediting it in the message
- Claude Codefirst seen 2026-04-30Named in .Rbuildignore: .claudePull request it wrote: opened by a project memberCommits: at least 5 crediting it in the message
- Gemini CLIfirst seen 2026-05-17Config: a file or ignore line, not recorded which
- Claude Opus 4.85 commits · Sep 2026
Dependencies
Installing gsDesignNB adds 79 packages (38 with compiled code, 70 MB of source tarballs). Heaviest: stringi 11 MB, ggplot2 6.0 MB, data.table 5.7 MB.
CRAN will archive these unless their check problems are fixed by the date shown. This package needs each one to install.
Code & Tests
Datasets
People & History
Pick two releases to compare their code metrics.
- 0.3.2Latest2026-07-06 · current release · diff ↗ ·
added 10 exports
fit_nb_glmm, impute_nb, impute_nb_composite, impute_nb_mar, impute_nb_mnar_ref, preview_pkgdown_site, run_ssr_shiny, sim_ssr_nbinom, summarize_ssr_sim, update_gsNB - RR 4.6.0 released · 2026-04-24
- 0.2.62026-02-16
- RR 4.5.0 released · 2025-04-11
Package metadata
- First published
- 2026-02-16
- Total releases
- 2 / 1 yrs
- License
- GPL (>= 3) OSI
- Minimum R
- ≥ 4.1.0
- Download size
- 4.9 MB
Cite
Cite this package
Run in R for the authors' preferred citation:
citation("gsDesignNB")This package has no citation file, so citation() returns this entry built from DESCRIPTION.
Cite the R Observatory
For a number measured here: a download total, a coverage figure, an archival date.
From data release v2026-10-21, which the citation names so these numbers can be found later. More on citing and the projects behind them.