HoloTrait: Holobiont Evolutionary Simulation Framework

HoloTrait is a Python framework for simulating holobiont population dynamics under host-level selection for optimal microbiome composition. The framework models how host-microbiome systems evolve across generations under fitness landscapes defined by microbial community structure, environmental influx, and within-host proliferation.

HoloTrait tracks three functional microbial groups — Competitors (C), Stress-responders (S), and Opportunists (O) — on a compositional simplex, using a multivariate Gaussian fitness kernel in logit-transformed composition space.

---

Features

• Object-oriented architecture with modular, extensible core classes
• Interactive Shiny web interface for real-time parameter exploration
• Multi-phase niche shift experiments via holotrait_multiphase.py
• Support for environmental influx, within-host proliferation, and pool mixing
• Absolute and relative fitness tracking with logit-space variance diagnostics
• Ternary plots, fitness landscapes, and time-series visualization

---

Installation

Requirements

• Python 3.10 or higher
• Conda (recommended)

Setup

# Clone the repository
git clone https://github.com/eshunwilson/HoloTrait.git
cd HoloTrait

# Create and activate environment
conda create -n holotrait python=3.10
conda activate holotrait

# Install dependencies
pip install -r requirements.txt

---

Quick Start

Run the web app

shiny run app.py

Opens at http://127.0.0.1:8000. Use the interface to set simulation parameters, run experiments, and view results interactively.

Run a simulation in Python

from holotrait_oop import HoloTraitSimulation, SimulationParams

params = SimulationParams(
    T=1000,
    num_hosts=1000,
    target_p=(0.33, 0.33, 0.34),
    niche_shift_gen=500,
    new_target_p=(0.10, 0.80, 0.10)
)

sim = HoloTraitSimulation(params)
sim.run()
sim.save_results()

Run a multi-phase niche shift

from holotrait_multiphase import run_multiphase

history = run_multiphase(
    phases=[
        {"target_p": (0.33, 0.33, 0.34), "T": 150},
        {"target_p": (0.10, 0.80, 0.10), "T": 150},
        {"target_p": (0.80, 0.10, 0.10), "T": 150},
        {"target_p": (0.33, 0.33, 0.34), "T": 150},
    ]
)

---

Project Structure

HoloTrait/
├── holotrait_oop.py          # Core simulation library
├── holotrait_multiphase.py   # Multi-phase niche shift runner
├── holotrait_runners.py      # Experiment runner utilities
├── app.py                    # Shiny web interface
├── requirements.txt          # Python dependencies
├── README.md                 # This file
└── docs/                     # Additional documentation

---

Core Classes

Class	Description
SimulationParams	Configuration dataclass for all simulation parameters
Holobiont	Individual host-microbiome unit
Population	Collection of holobionts
PopulationDynamics	Pool mixing, environmental influx, and within-host proliferation
FitnessCalculator	Gaussian fitness kernel in logit-transformed composition space
Selector	Fitness-weighted selection and offspring generation
SimulationHistory	Time-series storage including absolute fitness and logit variance
Visualizer	Ternary plots, fitness landscapes, and time-series figures
HoloTraitSimulation	Main simulation controller

---

Key Parameters

Parameter	Default	Description
T	1000	Number of generations
num_hosts	1000	Population size
target_p	(0.33, 0.33, 0.34)	Host optimum composition (C, S, O)
sigma_composition	(0.9, 0.9, 0.9)	Fitness kernel width per dimension
m	0.0001	Pool mixing rate
envir_influx	0.0	Environmental influx magnitude
envir_profile	(0.33, 0.33, 0.34)	Environmental composition
growth_multiplier	1.0	Within-host proliferation rate multiplier
selection_on	True	Enable or disable host-level selection
niche_shift_gen	0	Generation at which first niche shift occurs (0 = disabled)
niche_shift_gen_2	0	Generation at which second niche shift occurs (0 = disabled)
dirichlet_scale	100.0	Inheritance noise (higher = less noise)

---

Dependencies

• numpy >= 1.21.0
• scipy >= 1.7.0
• matplotlib >= 3.4.0
• pandas >= 1.3.0
• seaborn >= 0.11.0
• shiny >= 1.0.0
• python-ternary >= 1.0.8

Install all dependencies with:

pip install -r requirements.txt

---

Citation

If you use HoloTrait in your research, please cite:

Citation information will be added upon publication.

---

License

MIT

---

Contact

For questions or issues, please open a GitHub issue at https://github.com/eshunwilson/HoloTrait/issues.