jfan123/data3888-image9-models

DATA3888 Image9 Shiny App Guide

1. App overview

This Shiny app is designed for exploring class imbalance in breast tissue image classification. It allows users to inspect class distribution, compare model performance under different imbalance-handling strategies, upload H&E patch images, and view case-level predictions with model explanation maps.

The app uses two model types:

• ResNet18
• ResNet18 + ABN

The prediction function is implemented in predict.py and is called from Shiny through reticulate.

2. App structure

The main Shiny files are:

• ui.R: defines the app interface and page layout.
• server.R: controls navigation, uploads, predictions, plots, and summary text.
• global.R: loads shared packages, reads result files, defines scenario labels, and declares Python dependencies.
• predict.py: loads PyTorch models, runs prediction, and generates explanation maps.

Important folders:

• model/: contains the trained .pth model files used for prediction.
• results/: contains results_all.csv, which is used by the Performance Evaluation page.
• shiny_data/: contains scenario_counts.csv, which is used by the Class Imbalance Explorer page.
• www/: contains static assets such as workflow.png and uploaded case images.

3. Required packages

Required R packages

• shiny
• bslib
• readr
• dplyr
• ggplot2
• reticulate

Required Python packages

The app uses Python through reticulate for model prediction and explanation map generation. Required Python packages are declared in global.R:

• torch==2.2.2
• torchvision==0.17.2
• pillow
• numpy
• matplotlib

Use the standard PyPI package names in global.R (torch==2.2.2 and torchvision==0.17.2). Do not use platform-specific wheel suffixes such as +cpu in the app code.

For shinyapps.io deployment, the app must not depend on a local laptop Python environment. When a user runs the first prediction on shinyapps.io, the server creates a virtualenv named data3888-image9, installs the declared Python packages from PyPI, and binds reticulate to that virtualenv. This is delayed until prediction so the Shiny interface can start before Python and PyTorch are prepared. A local .venv is only used if DATA3888_USE_LOCAL_VENV=true is set before launching the app.

4. Local deployment

Local deployment is mainly for development or testing.

Before launching R, go inside the app folder:

cd data3888_image9

Then launch the app in R:

library(shiny)
runApp()

For local prediction to work, the local machine must have access to the required Python environment and the .pth model files in model/.

5. Online deployment

The app can be deployed online through shinyapps.io using the rsconnect package.

The current online deployment is:

https://data3888-image9.shinyapps.io/data3888_image9/

For online deployment, the server is responsible for preparing the R and Python environment. Users do not need to install R, Python, PyTorch, or model files on their own computers.

Before deploying, make sure the app folder includes:

• ui.R
• server.R
• global.R
• predict.py
• model/
• results/results_all.csv
• shiny_data/scenario_counts.csv
• www/

Files not required by the app, such as large raw datasets or cached explanation images, should not be included in the deployment folder. The .rscignore file excludes .venv, uploaded case images, cached explanation images, and local case-library state so shinyapps.io starts with a clean case library and builds its own Python environment.

Before deploying, open R from inside the app folder, then run:

rsconnect::deployApp()

The first prediction run may take longer because the server needs to prepare the Python environment and load the PyTorch models.

6. User workflow

Once the app is deployed online, users only need to open the web link and use the interface:

1. Open the app URL.
2. Use Class Imbalance Explorer to inspect how uneven the class distribution is.
3. Use Performance Evaluation to compare model performance across scenarios, strategies, and metrics.
4. Go to Upload Image & Case Library and upload a H&E patch image.
5. Click Open for the selected case.
6. In Case Settings, choose the imbalance scenario and handling strategy.
7. Click Run Prediction.
8. Review the predictions and explanation maps in Prediction Results.

Users do not need to run R code when using the online app.