# whiffe/scb-dataset architecture

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

- Interactive diagram: https://gitdiagram.com/whiffe/scb-dataset
- Repository: https://github.com/whiffe/scb-dataset

## Overview

##### Project type and purpose
- This is a research-oriented, modular Python toolkit for detecting and analyzing student classroom behaviors.
- It contains data-preprocessing scripts, model-training code (YOLOv7+Biformer, LSTM), evaluation modules (rule-based & neural), similarity-calculation utilities, and visualization tools.

##### File structure
Top-level directories define major functional areas:
- Data Preparation
– yolo2ava/* (video→frame extraction, AVA annotation conversion)
– SCB_extend_ava/img2video.py (extend dataset via videos)
– FPS_IOU_png2jpg_yaml/* (image format conversion, YAML configs, FPS & IOU benchmarks for YOLO variants)
- Model Training & Inference
– YOLOv7+Biformer/* (detection code, model scripts)
– EvaluationMethod/LSTM/* (Jupyter notebooks & Python scripts for sequence modeling)
- Rule-based & Statistical Evaluation
– EvaluationMethod/Rule-based assessment…/* (behavior rule scripts, CSV data merges, down-video generation)
- Similarity Calculation
– Behavior-Similarity-Calculation/*.py (compute behavioral‐sequence similarity, image filtering)
- Analysis & Visualization
– Student_Behavioral_Concentration_Analysis/* (Excel‐driven analysis scripts)
– figures/*.py (stacked bar chart generator)
– yolo-gradcam/*.py (heatmap visualization for YOLOv5/7/8)

##### Extract additional insights from the README
- Focus is on the SCB-dataset and related open datasets (STBD-08, ClaBehavior, etc.)
- Emphasis on dataset links, paper citations, dataset statistics
- No web service or front-end—pure research pipelines

1. External Dataset Sources (Baidu, Roboflow, paid websites)
2. Data Ingestion & Conversion
- yolo2ava, SCB_extend_ava, FPS_IOU_png2jpg_yaml (png2jpg, YAML gen)
3. Data Storage
- Video files, frame directories, CSV/Excel annotation stores
4. Model Training Modules
- YOLOv7+Biformer, LSTM notebooks
5. Inference & Detection Output
- Trained weights, detection logs, JSON/CSV outputs
6. Evaluation & Metrics
- Rule-based folder, LSTM eval, behavior-similarity calculation
7. Analysis & Visualization
- yolo-gradcam heatmaps, figures/*.py charts
8. Results & Reports
- Summary CSVs, generated down-videos, Excel sheets

– External Datasets → Data Ingestion
– Ingestion → Data Storage → Model Training
– Trained Models → Inference → Detection Output
– Detection Output → Evaluation Modules → Metrics
– Metrics → Similarity Calculation & Analysis → Visualization
– Visualization → Final Reports

c. Architectural patterns & principles:
- Pipeline pattern (linear data flow from raw inputs to reports)
- Modular separation: preprocessing, modeling, evaluation, visualization

d. Key technologies & frameworks:
- Python scripts & Jupyter notebooks
- YOLOv7 (PyTorch) + custom Biformer head
- LSTM implementations (Keras/PyTorch)
- Rule-based Python logic for behavior assessment
- OpenCV / ffmpeg (video↔frame)
- Pandas / Excel for analysis
- Matplotlib / Grad-CAM for visualization

##### Detail
- Every folder/script group as its own component.
- Intermediate data artifacts (frames, YAML configs, CSVs).
- External dataset sources and model-weights repositories as boundary elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Sources
    ExtDatasets["External Dataset Sources"]:::external
    ExtModels["Pre-trained Model Weights"]:::external

    %% Data Ingestion & Conversion
    subgraph "Data Ingestion & Conversion"
        DI1["yolo2ava/"]:::ingestion
        DI2["ava2SCB_behavior.py"]:::ingestion
        DI3["extractFrames.sh"]:::ingestion
        DI4["yolo2ava.py"]:::ingestion
        DI5["SCB_extend_ava/img2video.py"]:::ingestion
        DI6["PNG→JPG Conversion"]:::ingestion
        DI7["HRW.yaml"]:::ingestion
        DI8["risehand.yaml"]:::ingestion
        DI9["fps_yolov5.py"]:::ingestion
        DI10["general.py (EIoU)"]:::ingestion
        DI11["loss.py (EIoU)"]:::ingestion
        DI12["general.py (FocalEIoU)"]:::ingestion
        DI13["loss.py (FocalEIoU)"]:::ingestion
        DI14["general.py (Wise-IOU)"]:::ingestion
        DI15["loss.py (Wise-IOU)"]:::ingestion
    end

    %% Data Storage
    subgraph "Data Storage"
        DS1["Video Files"]:::storage
        DS2["Frame Directories"]:::storage
        DS3["CSV/Excel Annotations"]:::storage
    end

    %% Model Training & Inference
    subgraph "Model Training & Inference"
        MT1["yolo.py"]:::training
        MT2["Biformer.py"]:::training
        MT3["common.py"]:::training
        MT4["LSTM.ipynb"]:::training
        MT5["LSTM2.ipynb"]:::training
        MT6["LSTM.py"]:::training
    end

    %% Inference & Detection Output
    subgraph "Inference & Detection Output"
        INF1["Detection Logs"]:::training
        INF2["JSON/CSV Outputs"]:::training
        INF3["Trained Weights"]:::training
    end

    %% Evaluation & Metrics
    subgraph "Evaluation & Metrics"
        EV1["Rule-based Scripts"]:::evaluation
        EV2["focus_seq.csv"]:::evaluation
        EV3["dataMerge.py"]:::evaluation
        EV4["analyse.py"]:::evaluation
        EV5["generate_down_videos3.py"]:::evaluation
        EV6["behavior_analysis.py"]:::evaluation
        EV7["focus_summary.csv"]:::evaluation
    end

    %% Similarity Calculation & Analysis
    subgraph "Similarity & Analysis"
        SA1["BehaviorSimilarityCalculation.py"]:::analysis
        SA2["filterImage.py"]:::analysis
        SA3["behavior_analysis.py"]:::analysis
        SA4["behavior.xlsx"]:::analysis
    end

    %% Visualization Tools
    subgraph "Visualization"
        VIZ1["Classes-bar-chart-stacked.py"]:::analysis
        VIZ2["yolov5_heatmap.py"]:::analysis
        VIZ3["yolov7_heatmap.py"]:::analysis
        VIZ4["yolov8_heatmap.py"]:::analysis
    end

    %% Results & Reports
    subgraph "Results & Reports"
        R1["Summary CSVs"]:::external
        R2["Down-videos"]:::external
        R3["Excel Reports"]:::external
    end

    %% Data Flow
    ExtDatasets -->|ingest| DI1
    ExtDatasets --> DI5
    DI1 --> DI2 --> DI3 --> DI4
    DI1 --> DS1
    DI3 --> DS2
    DI4 --> DS3
    DI5 --> DS1
    DS1 --> MT1
    DS2 --> MT4
    DS3 --> MT4
    ExtModels --> MT1
    MT1 --> INF3
    MT2 --> INF3
    MT3 --> MT1
    MT3 --> MT2
    MT1 --> INF1
    INF1 --> EV1
    INF2 --> EV1
    INF2 --> EV6
    EV1 --> EV3 --> EV4 --> EV5 --> R2
    EV6 --> R1
    EV7 --> R1
    EV4 --> SA1 --> SA2 --> SA3 --> VIZ1 --> R3
    SA1 --> VIZ2
    SA1 --> VIZ3
    SA1 --> VIZ4

    %% Click Events
    click DI1 "https://github.com/whiffe/scb-dataset/tree/main/yolo2ava/"
    click DI2 "https://github.com/whiffe/scb-dataset/blob/main/yolo2ava/ava2SCB_behavior.py"
    click DI3 "https://github.com/whiffe/scb-dataset/blob/main/yolo2ava/extractFrames.sh"
    click DI4 "https://github.com/whiffe/scb-dataset/blob/main/yolo2ava/yolo2ava.py"
    click DI5 "https://github.com/whiffe/scb-dataset/blob/main/SCB_extend_ava/img2video.py"
    click DI6 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/png2jpg/png2jpg.py"
    click DI7 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/yaml/HRW.yaml"
    click DI8 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/yaml/risehand.yaml"
    click DI9 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/FPS/fps_yolov5.py"
    click DI10 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/IOU/YOLOv7+EIoU/general.py"
    click DI11 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/IOU/YOLOv7+EIoU/loss.py"
    click DI12 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/IOU/YOLOv7+FocalEIoU/general.py"
    click DI13 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/IOU/YOLOv7+FocalEIoU/loss.py"
    click DI14 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/IOU/YOLOv7+Wise-IOU/general.py"
    click DI15 "https://github.com/whiffe/scb-dataset/blob/main/FPS_IOU_png2jpg_yaml/IOU/YOLOv7+Wise-IOU/loss.py"
    click MT1 "https://github.com/whiffe/scb-dataset/blob/main/YOLOv7+Biformer/yolo.py"
    click MT2 "https://github.com/whiffe/scb-dataset/blob/main/YOLOv7+Biformer/Biformer.py"
    click MT3 "https://github.com/whiffe/scb-dataset/blob/main/YOLOv7+Biformer/common.py"
    click MT4 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/LSTM/LSTM.ipynb"
    click MT5 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/LSTM/LSTM2.ipynb"
    click MT6 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/LSTM/LSTM.py"
    click EV1 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/Rule-based assessment of student behavior/behavio‌​r_seq.py"
    click EV2 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/Rule-based assessment of student behavior/focus_seq.csv"
    click EV3 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/Rule-based assessment of student behavior/dataMerge.py"
    click EV4 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/Rule-based assessment of student behavior/analyse.py"
    click EV5 "https://github.com/whiffe/scb-dataset/blob/main/EvaluationMethod/Rule-based assessment of student behavior/generate_down_videos3.py"
    click SA1 "https://github.com/whiffe/scb-dataset/blob/main/Behavior-Similarity-Calculation/BehaviorSimilarityCalculation.py"
    click SA2 "https://github.com/whiffe/scb-dataset/blob/main/Behavior-Similarity-Calculation/filterImage.py"
    click SA3 "https://github.com/whiffe/scb-dataset/blob/main/Student_Behavioral_Concentration_Analysis/behavior_analysis.py"
    click SA4 "https://github.com/whiffe/scb-dataset/blob/main/Student_Behavioral_Concentration_Analysis/behavior.xlsx"
    click VIZ1 "https://github.com/whiffe/scb-dataset/blob/main/figures/Classes-bar-chart-stacked.py"
    click VIZ2 "https://github.com/whiffe/scb-dataset/blob/main/yolo-gradcam/yolov5_heatmap.py"
    click VIZ3 "https://github.com/whiffe/scb-dataset/blob/main/yolo-gradcam/yolov7_heatmap.py"
    click VIZ4 "https://github.com/whiffe/scb-dataset/blob/main/yolo-gradcam/yolov8_heatmap.py"

    %% Styles
    classDef ingestion fill:#B3E5FC,stroke:#0288D1,color:#01579B;
    classDef storage fill:#E1F5FE,stroke:#0277BD,color:#01579B;
    classDef training fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20;
    classDef evaluation fill:#FFE0B2,stroke:#EF6C00,color:#E65100;
    classDef analysis fill:#E1BEE7,stroke:#8E24AA,color:#6A1B9A;
    classDef external fill:#ECEFF1,stroke:#546E7A,color:#37474F;
```
