Tutorial: translating a validated breast cancer prediction model into a web-based decision aid using R Shiny

Introduction

In recent years, the development of risk prediction models has increased rapidly, yet few have been integrated into patient care. Models available through online medical calculator platforms such as “MDCalc” rarely include information on how to incorporate risk estimates into medical decision-making. This gap is particularly evident in breast cancer screening among older women. Current guidelines recommend shared decision-making for women aged ≥75 years (1), and some specifically recommend not screening women with <10-year life expectancy. Guidelines also vary as to how often women aged 55 and older should be screened (annually or biennially), with experts recommending consideration of women’s risk of breast cancer, their health, and their preferences in these decisions (2). However, implementing these recommendations requires individualized estimates of both breast cancer risk and competing mortality risk. Widely used models, including the Breast Cancer Risk Assessment Tool (BCRAT or “Gail model”) (3), the Tyrer-Cuzick model (4), and the Breast Cancer Surveillance Consortium (BCSC) model (5), estimate breast cancer risk but do not account for individualized competing risks of death or provide decision support to guide breast cancer screening or prevention decisions.

To address this gap, we previously developed a competing risk regression model (6) using Fine and Gray methodology (7) to simultaneously predict 5- and 10-year breast cancer risk and 10-year risk of death among women 55 and older. The model was developed using data from over 83,000 participants in the Nurses’ Health Study and demonstrated good discrimination for predicting 10-year non-breast cancer mortality risk (c-index 0.79) and modest discrimination for breast cancer risk (c-index 0.61). External validation (8) in the Black Women’s Health Study, Women’s Health Initiative and Multiethnic Cohort demonstrated comparable or improved model performance relative to established models (breast cancer c-index 0.57–0.58; mortality c-index 0.76–0.77) with good calibration. Following model development and validation, we created an R Shiny application (https://bcrisk55plus.shinyapps.io/risktool/) that integrates our model’s risk prediction estimates with decision support for breast cancer screening and prevention in an interactive web-based tool. We developed our decision aid in R Shiny because it is a flexible, open-source platform used in research and medicine for building interactive web applications. While developing the aid, we obtained iterative feedback from 45 women aged 55 and older and 30 experts in women’s health and refined the aid to improve its clarity and individualization based on these end-users’ feedback (9). The majority of end-users found the decision aid helpful, easy-to-use, and informative.

In this tutorial, we demonstrate how predictive models can be deployed in web-based decision-aid tools with R Shiny, using our breast cancer risk-based decision aid as an example. We illustrate key components of building a web-based decision aid, including application structure, collection of model inputs or risk factors, real-time risk computation, data visualization and conditional display. Despite the growing number of risk models, there is limited guidance on how to implement these models as tools that combine individualized risk estimation, visualization and tailored decision support. Due to the technical nature of this work, we followed established principles for technical and software-oriented scientific reporting (10,11).

Application structure and layout

This guide assumes a basic working knowledge of R programming (12) and the R Shiny package (13). Readers should be familiar with the fundamental structure of a Shiny app, including the user interface (UI) that defines layout and visual elements, and the server function, which defines the application’s reactive logic and functionality. For readers seeking an introduction or refresher, Posit provides introductory materials (14) for developing simple Shiny applications.

Our multi-page application is organized using a tab-based navigation structure, where each page is presented as a separate tab. The app contains seven pages: Home, Assessment, Chance of Breast Cancer, Chance of Death, Mammography Information, Prevention Medicine Information, and References. Figure 1A illustrates the overall application structure, and Figure 1B shows the corresponding UI.

Figure 1 TabsetPanels. (A) Code structure; (B) user interface.

User input widgets

Each page of the application includes interface elements relevant to the intended application workflow, including instructional text, input fields, and data visualizations. These components are defined using Shiny functions and HTML elements. Shiny provides built-in interface components, or widgets, that collect user input and structure page content.

For example, the Assessment page in our app consists of several widgets that collect user-reported clinical and demographic information. These inputs are used to generate individualized risk estimates that are displayed on subsequent pages. The Assessment page uses numeric and categorical input widgets to capture user responses. Figure 2 demonstrates an example of a categorical input interface, where users select one of several response options.

Figure 2 Widget example. (A) Code; (B) user interface.

The application also uses interactive button widgets to support navigation and user interaction within the decision aid, including advancing through pages and resetting inputs when needed.

Risk calculation and reactive values

A central component of the application is the risk calculator, which uses Shiny’s reactive value framework to calculate risk estimates based on our previously developed competing risk regression model. User-reported risk factors are combined with pre-specified model coefficients to compute individualized risk estimates. As users enter or modify input values, risk estimates are updated dynamically to reflect the current set of covariates. Once all required inputs are provided, the model generates predicted survival probabilities that are displayed on subsequent pages of the app. This reactive functionality allows risk estimates to remain synchronized with user input.

Figure 3 demonstrates how continuous body mass index (BMI) is derived from height and weight inputs and mapped to model coefficients based on predefined categories. This process is repeated for each predictor in the model. The linear combination of the coefficients and the observed values of the predictor yields the sum (Xβ). The predicted survival probability is computed as S(t) = S₀(t)^exp(Xβ), where S₀(t) is the baseline survival function. The risk probability is computed as 1-S(t). While we used a survival model, this approach is applicable to other model types as well.

Figure 3 Risk calculator example: body mass index. (A) Assessment page input; (B) reactiveValues and risk calculation.

Data visualization

Once calculations are complete, the results must be presented in a format that facilitates interpretation. Data visualization provides a powerful means of conveying model outputs. In this application, waffle plots are used to illustrate the primary output of our model, though any plot generated with ggplot2 or other R packages can be incorporated into a Shiny app.

We present 5- and 10-year risk of breast cancer and 10-year risk of non-breast cancer death, expressed as percentages; however, the underlying model can generate risk estimates for any timepoint up to 10 years. Waffle plots composed of 1,000 blocks represent the relative probability of each outcome. Presenting risk this way contextualizes the users’ competing risks, consistent with prior work (15).

Figure 4 presents an example output for an 80-year-old woman with diabetes and heart failure. Her estimated 10-year risk of breast cancer (Figure 4A) is 1.9%, corresponding to 19 of 1,000 filled blocks. In contrast, her estimated 10-year risk of non-breast cancer death (Figure 4B) is 49%, or 490 of 1,000 blocks. In this example, the competing risk of non-breast cancer death exceeds the risk of developing breast cancer within 10 years, providing context relevant to screening decisions.

Figure 4 Waffle plots. (A) Risk of breast cancer; (B) risk of non-breast cancer death; (C) user interface and server code example.

To incorporate visual elements into a Shiny app, plotting functions are linked across the UI and server components. Figure 4C presents example code for generating a simple waffle plot incorporating model-based risk estimates. The UI defines where the visualization appears within the application, while server-side logic generates the plot dynamically based on calculated risk values. In our app, risk percentages were transformed into counts out of 1,000 to populate the waffle plots. The plots were created using the waffle function, although other R plotting functions could be substituted at this stage.

Several additional visualization techniques are incorporated into the application, including tables, images and a slider input. After viewing risk estimates, users are presented with information on the potential benefits and downsides of mammography, along with factors relevant to screening frequency decisions. The final page (Figure 5) synthesizes this information using multiple visual elements, including an image of a scale to represent consideration of benefits and harms, a summary table, and a slider input allowing users to indicate screening preference by moving the slider in either direction. While the slider is not used analytically, it was designed to provide an interactive mechanism for users to reflect on their screening preferences. The slider was not included in the original version of the application, but was added based on end-user feedback (9).

Figure 5 Visualization of decision.

These visual elements work together to present information in an integrated format for decision-making. During end-user testing, patients and experts reported highly valuing the personalized risk information provided by the aid for understanding and reflecting on breast cancer screening decisions (9).

Conditional display of outputs

So far, we have demonstrated how to structure a decision aid that calculates an individual user’s risk and presents results using multiple display formats. However, not all users should see the same information. Application flow depends on user characteristics and estimated risks of breast cancer and non-breast cancer death. For example, mammography guidelines differ for women aged 75 and older or for those with high estimated risk of mortality. Therefore, to personalize content and flow, we implemented conditional display of elements throughout the app.

Shiny supports multiple approaches to the conditional display of content. One method uses conditional logic within server-side processing to modify display content based on user inputs. Figure 6A illustrates an example where different text is displayed depending on whether a woman’s estimated 10-year mortality risk exceeded 50%. Users with >50% risk of 10-year mortality are estimated to have <10-year life expectancy, since life expectancy is the median survival of a population and guidelines do not recommend screening for these women. By conditioning each output on relevant variables, we tailored the displayed content to women in different clinical scenarios.

Figure 6 Conditional display. (A) If statement; (B) observeEvent function.

Another key function used throughout the app is observeEvent, which triggers reactive actions when a defined event occurs, such as clicking a button or modifying a widget. The observeEvent is used to manage navigation and determine which content becomes available as the user progresses through the decision aid. Users begin on the home page with access only to the Assessment page, and additional pages are displayed as users proceed through the application. Figure 6B provides an example in which submission of assessment information reveals the risk results page.

Additional uses of observeEvent include conditionally displaying the breast cancer prevention medications section for users meeting predefined risk thresholds, dynamically showing or hiding assessment questions based on prior responses, resetting inputs, and displaying error messages when inputs are missing or out of range.

Finalizing the application

After the core structure is complete, the application’s appearance can be customized using Cascading Style Sheets (CSS) (16), allowing modification of visual elements such as color, font, and sizing.

For deployment, options include cloud-based hosting with shinyapps.io or on-premises deployment via Shiny Server or Posit Connect (17). We deployed our app using shinyapps.io, which requires no local hardware or server installation and allows direct deployment from R. A free tier is available, lowering barriers to deployment. Updates can be implemented by modifying the source code and redeploying the application. As models evolve, model parameters can be updated without altering the app’s structure or appearance. To facilitate transparency and reproducibility, the full source code for our application is provided in the supplementary appendix (available online at https://cdn.amegroups.cn/static/public/atm-2026-0070-1.pdf).

Discussion

Prior tutorials for developing Shiny apps for use in clinical settings have focused on constructing a simple risk calculator (18) or implementing complex models, including machine learning methods (19). Our work extends these tutorials by providing a framework to integrate a risk calculator into a broader application with personalized decision support. We demonstrate a wide range of Shiny functionalities that transform a basic Shiny app into a comprehensive, clinically useful decision aid.

Using Shiny to develop our decision aid offered several advantages. We were able to create an early prototype and make changes easily based on end-user feedback (9). Shiny is more accessible to researchers than traditional HTML programming, particularly given the widespread use of R in research settings. Its direct integration with R allows statistical models to be incorporated directly, without translating code into another programming language. R’s open-source nature and extensive support facilitate access to packages, community resources and long-term maintenance. Developing a comparable site in HTML usually requires external contractors and may be more costly for researchers, particularly if iterative changes are needed throughout development. Even if an HTML site is ultimately required, Shiny can serve as a convenient and inexpensive tool for creating an early prototype while refining and improving a decision aid during the development phase.

Despite its advantages, there are several limitations to using Shiny to create a decision aid. While Shiny provides many built-in interface components, fully customized interfaces may require HTML, CSS, or JavaScript. Widgets, while easy to implement, are functionally limited. For example, the slider widget provides an interactive way for users to indicate their preference for mammography frequency, but it requires a finite number of stopping points rather than sliding smoothly. We also needed to add error messages to the assessment page to prevent out-of-range inputs. In addition, we were somewhat constrained by the visualization options available through existing R packages. Although these options are often sufficient, our ideal waffle plot would have represented risk using 1,000 individual pictographs of people rather than squares. Additionally, Shiny applications do not natively support mobile app development, which may limit application reach and portability. Finally, large-scale deployment may require more robust infrastructure depending on expected user traffic.

As risk prediction models become increasingly common, it is important to make them accessible to users along with the information necessary to interpret the results. Our decision aid application provides a framework for using R Shiny to integrate risk estimation with visualization, personalized information and interactive decision support. By incorporating multi-page application structure, dynamic risk calculation, data visualization and conditional display, prediction models can be implemented as patient-facing decision aids that support informed and individualized decision-making.

Acknowledgments

None.

Footnote

Peer Review File: Available at https://atm.amegroups.com/article/view/10.21037/atm-2026-0070/prf

Funding: This work was supported by a National Cancer Institute R01 (CA242747); and a National Institute on Aging K24 (AG071906).

Conflicts of Interest: All authors have completed the ICMJE uniform disclosure form (available at https://atm.amegroups.com/article/view/10.21037/atm-2026-0070/coif). M.A.S receives grants from NIA (K24 AG071906) and NCI (R01 CA242747), and royalty payments from UpToDate for reviewing pages on prevention. The other authors have no conflicts of interest to declare.

Ethical Statement: The authors are accountable for all aspects of the work in ensuring that questions related to the accuracy or integrity of any part of the work are appropriately investigated and resolved.

Open Access Statement: This is an Open Access article distributed in accordance with the Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International License (CC BY-NC-ND 4.0), which permits the non-commercial replication and distribution of the article with the strict proviso that no changes or edits are made and the original work is properly cited (including links to both the formal publication through the relevant DOI and the license). See: https://creativecommons.org/licenses/by-nc-nd/4.0/.

References

1. Qaseem A, Harrod CS, Balk EM, et al. Screening for Breast Cancer in Asymptomatic, Average-Risk Adult Females: A Guidance Statement From the American College of Physicians (Version 2). Ann Intern Med 2026;179:842-56. [Crossref] [PubMed]
2. Mango V, Bryce Y, Morris EA, et al. Commentary ACOG Practice Bulletin July 2017: Breast Cancer Risk Assessment and Screening in Average-Risk Women. Br J Radiol 2018;91:20170907. [Crossref] [PubMed]
3. National Cancer Institute. Breast Cancer Risk Assessment Tool (BCRAT) Online Calculator. Bethesda, MD: NCI. Available online: https://bcrisktool.cancer.gov/
4. Ikonopedia, Inc. IBIS (Tyrer Cuzick) Breast Cancer Risk Evaluation Tool. Richardson, TX: Ikonopedia, Inc. Available online: https://ibis.ikonopedia.com/
5. Breast Cancer Surveillance Consortium. BCSC 5 Year Invasive Breast Cancer Risk Calculator. Sacramento, CA: Breast Cancer Surveillance Consortium. Available online: https://tools.bcsc-scc.ucdavis.edu/BC5yearRisk/#/
6. Schonberg MA, Wolfson EA, Eliassen AH, et al. A model for predicting both breast cancer risk and non-breast cancer death among women > 55 years old. Breast Cancer Res 2023;25:8. [Crossref] [PubMed]
7. Fine JP, Gray RJ. A proportional hazards model for the subdistribution of a competing risk. J Am Stat Assoc 1999;94:496-509.
8. Wolfson EA, Schonberg MA, Eliassen AH, et al. Validating a model for predicting breast cancer and nonbreast cancer death in women aged 55 years and older. J Natl Cancer Inst 2024;116:81-96. [Crossref] [PubMed]
9. Schonberg MA, Jushchyshyn J, Shah R, et al. Developing a website to help women aged 55 + incorporate risk in decision-making about breast cancer screening and prevention medications. Patient Educ Couns 2025;137:108819. [Crossref] [PubMed]
10. Ernst MW. How to write a technical paper. University of Washington; 2005. Available online: https://homes.cs.washington.edu/~mernst/advice/write-technical-paper.html
11. R Foundation for Statistical Computing. R Journal: Guidelines for Authors (Software and Applications). Vienna: R Foundation for Statistical Computing. Available online: https://journal.r-project.org
12. R Core Team. R: A language and environment for statistical computing. Vienna, Austria: R Foundation for Statistical Computing; 2022. Available online: https://www.R-project.org/
13. Posit. Shiny: Web application framework for R. Available online: https://shiny.posit.co/
14. Posit. Shiny Basics — Lesson 1. Available online: https://shiny.posit.co/r/getstarted/shiny-basics/lesson1/
15. Kandel J, Liu J, Wang AZ, et al. Graphical Perception of Icon Arrays versus Bar Charts for Value Comparisons in Health Risk Communication. IEEE Trans Vis Comput Graph 2026;32:780-90. [Crossref] [PubMed]
16. Posit. Using CSS with Shiny. Available online: https://shiny.posit.co/r/articles/build/css/
17. Posit. Deploying Shiny applications. Available online: https://shiny.posit.co/r/deploy.html
18. Ji X, Kattan MW. Tutorial: development of an online risk calculator platform. Ann Transl Med 2018;6:46. [Crossref] [PubMed]
19. Eddington HS, Trickey AW, Shah V, et al. Tutorial: implementing and visualizing machine learning (ML) clinical prediction models into web-accessible calculators using Shiny R. Ann Transl Med 2022;10:1414. [Crossref] [PubMed]