How fw1121/survivalml works
Project Type and Purpose
• SurvivalML is a Shiny web application built in R for “Efficient Discovery of Robust Prognostic Biomarkers and Signatures in Solid Tumors”. It is designed to facilitate multi-omics survival analysis for cancer research, including validation across multiple cohorts.
• The project leverages R’s Shiny framework for interactive web applications. It incorporates a modular design for both the UI and the server components, integrating complex analysis workflows, external data (spreadsheet and text files under “db”), and detailed documentation and help files.
File Structure
• Key directories include:
– Root files: LICENSE.txt, README.md, SurvivalML.Rproj, app.R (entry point), and init.config.R for configuration.
– db: Contains raw data files and auxiliary data/info (e.g., Excel files, text files) that serve as the database for analysis.
– doc: Contains user documentation, help materials (including FAQs, citation instructions, and policy files).
– lib: Contains common library scripts (global functions, package loaders, and utility scripts like shinyLink.R). There’s also a packaged dependency (KEGG.db tarball) and a script to list required R packages.
– server: Contains a set of modular R scripts (e.g., module_cm_candidate_agents.R, module_pm_functional_analysis.R, etc.) that encapsulate backend logic for various analysis workflows.
– ui: Contains modular UI components corresponding to the server modules (e.g., module_cm_candidate_agents.R, ui/home.R, etc.), which furnish the front-end layout.
– www: Contains static assets such as CSS, JavaScript, images, and HTML files needed for the frontend aesthetics and functionality.
– step by step: Contains workflow scripts and example runs (e.g., AM1, CM1 scripts) that likely demonstrate the analytical pipelines from data processing to model evaluation.
• This directory structure reveals a clear separation of concerns between the UI, server logic, libraries, data storage, and documentation.
a. Main Components:
• Client Interface (Frontend): Represented by the ui folder and www – these include user interface scripts (page layout, interactivity) and static assets (CSS, JS, images).
• Server (Backend) Application: Comprised of the app.R entry point, the server folder’s modular scripts for different functionalities (e.g., clinical associations, immunotherapy modules), and key configuration scripts.
• Business Logic and Utilities: The lib folder is crucial here, containing global functions, package-loading scripts, and supporting tools (e.g., shinyLink.R, database packages) that underpin both UI and server operations.
• Data Management and Storage: The db directory contains the primary datasets and preloaded information (Excel files, citation details, etc.) that feed into the analysis.
• Documentation and Help: The doc folder (and associated help files) explains the system, user guidance, and legal/copyright policies.
• Example Pipelines: The step by step folder, which shows example scripts for different analytical steps (calculations, evaluations, survival significance, etc.), illustrates the end-to-end processing workflows.
b. Relationships and Interactions:
• The user accesses the application via the UI elements (from the ui and www directories), which send interactions and inputs to the Shiny server.
• The Shiny server (via app.R) initializes the application, loading necessary global libraries from lib and processing requests by routing to appropriate server-side modules.
• Each server module (e.g., module_cm_candidate_agents.R, module_pm_immunotherapy.R) performs specific survival analysis functions using data from the db directory.
• Helper functions and shared resources in lib provide common functionalities (e.g., data loading, package management) available to both UI and server modules.
c. Architectural Patterns and Design Principles:
• Modular architecture: The separation of the UI and server directories into various modules encourages reusability and clearer maintenance.
• MVC-like separation: Even though it’s a Shiny app, the design separates the presentation (ui), business logic (server and lib) and data layer (db) akin to the Model-View-Controller (MVC) pattern.
• Configurability: The presence of configuration files (init.config.R, SurvivalML.Rproj) indicates environment-specific options and dependency management.
d. Relevant Technologies & Frameworks:
• R Language and Shiny Framework: The primary environment in which the application runs.
• Various R packages: As specified in the README (ComplexHeatmap, summaryBox, bsplus, etc.), which support data visualization, statistical analysis, and interactive components.
• Frontend assets: JavaScript and CSS in the www folder.
• External Data Sources: Excel files and text data within the db folder.
Elements to Explicitly Include
• UI Components: "Home, About, Contact, Analysis Modules" derived from ui/ files.
• Server Modules: "Clinical Association," "Prognostic Model," "Candidate Agents," etc., from server/ files.
• Utility/Library Functions: "Global Functions, Package Loaders" from the lib directory.
• Data Layer: "Raw Data & Database Files" from the db directory.
• Workflow Scripts: "Step-by-Step Analysis Pipelines" from the step by step directory.
• Configuration and documentation elements as supportive blocks, showing how external data and user guidance integrate into the overall system.
• Under the Backend, further segment it into domain-specific modules (e.g., clinical, prognostic, consensus model modules).
• Link the backend with the data repository (db) to showcase data flow and processing.
• Ancillary components such as setup (init.config.R) and documentation (doc), perhaps as peripheral yet connected modules.