# jameslu01/neural_pk architecture

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

- Interactive diagram: https://gitdiagram.com/jameslu01/neural_pk
- Repository: https://github.com/jameslu01/neural_pk

## Overview

##### Project Type and Purpose
- This is a scientific/machine-learning codebase (not a web app).
- Purpose: apply Neural-ODEs to pharmacokinetics (PK) modeling, compare to LSTM, LightGBM, NLME.

##### Main Architectural Components
a. Data Layer
- Raw/Example data: `ExampleData/sim_data.csv` (or clinical dataset upon request).
- Columns: PTNM, STUD, DSFQ, CYCL, AMT, TIME, TFDS, DV.
b. Preprocessing Pipeline
- args.py: parse CLI parameters (data paths, hyperparameters, cross-validation flags).
- data_parse.py: load CSVs, filter/validate columns.
- process_data.py: feature engineering (compute TFDS, cycle counts), normalization.
- data_split.py: either 5-fold cross‐validation splits or cross-dosing schedule splits.
c. Core Modeling Layer
- model.py: defines the Neural-ODE network using PyTorch + torchdiffeq ODE solver.
- utils.py: helper routines (logging, checkpoint I/O, metrics calculation).
d. Pipeline Orchestration Scripts
- run_train.py: coordinates preprocessing → model instantiation → training loop.
- run_predict.py: loads trained weights → performs inference on test/cross-schedule sets.
- run.sh: wrapper shell script that invokes run_train.py and run_predict.py with proper args.
- (cross-schedule only) generate_interp_nodosing.py: specialized interpolation for new dosing regimens.
e. Evaluation & Output
- evaluation.py: computes performance metrics (e.g., RMSE, MAE), generates summary tables.
f. Environment & Dependencies
- environment.yml / requirements.txt: Python 3.7.5, PyTorch 1.5.1, torchdiffeq.
- license.txt: project licensing.

##### Relationships & Data Flow
- Post‐training: checkpoint → run_predict.py → evaluation.py → figures and metrics output.
- For cross-schedule pipeline, insert generate_interp_nodosing.py between split and predict.
- External libraries (PyTorch, torchdiffeq) sit alongside model.py as dependencies.

##### Architectural Patterns & Principles
- Modular pipeline: clear separation of parsing, processing, modeling, evaluation.
- Reproducible experiments: use of CLI args, consistent run.sh wrapper.
- Reusable components: utils.py for logging and metrics; same model definition for both pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        Data5[(“sim_data.csv”)]:::data
        click Data5 "https://github.com/jameslu01/neural_pk/blob/main/ExampleData/sim_data.csv"
        DataCS[(“sim_data.csv”)]:::data
        click DataCS "https://github.com/jameslu01/neural_pk/blob/main/ExampleData/sim_data.csv"
    end

    %% Preprocessing 5-fold
    subgraph "5-fold Preprocessing" 
        direction TB
        Args5["args.py"]:::processing
        click Args5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/args.py"
        Parse5["data_parse.py"]:::processing
        click Parse5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/data_parse.py"
        Proc5["process_data.py"]:::processing
        click Proc5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/process_data.py"
        Split5["data_split.py"]:::processing
        click Split5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/data_split.py"
    end

    %% Preprocessing Cross-schedule
    subgraph "Cross-schedule Preprocessing" 
        direction TB
        ArgsCS["args.py"]:::processing
        click ArgsCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/args.py"
        ParseCS["data_parse.py"]:::processing
        click ParseCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/data_parse.py"
        ProcCS["process_data.py"]:::processing
        click ProcCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/process_data.py"
        SplitCS["data_split.py"]:::processing
        click SplitCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/data_split.py"
    end

    %% Cross-schedule special interpolation
    Generate["generate_interp_nodosing.py"]:::processing
    click Generate "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/generate_interp_nodosing.py"

    %% Core Modeling Layer
    subgraph "Core Modeling" 
        direction TB
        Model["model.py\n(torchdiffeq submodule)"]:::model
        click Model "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/model.py"
        %% Cross schedule model click as well
        click Model "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/model.py"
        Utils["utils.py"]:::model
        click Utils "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/utils.py"
        click Utils "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/utils.py"
    end

    %% Pipeline Orchestration 5-fold
    subgraph "5-fold Orchestration" 
        direction TB
        Train5["run_train.py"]:::scripts
        click Train5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/run_train.py"
        Predict5["run_predict.py"]:::scripts
        click Predict5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/run_predict.py"
        Wrapper5["run.sh"]:::scripts
        click Wrapper5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/run.sh"
    end

    %% Pipeline Orchestration Cross-schedule
    subgraph "Cross-schedule Orchestration" 
        direction TB
        TrainCS["run_train.py"]:::scripts
        click TrainCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/run_train.py"
        PredictCS["run_predict.py"]:::scripts
        click PredictCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/run_predict.py"
        WrapperCS["run.sh"]:::scripts
        click WrapperCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/run.sh"
    end

    %% Evaluation & Outputs
    Evaluation5["evaluation.py"]:::scripts
    click Evaluation5 "https://github.com/jameslu01/neural_pk/blob/main/5fold_models/Neural-ODE/evaluation.py"
    EvaluationCS["evaluation.py"]:::scripts
    click EvaluationCS "https://github.com/jameslu01/neural_pk/blob/main/cross-schedule_models/Neural-ODE/evaluation.py"
    Figures["figures/"]:::data
    click Figures "https://github.com/jameslu01/neural_pk/tree/main/figures/"

    %% Dependencies
    subgraph "Environment & Dependencies"
        direction TB
        EnvYML["environment.yml"]:::deps
        ReqTXT["requirements.txt"]:::deps
        License["license.txt"]:::deps
    end

    %% 5-fold Flow
    Data5 -->|"CSV"| Parse5 -->|"Pandas DF"| Proc5 -->|"Normalized DF"| Split5 -->|"Splits"| Train5
    Train5 -->|"checkpoint"| Predict5 -->|"predictions"| Evaluation5 -->|"metrics & plots"| Figures

    %% Cross-schedule Flow
    DataCS --> ParseCS --> ProcCS --> SplitCS --> Generate --> TrainCS
    TrainCS --> PredictCS --> EvaluationCS --> Figures

    %% Orchestration to Core
    Train5 -->|"uses"| Model
    Train5 -->|"uses"| Utils
    Predict5 -->|"uses"| Model
    Predict5 -->|"uses"| Utils

    TrainCS -->|"uses"| Model
    TrainCS -->|"uses"| Utils
    PredictCS -->|"uses"| Model
    PredictCS -->|"uses"| Utils

    %% Wrapper triggers
    Wrapper5 -->|"> run_train.py & run_predict.py"| Train5
    WrapperCS -->|"> run_train.py & run_predict.py"| TrainCS

    %% Dependencies links
    Model -->|"relies on"| EnvYML
    Utils -->|"relies on"| ReqTXT
    Utils -->|"license"| License

    %% Styles
    classDef data fill:#D0E6A5,stroke:#000,stroke-width:1px
    classDef processing fill:#A0C4FF,stroke:#000,stroke-width:1px
    classDef model fill:#B9FBC0,stroke:#000,stroke-width:1px
    classDef scripts fill:#FFD6A5,stroke:#000,stroke-width:1px
    classDef deps fill:#CCCCCC,stroke:#000,stroke-width:1px
```
