# somalogic/somalogic-data architecture

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

- Interactive diagram: https://gitdiagram.com/somalogic/somalogic-data
- Repository: https://github.com/somalogic/somalogic-data

## Overview

Based on our analysis of the file tree and README, this project is not a full-stack application or a service-based system but rather a curated data repository that provides example ADAT files. These files illustrate the structure and sample content of SomaScan study data delivered in the SomaLogic-specific ADAT format. The repository is intended for customers and developers to preview and prepare for processing actual SomaScan datasets, and it also supports programmatic tools such as the R package (SomaDataIO) and the Python module (Canopy) that parse and utilize the ADAT files.

##### Main Components
- Data Repository: Represented by the repository itself, which contains the three ADAT example files (e.g., example_data.adat, example_data_v4.1_plasma.adat, example_data_v5.0_plasma.adat) and a supplementary figures directory (containing, for example, the logo).
- ADAT File Structure: Each ADAT file is composed of four key sections – HEADER, COL_DATA, ROW_DATA, and TABLE_BEGIN. These sections detail study-level metadata, reagent information, sample metadata, and the data matrix (RFU measurements), respectively.
- External Parsing/Processing Tools: Indicate the role of external components such as the R package (SomaDataIO), the Python module (Canopy), and the linked Digital Tools (DataDelve Statistics). They are designed to ingest, parse, and analyze these ADAT files.
- Data Normalization/Processing Pipeline: Capture the fact that all example files have gone through a standard data normalization procedure, which is a critical processing step.

##### Relationships and Data Flows
- That the repository “provides” the example ADAT files.

##### Architectural Patterns and Design Principles
- Modularity: Illustrate that the ADAT file format itself is modular (with clearly defined sections).
- Self-Describing Data: Emphasize that each ADAT file is intended to be flexible and self-explanatory, making it easier for external tools to understand and process the data.
- Interoperability: The existence of different programmatic tools (R, Python) points toward an architecture designed for wide compatibility.
- Clear Separation of Concerns: Distinguish between the static example repository, the data file structure, and the dynamic parsing/processing tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Repo["SomaLogic-Data Repository"]:::repo
    click Repo "https://github.com/somalogic/somalogic-data/tree/main/Repository root"

    subgraph "Example ADAT Files"
        data1["example_data.adat"]:::file
        click data1 "https://github.com/somalogic/somalogic-data/blob/main/example_data.adat"
        data2["example_data_v4.1_plasma.adat"]:::file
        click data2 "https://github.com/somalogic/somalogic-data/blob/main/example_data_v4.1_plasma.adat"
        data3["example_data_v5.0_plasma.adat"]:::file
        click data3 "https://github.com/somalogic/somalogic-data/blob/main/example_data_v5.0_plasma.adat"
    end

    figures["Supplementary Figures (logos, docs)"]:::directory
    click figures "https://github.com/somalogic/somalogic-data/tree/main/figures"
    
    %% Connect Repository to ADAT Files and Supplementary Figures
    Repo -->|"contains"| data1
    Repo --> data2
    Repo --> data3
    Repo --> figures

    %% ADAT File Structure for example_data.adat
    subgraph "ADAT File Structure: example_data.adat"
        header["HEADER: Study Metadata"]:::section
        colData["COL_DATA: Reagent Info"]:::section
        rowData["ROW_DATA: Sample Metadata"]:::section
        tableBegin["TABLE_BEGIN: Data Matrix (RFU measurements)"]:::section
    end

    %% Link example_data.adat file to its internal structure
    data1 -->|"ParsedInto"| header
    data1 --> colData
    data1 --> rowData
    data1 --> tableBegin

    %% Normalization Pipeline Node
    norm["Normalization Process"]:::pipeline
    header --> norm
    colData --> norm
    rowData --> norm
    tableBegin --> norm

    %% External Parsing/Processing Tools
    subgraph "External Parsing/Processing Tools"
        soma["R Package: SomaDataIO"]:::external
        canopy["Python Module: Canopy"]:::external
        datadelve["Digital Tools: DataDelve Statistics"]:::external
    end

    %% Data flow from Normalization Pipeline to External Tools
    norm -->|"DataIngestion"| soma
    norm -->|"DataIngestion"| canopy
    norm -->|"DataIngestion"| datadelve

    %% Styles
    classDef repo fill:#AED6F1,stroke:#21618C,stroke-width:2px;
    classDef file fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef directory fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef section fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef pipeline fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
