fedRBE

fedRBE Documentation

How-To-Start Guide Reproduce the Paper Tool README Local Tests
HowTo Guide Documentation GitHub FeatureCloud App

Federated limma remove batch effect (fedRBE)

License ArXiv

Table of Contents

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
fedRBE app states. Source: ArXiv 2412.05894

The repository serves two main purposes:

fedRBE architecture
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

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

If you encounter difficulties, please:

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:

Required files figure
Input files required for fedRBE.

Output files include:

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:

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.

This site is open source. Improve this page.