Welcome to pylluminator

Tutorials | API documentation | Source code | Release on pip

Pylluminator is a Python package designed to provide an efficient workflow for processing, analyzing, and visualizing DNA methylation data. Pylluminator is inspired from the popular R packages SeSAMe and ChAMP.

Pylluminator supports the following Illumina’s Infinium Beadchip array versions:

human: 27k, 450k, MSA, EPIC, EPIC+, EPICv2
mouse: MM285
mammalian: Mammal40

Main functionalities

idat files parsing
data preprocessing
- Type-I probes channel inference
- Dye bias correction (3 methods: using normalization control probes / linear scaling / non-linear scaling)
- Detection p-value calculation (pOOBAH)
- Background correction (NOOB)
- Batch effect correction (ComBat)
data analysis and visualisation
- beta values (density, PCA, MDS, dendrogram…)
- DMPs accounting for replicates / random effects, DMRs
- CNV, CNS
- pathway analysis with GSEApy (GSEA, ORA)
quality control

Visualization examples:

Fig 1. Samples beta values density	Fig 2. Differentially methylated regions (DMRs)
Fig 3. Probes beta values associated with a specific gene	Fig 4. Copy number variations (CNVs)

Installation

With pip

You can install Pylluminator directly with:

pip install pylluminator

Or, if you want to use the GSEA functionalities, you will need to install the additional dependencies using this command:

pip install pylluminator[gsea]

From source

We recommend using a virtual environment with Python 3.13 or 3.12 to build pylluminator from source. Here is an example using Conda.

Setup the virtual environment (optional)

If you don’t have Conda installed yet, here are the instructions depending on your OS : Windows | Linux | MacOS. After installing it, make sure you have Pip installed by running the following command in the terminal:

conda install anaconda::pip

Now you can create a Conda environment named “pylluminator” and activate it. You can change the name to your liking ;)

conda create -n pylluminator python=3.13
conda activate pylluminator

Install pylluminator

You can download the latest source from github, or clone the repository with this command:

git clone https://github.com/eliopato/pylluminator.git

Your are now ready to install the dependencies and the package :

cd pylluminator
pip install .

Or, as mentionned above, pip install .[gsea] if you want to use the GSEA functionalities.

Usage

Refer to https://pylluminator.readthedocs.io/ for step-by-step tutorials and detailed documentation.

Citing

Pylluminator is described in detail in: Pylluminator: fast and scalable analysis of DNA methylation data in Python, available on BioRxiv

If you use this package in your research, please cite our work.

If you use the updated version of the EPICv2/hg38 annotations, please cite Re-annotating the EPICv2 manifest with genes, intragenic features, and regulatory elements, (BioRxiv link)

Contributing

We welcome contributions! If you’d like to help improve the package, please follow these steps:

Fork the repository.
Create a new branch for your feature or bugfix.
Make your changes and test them.
Submit a pull request describing your changes.

The packages used for development (testing, packaging and building the documentation) can be installed with pip install pylluminator[dev,docs].

Bug reports / new features suggestion

If you encounter any bugs, have questions, or feel like the package is missing a very important feature, please open an issue on the GitHub Issues page.

When opening an issue, please provide as much detail as possible, including:

Steps to reproduce the issue
The version of the package you are using
Any relevant code snippets or error messages

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

This package is strongly inspired from SeSAMe and includes code from methylprep for .idat files parsing.