- PriorRhythm
PriorRhythm provides Bayesian hierarchical prior-building and target-study analysis workflows for cardiac safety pharmacology. It supports construction of informative priors from approved historical study data and comparison of historical-prior borrowing with a weak-prior comparator for new target-study data. The package is intended to support cardiac safety research, transparent quantitative summaries, and 3Rs-aligned study planning.
# install.packages("devtools")
devtools::install_github("pfizer-opensource/PriorRhythm")# Clone the repository, then run this from the package root.
devtools::install(".")The primary user workflow is the Shiny app. It loads the reviewed, precomputed prior bundle shipped with PriorRhythm by default; it does not build Stage 1 priors from raw historical data during an app session.
library(PriorRhythm)
# Launch the app with the reviewed bundled prior artifact.
run_app()In the app:
- Upload one target-study file in CSV or TSV format.
- Review the uploaded data and use Set up Analysis to select the animal, treatment, period, time, and response columns.
- Select a species and endpoint prior compatible with the target-study data.
- Run the analysis and review credible intervals and probability statements.
The app displays friendly reviewed species and endpoint labels where metadata is available, but internally retains the raw prior-bundle keys needed for selection and lookup. Users remain responsible for confirming that the selected prior and target-study data have compatible species, endpoint definitions, and measurement units.
Advanced users may supply a compatible, pre-built local prior bundle:
library(PriorRhythm)
run_app(prior_file = "path/to/my_priors.RDS")A custom bundle must pass the package’s structural and confidentiality
checks. Use list_prior_bundle_endpoints() to inspect its
non-confidential species/endpoint inventory before launching the app.
bundle_inventory <- list_prior_bundle_endpoints("path/to/my_priors.RDS")
print(bundle_inventory)See inst/extdata/priors/README.md for the expected prior-bundle schema
and convergence-diagnostics requirements.
Building a custom prior is an offline workflow for users with approved historical data. It runs Stage 1 JAGS MCMC and may take several minutes.
Historical data should be in long format and include study, animal,
treatment, period, time, endpoint-name, and endpoint-value columns. The
required alpha0_pop_mean must be chosen appropriately for the species
and endpoint.
library(PriorRhythm)
# Example outline only: use approved historical data and endpoint-specific
# settings appropriate for the analysis.
historical_long_data <- time_bins(
dat = historical_long_data,
time_col = "time"
)
priors <- historical_long_data |>
chain_priors_from_data(
treatment_col = "treatment_code",
study_col = "study_code",
animal_col = "animal_code",
period_col = "period_code",
time1_col = "time1",
time2_col = "time2",
assay_names_col = "parameter",
assay_values_col = "value",
assay_name = "q_tc",
alpha0_pop_mean = 250
)Use study_config() when you need reusable file-import, column-mapping,
time-parser, or endpoint-specific settings.
cfg <- study_config(
file_pattern = "\\.(csv|tsv)$",
animal_string = "monkey|dog",
endpoints = list(
q_tc = list(
alpha0_pop_mean = 250,
value_min = 150,
value_max = 400,
threshold = 10
)
),
active_endpoint = "q_tc"
)
historical_data <- import_historical_data(
data_path_dir = "path/to/historical-files",
config = cfg
)After Stage 1 fitting, create a compatible runtime prior bundle with the
controlled package build workflow before supplying it to run_app().
See the worked vignette and inst/extdata/priors/README.md for details.
| Function | Description |
|---|---|
run_app() |
Launch the Shiny app with the reviewed bundled prior artifact or a trusted custom bundle. |
app_ui() |
Build the package Shiny user interface. |
app_server() |
Configure the package Shiny server. |
list_prior_bundle_endpoints() |
List non-confidential species, endpoint, and convergence-status inventory from a compatible prior bundle. |
| Function | Description |
|---|---|
load_study_data() |
Load and clean one CSV or TSV study-data file. |
import_historical_data() |
Batch-import and normalize historical study files. |
time_bins() |
Parse time-interval labels into numeric time1 and time2 columns. |
study_config() |
Create a validated reusable study-configuration object. |
read_study_config() |
Read a study configuration from YAML. |
write_study_config_template() |
Write a documented study-configuration YAML template. |
random_data_generator() |
Generate synthetic study data for examples and testing. |
| Function | Description |
|---|---|
chain_priors_from_data() |
Build Bayesian priors from historical study data. |
chain_priors_from_data_helper() |
Run the lower-level Stage 1 prior-fitting workflow. |
chain_prior_plot() |
Plot Stage 1 prior distributions. |
check_jags_indices() |
Validate JAGS index vectors before model fitting. |
check_jags_inputs() |
Validate JAGS model-input structure. |
convergence_diag() |
Calculate Stage 1 MCMC convergence diagnostics. |
convergence_policy() |
Return the documented convergence-assessment thresholds. |
| Function | Description |
|---|---|
bayesian_test_example() |
Compare historical-prior borrowing with a weak-prior comparator. |
ci_plots() |
Plot credible intervals for treatment effects. |
ci_plots_combined() |
Plot combined credible-interval comparisons. |
prob_statement_plots() |
Plot probabilities of treatment effects exceeding a threshold. |
exceedance_prob() |
Calculate posterior exceedance probabilities. |
rope_analysis() |
Perform region-of-practical-equivalence analysis. |
generate_borrowing_report() |
Generate a Word borrowing report. |
| Function | Description |
|---|---|
sinusoidal_interval_mean() |
Calculate the sinusoidal interval mean used by the Chain et al. model. |
get_package_logo_path() |
Return the installed package-logo path. |
embed_spba_logo() |
Embed the package logo in a Shiny UI. |
logo_news() |
Display package branding and news content in the app. |
PriorRhythm uses the hierarchical sinusoidal dose-response JAGS model from Chain et al. (2013) when building Stage 1 priors.
model{
for(i in 1:N){
y[i] ~ dnorm( mu[i], pow(sig[s[i]], -2) )
mu[i] <- alpha[s[i]]+
A[s[i]]*(12/3.14159/(time2[i]-time1[i]))*(sin(3.14159/12*time2[i]+phi0)-sin(3.14159/12*time1[i]+phi0))+
beta[s[i]]*dose[i] +
u[a[i]] + v[b[i]]
}
for(i in 1:na){
u[i] ~ dnorm(0, pow(sig_u[sa[i]], -2) )
}
for(i in 1:nb){
v[i] ~ dnorm(0, pow(sig_v, -2) )
}
for(j in 1:ns){
alpha[j] ~ dnorm(alpha0, pow(sig_alpha, -2) )
A[j] ~ dnorm(A0, pow(sig_A, -2) )
beta[j] ~ dnorm(beta0, pow(sig_beta, -2) )
sig[j] ~ dt(0, pow(2.5,-2), 1) T(0,)
sig_u[j] ~ dt(0, pow(2.5,-2), 1) T(0,)
}
sig_v ~ dt(0, pow(2.5,-2), 1) T(0,)
alpha0 ~ dnorm(alpha0_pop_mean, 0.0004) T(0,)
A0 ~ dnorm(0, 0.001) T(0,)
beta0 ~ dnorm(0, 0.001)
phi0 ~ dunif(0, 6.28318)
sig_A ~ dt(0, pow(2.5,-2), 1) T(0,)
sig_alpha ~ dt(0, pow(2.5,-2), 1) T(0,)
sig_beta ~ dt(0, pow(2.5,-2), 1) T(0,)
}
For a detailed explanation of the Stage 1 and Stage 2 workflows, model parameters, prior-bundle structure, convergence evidence, and reporting outputs, see the package vignette.
-
Worked example:
vignette("bayesian-priors-workflow", package = "PriorRhythm") -
Bundled prior-artifact schema and privacy requirements:
inst/extdata/priors/README.md
This package follows the conventions documented in
STYLE_GUIDE.md:
- snake_case function and object names;
- explicit
return()values; cli::messaging;.data$or.data[["column"]]pronouns in dplyr expressions;- roxygen2 documentation for exported functions; and
- lowercase kebab-case source filenames organized by workflow or domain.
- The Shiny app is a priors-only runtime. It consumes an already-built prior bundle and does not fit Stage 1 JAGS models during an app session.
- Target-study upload currently supports CSV and TSV files only.
- The app does not automatically confirm species, endpoint-definition, or measurement-unit compatibility between uploaded target-study data and a selected prior.
- The packaged prior bundle contains posterior parameter draws and compact, non-confidential convergence summaries. It must not contain raw historical observations, animal identifiers, chain-level draws, or source-file paths.
- Credible intervals and probability statements are statistical summaries of the specified model and data. They are not, by themselves, regulatory determinations.
PriorRhythm includes Bayesian prior distributions derived from
historical cardiovascular safety pharmacology studies conducted in
animal models. No raw experimental datasets are distributed with this
package. See ETHICS.md for the full statement.
Statistical methodology is based on:
Chain, A.S.Y. et al. (2013). Identifying the translational gap in the evaluation of drug-induced QTc interval prolongation. British Journal of Clinical Pharmacology, 76(5), 779–790. https://doi.org/10.1111/bcp.12101
Package developed by Richard Virgen-Slane and Dean Dingzhou Li.
To obtain the current package citation, run:
citation("PriorRhythm")