# dhar7/compbioproject architecture

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

- Interactive diagram: https://gitdiagram.com/dhar7/compbioproject
- Repository: https://github.com/dhar7/compbioproject

## Overview

This repository implements a reproducible TCR–peptide–MHC negative-set research study. Its workflow prepares positive-pair and healthy-repertoire inputs, curates them into peptide-grouped folds, then runs model/control experiments and reports discrimination, chance thresholds, and uncertainty. Shared study utilities provide sampling, sequence encoding, training, and metrics. The tree also includes epiTCR and TITAN prediction-score utilities. Source excerpts show the main preparation and analysis calls; predictor replication details and some shared helpers are not shown, so those relationships are not inferred.

Main entry points: [`argha.py`](https://github.com/dhar7/compbioproject/blob/main/argha.py) (Control experiments), [`farhan.py`](https://github.com/dhar7/compbioproject/blob/main/farhan.py) (Curate and fold), [`prepare_data.py`](https://github.com/dhar7/compbioproject/blob/main/prepare_data.py) (Prepare inputs), [`data`](https://github.com/dhar7/compbioproject/tree/main/data) (Positive and repertoire tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Input preparation"]
  node_data_sources[("Study datasets")]
  node_prepare["Prepare inputs<br/>[prepare_data.py]"]
  node_prepared_tables[("Positive and repertoire tables")]
end

subgraph group_curation["Study curation"]
  node_farhan["Curate and fold<br/>[farhan.py]"]
  node_processed[("Processed folds")]
  node_shared["Shared study methods<br/>[study_common.py]"]
end

subgraph group_analysis["Model analysis"]
  node_argha["Control experiments<br/>[argha.py]"]
  node_encoder["Frozen ESM-2 encoder<br/>[study_common.py]"]
  node_splitter["Negative-set sampling<br/>[study_common.py]"]
  node_trainer["Control model training<br/>[study_common.py]"]
  node_evaluation["Metrics and uncertainty<br/>[study_common.py]"]
  node_study_results[("Study result tables")]
end

subgraph group_external["Predictor scoring"]
  node_epitcr_score["epiTCR score utility<br/>[score.py]"]
  node_titan_score["TITAN score utility<br/>[score.py]"]
end

node_prediction_files[("Prediction files")]

node_data_sources -->|"provides source files"| node_prepare
node_prepare -->|"writes tables"| node_prepared_tables
node_prepared_tables -->|"loads inputs"| node_farhan
node_farhan -->|"uses helpers"| node_shared
node_farhan -->|"writes folds"| node_processed
node_processed -->|"loads processed data"| node_argha
node_argha -->|"uses helpers"| node_shared
node_argha -->|"constructs encoder"| node_encoder
node_argha -->|"samples labeled splits"| node_splitter
node_argha -->|"fits controls"| node_trainer
node_argha -->|"computes metrics"| node_evaluation
node_argha -->|"writes summaries"| node_study_results
node_prediction_files -->|"reads predictions"| node_epitcr_score
node_prediction_files -->|"reads predictions"| node_titan_score

click node_data_sources "https://github.com/dhar7/compbioproject/tree/main/data"
click node_prepare "https://github.com/dhar7/compbioproject/blob/main/prepare_data.py"
click node_prepared_tables "https://github.com/dhar7/compbioproject/tree/main/data"
click node_farhan "https://github.com/dhar7/compbioproject/blob/main/farhan.py"
click node_processed "https://github.com/dhar7/compbioproject/tree/main/data/processed"
click node_shared "https://github.com/dhar7/compbioproject/blob/main/study_common.py"
click node_argha "https://github.com/dhar7/compbioproject/blob/main/argha.py"
click node_encoder "https://github.com/dhar7/compbioproject/blob/main/study_common.py"
click node_splitter "https://github.com/dhar7/compbioproject/blob/main/study_common.py"
click node_trainer "https://github.com/dhar7/compbioproject/blob/main/study_common.py"
click node_evaluation "https://github.com/dhar7/compbioproject/blob/main/study_common.py"
click node_study_results "https://github.com/dhar7/compbioproject/tree/main/outputs/argha"
click node_epitcr_score "https://github.com/dhar7/compbioproject/blob/main/tcr_predictors/epitcr/score.py"
click node_titan_score "https://github.com/dhar7/compbioproject/blob/main/tcr_predictors/titan/score.py"

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_data_sources,node_prepare,node_prepared_tables toneBlue
class node_farhan,node_processed,node_shared,node_prediction_files toneAmber
class node_argha,node_encoder,node_splitter,node_trainer,node_evaluation,node_study_results toneMint
class node_epitcr_score,node_titan_score toneRose
```

## Components

### Input preparation

- [Study datasets](https://github.com/dhar7/compbioproject/tree/main/data): `data`
- [Prepare inputs](https://github.com/dhar7/compbioproject/blob/main/prepare_data.py): `prepare_data.py`
- [Positive and repertoire tables](https://github.com/dhar7/compbioproject/tree/main/data): `data`

### Study curation

- [Curate and fold](https://github.com/dhar7/compbioproject/blob/main/farhan.py): `farhan.py`
- [Processed folds](https://github.com/dhar7/compbioproject/tree/main/data/processed): `data/processed`
- [Shared study methods](https://github.com/dhar7/compbioproject/blob/main/study_common.py): `study_common.py`

### Model analysis

- [Control experiments](https://github.com/dhar7/compbioproject/blob/main/argha.py): `argha.py`
- [Frozen ESM-2 encoder](https://github.com/dhar7/compbioproject/blob/main/study_common.py): `study_common.py`
- [Negative-set sampling](https://github.com/dhar7/compbioproject/blob/main/study_common.py): `study_common.py`
- [Control model training](https://github.com/dhar7/compbioproject/blob/main/study_common.py): `study_common.py`
- [Metrics and uncertainty](https://github.com/dhar7/compbioproject/blob/main/study_common.py): `study_common.py`
- [Study result tables](https://github.com/dhar7/compbioproject/tree/main/outputs/argha): `outputs/argha`

### Predictor scoring

- [epiTCR score utility](https://github.com/dhar7/compbioproject/blob/main/tcr_predictors/epitcr/score.py): `tcr_predictors/epitcr/score.py`
- [TITAN score utility](https://github.com/dhar7/compbioproject/blob/main/tcr_predictors/titan/score.py): `tcr_predictors/titan/score.py`

### Other components

- **Prediction files**

## Connections

- Study datasets → Prepare inputs: provides source files (evidence: `prepare_data.py`)
- Prepare inputs → Positive and repertoire tables: writes tables (evidence: `prepare_data.py`)
- Positive and repertoire tables → Curate and fold: loads inputs (evidence: `farhan.py`)
- Curate and fold → Shared study methods: uses helpers (evidence: `farhan.py`)
- Curate and fold → Processed folds: writes folds (evidence: `farhan.py`)
- Processed folds → Control experiments: loads processed data (evidence: `argha.py`)
- Control experiments → Shared study methods: uses helpers (evidence: `argha.py`)
- Control experiments → Frozen ESM-2 encoder: constructs encoder (evidence: `argha.py`)
- Control experiments → Negative-set sampling: samples labeled splits (evidence: `argha.py`)
- Control experiments → Control model training: fits controls (evidence: `argha.py`)
- Control experiments → Metrics and uncertainty: computes metrics (evidence: `argha.py`)
- Control experiments → Study result tables: writes summaries (evidence: `argha.py`)
- Prediction files → epiTCR score utility: reads predictions (evidence: `tcr_predictors/epitcr/score.py`)
- Prediction files → TITAN score utility: reads predictions (evidence: `tcr_predictors/titan/score.py`)
