# razaxq/frecs-net architecture

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

- Interactive diagram: https://gitdiagram.com/razaxq/frecs-net
- Repository: https://github.com/razaxq/frecs-net

## Overview

FReCS-Net is a Python research system for joint chest-X-ray and description segmentation. Its primary workflow reads paired images, masks and text, trains a configured LViT-derived FSDR/RACE model, selects checkpoints by validation IoU, then evaluates a matched checkpoint and exports segmentation metrics. The graph highlights the documented FSDR and RACE branches, training/evaluation and experiment configuration. Some subsystem wiring is inferred only from README-level descriptions because source excerpts are partial; uncertain call edges are omitted.

Main entry points: [`nets/LViT.py`](https://github.com/razaxq/frecs-net/blob/main/nets/LViT.py) (LViT encoder-decoder), [`train_model.py`](https://github.com/razaxq/frecs-net/blob/main/train_model.py) (Training entry), [`tools/export_validation_metrics.py`](https://github.com/razaxq/frecs-net/blob/main/tools/export_validation_metrics.py) (Validation metrics), [`tools/export_stage1_metrics.py`](https://github.com/razaxq/frecs-net/blob/main/tools/export_stage1_metrics.py) (Stage metrics export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data input"]
  node_dataset["Dataset loading<br/>[Load_Dataset.py]"]
end

subgraph group_model["Segmentation model"]
  node_backbone["LViT encoder-decoder<br/>[LViT.py]"]
  node_vit["Vision transformer<br/>[Vit.py]"]
  node_fsdr["FSDR refinement<br/>[fsdr.py]"]
  node_eppa["Frequency refinement<br/>[eppa.py]"]
  node_race["RACE evidence routing<br/>[race_fuse.py]"]
  node_race_pe["RACE auxiliary objective<br/>[race_pe.py]"]
  node_text["Text features<br/>[textlevel.py]"]
end

subgraph group_train["Training and selection"]
  node_train_entry["Training entry<br/>[train_model.py]"]
  node_epoch["Epoch training<br/>[Train_one_epoch.py]"]
  node_checkpoint["Checkpoint selection"]
end

subgraph group_eval["Evaluation"]
  node_validation["Validation metrics"]
  node_stage_export["Stage metrics export"]
  node_results["Metric results"]
end

subgraph group_experiment["Experiment setup"]
  node_config["Run configuration<br/>[Config.py]"]
  node_profiles["Experiment profiles"]
  node_recipe["Training recipe<br/>[training_recipe.py]"]
end

node_researcher(("Researcher"))
node_cxr_dataset[("QaTa-COV19 data")]
node_hf[("CXR-BERT weights")]

node_researcher -->|"starts training"| node_train_entry
node_researcher -->|"requests evaluation"| node_validation
node_cxr_dataset -->|"supplies samples"| node_dataset
node_dataset -->|"provides batches"| node_train_entry
node_config -->|"configures run"| node_train_entry
node_profiles -->|"selects profile"| node_config
node_recipe -->|"configures schedule"| node_train_entry
node_train_entry -.->|"loads text encoder"| node_hf
node_train_entry -->|"constructs model"| node_backbone
node_backbone -->|"encodes image"| node_vit
node_backbone -->|"refines features"| node_fsdr
node_backbone -->|"uses frequency refinement"| node_eppa
node_backbone -->|"routes evidence"| node_race
node_backbone -->|"encodes description"| node_text
node_race -.->|"supports auxiliary supervision"| node_race_pe
node_train_entry -->|"runs epochs"| node_epoch
node_epoch -->|"predicts masks"| node_backbone
node_train_entry -->|"selects best checkpoint"| node_checkpoint
node_checkpoint -->|"provides checkpoint"| node_validation
node_researcher -->|"requests registered evaluation"| node_stage_export
node_validation -->|"loads evaluation split"| node_dataset
node_stage_export -->|"loads authorized split"| node_dataset
node_validation -->|"runs inference"| node_backbone
node_stage_export -->|"runs inference"| node_backbone
node_validation -->|"exports metrics"| node_results
node_stage_export -->|"exports metrics"| node_results
node_results -->|"reports scores"| node_researcher

click node_config "https://github.com/razaxq/frecs-net/blob/main/Config.py"
click node_profiles "https://github.com/razaxq/frecs-net/blob/main/paper_experiments.py"
click node_recipe "https://github.com/razaxq/frecs-net/blob/main/training_recipe.py"
click node_dataset "https://github.com/razaxq/frecs-net/blob/main/Load_Dataset.py"
click node_backbone "https://github.com/razaxq/frecs-net/blob/main/nets/LViT.py"
click node_vit "https://github.com/razaxq/frecs-net/blob/main/nets/Vit.py"
click node_fsdr "https://github.com/razaxq/frecs-net/blob/main/nets/fsdr.py"
click node_eppa "https://github.com/razaxq/frecs-net/blob/main/nets/eppa.py"
click node_race "https://github.com/razaxq/frecs-net/blob/main/nets/race_fuse.py"
click node_race_pe "https://github.com/razaxq/frecs-net/blob/main/nets/race_pe.py"
click node_text "https://github.com/razaxq/frecs-net/blob/main/nets/textlevel.py"
click node_train_entry "https://github.com/razaxq/frecs-net/blob/main/train_model.py"
click node_epoch "https://github.com/razaxq/frecs-net/blob/main/Train_one_epoch.py"
click node_checkpoint "https://github.com/razaxq/frecs-net/blob/main/checkpoint_selection.py"
click node_validation "https://github.com/razaxq/frecs-net/blob/main/tools/export_validation_metrics.py"
click node_stage_export "https://github.com/razaxq/frecs-net/blob/main/tools/export_stage1_metrics.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_dataset toneBlue
class node_backbone,node_vit,node_fsdr,node_eppa,node_race,node_race_pe,node_text,node_cxr_dataset,node_hf toneAmber
class node_train_entry,node_epoch,node_checkpoint toneMint
class node_validation,node_stage_export,node_results toneRose
class node_config,node_profiles,node_recipe,node_researcher toneIndigo
```

## Components

### Data input

- [Dataset loading](https://github.com/razaxq/frecs-net/blob/main/Load_Dataset.py): `Load_Dataset.py`

### Segmentation model

- [LViT encoder-decoder](https://github.com/razaxq/frecs-net/blob/main/nets/LViT.py): `nets/LViT.py`
- [Vision transformer](https://github.com/razaxq/frecs-net/blob/main/nets/Vit.py): `nets/Vit.py`
- [FSDR refinement](https://github.com/razaxq/frecs-net/blob/main/nets/fsdr.py): `nets/fsdr.py`
- [Frequency refinement](https://github.com/razaxq/frecs-net/blob/main/nets/eppa.py): `nets/eppa.py`
- [RACE evidence routing](https://github.com/razaxq/frecs-net/blob/main/nets/race_fuse.py): `nets/race_fuse.py`
- [RACE auxiliary objective](https://github.com/razaxq/frecs-net/blob/main/nets/race_pe.py): `nets/race_pe.py`
- [Text features](https://github.com/razaxq/frecs-net/blob/main/nets/textlevel.py): `nets/textlevel.py`

### Training and selection

- [Training entry](https://github.com/razaxq/frecs-net/blob/main/train_model.py): `train_model.py`
- [Epoch training](https://github.com/razaxq/frecs-net/blob/main/Train_one_epoch.py): `Train_one_epoch.py`
- [Checkpoint selection](https://github.com/razaxq/frecs-net/blob/main/checkpoint_selection.py): `checkpoint_selection.py`

### Evaluation

- [Validation metrics](https://github.com/razaxq/frecs-net/blob/main/tools/export_validation_metrics.py): `tools/export_validation_metrics.py`
- [Stage metrics export](https://github.com/razaxq/frecs-net/blob/main/tools/export_stage1_metrics.py): `tools/export_stage1_metrics.py`
- **Metric results**

### Experiment setup

- [Run configuration](https://github.com/razaxq/frecs-net/blob/main/Config.py): `Config.py`
- [Experiment profiles](https://github.com/razaxq/frecs-net/blob/main/paper_experiments.py): `paper_experiments.py`
- [Training recipe](https://github.com/razaxq/frecs-net/blob/main/training_recipe.py): `training_recipe.py`

### Other components

- **Researcher**
- **QaTa-COV19 data**
- **CXR-BERT weights**

## Connections

- Researcher → Training entry: starts training
- Researcher → Validation metrics: requests evaluation
- QaTa-COV19 data → Dataset loading: supplies samples
- Dataset loading → Training entry: provides batches
- Run configuration → Training entry: configures run
- Experiment profiles → Run configuration: selects profile
- Training recipe → Training entry: configures schedule
- Training entry → CXR-BERT weights: loads text encoder
- Training entry → LViT encoder-decoder: constructs model
- LViT encoder-decoder → Vision transformer: encodes image
- LViT encoder-decoder → FSDR refinement: refines features
- LViT encoder-decoder → Frequency refinement: uses frequency refinement
- LViT encoder-decoder → RACE evidence routing: routes evidence
- LViT encoder-decoder → Text features: encodes description
- RACE evidence routing → RACE auxiliary objective: supports auxiliary supervision
- Training entry → Epoch training: runs epochs
- Epoch training → LViT encoder-decoder: predicts masks
- Training entry → Checkpoint selection: selects best checkpoint
- Checkpoint selection → Validation metrics: provides checkpoint
- Researcher → Stage metrics export: requests registered evaluation
- Validation metrics → Dataset loading: loads evaluation split
- Stage metrics export → Dataset loading: loads authorized split
- Validation metrics → LViT encoder-decoder: runs inference
- Stage metrics export → LViT encoder-decoder: runs inference
- Validation metrics → Metric results: exports metrics
- Stage metrics export → Metric results: exports metrics
- Metric results → Researcher: reports scores