PyModulon: Analyzing iModulons in Python

PyPI - Python Version PyPI Conda installation Docker container Documentation Status Black code style MIT License

What is an iModulon?

Gene expression datasets are highly complex. Differential expression analysis is the most common analytical tool used to analyze these datasets, but often result in large sets of differentially genes, many of which have little to no functional annotation. Recent studies of large transcriptomic datasets have introduced Independent Component Analysis (ICA) as a scalable alternative that produces easily-interpretable results [SGS+19].

When applied to a gene expression dataset, ICA extracts independently modulated groups of genes, called iModulons. In bacteria, iModulons recapitulate known regulation with remarkable accuracy, and often encode complete metabolic pathways [cite].

In addition, ICA simultaneously computes iModulon activities, which represents the effect of the associated transcriptional regulator on gene expression.

For more information on iModulons, see the iModulonDB About Page.

What is PyModulon?

PyModulon contains modules for the analysis, visualization, and dissemination of iModulons. PyModulon is designed with Jupyter notebooks in mind. In addition, it enables users to easily create their own iModulonDB pages for any analyzed dataset.


The pymodulon manuscript is currently in preparation. For now, please cite [SGS+19]. If you use the custom iModulonDB pages, please cite [RDS+20].


With Docker

The easiest way to get started with PyModulon is using the Docker container.

  1. Install Docker

  2. Open terminal and navigate to your work folder

  3. Run the following commands to start a Jupyter Notebook server:

    docker run -p 8888:8888 -v "${PWD}":/home/jovyan/work sbrg/pymodulon
  4. Copy the URL from terminal to connect to the Jupyter notebook

  5. Navigate to the work folder, which has your current directory mounted.

  6. To close the notebook, press Ctrl+C in terminal. All changes made to files in your current directory are saved to your local machine.

With Pip

You can install PyModulon from PyPI using pip as follows:

python -m pip install pymodulon

With Conda

Alternatively, you can install using Conda:

conda install -c conda-forge pymodulon

We recommend installing through a conda environment:

conda create -n pymodulon -c conda-forge pymodulon
conda activate pymodulon

Optional Dependencies

Some features of PyModulon require additional dependencies. Follow the links below for installation instructions.

  1. GraphViz


  3. MEME Suite

This step is not necessary if you use the Docker container.

Example Workflow

We have provided an example workflow here illustrating how to compile and process all publicly available RNA-seq data for Bacillus subtilis, and subsequently compute and characterize its iModulons. This tutorial was designed to be easily applied to any other bacteria.

Additional Resources

Indices and tables