Skip to content

README.md

Latest commit

 

History

History
274 lines (198 loc) · 11.2 KB

README.md

File metadata and controls

274 lines (198 loc) · 11.2 KB

🐝 Collective Flow of Circadian Clock Information in Honeybee Colonies

Preprint License Python Conda Docker SLURM Zenodo

Analyzing social behaviour and rhythmicity in honey bee colonies through advanced computational methods

📑 Table of Contents

🎯 Goal

This project provides a comprehensive implementation of methods for studying and analyzing behavioral rhythmicity in honey bees, as detailed in our paper: Collective flow of circadian clock information in honeybee colonies.

🔬 Key Objectives

Objective Description
📊 Data Acquisition Implement methods for collecting trajectory data of marked bees using the BeesBook system
🕐 Cosinor Modeling Develop algorithms for fitting cosine curves to individual bee movement speeds to analyze rhythmic expression
🤝 Interaction Analysis Implement techniques for detecting and analyzing bee interactions based on trajectory data
📈 Statistical Validation Conduct statistical tests to validate observed behavior patterns against null models
📊 Visualization Provide comprehensive visualization tools for interpreting and presenting analysis results

📅 Analysis Period: August 1-25, 2016 and August 20 - September 14, 2019

Overview Figure Figure: Overview of the collective flow analysis framework

📁 Project Structure

📂 Click to expand directory structure 
speedtransfer/
├── 📊 analysis/                    # Core analysis scripts
│   ├── cosinor_fit_per_bee.py     # Individual rhythm analysis
│   ├── velocity_change_per_interaction.py  # Interaction detection
│   └── ...
├── 📈 figures/                     # Visualization notebooks
│   ├── figure_panel_1.ipynb       # Movement speed analysis
│   ├── figure_panel_2.ipynb       # Speed transfer analysis
│   └── imgs/                       # Generated figures
├── 📋 aggregated_results/          # Processed data outputs
│   ├── 2016/                       # 2016 analysis results
│   └── 2019/                       # 2019 analysis results
├── 💾 data/                        # Raw data (download required)
│   ├── 2016/
│   └── 2019/
├── 🔧 simulation/                  # Simulation scripts
├── ⚙️ path_settings.py            # Path configuration
├── 📦 environment.yml             # Conda environment
└── 🐳 Dockerfile                  # Container setup

📂 Directory Details

Directory Purpose Key Features
🔬 analysis/ Core analysis scripts SLURM-compatible, modular design
📊 figures/ Jupyter visualization notebooks Interactive plots, publication-ready figures
📈 aggregated_results/ Processed data for visualization Pre-computed results for faster plotting
💾 data/ Raw trajectory data Download from Zenodo
🔧 simulation/ MATLAB simulation scripts Agent-based modeling

🚀 Getting Started

📦 Installation

Option 1: Conda Environment 
# Create conda environment
conda env create -f environment.yml

# Activate environment
conda activate speedtransfer

⚠️ Note: This environment only supports Linux.

Option 2: VS Code Dev Containers (Recommended)
  1. Install the Dev Containers extension in VS Code
  2. Click Reopen in Container when prompted, or:
    • Press Ctrl+Shift+P (Linux/Windows) or Cmd+Shift+P (Mac)
    • Type Dev Containers: Reopen in Container
Option 3: Docker 
# Build the container
docker build -t speedtransfer .

# Run the container
docker run -it speedtransfer

📊 Analysis Pipeline

Our analysis framework provides comprehensive tools for studying bee rhythmicity and social interactions:

🔬 Core Analysis Scripts

Script Function Key Features
🕐 cosinor_fit_per_bee.py Individual Rhythm Analysis Fits cosine curves to movement speeds, detects 24h rhythms
📊 mean_velocity_per_age_group.py Age-based Velocity Analysis Generates mean velocity data per age group (10-min intervals)
🌐 social_network_interaction_tree.py Social Network Analysis Maps sequential interaction cascades, constructs graph-theoretic trees
🤝 velocity_change_per_interaction.py Interaction Detection Identifies bee interactions, measures speed changes
🎲 velocity_change_per_interaction_null_model.py Null Model Generation Creates randomized interaction models for statistical validation

💡 Note: These scripts are designed for slurmhelper compatibility for high-performance computing environments.

⚙️ SLURM Configuration

For scripts with SLURM support, adapt the job configuration:

# create job
job = SLURMJob("foo_job_name", "foo_job_directory") # Choose job name and a directory where the job is stored
job.map(run_job_2016, generate_jobs_2016()) # either _2016 or _2019

# set job parameters for slurm settings
job.qos = "standard"
job.partition = "main,scavenger"
job.max_memory = "{}GB".format(2)
job.n_cpus = 1
job.max_job_array_size = 5000
job.time_limit = datetime.timedelta(minutes=60)
job.concurrent_job_limit = 100
job.custom_preamble = "#SBATCH --exclude=g[013-015],b[001-004],c[003-004],g[009-015]"
job.exports = "OMP_NUM_THREADS=2,MKL_NUM_THREADS=2"
job.set_postprocess_fun(concat_jobs_2016) # either _2016 or _2019
# Create SLURM job array
python analysis_script.py --create

# Run jobs automatically
python analysis_script.py --autorun

# Or run manually
python analysis_script.py --run

# Post-process/concatenate results
python analysis_script.py --postprocess

📚 More Information: See slurmhelper documentation or run python script.py --help

The remaining scripts can either be executed locally or on a HPC cluster using the provided bash scripts:

  • run_individual_job.sh - Single job execution
  • run_parallel_jobs.sh - Parallel job execution

📊 Visualization & Figures

Explore our comprehensive Jupyter notebooks for data visualization and figure generation:

📈 Available Notebooks

Notebook Content Key Visualizations
📊 figure_panel_1.ipynb Movement & Rhythm Analysis Group/individual speeds, cosinor fits, age-based rhythmicity
🤝 figure_panel_2.ipynb Interaction Analysis Speed transfer patterns, body-location mapping
🗺️ figure_panel_3.ipynb Spatial Analysis Activity phase distribution, interaction cascades
📋 figure_supplementary.ipynb Supplementary Data Observation statistics, additional metrics
🎬 animations.ipynb Dynamic Visualizations Animated activity flow patterns

🎯 Quick Start with Figures

# Navigate to figures directory
cd figures/

# Launch Jupyter Lab
jupyter lab

# Open any notebook and run all cells

🔬 Simulation Framework

Our MATLAB-based simulation environment provides agent-based modeling capabilities for validating theoretical predictions:

🔧 Simulation Components

Script Purpose
run_simulation.m Main simulation runner
sketch_agents_2D.m / sketch_agents_3D.m Agent visualization
draw_positions_from_gaussian.m Spatial position generation
draw_velocities.m Velocity distribution modeling
fit_sine.m Sine wave fitting for rhythm analysis

💾 Data Access

Zenodo DOI

📥 Download Instructions

# Download data from Zenodo (adjust link for different files)
wget https://zenodo.org/records/10869728/files/interactions_side0_2019.zip

# Extract to data directory
unzip data.zip

# Verify structure
ls data/

⚠️ Important: Data must be placed in the data/ directory for proper path imports in analysis scripts. Alternatively adjust the path_settings.py file.

🏆 Citation

If you use this code or methodology in your research, please cite our work:

@article{mellert2024collective,
  title={Collective flow of circadian clock information in honeybee colonies},
  author={Mellert, Julia and K{\l}os, Weronika and Dormagen, David M and Wild, Benjamin and Zachariae, Adrian and Smith, Michael L and Galizia, C Giovanni and Landgraf, Tim},
  journal={bioRxiv},
  pages={2024--07},
  year={2024},
  publisher={Cold Spring Harbor Laboratory}
}

🐝 Made with 💛 for bee research

📖 Paper • 💾 Data • 🐛 Issues • 🤝 Contributing