software

Team UM-macau 2025 software tool

If your team competes in the software & ai village or wants to apply for the best software tool prize, you must host all the source code of your team's software tool in this repository, main branch. by the wiki freeze, a release will be automatically created as the judging artifact of this software tool. you will be able to keep working on your software after the grand jamboree.

If your team does not have any software tool, you can totally ignore this repository. if left unchanged, this repository will be automatically deleted by the end of the season.

Description

This software tool, developed by team um-macau in 2025, is designed to simulate and analyze the spread of harmful factors (such as toxins or pathogens) within termite colonies using a modified seir - contact network model and a derivative seid - based termite infection model. it enables users to quantify, simulate, and predict the transmission process of these harmful factors among different castes of termites (workers, reproductives, young, soldiers, nymphs). by adjusting various parameters related to termite transmission, conversion, and mortality rates, as well as foraging - related settings, users can explore how these factors impact termite colony dynamics like population survival and caste - specific mortality. for more detailed background and context, you can refer to our team wiki.

Key features of this tool include:

Multi - caste simulation: simulates the spread dynamics for five termite castes with distinct parameters.
Parameter customization: allows users to adjust transmission rates, mortality rates, recovery rates, and foraging - related settings to observe different simulation outcomes.
Visualization of population trends: provides plots to display the trends of total population, alive population, and population status across different castes over time.
Detailed caste - level analysis: enables in - depth exploration of population dynamics, cumulative deaths, and related equations for each termite caste.

Compared to alternative termite infection simulation tools, our project stands out with its focus on the specific seid model adaptation for termites, detailed parameterization based on termite biology and behavior studies, and comprehensive visualization of both overall and caste - specific dynamics.

Installation

Requirements

R environment: this software requires r to be installed on your system. you can download r from cran.
Required r packages: the following r packages need to be installed: shiny, desolve, ggplot2, dplyr, scales, tidyr, bslib, shinydashboard.

Installation steps

Install r from the official cran website if you haven't already.
Open r or rstudio.

Install the required packages by running the following commands in the r console:

install.packages(c("shiny", "deSolve", "ggplot2", "dplyr", "scales", "tidyr", "bslib", "shinydashboard"))

Usage

Running the application:

Save the provided r shiny code as a .r file (e.g., termite_simulator.r).
Open the file in rstudio (or your preferred r environment).
Click the "run app" button in rstudio, or run the following command in the r console:
```
Shiny::runApp("path/to/termite_simulator.R")
```

Using the interface:

Sidebar settings: adjust global settings such as worker forage interval, forage infection rate, initial infection proportions for different castes, and simulation days.
Tab panels: navigate through different tab panels (overview, workers, reproductives, young, soldiers, nymphs) to view population trends, dynamics, cumulative deaths, and related equations for each caste. adjust parameters in each caste's panel to see how they affect the simulation results.

Example usage:

Default simulation: run the app with default parameters to see a baseline simulation of termite population dynamics over 60 days, with a forage interval of 2 days and 70% forage infection rate.
Adjusting forage interval: change the "forage interval (days)" slider to 1 and observe how more frequent foraging affects the spread of harmful factors.
Changing mortality rate: in the "workers" tab, increase the "mortality rate (γ_w)" slider to 0.5 and see the impact on worker population deaths.

Contributing

we welcome contributions to this project! if you want to contribute, please follow these steps:

Fork the repository: fork this repository(https://gitlab.igem.org/2025/software-tools/um-macau.git) to your own github account.
Clone the fork: clone the forked repository to your local machine.
Create a branch: create a new branch for your feature or bug fix (e.g., git checkout -b feature/new-feature or git checkout -b bugfix/issue-fix).
Make changes: implement your changes, following the existing code style and structure.
Test your changes: ensure that the application runs correctly with your changes and that any new features or fixes work as intended.
Commit and push: commit your changes and push them to your forked repository.
Create a pull request: open a pull request from your branch to the main branch of this repository(https://gitlab.igem.org/2025/software-tools/um-macau.git).

Development commands

Linting: although not strictly enforced, you can use r linting tools like lintr to check your code for style and potential issues. install lintr with install.packages("lintr") and run lintr::lint("path/to/your/code.r").
testing: currently, there are no formal tests, but you should manually test the application thoroughly after making changes.

Authors and Acknowledgment

This software tool was developed by team um-macau in 2025. we would like to acknowledge the contributions of all team members who worked on the modeling, coding, and testing of this application. special thanks to those who conducted research on termite behavior and biology, which provided the foundation for the parameters and models used in this tool.