# jaredl7/soursop architecture

> Architecture diagram of the GitHub repository jaredl7/soursop, 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/jaredl7/soursop
- Repository: https://github.com/jaredl7/soursop

## Overview

##### Project type and purpose
- SOURSOP is an open-source Python library for analyzing molecular dynamics simulations of intrinsically disordered proteins. It is not a web or mobile app, but a domain-specific analysis toolkit built on top of the mdtraj library.
- Its primary purpose is to provide a modular API for loading trajectory data, computing structural properties (e.g., radii of gyration, center‐of‐mass distances, secondary structure), and extending functionality via plugins.

##### File structure
- Top-level:
- soursop/            → core Python package
- demo_examples/     → Jupyter notebooks and figures showcasing library usage
- docs/              → Sphinx documentation
- devtools/          → scripts and Conda recipes for development, CI, packaging
- soursop/tests/     → pytest‐based unit and integration tests
- configuration files for CI (.travis.yml, GitHub workflows), packaging (setup.py, setup.cfg, MANIFEST.in), code quality (.codecov.yml, .lgtm.yml)
- Within soursop/:
- __init__.py + soursop.py → top-level API entry points
- modules by function: sstrajectory.py, ssprotein.py, ssnmr.py, sspolymer.py, ssp­re.py, ssmutualinformation.py, etc.
- ssio.py, ssutils.py → I/O and general utility functions
- data/              → bundled test data and lookup tables
- plugins/           → plugin loader and example plugin (sparrow_plugin)
- _internal_data.py, configs.py → configuration and static data
- tests in soursop/tests/ verify each module’s behavior

##### README for additional insights
- Confirms mdtraj dependency and plugin extensibility
- Points to Sphinx docs for usage, examples, and developer guidelines (especially plugin development)

##### Elements
- Clear labels for: Core API, Functional Modules, Plugin System, External Library (mdtraj), Data Store, Testing & CI, Documentation
- User code → Core API → Functional Modules → mdtraj / Data
- Plugin loader ↔ Plugin modules
- CI/CD → Tests & Coverage → Reports
- Docs generator → Source code → HTML docs
- Blue rectangles for code modules
- Orange hexagon for external dependencies

##### Final advice
- Be thorough: include each top‐level directory as a bounded subsystem
- Data flow from user input to analysis output and reporting
- Do not overcomplicate: focus on separating distinct responsibilities (analysis modules, I/O, plugins, CI, docs)
- Use the README and module docstrings to annotate each component with its role

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code
    UserCode["User Code / demo_examples"]:::code
    click UserCode "https://github.com/jaredl7/soursop/tree/master/demo_examples/"

    %% Soursop Package
    subgraph "soursop Package"
        direction TB
        %% Core API
        subgraph "Core API"
            direction TB
            Init["__init__.py"]:::code
            SoursopMain["soursop.py"]:::code
            Version["_version.py"]:::code
        end

        %% Functional Modules
        subgraph "Functional Modules"
            direction TB
            Trajectory["Trajectory Analysis\n(sstrajectory.py)"]:::code
            Protein["Protein Properties\n(ssprotein.py)"]:::code
            NMR["NMR Observables\n(ssnmr.py)"]:::code
            Polymer["Polymer Metrics\n(sspolymer.py)"]:::code
            PRE["PRE Rates\n(sspre.py)"]:::code
            MI["Mutual Information\n(ssmutualinformation.py)"]:::code
            DataInterface["Static Data Interface\n(ssdata.py)"]:::code
        end

        %% I/O and Utilities
        subgraph "I/O & Utilities"
            direction TB
            IO["File I/O\n(ssio.py)"]:::code
            Utils["General Utilities\n(ssutils.py)"]:::code
            Tools["Additional Tools\n(sstools.py)"]:::code
        end

        %% Plugin Subsystem
        subgraph "Plugin Subsystem"
            direction TB
            PluginLoader["Plugin Loader\n(plugins/__init__.py)"]:::code
            ExamplePlugin["Example Plugin\n(sparrow_plugin)"]:::code
        end

        %% Configuration & Static Data
        subgraph "Configuration & Static Data"
            direction TB
            Configs["Configuration Definitions\n(configs.py)"]:::code
            InternalData["Internal Static Data\n(_internal_data.py)"]:::code
            DataDir["Bundled Data\n(data/)"]:::data
        end
    end

    %% External Dependencies
    Mdtraj["mdtraj\n(External Library)"]:::external

    %% Data Store
    subgraph "Data Store"
        direction TB
        TestData["Test Data Directory\n(test_data/)"]:::data
        Lookup1["bbseg2.dat"]:::data
        Lookup2["SASA_SUMMARY.csv"]:::data
    end

    %% Documentation & CI
    Docs["Sphinx Docs\n(docs/)"]:::code
    TestsCI["Testing & CI"]:::code

    %% Development Tools & Packaging
    DevTools["Dev Tools & Packaging"]:::code

    %% Connections
    UserCode -->|imports| Init
    Init -->|dispatches| Trajectory
    Init --> Protein
    Init --> NMR
    Init --> Polymer
    Init --> PRE
    Init --> MI
    Init --> DataInterface

    Trajectory -->|uses| Mdtraj
    Protein --> Mdtraj
    NMR --> Mdtraj
    Polymer --> Mdtraj
    PRE --> Mdtraj
    MI --> Mdtraj

    Init --> IO
    Trajectory --> IO
    Protein --> Utils
    NMR --> Utils

    PluginLoader --> ExamplePlugin
    Init --> PluginLoader

    DataInterface --> InternalData
    Trajectory --> DataDir
    Protein --> DataDir

    TestsCI -->|runs tests| soursop_tests["soursop/tests/"] 
    TestsCI -->|CI configs| Travis[".travis.yml"]
    TestsCI -->|CI configs| GHActions[".github/workflows/soursop-ci.yml"]
    TestsCI -->|coverage| Codecov[".codecov.yml"]

    Docs -->|builds from| Init
    Docs -->|includes| FunctionDocs["docs/modules/"]

    DevTools -->|conda| CondaEnv["devtools/conda-envs/"]
    DevTools -->|recipes| CondaRecipe["devtools/conda-recipe/"]
    DevTools -->|scripts| Scripts["devtools/scripts/"]
    DevTools -->|versioning| Versioneer["versioneer.py"]

    %% Click Events
    click Init "https://github.com/jaredl7/soursop/blob/master/soursop/__init__.py"
    click SoursopMain "https://github.com/jaredl7/soursop/blob/master/soursop/soursop.py"
    click Version "https://github.com/jaredl7/soursop/blob/master/soursop/_version.py"
    click Trajectory "https://github.com/jaredl7/soursop/blob/master/soursop/sstrajectory.py"
    click Protein "https://github.com/jaredl7/soursop/blob/master/soursop/ssprotein.py"
    click NMR "https://github.com/jaredl7/soursop/blob/master/soursop/ssnmr.py"
    click Polymer "https://github.com/jaredl7/soursop/blob/master/soursop/sspolymer.py"
    click PRE "https://github.com/jaredl7/soursop/blob/master/soursop/sspre.py"
    click MI "https://github.com/jaredl7/soursop/blob/master/soursop/ssmutualinformation.py"
    click DataInterface "https://github.com/jaredl7/soursop/blob/master/soursop/ssdata.py"
    click IO "https://github.com/jaredl7/soursop/blob/master/soursop/ssio.py"
    click Utils "https://github.com/jaredl7/soursop/blob/master/soursop/ssutils.py"
    click Tools "https://github.com/jaredl7/soursop/blob/master/soursop/sstools.py"
    click PluginLoader "https://github.com/jaredl7/soursop/blob/master/soursop/plugins/__init__.py"
    click ExamplePlugin "https://github.com/jaredl7/soursop/blob/master/soursop/plugins/sparrow_plugin/__init__.py"
    click Configs "https://github.com/jaredl7/soursop/blob/master/soursop/configs.py"
    click InternalData "https://github.com/jaredl7/soursop/blob/master/soursop/_internal_data.py"
    click DataDir "https://github.com/jaredl7/soursop/tree/master/soursop/data/"
    click TestData "https://github.com/jaredl7/soursop/tree/master/soursop/data/test_data/"
    click Lookup1 "https://github.com/jaredl7/soursop/blob/master/soursop/data/bbseg2.dat"
    click Lookup2 "https://github.com/jaredl7/soursop/blob/master/soursop/data/SASA_SUMMARY.csv"
    click Docs "https://github.com/jaredl7/soursop/tree/master/docs/"
    click FunctionDocs "https://github.com/jaredl7/soursop/tree/master/docs/modules/"
    click soursop_tests "https://github.com/jaredl7/soursop/tree/master/soursop/tests/"
    click Travis "https://github.com/jaredl7/soursop/blob/master/.travis.yml"
    click GHActions "https://github.com/jaredl7/soursop/blob/master/.github/workflows/soursop-ci.yml"
    click Codecov "https://github.com/jaredl7/soursop/blob/master/.codecov.yml"
    click CondaEnv "https://github.com/jaredl7/soursop/tree/master/devtools/conda-envs/"
    click CondaRecipe "https://github.com/jaredl7/soursop/tree/master/devtools/conda-recipe/"
    click Scripts "https://github.com/jaredl7/soursop/tree/master/devtools/scripts/"
    click Versioneer "https://github.com/jaredl7/soursop/blob/master/versioneer.py"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#3498DB
    classDef data fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#FCF3CF,stroke:#F39C12
```
