# fanglab/nanodisco architecture

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

- Interactive diagram: https://gitdiagram.com/fanglab/nanodisco
- Repository: https://github.com/fanglab/nanodisco

## Overview

##### Project type and purpose
- `nanodisco` is a command-line bioinformatics toolbox (an open-source tool), packaged as a Docker/Singularity image.
- It orchestrates a series of R and shell scripts to perform (a) *de novo* DNA methylation discovery, (b) methylation motif typing/fine-mapping, and (c) methylation-based metagenomic binning from nanopore sequencing data.

##### File structure
- Top-level:
- Container specs: `Dockerfile`, `Singularity`
- Executable wrapper: `code/nanodisco` (CLI entry point)
- Processing scripts: `code/*.R` and `*.sh`
- Documentation: `docs/` (Sphinx sources)
- Protocols: `protocol/` (PDF lab protocols)
- Scripts implement a modular pipeline:
- Pre-processing & alignment (`preprocess.sh`, `realign_events.sh`)
- Signal difference calling (`difference.sh`, `difference_chunks.R`, `difference_functions.R`)
- Motif discovery & characterization (`run_meme.sh`, `motif.R`, `characterize.R`, `score.R`)
- Methylation profiling & binning (`profile.R`, `filter_profile.R`, `select_feature.R`, `binning.R`, `plot_binning.R`)

##### README for architectural hints
- The CLI exposes subcommands: `difference`, `characterize`, `profile`, `binning`, `plot_binning`, `score`, etc.
- Dependencies: R (packages), MEME suite, nanopore event realignment tools, Singularity/Docker.

##### Main components and their interactions
a. User & CLI
- The user invokes `nanodisco <subcommand> [options]` inside a container (Docker/Singularity).
b. Container layer
- Encapsulates all dependencies: R interpreter, shell utilities, MEME, nanopolish/event realigner.
c. Pipeline modules (scripts)
1. Pre-processing
- preprocess.sh → realign_events.sh → raw signal and reference FASTA → aligned signals
2. Difference calling
- difference.sh → difference_chunks.R → RDS files of current differences
3. Motif discovery & fine mapping
- run_meme.sh → motif.R → characterize.R → score.R → motif classification outputs (PDF, TSV)
4. Profiling & binning
- profile.R → filter_profile.R → select_feature.R → methylation profile RDS
- binning.R → plot_binning.R → bin assignments and visualizations (PDF, RDS)
d. Data store
- Intermediate files (RDS, TSV), final outputs (PDF, plots), logs—all on the container’s filesystem, mountable to host.

##### Architectural patterns & design principles
- Modular pipeline: each subcommand encapsulates a distinct analysis step.
- Stateless scripts: data flows through files (RDS/TSV) rather than in-memory objects across steps.
- Containerization: ensures reproducibility and isolates dependencies.
- Extensibility: new subcommands and R scripts can be added to `code/` and exposed via the CLI launcher script.

##### Elements
- Clear labels: script names and command names (`nanodisco difference`, `nanodisco profile`, etc.)
- Blue for preprocessing & alignment
- Green for methylation discovery
- Orange for profiling & binning
- Gray for external tools (MEME, realigner)

##### Capturing essential details without over-splitting
- Data artifacts (RDS, motifs.tsv, binning.pdf) rather than every intermediate file.
- Extensibility: show that adding a new subcommand plugs into the CLI launcher and the container.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Container" 
        direction TB
        CLI["CLI Entry: nanodisco"]:::cli

        subgraph "Preprocessing & Alignment"
            direction TB
            Pre1["preprocess.sh"]:::pre
            Pre2["realign_events.sh"]:::pre
        end

        subgraph "Difference Calling"
            direction TB
            DiffSH["difference.sh"]:::pre
            DiffChunks["difference_chunks.R"]:::pre
            DiffFuncs["difference_functions.R"]:::pre
        end

        subgraph "Motif Discovery & Characterization"
            direction TB
            RunMeme["run_meme.sh"]:::motif
            MotifR["motif.R"]:::motif
            Characterize["characterize.R"]:::motif
            ScoreR["score.R"]:::motif
        end

        subgraph "Profiling & Binning"
            direction TB
            ProfileR["profile.R"]:::prof
            FilterProfile["filter_profile.R"]:::prof
            SelectFeature["select_feature.R"]:::prof
            BinningR["binning.R"]:::prof
            PlotBinning["plot_binning.R"]:::prof
        end

        Dockerfile["Dockerfile"]:::spec
        Singularity["Singularity"]:::spec

        subgraph "External Tools"
            direction TB
            ET["External Tools\n(MEME suite, Event Realigner)"]:::external
        end
    end

    Raw(("Raw Input\n(FAST5/FASTQ, FASTA)")):::datastore
    Aligned(("Aligned Signals")):::datastore
    DiffRDS(("Difference RDS")):::datastore
    Motifs(("Motifs.tsv / PDF")):::datastore
    ProfileRDS(("Profile RDS")):::datastore
    BinPDF(("Binning PDF / RDS")):::datastore

    CLI --> Pre1
    Pre1 --> Pre2
    Pre2 --> Aligned
    Aligned --> DiffSH
    DiffSH --> DiffChunks
    DiffChunks --> DiffFuncs
    DiffFuncs --> DiffRDS
    DiffRDS --> RunMeme
    RunMeme --> MotifR
    MotifR --> Characterize
    Characterize --> ScoreR
    ScoreR --> Motifs

    DiffRDS --> ProfileR
    ProfileR --> FilterProfile
    FilterProfile --> SelectFeature
    SelectFeature --> ProfileRDS
    ProfileRDS --> BinningR
    BinningR --> PlotBinning
    PlotBinning --> BinPDF

    ET -.-> Pre2
    ET -.-> RunMeme

    Raw --> Pre1

    click CLI "https://github.com/fanglab/nanodisco/tree/master/code/nanodisco"
    click Pre1 "https://github.com/fanglab/nanodisco/blob/master/code/preprocess.sh"
    click Pre2 "https://github.com/fanglab/nanodisco/blob/master/code/realign_events.sh"
    click DiffSH "https://github.com/fanglab/nanodisco/blob/master/code/difference.sh"
    click DiffChunks "https://github.com/fanglab/nanodisco/blob/master/code/difference_chunks.R"
    click DiffFuncs "https://github.com/fanglab/nanodisco/blob/master/code/difference_functions.R"
    click RunMeme "https://github.com/fanglab/nanodisco/blob/master/code/run_meme.sh"
    click MotifR "https://github.com/fanglab/nanodisco/blob/master/code/motif.R"
    click Characterize "https://github.com/fanglab/nanodisco/blob/master/code/characterize.R"
    click ScoreR "https://github.com/fanglab/nanodisco/blob/master/code/score.R"
    click ProfileR "https://github.com/fanglab/nanodisco/blob/master/code/profile.R"
    click FilterProfile "https://github.com/fanglab/nanodisco/blob/master/code/filter_profile.R"
    click SelectFeature "https://github.com/fanglab/nanodisco/blob/master/code/select_feature.R"
    click BinningR "https://github.com/fanglab/nanodisco/blob/master/code/binning.R"
    click PlotBinning "https://github.com/fanglab/nanodisco/blob/master/code/plot_binning.R"
    click Dockerfile "https://github.com/fanglab/nanodisco/tree/master/Dockerfile"
    click Singularity "https://github.com/fanglab/nanodisco/tree/master/Singularity"

    classDef cli fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef pre fill:#add8e6,stroke:#333,stroke-width:1px
    classDef motif fill:#90ee90,stroke:#333,stroke-width:1px
    classDef prof fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef spec fill:#f5f5f5,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffffff,stroke:#333,stroke-width:1px,shape:cylinder
```
