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, 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:

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.