Metadata-Version: 2.1
Name: scmkl
Version: 0.5.1
Summary: Single-cell analysis using Multiple Kernel Learning
Home-page: https://github.com/ohsu-cedar-comp-hub/scMKL/tree/main
Author: Sam Kupp, Ian VanGordon, Cigdem Ak
Author-email: kupp@ohsu.edu, vangordi@ohsu.edu, ak@ohsu.edu
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11.1,<=3.13.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wheel
Requires-Dist: anndata
Requires-Dist: celer
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: numba
Requires-Dist: plotnine
Requires-Dist: matplotlib
Requires-Dist: scanpy
Requires-Dist: umap-learn
Requires-Dist: muon
Requires-Dist: gseapy

<h1 align="center">
<img src="https://github.com/ohsu-cedar-comp-hub/scMKL/blob/main/scMKL_logo.png?raw=true" width="500"/>
</h1><br>


![PyPI](https://img.shields.io/pypi/v/scmkl?label=pypi%20package)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/scmkl?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/scmkl)
[![Anaconda-Server Badge](https://anaconda.org/ivango17/scmkl/badges/version.svg?style=flat&cache-control=no-cache)](https://anaconda.org/ivango17/scmkl)
[![Anaconda-Server Badge](https://anaconda.org/ivango17/scmkl/badges/downloads.svg?style=flat&cache-control=no-cache)](https://anaconda.org/ivango17/scmkl)
[![Anaconda-Server Badge](https://anaconda.org/ivango17/scmkl/badges/latest_release_date.svg?style=flat&cache-control=no-cache)](https://anaconda.org/ivango17/scmkl)


Single-cell analysis using Multiple Kernel Learning, scMKL, is a binary 
classification algorithm utilizing prior information to group features to 
enhance classification and aid understanding of distinguishing features in 
omic and multi-omic data sets.

We have demonstrated scMKL's ability to achieve high classification 
performance while providing the added confidence of model interpretability on 
single-cell RNA, ATAC, ADT, and methylation data.


## Installation

### Conda install

Conda is the recommended method to install scMKL and Python version must be 
`'>=3.11.1,<=3.13'`:

```bash
conda create -n scmkl_env -c conda-forge -c bioconda ivango17::scmkl
```
Ensure bioconda and conda-forge are in your available conda channels.


### Pip install

First, create a virtual environment with `'python>=3.11.1,<=3.13'`.

Then, install scMKL with:
```bash
# activate your new env with python>=3.11.1 and <3.14
pip install scmkl
```

If wheels do not build correctly, ensure ```gcc``` and ```g++``` are installed 
and up to date. They can be installed with ```sudo apt install gcc``` and 
```sudo apt install g++```.


## Usage

The table below shows what type of data scMKL expects based on the modality in 
question. In all situations, matrices should be cells x features.

| Modality | Input matrix description |
| -------- | ----------------- |
| Transcriptomics (RNA) | Counts matrix |
| Chromatin  Accessibility (ATAC) | Binarized counts matrix (any counts more than 0 become 1) |
| Epitope (ADT) | Counts matrix |
| Methylomics (MET) | Aggregated methylation over windows (e.g. mean methylation per genomics window) |

Additionally, scMKL requires a feature grouping dictionary where each key, 
value pair is represented as `'group1': ['feature1', 'feature2', 'feature7']`. 
Features can be genes for RNA, regions for ATAC and MET, or proteins for ADT. 
Any number of groups can be used and features can be overlapping between 
groups (e.g. `'feature1'` is in five groups). For help getting feature 
groupings, see our notebooks in [examples](./example/). 

scMKL implements `AnnData.anndata` objects in one of two ways:

1) Taking an existing `AnnData.anndata` object and formatting it for scMKL to 
train and test on. 

```python
import scmkl
import numpy as np
import anndata as ad

# Read in your AnnData.anndata obj
adata = ad.read_h5ad('your_adata.h5ad')

# Read in feature grouping dictionary (e.g. geneset library for RNA)
group_dict = np.load('your_grouping.pkl', allow_pickle=True)
# or for RNA, pull a gene set from the internet with 
group_dict = scmkl.get_gene_groupings('Azimuth_2021', organism='human')

# Apply scmkl formatting where 'phenotype_obs_key' is the col name in obs 
# for labels, can also be an array of labels and set `allow_multiclass` to 
# true if there are more than two cell classes 
adata = scmkl.format_adata(
    adata, 
    cell_labels='phenotype_obs_key', 
    group_dict=group_dict,
    allow_multiclass=True
    )
```


2) Reading in data separately and creating an scMKL formatted 
`AnnData.anndata` object.

```python
import scmkl
import numpy as np

# Read in feature names
var_names = np.load('your_feature_names.npy')

# Read in feature grouping dictionary (e.g. geneset library for RNA)
group_dict = np.load('your_grouping.pkl', allow_pickle=True)
# or for RNA, pull a gene set from the internet with
group_dict = scmkl.get_gene_groupings('Azimuth_2021', organism='human')

# Read in cell labels
obs = np.load('your_cell_labels.npy')

# Read in data matrix (can also be a scipy.sparse matrix)
mat = np.load('your_matrix.npy')

# Create scMKL formatted AnnData.anndata and set `allow_multiclass` to true 
# if there are more than two cell classes 
adata = scmkl.create_adata(
    data_mat, 
    feature_names=gene_names, 
    group_dict=group_dict,
    allow_multiclass=True
    )
```

If you are not using RNA data and do not have a grouping dictionary but want 
to try scMKL on your dataset, you can create a random grouping with:

```python
# Assuming feature names and numpy are loaded
n_groups = 50
group_size = 25
grouping_dict = {f'group_{i}': np.random.choice(
                                   var_names, 
                                   size=group_size, 
                                   replace=False
                                   ) 
                    for i in range(n_groups)}
```

Then, depending on whether or not your labels are binary, train and test your 
model.

For binary:

```python 
results = scmkl.run(adata)
```

For multiclass:

```python
results = scmkl.one_v_rest(
    adata, 
    names=['RNA']
    )
```

Both of these functions return a dictionary with evaluation metrics, group 
weights, etc... To learn more about accessing this data, see our 
[GitHub Pages](https://ohsu-cedar-comp-hub.github.io/scMKL/).


## Links

Repo: [https://github.com/ohsu-cedar-comp-hub/scMKL](https://github.com/ohsu-cedar-comp-hub/scMKL)

PyPI: [https://pypi.org/project/scmkl/](https://pypi.org/project/scmkl/)

Anaconda: [https://anaconda.org/ivango17/scmkl](https://anaconda.org/ivango17/scmkl)

API: [https://ohsu-cedar-comp-hub.github.io/scMKL/](https://ohsu-cedar-comp-hub.github.io/scMKL/)


## Publication

If you use scMKL in your research, please cite using:

> Kupp, S., VanGordon, I., Gönen, M., Esener, S.,  Eksi, S., Ak, C. 
Interpretable and integrative analysis of single-cell multiomics with scMKL. *Commun Biol* **8**, 1160 (2025). 
https://doi.org/10.1038/s42003-025-08533-7

Our Shiny for Python application for viewing data produced from this work can 
be found here: 
[scMKL_analysis](https://huggingface.co/spaces/scMKL-team/scMKL_analysis)


## Issues

Please report bugs [here](https://github.com/ohsu-cedar-comp-hub/scMKL/issues). 
