Federated limma remove batch effect (fedRBE)

---

Table of Contents

• Architecture overview
• Installation
  • Prerequisites
  • Clone the repository
• Usage
  • Glossary & further resources
  • Input and Output
  • Configuration
  • Quick start
• Reproducing the paper
• Single-machine simulation
• Troubleshooting
• License
• How to cite
• Contact information

---

Architecture overview

The Federated Limma Remove Batch Effect (fedRBE) is a federated implementation of the limma removeBatchEffect algorithm, developed within the FeatureCloud platform. It enables privacy-preserving batch effect correction by keeping raw data decentralized and utilizing Secure Multiparty Computation (SMPC) for secure data aggregation.

fedRBE allows multiple participants to collaboratively remove batch effects from their data without sharing raw data, ensuring privacy. It effectively eliminates non-biological variations arising from different sources such as labs, time points, or technologies, using limma’s removeBatchEffect. The tool supports various data formats and seamlessly integrates with the FeatureCloud platform for streamlined workflow management.

fedRBE app states. Source: ArXiv 2412.05894

The repository serves two main purposes:

• fedRBE Implementation: Located in the batchcorrection subfolder, providing the federated batch effect removal tool.
• Reproducibility: Contains code and scripts to reproduce the analyses presented in our ArXiv preprint.

fedRBE architecture. Source: ArXiv 2412.05894

You can access and use the fedRBE app directly on FeatureCloud.

For detailed usage instructions and implementation information, refer to the How To Guide and the README.

For a comprehensive overview of the workflow, please consult the How To Guide.

---

Installation

Prerequisites

Before installing fedRBE, ensure you have the following installed:

1. Docker: Installation Instructions
2. FeatureCloud CLI. For Windows users, git must also be installed and added to PATH. We recommend and tested using WSL.
3. App Image (either build locally or pull).

For installation and setup details, see the main README.

Clone the repository

If you want to run the simulations locally, clone the repository (or check Quick Start below):

git clone https://github.com/Freddsle/fedRBE.git
cd fedRBE

This will clone the repository to your local machine with example files and simulation scripts.

---

Usage

Glossary & further resources

• FeatureCloud: A platform enabling federated analyses. FeatureCloud docs
• limma: A popular R package for differential expression analysis. RemoveBatchEffect is a function from limma.

For more advanced configurations and detailed explanations, see the main README and the ArXiv preprint.

If you encounter difficulties, please:

• Check the logs for error messages.
• Revisit the main README.
• Reach out to the support by creating an issue on the GitHub repository

---

Input and Output

For files preparation, format, config file, and output details, refer to the How To Guide.

In summary, you need two main inputs and one optional file:

Input files required for fedRBE.

Output files include:

• Corrected Data: The batch-corrected data in the same format as the input.
• Report: A summary of the correction process and results.

---

Configuration

fedRBE is highly configurable via the config.yml file. This file controls data formats, normalization methods, and other essential parameters.

Example config.yml:

flimmaBatchCorrection:
data_filename: "expression_data_client1.csv"
expression_file_flag: False
index_col: "GeneIDs"
covariates: ["Pyr"]
separator: ","
design_separator: ","
normalizationMethod: "log2(x+1)"
smpc: True
min_samples: 2
position: 1
reference_batch: ""

For a comprehensive list of configuration options, refer to the Configuration Section in the batchcorrection README.

---

Quick start

1. For a step-by-step detailed instructions on how to start collaboration using multiple machines, refer to the How To Guide
2. For a step-by-step instructions on how to simulate collaboration via test environment, refer to the Local Test Guide

---

Reproducing the paper

This repository includes all necessary code and data to reproduce the analyses presented in our ArXiv preprint.

Steps to Reproduce:

1. Ensure Prerequisites are Met:

   • Docker installed
   • FeatureCloud CLI installed and running (featurecloud controller start)
   • fedRBE app built or pulled as per the Installation section
   • Install necessary dependencies.

2. Run the Federated Batch Effect Removal:

   python3 ./evaluation_utils/get_federated_corrected_data.py

3. Compare with Centralized Correction:

   python3 ./evaluation_utils/analyse_fedvscentral.py

For detailed instructions on reproducing the paper, refer to the Reproducibility Guide.

---

Single-machine simulation

To simulate a federated workflow on a single machine using provided sample data:

1. Check the Prerequisites and Clone the Repository.
2. Run the Sample Experiment according to the Local Test Guide.

---

Troubleshooting

Encountering issues? Here are some common problems and their solutions:

• Missing Files: Ensure config.yml and data files are in the correct directory.
• Incorrect Format: Verify expression_file_flag and index_col settings in config.yml.
• No Output Produced: Check report.txt and logs for error messages.
• Errors with Test runs: Ensure the is no leftover running Docker containers. Restart Docker / System if necessary.

For detailed troubleshooting tips, refer to the How To Guide.

License

This project is licensed under the Apache License 2.0.

---

How to cite

If you use fedRBE in your research, please cite our ArXiv preprint:

Burankova, Y., Klemm, J., Lohmann, J.J., Taheri, A., Probul, N., Baumbach, J. and Zolotareva, O., 2024. FedRBE--a decentralized privacy-preserving federated batch effect correction tool for omics data based on limma. arXiv preprint arXiv:2412.05894.

@misc{burankova2024fedrbedecentralizedprivacypreserving,
      title={FedRBE -- a decentralized privacy-preserving federated batch effect correction tool for omics data based on limma}, 
      author={Yuliya Burankova and Julian Klemm and Jens J. G. Lohmann and Ahmad Taheri and Niklas Probul and Jan Baumbach and Olga Zolotareva},
      year={2024},
      eprint={2412.05894},
      archivePrefix={arXiv},
      primaryClass={q-bio.QM},
      url={https://arxiv.org/abs/2412.05894}, 
}

---

Contact information

For questions, issues, or support, please open an issue on the GitHub repository.