README.rst

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)
  • Missing beta values imputation
  • Lift over annotation
• 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 uv (recommended)

uv is a fast Python package manager. If you don't have it yet, install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install Pylluminator into a uv-managed project:

uv add pylluminator

Or with the optional GSEA extras:

uv add "pylluminator[gsea]"

With pip

You can install Pylluminator directly with:

pip install pylluminator

Or, if you want to use the GSEA functionalities, install the additional dependencies with:

pip install pylluminator[gsea]

From source

We recommend using uv to build pylluminator from source. The project requires Python 3.12 or later.

Install uv (if needed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and install

git clone https://github.com/eliopato/pylluminator.git
cd pylluminator
uv sync

This creates a virtual environment and installs all dependencies automatically. To include optional extras:

uv sync --extra gsea
uv sync --extra dev
uv sync --extra docs

Run scripts or tests within the project environment using uv run:

uv run pytest

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, published in Bioinformatics Advances, Volume 6, Issue 1, 2026, (https://doi.org/10.1093/bioadv/vbag146)

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:

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

The packages used for development (testing, packaging and building the documentation) can be installed with:

uv sync --extra dev --extra 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.