Installation

Requirements

To install DeerLab, first install Python on your computer. Python can be downloaded from the official Python distribution. There are many online tutorials to guide you through the installation and setup (see here for example). Make sure you install one of the Python versions compatible with DeerLab, either Python 3.8, 3.9, 3.10, or 3.11.

Windows systems

For Windows systems it is important to ensure that the Install launcher for all users (recommended) and the Add Python 3.x to PATH checkboxes at the bottom are checked. To test if python has been successfully installed, open a terminal window and run the command:

python

which should display the installed Python version and launch the Python command line. To exit, use the exit() command or close the console.

Installing DeerLab

Installing from PyPI

A pre-built distribution can be installed using pip.

First, it is important to ensure that pip is up-to-date. From a terminal (preferably with administrative privileges) use the following command:

python -m pip install --upgrade pip

Next, install DeerLab and all its dependencies via:

python -m pip install deerlab

DeerLab installs the following packages:

  • matplotlib - A comprehensive library for creating data visualizations with Python

  • memoization - A powerful caching library for Python

  • pytest - A Python testing framework

  • cvxopt - Free software package for convex optimization

  • numpy - The fundamental package for scientific computing with Python

  • scipy - Fundamental library for scientific computing

  • joblib - Library lightweight pipelining and parallelization.

  • tqdm - A lightweight package for smart progress meters.

  • dill - An extension of Python’s pickle module for serializing and de-serializing python objects.

  • quadprog - A quadratic programming solver (Only for Python versions < 3.11)

Importing DeerLab

As a Python package, DeerLab must be imported before using it. For this, use the import statement:

import deerlab as dl

This makes DeerLab functions accessible via the abbreviated name dl. For example, the function fit can be called via dl.fit. We recommend to use dl as the standard import abbreviation for DeerLab.

Updating to the latest release

To upgrade an existing DeerLab installation to the latest released version, use the following command from a terminal:

python -m pip install --upgrade deerlab

Other installations

Installing specific versions

Any DeerLab version released after v0.10.0 can be installed via pip using the following command matching the x.y.z to the desired version:

python -m pip install deerlab==x.y.z

Installing from source

If you wish to contribute to DeerLab or like to get the latest updates as they come, install DeerLab from git. If your OS has not git installed, you can download it and install it from the official Git distribution. To download (clone) the repository, execute the following from the command line:

git clone https://github.com/JeschkeLab/DeerLab.git

To update to the latest version, go the local directory where DeerLab has been downloaded and execute:

git pull origin main

Now in the DeerLab directory run the installation script as follows to install DeerLab:

python -m setup install

In order to install DeerLab but be able to edit the code or update frequently without having to re-install the package, use the command:

python -m setup develop

Any changes made to the source code will then immediate effect.

Linking against BLAS libraries

The installed numerical computing packages (numpy, scipy, cvxopt) are automatically linked against different BLAS libraries depending on the OS:

  • Linux: OpenBLAS

  • Mac: BLAS/LAPACK from the Accelerate framework

In Windows systems, these packages can be linked against the Intel MKL libraries. To do so, DeerLab provides a script mkl_link.py that can be used to link against the Intel MKL libraries automatically:

python mkl_link.py

The script will download the binaries from the Gohlke repository and override any currently installed version of the mentioned packages.

Installation failed

Under certain circumstances the installation using some of the methods described above may fail due to specific technical reasons. This is a selection of some of the known issues that may arise during installation of DeerLab along with instructions to solve them.

Known Issue #1: DLL load failed

On a Windows computer, if you are trying to run a DeerLab function, you might get the following message:

ImportError: DLL load failed: The specified module could not be found.

This issue can occur when a specific python package is not installled properly. This typicaly happens when installing the MKL linked libaries but can occur when installing packages normaly from PyPI. This can happen due to firewall restrictions, user rights, or internet connection issues during the DeerLab installation.

If your where installing packages from PyPI (i.e. via pip) then please uninstall the package and reinstall it.

python -m pip uninstall <package_name>
python -m pip install <package_name>

If you were trying to install the MKL linked libraries then please follow the instructions below.

  1. Go to https://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy

  2. Download the appropriate numpy wheels file according to your installed Python version and Windows system:

            Python version (3.x)
Package name       |         Windows architecture (32-64 bit)
|                  |          |
v                  v          v
numpy-1.19.1+mkl-cp36-cp36m-win_amd64.whl

  1. Once downloaded, open a terminal at the location of the .whl file and run the command:

    python -m pip install "numpy-1.19.1+mkl-cp36-cp36m-win_amd64.whl"

    making sure that the name of the .whl file matches the one that you downloaded.

This will install numpy and properly link all MKL DLL files. DeerLab should work now. Should the error persists, repeat this process for the scipy and cvxopt packages (in that order).

Known Issue #2: __path__ attribute not found

During installation on certain systems (e.g. some computation clusters) using one of the following commands

python -m setup.py install
python -m setup.py develop

the following error might be raised during the installation:

Error while finding module specification for 'setup.py'
(ModuleNotFoundError: __path__ attribute not found on 'setup' while trying to find 'setup.py')

In such cases, the error can be avoided by omitting the -m argument in the installation command, i.e.

python setup.py install
python setup.py develop