# compepigen/pyjacker architecture

> Architecture diagram of the GitHub repository compepigen/pyjacker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/compepigen/pyjacker
- Repository: https://github.com/compepigen/pyjacker

## Overview

##### Project type and purpose
- pyjacker is a Python‑based command‑line bioinformatics tool for detecting enhancer hijacking events in cancer cohorts.
- It ingests genomic data (WGS breakpoints, RNA‑seq expression, allele counts, CNAs, TADs, enhancers, fusions), applies statistical and proximity filters, and outputs interactive HTML reports.

##### File structure
- Top level:
- Dockerfile, LICENSE, README.md, pyproject.toml (packaging & deployment)
- config_AML.yaml (example config)
- data/ (input examples: TPM, breakpoints, GTFs, cytobands, TADs, ASE files, CNAs, enhancers, fusions)
- pyjacker/ (core Python package)
- Key modules under pyjacker/:
- ase.py – allele‑specific expression
- breakpoints.py – process and filter breakpoints
- cna.py – copy‑number correction
- genes.py – gene coordinate parsing & filtering
- outlier_expression.py – detect expression outliers
- html_reports.py – generate output reports
- pyjacker.py – orchestrator, CLI entrypoint

##### README for insights
- Config‑driven, single CLI: `pyjacker config.yaml`
- Optional inputs alter workflow branches (e.g., TAD filtering vs. fixed distance)
- Docker image available for environment encapsulation
- Integration with Nextflow workflow (external) to generate inputs from BAMs

a. Main components:
1. Configuration Layer (config.yaml, config_AML.yaml)
2. Data Sources (data/ folder: expression, breakpoints, GTF, cytobands, TADs, ASE counts, CNAs, enhancers, fusions)
3. Processing Modules (pyjacker/*.py):
– ASE detection
– Expression outlier detection
– Copy‑number correction
– Breakpoint annotation
– Gene coordinate filtering
4. Orchestration Engine (pyjacker.py)
5. Reporting Module (html_reports.py → HTML output)
6. Deployment Runtime (Python interpreter, Docker container)
7. External Workflow (Nextflow pipeline for input generation)
b. Relationships & interactions:
- Config file feeds parameters to the Orchestration Engine.
- Orchestration Engine calls each Processing Module in sequence or conditionally (depending on available inputs).
- Data flows from Data Sources through modules → combined in Orchestration → passed to Reporting Module → HTML output files.
- Deployment Runtime encapsulates the entire pipeline; optional Nextflow workflow sits upstream.
c. Architectural patterns & design principles:
- Modular “pipeline” pattern: each module has a single responsibility.
- Central orchestrator for sequential / conditional execution.
- Plugin‑style extensibility: optional data inputs trigger additional modules.
d. Technologies / frameworks / libraries:
- Python ≥3.7, pandas/numpy (implied)
- pip packaging (pyproject.toml)
- Docker for containerization
- Nextflow (external) for upstream input generation
- HTML templating for reports

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Nextflow
    Nextflow["Nextflow Pipeline"]:::external
    Nextflow -->|provides inputs| DataSources

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["config_AML.yaml"]:::config
    end

    %% Data Sources
    subgraph "Data Sources"
        ASEcounts["ASE counts"]:::data
        CNAs["Copy-number alterations"]:::data
        GTF37["GTF GRCh37"]:::data
        GTF38["GTF GRCh38"]:::data
        TAD1["TADs IMR90 hg19"]:::data
        TAD2["TADs IMR90 hg38"]:::data
        TAD3["TADs HSPC hg19"]:::data
        TPM["Expression (TPM)"]:::data
        BPs["Breakpoints"]:::data
        Cyt1["Cytobands hg19"]:::data
        Cyt2["Cytobands hg38"]:::data
        Enhancers["Enhancers"]:::data
        Fusions["Fusions"]:::data
    end
    Nextflow --> DataSources
    Config --> Orchestrator

    %% Processing Modules
    subgraph "Processing Modules"
        ASE["ASE Detection"]:::process
        Outlier["Expression Outlier Detection"]:::process
        CNAproc["Copy-Number Correction"]:::process
        BPproc["Breakpoint Processing & Filtering"]:::process
        Genes["Gene Coordinate Parsing & Filtering"]:::process
    end

    %% Orchestration
    subgraph "Orchestration Engine"
        Orchestrator["pyjacker (CLI)"]:::orchestration
    end

    %% Reporting Module
    subgraph "Reporting Module"
        Reporting["HTML Report Generation"]:::process
    end

    %% Deployment Runtime
    subgraph "Deployment Runtime"
        Docker["Docker Container"]:::deployment
        PythonPkg["Python Packaging"]:::deployment
    end

    %% Data flow
    DataSources -->|uses| ASE
    DataSources -->|uses| Outlier
    DataSources -->|uses| CNAproc
    DataSources -->|uses| BPproc
    DataSources -->|uses| Genes

    ASE -->|results| Orchestrator
    Outlier -->|results| Orchestrator
    CNAproc -->|results| Orchestrator
    BPproc -->|results| Orchestrator
    Genes -->|results| Orchestrator

    Orchestrator -->|aggregates| Reporting
    Reporting -->|outputs| HTML["Interactive HTML Reports"]:::data

    %% Deployment connections
    Docker -->|runs| Orchestrator
    PythonPkg -->|provides| Orchestrator

    %% Click events
    click Config "https://github.com/compepigen/pyjacker/blob/main/config_AML.yaml"
    click ASEcounts "https://github.com/compepigen/pyjacker/tree/main/data/ASE_ckAML/"
    click CNAs "https://github.com/compepigen/pyjacker/blob/main/data/CNAs_ckAML.tsv"
    click GTF37 "https://github.com/compepigen/pyjacker/blob/main/data/Homo_sapiens.GRCh37.75.gtf.gz"
    click GTF38 "https://github.com/compepigen/pyjacker/blob/main/data/Homo_sapiens.GRCh38.113.gtf.gz"
    click TAD1 "https://github.com/compepigen/pyjacker/blob/main/data/TADs_Dixon_IMR90_hg19.bed"
    click TAD2 "https://github.com/compepigen/pyjacker/blob/main/data/TADs_Dixon_IMR90_hg38.bed"
    click TAD3 "https://github.com/compepigen/pyjacker/blob/main/data/TADs_HSPC_hg19.bed"
    click TPM "https://github.com/compepigen/pyjacker/blob/main/data/TPM_ckAML.tsv"
    click BPs "https://github.com/compepigen/pyjacker/blob/main/data/breakpoints_ckAML.tsv"
    click Cyt1 "https://github.com/compepigen/pyjacker/blob/main/data/cytobands_hg19.tsv"
    click Cyt2 "https://github.com/compepigen/pyjacker/blob/main/data/cytobands_hg38.tsv"
    click Enhancers "https://github.com/compepigen/pyjacker/blob/main/data/enhancers_myeloid_hg19.tsv"
    click Fusions "https://github.com/compepigen/pyjacker/blob/main/data/fusions_ckAML.tsv"
    click ASE "https://github.com/compepigen/pyjacker/blob/main/pyjacker/ase.py"
    click Outlier "https://github.com/compepigen/pyjacker/blob/main/pyjacker/outlier_expression.py"
    click CNAproc "https://github.com/compepigen/pyjacker/blob/main/pyjacker/cna.py"
    click BPproc "https://github.com/compepigen/pyjacker/blob/main/pyjacker/breakpoints.py"
    click Genes "https://github.com/compepigen/pyjacker/blob/main/pyjacker/genes.py"
    click Orchestrator "https://github.com/compepigen/pyjacker/blob/main/pyjacker/pyjacker.py"
    click Reporting "https://github.com/compepigen/pyjacker/blob/main/pyjacker/html_reports.py"
    click Docker "https://github.com/compepigen/pyjacker/tree/main/Dockerfile"
    click PythonPkg "https://github.com/compepigen/pyjacker/blob/main/pyproject.toml"

    %% Styles
    classDef config fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef data fill:#D0F0C0,stroke:#333,stroke-width:1px
    classDef process fill:#C2E0FF,stroke:#333,stroke-width:1px
    classDef orchestration fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef deployment fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    class ASEcounts,CNAs,GTF37,GTF38,TAD1,TAD2,TAD3,TPM,BPs,Cyt1,Cyt2,Enhancers,Fusions data
    class ASE,Outlier,CNAproc,BPproc,Genes,Reporting process
    class Config config
    class Orchestrator orchestration
    class Docker,PythonPkg deployment
    class Nextflow external
```
