# laurapeng/decoder architecture

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

- Interactive diagram: https://gitdiagram.com/laurapeng/decoder
- Repository: https://github.com/laurapeng/decoder

## Overview

##### Main Components
- Input/Configuration Module:
- Configuration files: config_de_novo.tsv, config_de_novo_parmode.tsv, and config_single_sample.tsv.
- Data files: Located under the “data” directory (e.g., .mat, .tsv, and sometimes .csv files), including demo_data examples.

- Core Processing Modules:
- De novo deconvolution functions: Main entry points are Decon_de_novo.m (integrated mode), Decon_de_novo_parmode_step1.m, and Decon_de_novo_parmode_step2.m (for parallel/HPC mode).
- Single-sample deconvolution: Executed via the Decon_single_sample.m script.

- Utility/Supporting Functions:
- The “utils” directory contains helper scripts (e.g., Load_data.m, Train_NMF_seed.m, nnmf_unmix_quick.m, Plot_factor_tree.m) that support data loading, transformation, processing, plotting, and saving of intermediate results.

- External/Cluster Integration:
- Launch and scheduling scripts such as launch_DECODER_K7.m and launch_sbatch.sh, which facilitate parallel processing on a cluster/HPC environment.

- Output/Result Management:
- The “results” directory where deconvolution outputs are stored (such as factor trees in PDF, sample weights, gene scores, and other text files), representing the analysis results.

##### Relationships and Data Flow
- The user (or automation script) begins by placing data and setting configurations in the working directory.
- The input component (configuration and data files) is read and preprocessed by the core MATLAB functions (Decon_de_novo.m or Decon_single_sample.m).
- In the integrated or de novo modes, the framework processes the raw matrix data via several algorithmic steps (e.g., non-negative matrix factorization and iterative updates) that are supported by various utility functions.
- In the parallel HPC mode, processing is split into two steps: first (using launch_DECODER_K7.m/launch_sbatch.sh) the system launches multiple jobs for increasing K values, and then a collection step (Decon_de_novo_parmode_step2.m) merges and finalizes the results.
- Once analysis completes, the outputs are generated in the “results” directory (with detailed subfolders especially for multi-dataset results like TCGA and Moffitt microarray data).

##### Architectural Patterns and Technologies
- Modular design: Main deconvolution functions are separated by analysis mode, and utility functions encapsulate common tasks (data loading, plotting, etc.).
- Batch/parallel processing: Parallel mode implementation demonstrates that the framework has been designed to run on HPC clusters using shell scripts and MATLAB integration.
- Scientific computing: The implementation uses MATLAB-specific functions and scripting for numerical and matrix-based data analysis, including NMF/nnmf operations.

- Clear Labels: Each block should be clearly labeled (e.g., “Config Files (TSV)”, “Data Files (MAT/TSV)”, “Decon_de_novo.m”, “Parallel Dispatch (launch_DECODER_K7.m/launch_sbatch.sh)”, “Aggregate Results (Decon_de_novo_parmode_step2.m)”).

Final Note:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input/Configuration subgraph
    subgraph "Input/Configuration"
        C1["config_de_novo.tsv"]:::input
        C2["config_de_novo_parmode.tsv"]:::input
        C3["config_single_sample.tsv"]:::input
        D["Data Files (data/)"]:::input
    end

    %% Utility Functions subgraph
    subgraph "Utility Functions"
        Utils["utils/ Directory"]:::util
    end

    %% Core Processing subgraph
    subgraph "Core Processing"
        subgraph "De novo Deconvolution"
            IN1["Decon_de_novo.m (Integrated Mode)"]:::core
            subgraph "Parallel/HPC Mode"
                P1["Decon_de_novo_parmode_step1.m"]:::core
                P2["launch_DECODER_K7.m"]:::core
                P3["launch_sbatch.sh"]:::core
                HPCProc["Job Dispatch"]:::core
                PA["Aggregate Results: Decon_de_novo_parmode_step2.m"]:::core
            end
            SS["Decon_single_sample.m (Single-Sample)"]:::core
        end
    end

    %% Output/Results subgraph
    subgraph "Output/Results"
        Out["results/ Directory"]:::output
    end

    %% Cluster/Job Management subgraph
    subgraph "Cluster/Job Management"
        HPC["HPC Cluster"]:::cluster
    end

    %% Data Flow: Input to Utility Functions
    C1 --> Utils
    C2 --> Utils
    C3 --> Utils
    D  --> Utils

    %% Utility Functions to Core Processing
    Utils --> IN1
    Utils --> P1
    Utils --> SS

    %% Integrated Mode Flow
    IN1 --> Out

    %% Parallel HPC Mode Flow
    P1 --> P2
    P2 --> P3
    P3 --> HPC
    HPC --> PA
    PA --> Out

    %% Single-Sample Mode Flow
    SS --> Out

    %% Styles
    classDef input fill:#AED6F1,stroke:#1B4F72,color:#1B2631,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#186A3B,color:#145A32,stroke-width:2px;
    classDef util fill:#F9E79F,stroke:#B7950B,color:#7D6608,stroke-width:2px;
    classDef output fill:#D2B4DE,stroke:#6C3483,color:#512E5F,stroke-width:2px;
    classDef cluster fill:#F5B7B1,stroke:#C0392B,color:#641E16,stroke-width:2px;

    %% Click Events
    click C1 "https://github.com/laurapeng/decoder/blob/master/config_de_novo.tsv"
    click C2 "https://github.com/laurapeng/decoder/blob/master/config_de_novo_parmode.tsv"
    click C3 "https://github.com/laurapeng/decoder/blob/master/config_single_sample.tsv"
    click D "https://github.com/laurapeng/decoder/tree/master/data/"
    click IN1 "https://github.com/laurapeng/decoder/blob/master/Decon_de_novo.m"
    click P1 "https://github.com/laurapeng/decoder/blob/master/Decon_de_novo_parmode_step1.m"
    click P2 "https://github.com/laurapeng/decoder/blob/master/launch_DECODER_K7.m"
    click P3 "https://github.com/laurapeng/decoder/blob/master/launch_sbatch.sh"
    click PA "https://github.com/laurapeng/decoder/blob/master/Decon_de_novo_parmode_step2.m"
    click SS "https://github.com/laurapeng/decoder/blob/master/Decon_single_sample.m"
    click Utils "https://github.com/laurapeng/decoder/tree/master/utils/"
    click Out "https://github.com/laurapeng/decoder/tree/master/results/"
```
