Metadata-Version: 2.4
Name: poseigen_oyster
Version: 2.0.0
Summary: The basics for Poseigen software
Author-email: Husam Abdulnabi <husam.abdulnabi@gmail.com>
Maintainer-email: Husam Abdulnabi <husam.abdulnabi@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/husam94/poseigen_oyster
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: torch
Requires-Dist: poseigen_seaside
Requires-Dist: poseigen_trident
Requires-Dist: poseigen_chisel
Requires-Dist: scikit-learn
Requires-Dist: kneed
Dynamic: license-file

# Oyster

Oyster is a glass-box neural network for genomic sequence-to-function modeling. It learns the effects of k-mer composition and position while intentionally excluding k-mer associations (interactions among k-mers). The position-specific k-mer contributions can be read directly from the learned model weights.

See the paper: [Oyster: A Neural Network for Modeling Genomic Sequences with Exact Position-Specific k-mer Contributions](https://www.biorxiv.org/content/10.1101/2025.11.01.686014v2.full). The paper compares Oyster with models that learn k-mer associations. Those models can achieve better predictive performance, while Oyster predictions remain in strong agreement and can serve as interpretable proxies.

## Installation

Requires Python 3.12 or newer. Install from PyPI with:

```bash
python -m pip install poseigen_oyster
```

## Package

- **`model`** provides `Oyster` and `Dual_Oyster`. `Dual_Oyster` combines two Oyster models, allowing each branch to use different inputs, k-mer sizes, position-pooling settings, and chunking.
- **`analysis`** provides tools for inspecting Oyster models, including sequence and k-mer contributions, PWM-derived contributions, clustering, and cluster refinement.
- `Oyster_BaseDict` and `Dual_Oyster_BaseDict` define hyperparameter search spaces for `Oyster` and `Dual_Oyster` to use with [poseigen_compass](https://github.com/Husam94/poseigen_compass).
- Oyster is built using [poseigen_trident](https://github.com/Husam94/poseigen_trident).

## Case studies

Oyster has been exemplified in the following case studies:

- **Protein-DNA interactions**
  - [CTCF case study](https://github.com/Husam94/CS-CTCF)
  - [YY1 case study](https://github.com/Husam94/CS-YY1)
- **Enhancer activity**
  - [Enhancer activity case study](https://github.com/Husam94/CS-EnhAct)
