Metadata-Version: 2.4
Name: sisal
Version: 0.1.0
Summary: Beta-variational autoencoder for IMS (and other) data.
Author-email: Paul-Louis Delacour <delacourpaullouis@gmail.com>
License: BSD 3-Clause License
Project-URL: homepage, https://github.com/pauldelacour/sisal
Project-URL: repository, https://github.com/pauldelacour/sisal
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: numba
Requires-Dist: matplotlib
Requires-Dist: torch
Requires-Dist: imageio
Requires-Dist: cmasher
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: tqdm
Provides-Extra: demo
Requires-Dist: h5py; extra == "demo"
Requires-Dist: jupyterlab; extra == "demo"
Requires-Dist: pooch; extra == "demo"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: dev
Requires-Dist: ipython; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pdbpp; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: rich; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: check-manifest; extra == "dev"
Requires-Dist: sisal[test]; extra == "dev"
Dynamic: license-file

# sisal

[![License](https://img.shields.io/pypi/l/sisal.svg?color=green)](https://github.com/vandeplaslab/sisal/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/sisal.svg?color=green)](https://pypi.org/project/sisal)
[![Python Version](https://img.shields.io/pypi/pyversions/sisal.svg?color=green)](https://python.org)
[![CI](https://github.com/vandeplaslab/sisal/actions/workflows/ci.yml/badge.svg)](https://github.com/vandeplaslab/sisal/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/vandeplaslab/sisal/branch/main/graph/badge.svg)](https://codecov.io/gh/vandeplaslab/sisal)

The SiSAL package is an approach based on the beta-variational autoencoder and kernel density estimation
to dissect data along independent, uncertainty-aware, and interpretable (yet non-linear) latent axes. 
It includes a novel comparative-latent-traversal algorithm to
translate latent findings back into the original measurement context. 
You can find demonstrations in the /experiments folder. 
It includes an imaging mass spectrometry-based molecular imaging of human kidney and a synthetic dataset. 
The approach’s disentangling properties are shown to impose a latent space structure
that separates signal strength from relative signal content, offering exceptional
chemical insight. 

## Installing

You can install sisal from PyPI:

```bash
pip install sisal
```

or directly from source:

```bash
git clone https://github.com/vandeplaslab/sisal.git

pip install "."
```

## Examples

If you are planning on running the examples, you can install the optional dependencies with:

```bash
pip install sisal[demo]
```

This will include additional packages such as `jupyterlab` and `pooch` to download data from Zenodo.

You can find the example data on [Zenodo](https://zenodo.org/records/17910325).

## Contributing

Contributions are always welcome. Please feel free to submit PRs with new features, bug fixes, or documentation improvements.

```bash
git clone https://github.com/vandeplaslab/sisal.git

pip install -e .[dev]
```


## Figures

### Kidney imaging mass spectrometry datasets
<table>
  <tr>
    <td align="center" style="padding: 15px;">
      <img src="images/kde-and-masks.png" width="300"><br>
      <em><strong>Figure 1:</strong> Kernel density estimation of the latent space generated by the SiSAL approach together with the associated masks.</em>
    </td>
    <td align="center" style="padding: 15px;">
      <img src="images/traversal-kidney.png" width="300"><br>
      <em><strong>Figure 2 (latent traversal):</strong> Traversal example between the two highlighted regions.</em>
    </td>
    <td align="center" style="padding: 15px;">
      <img src="images/traversal-kidney-importance.png" width="300"><br>
      <em><strong>Figure 3 (feature differentiators):</strong> The traversal algorithm extracts the most important molecular features between the two regions.</em>
    </td>
  </tr>
</table>
