2. Installation

CpGtools supports Python 3.9 or later and can be installed with pip. Most Python dependencies are installed automatically.

Some commands require additional software, such as R or TensorFlow.

2.1. Install in a Virtual Environment

Using a virtual environment is recommended because it keeps CpGtools and its Python dependencies isolated from the system Python installation and from other projects.

2.1.1. Create a virtual environment

First, create a new environment using Python’s built-in venv module:

python3 -m venv cpgtools-env

Activate the environment:

On Linux or macOS:

source cpgtools-env/bin/activate

On Windows Command Prompt:

cpgtools-env\Scripts\activate.bat

On Windows PowerShell:

cpgtools-env\Scripts\Activate.ps1

After activation, the environment name usually appears at the beginning of the command prompt, for example:

(cpgtools-env) $

2.1.2. Install CpGtools

Upgrade pip and install CpGtools from PyPI:

python -m pip install --upgrade pip
python -m pip install cpgtools

Verify the installation:

epical --version
beta_impute --version

When finished, leave the virtual environment with:

deactivate

To use CpGtools again later, reactivate the same environment rather than reinstalling the package.

2.2. Install from PyPI

The recommended installation method is:

python -m pip install cpgtools

To upgrade an existing installation:

python -m pip install --upgrade cpgtools

2.3. Install from GitHub

To install the latest development version directly from GitHub:

python -m pip install git+https://github.com/liguowang/cpgtools.git

2.4. Install from Source

Clone the repository and install CpGtools locally:

git clone https://github.com/liguowang/cpgtools.git
cd cpgtools
python -m pip install .

For development, use an editable installation:

python -m pip install -e .

2.5. Python Dependencies

The following packages are installed automatically with CpGtools:

numpy
scipy
pandas
scikit-learn
matplotlib
umap-learn
bx-python
weblogo
pycombat

Additional dependencies required by these packages are resolved automatically by pip.

2.6. Optional Dependencies

2.6.1. TensorFlow

TensorFlow is required only when using the MOREL imputation method with the dense neural-network model:

beta_impute morel --model DNN ...

The default Random Forest model (--model RF) does not require TensorFlow.

Install TensorFlow separately if needed:

python -m pip install tensorflow

2.6.2. R and R Packages

Some CpGtools commands call R and therefore require an R installation.

R: Required by commands that execute generated R scripts.
aod: Required by dmc_bb.
beanplot: Required by beta_jitter_plot.

These R dependencies are not installed automatically by pip.

2.7. Verify the Installation

After installation, verify several command-line programs:

epical --version
beta_impute --version
epical -h
beta_impute -h
beta_deconvolution -h

You can also verify that the Python package is importable:

python -c "import cpgmodule; print(cpgmodule.__file__)"

2.8. Troubleshooting

If a command is not found after installation, confirm that CpGtools is installed in the active Python environment:

python -m pip show cpgtools

When using a virtual or Conda environment, make sure that environment is activated before installing or running CpGtools.