Metadata-Version: 2.4
Name: chi-som
Version: 1.1.1
Summary: Fast self-oranizing maps for cheminformatics using numba
Keywords: som,self-organizing map,machine learning,rdkit,cheminformatics,drug discovery,numba
Author: Johannes Kaminski, Oliver Koch
Author-email: Johannes Kaminski <j.kaminski@uni-muenster.de>, Oliver Koch <okoch@uni-muenster.de>
License-Expression: LGPL-3.0-or-later
License-File: LICENSES/GPL-3.0-only
License-File: LICENSES/LGPL-3.0-only
License-File: LICENSES/copyright
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Environment :: GPU :: NVIDIA CUDA :: 13
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Dist: numba>=0.61.2
Requires-Dist: pandas>=2.2.3
Requires-Dist: rdkit>=2024.9.6
Requires-Dist: tables>=3.10.2
Requires-Dist: tqdm>=4.65
Requires-Dist: scipy>=1.15.2
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2,<2.4
Requires-Dist: networkx>=3.6.1
Requires-Dist: numba-cuda-mlir[cu12]>=0.4.2 ; extra == 'cu12'
Requires-Dist: numba-cuda-mlir[cu13]>=0.4.2 ; extra == 'cu13'
Requires-Dist: pyarrow>=25.0.1 ; extra == 'gui'
Requires-Dist: pyqtgraph>=0.13.7 ; extra == 'gui'
Requires-Dist: pyside6>=6.10.0 ; extra == 'gui'
Maintainer: Johannes Kaminski
Maintainer-email: Johannes Kaminski <j.kaminski@uni-muenster.de>
Requires-Python: >=3.13
Project-URL: Homepage, https://kochlab.org
Project-URL: Documentation, https://kochgroup.github.io/ChI-SOM
Project-URL: Repository, https://github.com/kochgroup/ChI-SOM
Project-URL: Issues, https://github.com/kochgroup/ChI-SOM/issues
Provides-Extra: cu12
Provides-Extra: cu13
Provides-Extra: gui
Description-Content-Type: text/markdown

# &#7521;-SOM

> **Ch**em**I**nformatics SOM Toolkit

&#7521;-SOM is a high-performance framework for training emergent self-organizing maps (ESOMs) with a specific focus on cheminformatics; including on-disc, low-latency data storage and a GUI.  
It was specifically developed for visualising the chemical space of million-scale molecular datasets and for interactive exploration.


![Overview of the ChI-SOM GUI](images/gui_screenshot.png "The GUI")

- **Scales to millions of molecules** — a dedicated HDF5 layout gives random, millisecond-latency access to fingerprints that do not fit in memory, through the PyTorch `DataLoader` interface.
- **CPU and CUDA backends** — numba-compiled training on either, selected with a single flag.
- **Interactive exploration** — an interactive viewer for colouring, filtering and inspecting the molecules behind every unit of a trained map.

## Installation
Currently, __ChI-SOM__ is only available for Linux, and Windows using _WSL2_.

It can be installed directly from PyPI
```sh
pip install chi-som
```  
  
The interactive viewer is an optional extra and is **not** part of the base install
```sh
pip install 'chi-som[gui]'
```  
  
For the CUDA compute backend, `numba-cuda-mlir` is required.
On systems running CUDA, ChI-SOM can be installed with CUDA support via
```sh
pip install 'chi-som[cu12]'
```
for CUDA12 or 
```sh
pip install 'chi-som[cu13]'
```
for CUDA13  
  
Please refer to the [numba-cuda-mlir](https://nvidia.github.io/numba-cuda-mlir/latest/) documentation for more complex setups.

Extras combine, e.g. `pip install 'chi-som[cu12,gui]'`. Full details, including the development setup and troubleshooting, are in the [installation guide](https://kochgroup.github.io/ChI-SOM/installation/).

## Documentation
Documentation for ChI-SOM is available at <https://kochgroup.github.io/ChI-SOM/>

- [Installation](https://kochgroup.github.io/ChI-SOM/installation/)
- [The Viewer](https://kochgroup.github.io/ChI-SOM/gui/)
- [How-To Guides](https://kochgroup.github.io/ChI-SOM/how-to-guides/)
- [Upgrading to 1.1](https://kochgroup.github.io/ChI-SOM/upgrading/)
- [Limitations](https://kochgroup.github.io/ChI-SOM/limitations/)
- [Library Reference](https://kochgroup.github.io/ChI-SOM/reference/)

## Usage example

```python
import numpy as np
import pandas as pd

from chisom import Som, start_chisom_viewer
from chisom.utils import lattice_size

data = np.random.random((600, 400))

# Set up with ESOM rules
n_datapoints, n_features = data.shape
rows, columns = lattice_size(n_datapoints)

# Create a SOM object
# The high and low parameters should be chosen according to the dataset values
som = Som(
    rows,
    columns,
    n_features,
    low=data.min(),
    high=data.max(),
)

N_EPOCHS = 30

# Train the SOM for all epochs in a single call
som.train(data, N_EPOCHS, 0.8)

# Get the U-Matrix, shape (n_layers, rows, columns)
umx = som.umatrix

# Predict the best matching units and quantization errors for all data points
bmus, qe = som.predict(data)


# Using the GUI needs information to overlay on the datapoints
dataset = pd.DataFrame.from_dict(
    {"Type:": ["A"] * len(data)}
)

# Start the GUI
start_chisom_viewer(umx, bmus, dataset)
```

For instructions on how to train SOMs on large dataset using the [PyTorch DataLoader](https://docs.pytorch.org/docs/stable/data.html) interface, please refer to the [How-To Guides](https://kochgroup.github.io/ChI-SOM/how-to-guides/) section.

## Viewing a trained SOM from the command line

Once a U-Matrix and the BMUs have been saved to disk, the viewer can be opened directly, without writing a script:

```sh
chisom view -u umx.npy -b bmus.npy -d dataset.h5 --groups active --structure-column smiles
```

Every argument is optional — a bare `chisom view` opens an empty window and everything can be loaded from its _File_ menu instead. See [The Viewer](https://kochgroup.github.io/ChI-SOM/gui/) for the full set of options and what the interface can do.

## Caveats
- The _Viewer_ will only work on a systems with a display attached. When running the application on a server via a remote shell and calling `start_chisom_viewer` this will usually lead to errors (`"This application failed to start because no Qt platform plugin could be initialized"`). As solutions to this are very setup dependend, the recommended approach for very large SOMs is to only train the SOM on a powerful remote machine and analyse the trained SOM with the GUI locally.
- This software may be considered to be in beta stage. While the user-facing API is expected to remain stable up to a 2.0 release, the internal API might change at any release and can not be considered stable.  

The full list is documented under [Limitations](https://kochgroup.github.io/ChI-SOM/limitations/).

## Development Setup
ChI-SOM is developed, built, and packaged using [Astral uv](https://docs.astral.sh/uv/)

To set up a development environment initalize with
```sh
uv sync --group dev --extra gui
```  

To build run
```sh
uv build
```  

See the [installation guide](https://kochgroup.github.io/ChI-SOM/installation/#development-setup) for the CUDA variants and the full task list.


## Meta
Authors: Johannes Kaminski, Oliver Koch @ [AG Koch](https://www.uni-muenster.de/Chemie.pz/forschen/ag/koch/index.html)  
Contact: j.kaminski[at]uni-muenster.de

ChI-SOM is distributed under the LGPLv3. See LICENCES for more information.
