exprmat Documentation#

Installation and Configuration#

To avoid version conflicts, we recommend creating a Python or Anaconda virtual environment before installing the package, even if you do not use Anaconda for package management. Please choose a consistent package manager. For example, if you prefer using pip, then try to install all Python packages with pip. This package is published on the PyPI repository and is a hybrid Python & Rust package, so you need the Rust compiler to build it from source. Cargo requires an active network connection during compilation; otherwise, it will fail to download Rust dependencies automatically. For common Linux platforms, we provide pre-compiled Wheel binary distributions. This package supports nearly all Linux systems but does not support macOS or Windows.

In addition to the package, you need to install the corresponding version of the species database. Otherwise, most features will not work. The species database is manually curated and contains gene tables, reference genome annotations, chromosome structures, ligand-receptor databases, gene set databases, ortholog tables, and transcription factor libraries for each species. Currently, we only provide databases for human (hsa), mouse (mmu), and fruit fly (dme). As this is still in early development, there is no automated method for generating databases for other arbitrary species.

First, install the appropriate version of PyTorch (version 2.0 or later) based on your GPU and CPU

# for a cpu-only version:
pip install torch torchvision torchaudio

# you may install the corresponding version if you have a supported gpu.
# this is only an example.

Install the Rust compiler
```
conda install rust
```
Install the package
```
pip install -U exprmat
```
Install the database After installing the package, a companion helper tool is automatically installed, allowing you to incrementally download and install the exprmat database. Our database is hosted on Alibaba Cloud Object Storage Service (OSS) with requester-pays download. Therefore, you need an Alibaba Cloud account and a Token ID and secret. You can use the following command to automatically install a specific version of the database with your account. Note that the database version must match the package version, otherwise errors will occur.
```
# first, navigate to your intended location to install.
# this can be any location that are accessible as you like.
cd /your/path/to/database

# please fill in the token and secret. and select the same version as your
# python package (e.g. "0.1.38")
bsync-fetch --id "your-aliyun-token" \
            --secret "your-token-secret" \
            --endpoint oss-cn-wuhan-lr.aliyuncs.com \
            --bucket exprmat-data \
            --version "exprmat-version"
```
Configure the package database path You can install the database at any path you prefer. After installation, you need to tell the package where the database is located. Create a configuration file in your home directory as follows:
~/.exprmatrc#
```
1{
2    "data": "/your/path/to/database"
3}
```

Once configured, you can type import exprmat in a Python REPL. If no errors occur, the installation was successful. On first import, the package will automatically compile its bundled C extension modules, so a C compiler must be available in your environment. In practice, every Linux environment comes with a C compiler, and the package will display compilation messages during the first import:

Python 3.10.18 (main, Jun  5 2025, 13:14:17) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

>>> import exprmat
[i] seems to be your first use of exprmat. the C modules are not compiled yet.
[i] compiling cython extension modules ...
[i] entering working directory: /usr/lib/python3.10/site-packages/exprmat
[i] compilation finished.

You can check the installation details with the following two version commands. Ensure that the installed database version number is exactly the same as the package version number.

Python 3.10.18 (main, Jun  5 2025, 13:14:17) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

>>> import exprmat

>>> _ = exprmat.version()
[i] exprmat 0.1.38 / exprmat-db 0.1.38
[i] os: posix (linux)  platform version: 5.15.0-139-generic
[i] loaded configuration from /home/user/.exprmatrc
[i] current working directory: /home/user/bioinfo/packages/exprmat/docs
[i] current database directory: /home/user/bioinfo/packages/database (0.1.38)
[i] resident memory: 708.21 MiB
[i] virtual memory: 4.76 GiB

>>> exprmat.cuda()
[i] PyTorch version: 2.8.0+cu128
[i] GPU acceleration availability: YES
[i] CUDA version: 12.8
[i] Number of installed GPUs: 1
[i] Supporting BF16 format: YES
[i] Devices:
[i] [0] NVIDIA GeForce RTX 4060 *
[i]     CUDA capability: (8, 9)
[i]     Installed VRAM (GiB): 7.89 GiB
[i]     Supporting TensorCore: YES
[i]     Current dedicated memory: 0.00 / 7.89 GiB (0.0%)

Getting Started#

License#

exprmat: Routines for manipulation of expression matrices

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.