Metadata-Version: 2.1
Name: deconomix
Version: 1.0.2
Summary: Provides methods for cellular composition, hidden background and gene regulation estimation of omics bulk mixtures.
Author: Malte Mensching-Buhr, Thomas Sterr, Nicole Seifert, Dennis Voelkl, Jana Tauschke, Austin Rayford, Helena U. Zacharias, Sushma Nagaraja Grellscheid, Tim Beissbarth,  Franziska Goertler, Michael Altenbuchinger
Author-email: michael.altenbuchinger@bioinf.med.uni-goettingen.de
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.5.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: scikit-learn
Requires-Dist: qpsolvers>=4.3.2
Requires-Dist: qpsolvers[quadprog]
Requires-Dist: qpsolvers[scs]
Requires-Dist: qpsolvers[clarabel]
Requires-Dist: matplotlib
Requires-Dist: pandas>=2.2.2
Requires-Dist: pyarrow
Requires-Dist: seaborn
Requires-Dist: scipy
Requires-Dist: tqdm>=4.66.4
Requires-Dist: ipywidgets

# Deconomix

## Overview

Deconomix is a Python library aimed at the bioinformatics community, offering methods to estimate cell type compositions, hidden background contributions and gene regulation factors of bulk RNA mixtures. Visit the documentation [here](https://medbioinf.pages.gwdg.de/MedicalDataScience/Deconomix/Deconomix/).

## Features

- **Data Simulation**: Generate artificial bulk mixtures from single-cell data in an efficient way to provide training data for your models.

- **Gene Weighting**: Learn gene weights from artifical bulk mixtures to optimize the cellular composition estimation of real bulk RNA mixtures.

- **Cellular Composition**: Estimate the cellular composition of your bulk RNA profiles or Spatial Transcriptomics spots.

- **Background Estimation**: Refine the composition estimation by estimate a hidden background contribution and profile, which cannot be explained by the cell types featured in the reference.

- **Gene Regulation**: Find out, how cell types in your bulk data is regulated in relation to your reference profiles, for instance in a disease context.

- **Visualization**: Visualize your results with predefined functions.

- **Evaluation**: Perform basic enrichment analysis for the estimated gene regulatory factors.

## Updates
This package will eventually be updated with our recent developments. The version provided for the biorXiv preprint is tagged accordingly. The version at first submission will be tagged and released as version 1.0.0. 

## Installation

Deconomix is added to the official PyPI repositories and can be installed from there directly:

```
pip install deconomix
```

Alternatively, this git repository can be cloned to install the latest version:

```
pip install git+https://gitlab.gwdg.de/MedBioinf/MedicalDataScience/Deconomix/Deconomix
```

Deconomix does not utilize GPUs -- to keep your installation lightweight, you can install a cpu-only torch version beforehand (180MB vs 3GB size)

```bash
pip install torch --index-url https://download.pytorch.org/whl/cpu
```
## Getting Started

Upon successful installation, users are encouraged to explore the curated examples provided in this repository. The `examples` directory contains Jupyter notebooks showcasing various example workflows. Start out with `Getting_started.ipynb` to get an introduction on how you can apply Deconomix models in the simplest way with the package. Continue with `Hyperparameter_Gridsearch.ipynb` to learn how to conduct a hyperparameter search for our advanced models. In `Plots_for_Tech_Note.ipynb` you can find some visualizations which are featured in the overview figure for the article.

## Advanced Users

If you want to build a custom deconvolution pipeline with out package from scratch, you can take a look at `Advanced_Workflow.ipynb`. Get a full overview of the available functions from the [documentation](https://medbioinf.pages.gwdg.de/MedicalDataScience/Deconomix/Deconomix/). Check out the [breast cancer case study](https://gitlab.gwdg.de/MedBioinf/MedicalDataScience/Deconomix/Deconomix-case-study) from the article as well. If further questions arise, do not hesitate to contact us!


## GUI Application

For easier usage, we also distribute a graphical user interface for our package, available for all common operating systems. It is an application built with Dash/Plotly and can be ran locally or on a webserver.
Check out the corresponding repository of [Deconomix GUI](https://gitlab.gwdg.de/MedBioinf/MedicalDataScience/Deconomix/Deconomix-gui).

## For Developers
For feature requests and bug reports do not hesitate to contact us via an issue or email.

If you want to generate or update the html documentation yourself, follow these steps:

Install `sphinx` and `sphinx-rtd-theme`:

```
pip install sphinx
pip install sphinx-rtd-theme
```

Then move into the `docs` directory and execute the make command:
```
make html
```
