You will need R (version 4.4.1 (2024-06-14) -- "Race for Your Life" as WEHI's internal Linux server runs on this version) and RStudio installed on your machine.
R Installation Links
-
Clone the repository:
git clone https://github.com/narolinelim/forecasting-with-workday-project.git
- If you're working on the forked version from Rowland, replace the URL with your forked repository URL.
-
Run the app
Open the
app.Rfile in RStudio. There might be updates and changes to the packages used in the code, but there is no need for the user to manually install or update any packages as the code will automatically check for package requirements and install any missing packages when the app is launched.Click Run App or run:
shiny::runApp("path/to/your/app.R")
-
Upload the Master Spreadsheet - The Master Spreadsheet contains all the necessary data for forecasting, including funding sources and expenses. In this version, the user will upload the Master Spreadsheet into the app to initiate the forecasting process.
-
Select the priority level - Select the priority level for the forecast. The priority level determines how funds are allocated to expenses based on their importance.
-
Generate the forecast - Generate the forecast based on the uploaded Master Spreadsheet and selected priority level. The app will process the data and provide a forecast of funding allocation and expenses.
-
Download the foretasted results in Dashboard - After generating the forecast, the user can download the results in the Dashboard section of the app. The results will be available in an Excel format.
This repository contains the codebase for the WEHI Forecasting with Workdays Shiny application. This is a proof of concept that streamlines the process of updates and finalisaiton for budget forecasting, ensuring that the forecast is consistent and systematic. The app accepts a Master Spreadsheet as input, processes the data, and generates a forecast based on user-defined priority levels.
├── README.md # Overview, setup and usage
├── app.R # App launcher
├── requirements/
│ └── packages.R # Dependency checks / install helper
├── www/ # Static assets: images, css, js
│ └── style.css # Custom styling
└── src/
├── main_ui.R # Main UI layout and page wiring
├── main_server.R # Main server wiring (main_server_logic + module sourcing)
├── server/ # Server-side modules (business logic)
│ ├── dashboard_server.R # Dashboard page server logic
│ ├── forecast_page_server.R # Forecast page server logic
│ ├── input_review_server.R # Input review page server logic
│ └── components/ # Reusable business logic components
│ ├── allocation_algorithm.R # Allocation engine (optimizer + helpers)
│ ├── data_processing.R # Read/clean Excel and validation routines
│ ├── edit_rows.R # CRUD helpers for funding & expense rows
│ ├── sorting.R # Sorting and reordering logic
│ ├── graph.R # Plot creation (shortfall, circos/chord)
│ └── output.R # Download handlers and Excel builders
└── ui/ # UI component files
├── dashboard_ui.R # Dashboard page UI and components
├── forecast_page_ui.R # Forecast page UI and components
└── input_review_ui.R # Input review page UI and components
The diagram below illustrates the structure and interaction of the various modules within the application. The modules sturcture as module A ---> module B indicates that module A calls function(s) in module B.
- Link to
function_callsdocumentation: link
Diagram is updated as of 16/02/2025
How to call variables across modules:
input$variable_name- Access input values from UI components.output$variable_name- Define output values to be rendered in the UI.values (reactiveValues)- Store and manage reactive values that can be shared across modules.values$variable_name- Access or modify reactive values.
Each component should have a ID defined in the UI and server modules that will be used as variable_name in the above calls.
-
Use descriptive names for variables and functions Variables and functions should have clear and descriptive names that indicate their purpose. Generic names like
dfortempshould be avoided. For special cases where generic names are used, comments should be added to clarify their purpose and how it can be used. -
Consistent naming style Use a consistent naming style throughout the codebase. In this project, we use
snake_casefor variable and function names (e.g.,calculate_forecast,user_input_data).
The function should have a clear purpose and a clear description of what it does. Each function should have a docstring that describes its purpose, input parameters, and return values.
Example:
function_name <- function(param1, param2) {
#' Function description and explaination
#'
#' @param param1 Description of param1
#' @param param2 Description of param2
#'
#' @return Description of the return value
# Function logic here
return(result) # Explixit return statement
}The function should explicity return a value using the return() statement, rather than relying on implicit returns in R for better readability and maintainability.
- Data Input - The user inputs funding sources and expenses.
- User can upload a Master Spreadsheet containing all necessary data for forecasting.
- User can also manually add/delete funding sources and expenses through the app interface.
- Data Processing - The app processes the uploaded data, cleaning and validating it for forecasting.
- Priority Selection - The user selects the priority level for the forecast.
- Column priorities: Sort the expenses based on user-defined columns.
- Manual priorities: User can manually reorder expenses to set their priorities.
- Forecast Generation - The app generates the forecast based on the processed data and selected priority level.
- Results Output - The user can download the forecasted results in Excel format.