Metadata-Version: 2.4
Name: pylluminator-modern
Version: 1.3
Summary: Tool to preprocess, analyze and visualize DNA methylation data from Illumina micro-arrays
Project-URL: Homepage, https://pylluminator.readthedocs.io/
Project-URL: Documentation, https://pylluminator.readthedocs.io/
Project-URL: Repository, https://github.com/eliopato/pylluminator
Project-URL: Issues, https://github.com/eliopato/pylluminator/issues
Author-email: Elio <elio.fanchon@univ-amu.fr>
Maintainer-email: Elio <elio.fanchon@univ-amu.fr>
License-Expression: MIT
License-File: LICENSE
Keywords: DMR,bioinformatics,dna-methylation,epigenetics,illumina,methylation,microarray
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Requires-Dist: inmoose>=0.9.1
Requires-Dist: joblib>=1.5.3
Requires-Dist: kdepy>=1.1.12
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: notebook>=7.5.5
Requires-Dist: numpy>=2.4.3
Requires-Dist: pandas>=2.2.0
Requires-Dist: patsy>=1.0.2
Requires-Dist: pyranges1>=1.3.3
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.17.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: statsmodels>=0.14.6
Provides-Extra: dev
Requires-Dist: coverage>=7.13.4; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Requires-Dist: sphinx>=9.1.0; extra == 'docs'
Provides-Extra: gsea
Requires-Dist: gseapy>=1.1.12; extra == 'gsea'
Requires-Dist: networkx>=3.6.1; extra == 'gsea'
Description-Content-Type: text/x-rst

|logo| Welcome to pylluminator
==============================

.. image:: https://img.shields.io/github/last-commit/eliopato/pylluminator.svg
   :target: https://github.com/eliopato/pylluminator/commits/dev
   :alt: Last commit

.. image:: https://img.shields.io/github/actions/workflow/status/eliopato/pylluminator/run_test.yml?branch=main
   :target: https://github.com/eliopato/pylluminator/actions
   :alt: Test Status

.. image:: https://img.shields.io/codecov/c/github/eliopato/pylluminator
   :target: https://codecov.io/gh/eliopato/pylluminator
   :alt: Code coverage

.. image:: https://readthedocs.org/projects/pylluminator/badge/?version=latest
   :target: https://pylluminator.readthedocs.io/en/latest/
   :alt: Documentation Status

.. image:: https://img.shields.io/badge/License-MIT-blue.svg
   :target: ./LICENSE
   :alt: MIT License

`Tutorials <https://pylluminator.readthedocs.io/en/latest/tutorials.html>`_ | `API documentation <https://pylluminator.readthedocs.io/en/latest/api.html>`_ | `Source code <https://github.com/eliopato/pylluminator>`_ | `Release on pip <https://pypi.org/project/pylluminator/>`_

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 <https://bioconductor.org/packages/release/bioc/html/sesame.html>`_ and  `ChAMP <https://bioconductor.org/packages/release/bioc/html/ChAMP.html>`_.


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

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

.. |logo| image:: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/logo.png
    :width: 100px


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:

.. list-table::

    * - .. figure:: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_1_-_Read_data_and_get_betas_16_0.png
            :target: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_1_-_Read_data_and_get_betas_16_0.png

            Fig 1. Samples beta values density

      - .. figure:: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_3_-_Calculate_DMP_and_DMR_15_0.png
            :target: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_3_-_Calculate_DMP_and_DMR_15_0.png

            Fig 2. Differentially methylated regions (DMRs)

    * - .. figure:: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_3_-_Calculate_DMP_and_DMR_17_1.png
            :target: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_3_-_Calculate_DMP_and_DMR_17_1.png

            Fig 3. Probes beta values associated with a specific gene

      - .. figure:: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_4_-_Copy_Number_Variation_9_0.png
            :target: https://raw.githubusercontent.com/eliopato/pylluminator/refs/heads/main/docs/images/tutorials_4_-_Copy_Number_Variation_9_0.png

            Fig 4. Copy number variations (CNVs)


Installation
------------

With pip
~~~~~~~~

You can install Pylluminator directly with:

.. code-block:: shell

    pip install pylluminator

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

.. code-block:: shell

    pip install pylluminator[gsea]

With uv (recommended)
~~~~~~~~~~~~~~~~~~~~~

`uv <https://docs.astral.sh/uv/>`_ is a fast Python package manager. If you don't have it yet, install it with:

.. code-block:: shell

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

Then install Pylluminator into a uv-managed project:

.. code-block:: shell

    uv add pylluminator

Or with the optional GSEA extras:

.. code-block:: shell

    uv add "pylluminator[gsea]"

From source
~~~~~~~~~~~

We recommend using `uv <https://docs.astral.sh/uv/>`_ to build pylluminator from source. The project requires Python 3.12 or later.

**Install uv (if needed)**

.. code-block:: shell

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

**Clone and install**

.. code-block:: shell

    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:

.. code-block:: shell

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

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

.. code-block:: shell

    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 <https://www.biorxiv.org/content/10.1101/2025.09.16.676547v1>`_

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) <https://www.biorxiv.org/content/10.1101/2025.03.12.642895v2>`_


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:

.. code-block:: shell

    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 <https://github.com/eliopato/pylluminator/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 <./LICENSE>`_ file for details.

Acknowledgements
----------------

This package is strongly inspired from `SeSAMe <https://bioconductor.org/packages/release/bioc/html/sesame.html>`_ and
includes code from `methylprep <https://github.com/FoxoTech/methylprep>`_ for .idat files parsing.

