Metadata-Version: 2.4
Name: autoencodix
Version: 0.2.2
Summary: Framework for multi-omics data integration by autoencoders.
Project-URL: Homepage, https://github.com/jan-forest/autoencodix_package
Project-URL: Issues, https://github.com/jan-forest/autoencodix_package/issues
Author-email: Maximilian Joas & Jan Ewald <jan.ewald@uni-leipzig.de>
License-Expression: Apache-2.0
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.13,>=3.9
Requires-Dist: anndata==0.10.8
Requires-Dist: captum==0.7.0
Requires-Dist: dill>=0.4.0
Requires-Dist: ipykernel>=6.29.5
Requires-Dist: ipywidgets>=8.1.7
Requires-Dist: lightning-fabric>=2.5.0.post0
Requires-Dist: llvmlite>=0.43.0
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: mistralai>=1.9.11
Requires-Dist: mkdocs-material>=9.6.19
Requires-Dist: mkdocstrings[python]>=0.30.0
Requires-Dist: mudata==0.2.4
Requires-Dist: numba>=0.60.0
Requires-Dist: numpy>=2.0.2
Requires-Dist: ollama>=0.6.1
Requires-Dist: openai==2.31.0
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: pandas-stubs>=2.2.2.240807
Requires-Dist: pandas>=2.2.3
Requires-Dist: pyarrow>=19.0.1
Requires-Dist: pydantic>=2.10.6
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: scanpy>=1.10.3
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: scipy>=1.13.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: tensorboard-plugin-profile==2.20.1
Requires-Dist: tensorboard>=2.20.0
Requires-Dist: torch<2.4.0,>=2.1.0
Requires-Dist: umap-learn>=0.5.7
Description-Content-Type: text/markdown

# AUTOENCODIX
Autoencoders are deep-learning-based networks for dimension reduction and embedding by a combination of a compressing encoder and decoder structure for non-linear and multi-modal data integration, with promising applications to complex biological data from large-scale omics measurements. Current ongoing research and publications provide many exciting architectures and implementations of autoencoders. However, there is a lack of easy-to-use and unified implementations covering the whole pipeline of autoencoder applications.
Consequently, we present `AUTOENCODIX` with the following features:
- Multi-modal data integration for any numerical or categorical data
- Different autoencoder architectures:
  - vanilla `vanillix`
  - variational `varix`
  - disentangled variational `disentanglix`
  - hierarchical/stacked `stackix`
  - ontology-based `ontix`
  - masking `maskix`
  - Image VAE (2D) `imagix`
  - cross-modal autoencoder (translation between different data modalities) `x-modalix` (works for multiple modalities paired and unpaired)
- A Python package with a scikit-learn-like interface

## Requirements
- Python>=3.8 <3.13
- uv or another package manager (we recommend uv)
- git or gh
## Installation
- `gh repo clone jan-forest/autoencodix_package`
- `cd autoencodix_package`
- `uv venv --python 3.10`
- `source .venv/bin/activate`
- `uv sync`

## Sample Usage
```python
import autoencodix as acx
from autoencodix.data.datapackage import DataPackage
from autoencodix.configs.vanillix_config import VanillixConfig
from autoencodix.configs.default_config import DataCase

# If your data is stored in pandas DataFrames, you can easily pass them to our custom DataPackage.
# For any tabular data that is not single-cell, provide it as a dictionary to the "multi_bulk" attribute of DataPackage.
# Note: "multi" might be misleading — it's valid to provide just one modality (1–n data modalities).
# Here, we assume paired metadata. If you have separate metadata for each modality, use the same dict keys as in multi_bulk, e.g.:
# annotation = {"rna": rna_annotation, "protein": protein_annotation}
my_datapackage: DataPackage = DataPackage(
    multi_bulk={"rna": raw_rna, "protein": raw_protein},
    annotation={"paired": annotation},
)

myconfig: VanillixConfig = VanillixConfig(data_case=DataCase.MULTI_BULK, epochs=30, device="cpu")
vanillix = acx.Vanillix(data=my_datapackage, config=myconfig)
result = vanillix.run()
```

## Getting Started
We provide extensive tutorials for all of our use cases. The best place to start is the `Vanillix Tutorial`. Here, we explain the design and features of our pipeline, which applies to other pipelines. From there, you can explore the tutorials for the more specialized architectures (`Varix`, `Ontix`, etc). We also provide tutorials for each pipeline, but the `Vanillix Tutorial` explains the general concepts, while the other tutorials go into the specifics of the corresponding pipeline. For even more details on extra functionality, such as visualizing or customizing we provide deep dive tutorials for these topics. You can find the tutorials here:

- Best to get started: [Vanillix Tutorial](https://github.com/jan-forest/autoencodix_package/blob/main/Tutorials/PipelineTutorials/Vanillix.ipynb)
- Tutorials for each specific pipeline (more advanced, do Vanillix first): [Pipeline Tutorials](https://github.com/jan-forest/autoencodix_package/tree/main/Tutorials/PipelineTutorials)
- Tutorials for specific extra functionality, see [Deep Dives](https://github.com/jan-forest/autoencodix_package/tree/main/Tutorials/DeepDives)
## Contributing
Whether you have a feature request, found a bug, or have any other idea, we're always happy. For more details, refer to our [Guide](https://github.com/jan-forest/autoencodix_package/blob/main/DEVELOPER.md)

## Read The Docs
You can find our documentation [here](https://jan-forest.github.io/autoencodix_package/).

## FAQ

### Reproducibility and CUBLAS_WORKSPACE_CONFIG
If you run for reproducibility with `FIX_RANDOMNESS: "all"` and you receive the following error:
```
RuntimeError: Deterministic behavior was enabled with either `torch.use_deterministic_algorithms(True)` or `at::Context::setDeterministicAlgorithms(true)`, but this operation is not deterministic because it uses CuBLAS and you have CUDA >= 10.2. 
```
You need to run the following in your terminal before running our pipeline: 
```
export CUBLAS_WORKSPACE_CONFIG=:16:8
```


## Cite

While we are working on a new publication of the Python package version, we are referring to our previous publication in [Nature Computational Science](https://doi.org/10.1038/s43588-025-00916-4) 

Please, use this to cite our work when using our framework: 

```
@article{joas2025autoencodix,
  title={AUTOENCODIX: a generalized and versatile framework to train and evaluate autoencoders for biological representation learning and beyond},
  author={Joas, Maximilian Josef and Jurenaite, Neringa and Pra{\v{s}}{\v{c}}evi{\'c}, Du{\v{s}}an and Scherf, Nico and Ewald, Jan},
  journal={Nature Computational Science},
  pages={1--13},
  year={2025},
  doi={}
  publisher={Nature Publishing Group US New York}
}
```

## License

Copyright [2026] [Maximilian Josef Joas & Jan Ewald, ScaDS.AI, Leipzig University]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0