Metadata-Version: 2.4
Name: gelada
Version: 0.1.1
Summary: Calls microcompartments across the genome from a chromatin loops file.
Author-email: Defne Ceyhan <ceyhan@mit.edu>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: igraph


<div align="left">
  <br>
  <img src="https://raw.githubusercontent.com/defne8/gelada/main/gelada_logo.svg" alt="GELADA Logo" width="600">
  <br>
</div>

**GELADA** (graph-based election via leiden clustering and degree averaging) identifies microcompartments (fine-scale, focal, and highly nested 3D interactions) across the genome from a table of pairwise chromatin loops/interactions. GELADA constructs a genome-wide graph network where anchors are nodes and loops are edges, Leiden clusters within connected components, and calculates the average degree of each cluster. Clusters are then thresholded by average degree to select microcompartments.

<div align="center">
  <img src="https://raw.githubusercontent.com/defne8/gelada/main/gelada_method_diagram.png" alt="GELADA Method" width="100%">
</div>

## Installation

```bash
pip install gelada
```

## Usage

GELADA requires a CSV/TSV, where each row describes the genomic coordinates of a pairwise chromatin interaction/loop, containing the following columns: `chr1`, `start1`, `end1`, `chr2`, `start2`, and `end2`.

```bash
gelada -i loops.txt -o microcomp_calls/ --prefix my_sample --edge-cols pair
```

### Arguments

| Argument | Description | Default |
| :--- | :--- | :--- |
| `-i`, `--input` | **(Required)** Path to the input pairwise interactions/loops file. | |
| `-o`, `--output-dir` | **(Required)** Path to output directory. | |
| `--prefix` | Output prefix. | *Input filename stem* |
| `--sep` | Input file delimiter (e.g., `\t`, `,`). | *Auto-detect* |
| `--edge-cols` | Comma-separated list of column names to make loop-level (edge) annotations. | |
| `--degree-cutoff` | Threshold a cluster's average degree must exceed to be called a microcompartment. | `2.0` |
| `--leiden-resolution` | Leiden resolution parameter for clustering within connected components. | `0.5` |
| `--[no-]normalize-anchor-sizes` | Map larger anchors to contained smaller anchors where possible. | `True` |

### Input file format
If your file contains extra annotation columns, GELADA infers their context based on their position in the file:
* **Anchor 1 Annotations:** Columns between `end1` and `chr2`.
* **Anchor 2 Annotations:** Columns after `end2` (unless explicitly flagged in `--edge-cols`).

## Outputs

GELADA generates three files in your designated output directory:

1. **`{prefix}_microcomp_anchors.csv`**
   Contain all unique anchors within microcompartments genome-wide, their anchor annotations, their assigned microcompartment's ID (`microcomp_index`), and their assigned microcompartment cluster's average degree.
   
2. **`{prefix}_microcomp_loops.csv`**
   Contains all network edges (loops) within microcompartment clusters, the annotations associated with their anchors, any loop-level annotations (your designated `--edge-cols`), their assigned microcompartment's ID (`microcomp_index`), and their assigned microcompartment cluster's average degree.
   
3. **`{prefix}_microcomp_summary.csv`**
   Contains all microcompartment IDs, their number of contained nodes and edges, and their average degree.
