# huiyum/tac_dose_adjustments architecture

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

- Interactive diagram: https://gitdiagram.com/huiyum/tac_dose_adjustments
- Repository: https://github.com/huiyum/tac_dose_adjustments

## Overview

This repository implements a tacrolimus pharmacokinetic prediction pipeline: patient CSV data is preprocessed, used to train and assess a GRU model, then evaluated on external data and used to produce dose recommendations. The graph follows the visible orchestration and sampled module calls; some cross-validation internals and the contents of app.py were not shown, so uncertain connections are omitted.

Main entry points: [`main.py`](https://github.com/huiyum/tac_dose_adjustments/blob/main/main.py) (Pipeline runner), [`src/cross_validation.py`](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/cross_validation.py) (Group cross-validation), [`src/evaluate.py`](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/evaluate.py) (Prediction evaluation), [`src/train.py`](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Pipeline orchestration"]
  node_main["Pipeline runner<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_data["Patient data preparation"]
  node_rawdata["Patient CSV data"]
  node_preprocessing["Feature preprocessing<br/>[preprocessing.py]"]
  node_dataset["Sequence dataset<br/>[dataset.py]"]
end

subgraph group_modeling["Model training and assessment"]
  node_crossvalidation["Group cross-validation"]
  node_training["Model training<br/>[train.py]"]
  node_model["GRU PK model<br/>[model.py]"]
  node_loss["Masked loss<br/>[losses.py]"]
  node_evaluation["Prediction evaluation<br/>[evaluate.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
end

subgraph group_analysis["Interpretation and dosing"]
  node_importance["Feature importance<br/>[importance.py]"]
  node_visualization["Result visualization<br/>[visualize.py]"]
  node_dose["Dose optimization"]
end

subgraph group_artifacts["Persisted outputs"]
  node_predictionfiles["Prediction CSVs"]
  node_modelartifacts["Model artifacts<br/>[model.pt]"]
end

node_operator(("Pipeline operator"))

node_operator -->|"runs"| node_main
node_main -->|"reads settings"| node_config
node_operator -->|"provides"| node_rawdata
node_main -->|"reads CSV"| node_rawdata
node_main -->|"preprocesses"| node_preprocessing
node_main -->|"runs folds"| node_crossvalidation
node_crossvalidation -->|"preprocesses folds"| node_preprocessing
node_crossvalidation -->|"trains folds"| node_training
node_training -->|"builds batches"| node_dataset
node_training -->|"optimizes"| node_model
node_training -->|"computes loss"| node_loss
node_crossvalidation -->|"evaluates folds"| node_evaluation
node_evaluation -->|"predicts with"| node_model
node_evaluation -->|"computes metrics"| node_metrics
node_crossvalidation -->|"analyzes features"| node_importance
node_importance -->|"builds permuted data"| node_dataset
node_importance -->|"measures impact"| node_evaluation
node_crossvalidation -->|"plots fold results"| node_visualization
node_visualization -->|"uses metrics"| node_metrics
node_main -->|"builds validation data"| node_dataset
node_main -->|"evaluates external data"| node_evaluation
node_main -->|"requests recommendations"| node_dose
node_dose -->|"predicts with"| node_model
node_main -->|"writes predictions"| node_predictionfiles
node_main -->|"saves weights"| node_modelartifacts
node_operator -->|"receives results"| node_predictionfiles

click node_main "https://github.com/huiyum/tac_dose_adjustments/blob/main/main.py"
click node_config "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/config.py"
click node_preprocessing "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/preprocessing.py"
click node_dataset "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/dataset.py"
click node_crossvalidation "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/cross_validation.py"
click node_training "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/train.py"
click node_model "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/model.py"
click node_loss "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/losses.py"
click node_evaluation "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/evaluate.py"
click node_metrics "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/metrics.py"
click node_importance "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/importance.py"
click node_visualization "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/visualize.py"
click node_dose "https://github.com/huiyum/tac_dose_adjustments/blob/main/src/dose_optimization.py"
click node_modelartifacts "https://github.com/huiyum/tac_dose_adjustments/blob/main/gru/model.pt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config toneBlue
class node_rawdata,node_preprocessing,node_dataset toneAmber
class node_crossvalidation,node_training,node_model,node_loss,node_evaluation,node_metrics toneMint
class node_importance,node_visualization,node_dose toneRose
class node_predictionfiles,node_modelartifacts,node_operator toneIndigo
```

## Components

### Pipeline orchestration

- [Pipeline runner](https://github.com/huiyum/tac_dose_adjustments/blob/main/main.py): `main.py`
- [Runtime configuration](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/config.py): `src/config.py`

### Patient data preparation

- **Patient CSV data**
- [Feature preprocessing](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Sequence dataset](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/dataset.py): `src/dataset.py`

### Model training and assessment

- [Group cross-validation](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/cross_validation.py): `src/cross_validation.py`
- [Model training](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/train.py): `src/train.py`
- [GRU PK model](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/model.py): `src/model.py`
- [Masked loss](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/losses.py): `src/losses.py`
- [Prediction evaluation](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/evaluate.py): `src/evaluate.py`
- [Evaluation metrics](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/metrics.py): `src/metrics.py`

### Interpretation and dosing

- [Feature importance](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/importance.py): `src/importance.py`
- [Result visualization](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/visualize.py): `src/visualize.py`
- [Dose optimization](https://github.com/huiyum/tac_dose_adjustments/blob/main/src/dose_optimization.py): `src/dose_optimization.py`

### Persisted outputs

- **Prediction CSVs**
- [Model artifacts](https://github.com/huiyum/tac_dose_adjustments/blob/main/gru/model.pt): `gru/model.pt`

### Other components

- **Pipeline operator**

## Connections

- Pipeline operator → Pipeline runner: runs (evidence: `README.md`)
- Pipeline runner → Runtime configuration: reads settings (evidence: `main.py`)
- Pipeline operator → Patient CSV data: provides (evidence: `README.md`)
- Pipeline runner → Patient CSV data: reads CSV (evidence: `main.py`)
- Pipeline runner → Feature preprocessing: preprocesses (evidence: `main.py`)
- Pipeline runner → Group cross-validation: runs folds (evidence: `main.py`)
- Group cross-validation → Feature preprocessing: preprocesses folds (evidence: `src/cross_validation.py`)
- Group cross-validation → Model training: trains folds (evidence: `src/cross_validation.py`)
- Model training → Sequence dataset: builds batches (evidence: `src/train.py`)
- Model training → GRU PK model: optimizes (evidence: `src/train.py`)
- Model training → Masked loss: computes loss (evidence: `src/train.py`)
- Group cross-validation → Prediction evaluation: evaluates folds (evidence: `src/cross_validation.py`)
- Prediction evaluation → GRU PK model: predicts with (evidence: `src/evaluate.py`)
- Prediction evaluation → Evaluation metrics: computes metrics (evidence: `src/evaluate.py`)
- Group cross-validation → Feature importance: analyzes features (evidence: `src/cross_validation.py`)
- Feature importance → Sequence dataset: builds permuted data (evidence: `src/importance.py`)
- Feature importance → Prediction evaluation: measures impact (evidence: `src/importance.py`)
- Group cross-validation → Result visualization: plots fold results (evidence: `src/cross_validation.py`)
- Result visualization → Evaluation metrics: uses metrics (evidence: `src/visualize.py`)
- Pipeline runner → Sequence dataset: builds validation data (evidence: `main.py`)
- Pipeline runner → Prediction evaluation: evaluates external data (evidence: `main.py`)
- Pipeline runner → Dose optimization: requests recommendations (evidence: `main.py`)
- Dose optimization → GRU PK model: predicts with (evidence: `src/dose_optimization.py`)
- Pipeline runner → Prediction CSVs: writes predictions (evidence: `main.py`)
- Pipeline runner → Model artifacts: saves weights (evidence: `main.py`)
- Pipeline operator → Prediction CSVs: receives results (evidence: `README.md`)
