# lorenzoorsini3/cpg-island-predictor architecture

> Architecture diagram of the GitHub repository lorenzoorsini3/cpg-island-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lorenzoorsini3/cpg-island-predictor
- Repository: https://github.com/lorenzoorsini3/cpg-island-predictor

## Overview

CIP predicts CpG islands from FASTA sequences through either a command-line or Tkinter interface. The core workflow reads and filters sequences, extracts mono-, di-, and trinucleotide features, runs ONNX inference, reports predictions, and writes CSV output with optional BED/GFF3 files. Metadata describes model compatibility and provenance. The README documents the stacked ensemble and position-independent design; excerpts support the feature, inference, and output stages. Some internal details and CLI startup flow were not sampled, so uncertain links are omitted.

Main entry points: [`CIP.py`](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py) (Prediction orchestration), [`gui.py`](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/gui.py) (Tkinter GUI), [`modules/logger.py`](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/logger.py) (Session logging), [`modules/features_extractor.py`](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/features_extractor.py) (K-mer features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI entry<br/>[CIP.py]"]
  node_gui["Tkinter GUI<br/>[gui.py]"]
end

subgraph group_prediction["Prediction workflow"]
  node_pipeline["Prediction orchestration<br/>[CIP.py]"]
  node_sequence_read["Sequence reading<br/>[CIP.py]"]
  node_sequence_filter["Sequence validation<br/>[CIP.py]"]
  node_features["K-mer features"]
  node_inference["ONNX inference<br/>[CIP.py]"]
  node_classification["Island predictions<br/>[CIP.py]"]
  node_output["Result files<br/>[CIP.py]"]
end

subgraph group_assets["Model and metadata"]
  node_model["Trained ensemble<br/>[model.onnx]"]
  node_metadata["Model metadata<br/>[metadata.json]"]
end

subgraph group_operations["Logging and errors"]
  node_errors["Error handling"]
  node_logger["Session logging<br/>[logger.py]"]
  node_archive["Log archiving<br/>[logger.py]"]
end

node_user(("Analyst"))
node_fasta["FASTA input"]

node_user -->|"runs"| node_cli
node_user -->|"opens"| node_gui
node_fasta -->|"supplies sequences"| node_pipeline
node_cli -->|"runs"| node_pipeline
node_gui -->|"calls predictor"| node_pipeline
node_pipeline -->|"reads FASTA"| node_sequence_read
node_pipeline -->|"validates sequences"| node_sequence_filter
node_pipeline -->|"extracts features"| node_features
node_pipeline -->|"runs batches"| node_inference
node_inference -->|"runs model"| node_model
node_pipeline -->|"produces predictions"| node_classification
node_pipeline -->|"writes results"| node_output
node_pipeline -->|"loads metadata"| node_metadata
node_pipeline -->|"formats errors"| node_errors
node_pipeline -->|"logs activity"| node_logger
node_logger -->|"archives logs"| node_archive

click node_cli "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_gui "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/gui.py"
click node_pipeline "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_sequence_read "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_sequence_filter "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_features "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/features_extractor.py"
click node_inference "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_classification "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_output "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py"
click node_model "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/config/model.onnx"
click node_metadata "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/config/metadata.json"
click node_errors "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/exception_handler.py"
click node_logger "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/logger.py"
click node_archive "https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/logger.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_gui toneBlue
class node_pipeline,node_sequence_read,node_sequence_filter,node_features,node_inference,node_classification,node_output toneAmber
class node_model,node_metadata toneMint
class node_errors,node_logger,node_archive toneRose
class node_user,node_fasta toneIndigo
```

## Components

### User interfaces

- [CLI entry](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`
- [Tkinter GUI](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/gui.py): `gui.py`

### Prediction workflow

- [Prediction orchestration](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`
- [Sequence reading](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`
- [Sequence validation](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`
- [K-mer features](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/features_extractor.py): `modules/features_extractor.py`
- [ONNX inference](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`
- [Island predictions](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`
- [Result files](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/CIP.py): `CIP.py`

### Model and metadata

- [Trained ensemble](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/config/model.onnx): `config/model.onnx`
- [Model metadata](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/config/metadata.json): `config/metadata.json`

### Logging and errors

- [Error handling](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/exception_handler.py): `modules/exception_handler.py`
- [Session logging](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/logger.py): `modules/logger.py`
- [Log archiving](https://github.com/lorenzoorsini3/cpg-island-predictor/blob/main/modules/logger.py): `modules/logger.py`

### Other components

- **Analyst**
- **FASTA input**

## Connections

- Analyst → CLI entry: runs (evidence: `README.md`)
- Analyst → Tkinter GUI: opens (evidence: `README.md`)
- FASTA input → Prediction orchestration: supplies sequences (evidence: `README.md`)
- CLI entry → Prediction orchestration: runs (evidence: `README.md`)
- Tkinter GUI → Prediction orchestration: calls predictor (evidence: `gui.py`)
- Prediction orchestration → Sequence reading: reads FASTA (evidence: `CIP.py`)
- Prediction orchestration → Sequence validation: validates sequences (evidence: `CIP.py`)
- Prediction orchestration → K-mer features: extracts features (evidence: `CIP.py`)
- Prediction orchestration → ONNX inference: runs batches (evidence: `CIP.py`)
- ONNX inference → Trained ensemble: runs model (evidence: `CIP.py`)
- Prediction orchestration → Island predictions: produces predictions (evidence: `CIP.py`)
- Prediction orchestration → Result files: writes results (evidence: `CIP.py`)
- Prediction orchestration → Model metadata: loads metadata (evidence: `CIP.py`)
- Prediction orchestration → Error handling: formats errors (evidence: `CIP.py`)
- Prediction orchestration → Session logging: logs activity (evidence: `CIP.py`)
- Session logging → Log archiving: archives logs (evidence: `modules/logger.py`)
