cnnamon 0.2.1

CNNAMON is a modular Python framework for building, training, and interpreting 1D Convolutional Neural Networks (CNNs) for DNA sequence analysis. It integrates data preparation, model construction, and rich explainability tools in a unified and flexible system tailored for genomics research.

CNNAMON

Convolutional Neural Network Analysis & Motif Discovery

A modular, interpretability-first framework for deep learning in genomics.

---

🧠 Overview

CNNAMON is a Python framework designed to bridge the gap between training high-performance
1D Convolutional Neural Networks (CNNs) on DNA sequences and understanding what they learn.

It provides an end-to-end ecosystem for:

1. Dataset Preparation – Converting genomic intervals (BED3 + labels) to one-hot tensors
2. Modeling – Building complex Keras models via simple JSON configuration files
3. Explainability – Extracting learned motifs, clustering filters by activation profiles, assessing filter importance, and associating filters with prediction classes

---

⚡ Key Features

Module	Functionality
🧬 PrepareData	Extract sequences from FASTA/BED files. Supports random, chromosome, or custom splits, and reverse-complement augmentation.
🏗 KerasBuilder	Define model architectures, optimizers, and callbacks using JSON for reproducible experiments.
🎨 FilterVisualize	Extract learned motifs using Top-Activating, Consensus, or Significant (permutation-based) strategies. Export to MEME for TOMTOM validation.
📉 FilterImportance	Rank filters by their contribution to model loss using perturbation analysis.
🌳 FilterClustering	Group redundant or co-activated filters with hierarchical clustering and visualize relationships using circular dendrograms.
🧪 Enrichment	Identify filters statistically enriched for prediction classes (e.g., Enhancer vs. Silencer).

---

📦 Installation

We recommend installing CNNAMON in a fresh environment to manage dependencies (TensorFlow, BedTools).

# 1. Create environment
conda create -n cnnamon_env python=3.10
conda activate cnnamon_env

# 2. Install CNNAMON
pip install cnnamon

# 3. Install BedTools (required for sequence extraction)
conda install -c bioconda bedtools

---

🚀 Quick Start

Train a model and visualize motifs in four steps:

import cnnamon as cn

# 1. Prepare data
preparer = cn.utility.PrepareData(
    intervalfile="peaks.bed", 
    genomefasta="hg38.fa", 
    outdir="data/",
    split_segmentation="random"
)
train, test, val = preparer.run()

# 2. Train model (from JSON config)
model = cn.utility.KerasModelBuilder.from_json("model_config.json")
model.train(train['x'], train['y'], val['x'], val['y'])

# 3. Extract significant motifs
motifs = cn.CNN1D.FilterVisualize.significant_activating(
    model, 
    data=test, 
    n_perturbations=1000,
    q_value_cutoff=0.05,
    n_cores=10
)

# 4. Plot sequence logos
motifs.to_motifs(savefig="learned_motifs.png")

---

📖 Documentation

Full documentation is available here:
👉 https://georgakilaslab.github.io/CNNAMON/

---

📚 Citation

If you use CNNAMON in your research, please cite:

(Add paper reference / DOI here when available)

---

_{Built by the Georgakilas Lab.}