# lilit-nersisyan/fivepseq architecture

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

- Interactive diagram: https://gitdiagram.com/lilit-nersisyan/fivepseq
- Repository: https://github.com/lilit-nersisyan/fivepseq

## Overview

##### Project Type and Purpose
- This is a Python-based command‐line bioinformatics tool (fivepseq) for analyzing 5′ endpoint distributions in RNA degradome (BAM) datasets.
- It also provides a shell‐based preprocessing pipeline (preprocess_scripts/fivepseq_preprocess.sh) to go from FASTQ → QC → trimming → alignment → deduplication → bedgraph.

##### File‐Structure Analysis
- Top‐level:
- fivepseq/             – core package (CLI entry, config, logic, util, viz, tests)
- preprocess_scripts/   – shell script pipeline
- setup.py, version.txt, README.rst
- fivepseq/logic:
- structures/ – domain models (Alignment, Annotation, Genome, Count objects)
- algorithms/ – statistical and pipeline modules (count_stats, general_pipelines)
- fivepseq/viz: uses Bokeh, HTML templating for plots and report generation
- fivepseq/util: I/O helpers (readers, writers, formatting)
- Configuration: fivepseq/config.py, CLI entry in __main__.py
- Tests under fivepseq/tests ensure modular correctness.

##### Key Components
a. User Inputs
- Raw FASTQ (optional) → Preprocessor Script
- Aligned reads (.bam/.bai), Genome (.fa/.fasta), Annotation (.gtf/.gff)
b. Preprocessing Pipeline (shell script)
- FASTQC/MultiQC → Cutadapt (adapter trimming) → UMI-tools → STAR aligner → Deduplication → Bedgraph generation
- Invokes external tools (FASTQC, STAR, Samtools, bedtools, etc.)
- Output: deduplicated BAM + index
c. fivepseq CLI Application
- CLI Parser (fivepseq/__main__.py) → Config Loader (config.py)
- Readers (util/readers.py) parse BAM, FASTA, GFF
- Data Structures populated (logic/structures)
- Statistical Algorithms (logic/algorithms/count_stats)
- Pipelines (logic/algorithms/general_pipelines: count_pipeline, viz_pipeline)
- Visualization (viz/bokeh_plots.py, header_html.py, template.html)
- Writers (util/writers.py) output CSV/TSV, HTML, image files (via phantomjs)
d. External Dependencies & Services
- Python libs: numpy, pysam, cython, bokeh, selenium/pillow/phantomjs
- Optionally run inside Docker

##### Relationships and Data Flow
- Preprocessor Script → external tool calls → generates BAM → fivepseq CLI
- fivepseq CLI:
Input files → Readers → Data Structures → Statistical Algorithms → Visualization Pipeline → Writers → Output Directory (HTML report, plots, stats)

##### Architectural Patterns & Principles
- Modular separation: I/O (util) vs. Domain Models (structures) vs. Computation (algorithms) vs. Presentation (viz)
- Pipeline pattern: sequential stages (count vs. viz pipelines)
- Dependency injection via config.py and CLI arguments
- Testable units: full test suite under fivepseq/tests

##### Technologies & Frameworks
- Python 3.x
- Bokeh (visualization)
- External CLI tools (STAR, Samtools, etc.)
- Sphinx for documentation (doc/source, build)
- Shell scripting for preprocessing
- Docker (optional containerization)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Preprocessing Pipeline
    subgraph "Preprocessing Pipeline"
        FASTQ["Raw FASTQ"]:::input
        FASTQ --> PreScript["Preprocessing Pipeline Script"]:::process
        click PreScript "https://github.com/lilit-nersisyan/fivepseq/blob/master/preprocess_scripts/fivepseq_preprocess.sh"
        PreScript --> QC["FastQC/MultiQC"]:::external
        QC --> Trim["Cutadapt"]:::external
        Trim --> UMI["UMI-tools"]:::external
        UMI --> Aligner["STAR Aligner"]:::external
        Aligner --> Dedup["Deduplication"]:::external
        Dedup --> Bedgraph["Bedgraph Generation"]:::external
        Bedgraph --> BAM["Deduplicated BAM"]:::output
    end

    %% CLI Analysis Pipeline
    subgraph "fivepseq CLI Analysis"
        CLI["CLI Parser"]:::process
        click CLI "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/__main__.py"
        CLI --> CFG["Config Loader"]:::process
        click CFG "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/config.py"
        CFG --> Readers["BAM/FASTA/GFF Readers"]:::process
        click Readers "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/util/readers.py"
        Readers --> Formatting["Formatting Helpers"]:::process
        click Formatting "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/util/formatting.py"
        Formatting --> Models["Data Structures"]:::process

        subgraph "Domain Models"
            A["Alignment Model"]:::process
            click A "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/structures/alignment.py"
            B["Annotation Model"]:::process
            click B "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/structures/annotation.py"
            C["Codons Model"]:::process
            click C "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/structures/codons.py"
            D["Counts Model"]:::process
            click D "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/structures/fivepseq_counts.py"
            E["Genome Model"]:::process
            click E "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/structures/genome.py"
        end

        Models --> Stats["Statistical Algorithms"]:::process
        subgraph "Stat Algorithms"
            CS["count_stats"]:::process
            click CS "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/algorithms/count_stats/count_stats.py"
            QS["queue_stats"]:::process
            click QS "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/algorithms/count_stats/queue_stats.py"
        end

        Stats --> Pipes["Pipeline Orchestration"]:::process
        subgraph "Pipelines"
            CP["Count Pipeline"]:::process
            click CP "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/algorithms/general_pipelines/count_pipeline.py"
            VP["Viz Pipeline"]:::process
            click VP "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/logic/algorithms/general_pipelines/viz_pipeline.py"
        end

        Pipes --> Viz["Visualization Components"]:::process
        subgraph "Visualization"
            Bokeh["Bokeh Plots"]:::process
            click Bokeh "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/viz/bokeh_plots.py"
            Header["Header HTML"]:::process
            click Header "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/viz/header_html.py"
            Template["HTML Template"]:::process
            click Template "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/viz/template.html"
        end

        Viz --> Writers["Writers"]:::process
        click Writers "https://github.com/lilit-nersisyan/fivepseq/blob/master/fivepseq/util/writers.py"
        Writers --> Output["Reports & Plots"]:::output
    end

    %% Data Flow Connections
    BAM --> CLI

    %% Class Definitions
    classDef input fill:#D6E9FF,stroke:#007ACC,color:#003366,shape:parallelogram;
    classDef process fill:#E6FFCC,stroke:#33AA33,color:#336633;
    classDef external fill:#F0F0F0,stroke:#999999,color:#666666,shape:cylinder;
    classDef output fill:#FFF5CC,stroke:#D4B000,color:#806300,shape:cylinder;
```
