Metadata-Version: 2.4
Name: pylluminator
Version: 1.2
Summary: Tool to preprocess, analyze and visualize DNA methylation data from Illumina micro-arrays
Author-email: Elio <elio.fanchon@univ-amu.fr>
Maintainer-email: Elio <elio.fanchon@univ-amu.fr>
License-Expression: MIT
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
Keywords: dna-methylation,epigenetics,illumina,bioinformatics,microarray,methylation,DMR
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: ailist==2.1.7
Requires-Dist: fastcluster==1.2.6
Requires-Dist: inmoose==0.8.1
Requires-Dist: joblib==1.5.2
Requires-Dist: KDEpy==1.1.12
Requires-Dist: linear_segment==1.2.1
Requires-Dist: matplotlib==3.10.6
Requires-Dist: notebook>=7.2.2
Requires-Dist: numpy<2.0.0
Requires-Dist: pandas<3.0.0,>=2.2.0
Requires-Dist: patsy==1.0.1
Requires-Dist: pyranges1==1.1.4
Requires-Dist: scikit-learn==1.7.2
Requires-Dist: scipy==1.15.3
Requires-Dist: statsmodels==0.14.5
Requires-Dist: seaborn==0.13.2
Provides-Extra: dev
Requires-Dist: coverage==7.10.6; extra == "dev"
Requires-Dist: pytest==8.4.2; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx==8.1.3; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Provides-Extra: gsea
Requires-Dist: gseapy==1.1.10; extra == "gsea"
Requires-Dist: networkx==3.5; extra == "gsea"
Dynamic: license-file

|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, you will need to install the additional dependencies using this command:

.. code-block:: shell

    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 <https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html>`_ | `Linux <https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html>`_ | `MacOS <https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html>`_.
After installing it, make sure you have Pip installed by running the following command in the terminal:

.. code-block:: shell

    conda install anaconda::pip

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

.. code-block:: shell

    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:

.. code-block:: shell

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

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

.. code-block:: shell

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

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

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 `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 <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.

