# nancy123a/ldsl-winter-school architecture

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

- Interactive diagram: https://gitdiagram.com/nancy123a/ldsl-winter-school
- Repository: https://github.com/nancy123a/ldsl-winter-school

## Overview

##### Project type and purpose
- This is an NLP/ML research project implemented as a training and evaluation pipeline for a convolutional neural network (CNN) that performs modal sense classification.
- Key indicators: a single Jupyter notebook (MSCtask_MASC_EN.ipynb), a README describing the CNN architecture and training details, and directories for logging.

##### File structure
Top-level items:
- MSCtask_MASC_EN.ipynb – the main notebook containing data loading, preprocessing, model definition, training loops, and evaluation.
- README.md – high-level description of the task, architecture, loss function, and dataset.
- log/ – directory for runtime logs (e.g., training loss, accuracy per epoch).
- log_file – possibly a flat file for serialized log outputs.
- yolo/ – a folder whose contents are unclear from the tree, but likely contains utility scripts or data submodules (treat it as an external or auxiliary component).

##### README
- Confirms the use of a CNN based on Germies (2020) for three-way classification: dynamic, epistemic, deontic.
- Indicates categorical cross-entropy loss and a custom dataset with uniform labels.

##### Components
a. Data Sources
- Raw dataset files (MASC_EN data)
b. Preprocessing Module
- Tokenization/embedding lookup
- Input formatting for CNN (e.g., sliding windows or sentence matrices)
c. Model Definition
- Convolutional layers, pooling layers, fully connected layers
- Loss function (categorical cross-entropy)
d. Training Pipeline
- Jupyter notebook orchestration
- Optimizer loop, checkpointing
e. Evaluation Module
- Test dataset evaluation
- Metrics calculation (accuracy, precision, recall)
f. Logging & Artifacts
- log/ directory for epoch logs
- log_file for consolidated run outputs
g. Auxiliary/External Components (yolo/)
- Any helper scripts, custom utility functions, or external data loaders

##### Relationships and interactions
- Model Definition ↔ Training Pipeline (forward pass, backpropagation)
- Training Pipeline → Logging & Artifacts (writes loss, accuracy per epoch)
- Trained Model → Evaluation Module → Logging & Artifacts (writes final metrics)
- Preprocessing Module ↔ Auxiliary Components (yolo/) if helpers are used

##### Architectural patterns & principles
- Linear pipeline (data→ preprocess→ train→ evaluate)
- Separation of concerns: keep preprocessing, model code, training orchestration, and logging in discrete modules
- Reproducibility: notebook plus logging directories for hyperparameter tracking and results

##### Detailed capture of architectural elements
- CNN block with layer types and dimensions (e.g., “Conv1D (kernel=3) → ReLU → MaxPool”)
- Checkpoints or model-save points in the Training Pipeline
- Categorical cross-entropy next to the loss node

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Components
    RawData["Raw Dataset Files"]:::data
    Labels["Label Definitions"]:::data

    %% Notebook Orchestration
    subgraph "Notebook Orchestration"
        Preprocess["Preprocessing Module"]:::compute
        ModelDef["Model Definition<br/>Conv1D→ReLU→MaxPool→FC"]:::compute
        TrainLoop["Training Pipeline<br/>(Optimizer loop, Checkpoints)"]:::compute
    end

    %% Evaluation
    Eval["Evaluation Module<br/>(Metrics: Accuracy, Precision, Recall)"]:::compute

    %% Artifacts & Logging
    LogsDir["log/ Directory"]:::artifact
    LogFile["log_file"]:::artifact
    ModelArtifact["Trained Model Weights"]:::artifact

    %% External
    YOLO["yolo/ Auxiliary Components"]:::external

    %% Data Flow
    RawData -->|"raw input"| Preprocess
    Labels -->|"label lookup"| Preprocess
    Preprocess -->|"formatted input"| ModelDef
    Preprocess <-->|"helper scripts"| YOLO
    ModelDef -->|"forward/backprop"| TrainLoop
    TrainLoop -->|"checkpoint save"| ModelArtifact
    TrainLoop -->|"epoch logs"| LogsDir
    TrainLoop -->|"run outputs"| LogFile
    ModelArtifact -->|"trained weights"| Eval
    RawData -->|"test input"| Eval
    Eval -->|"evaluation metrics"| LogsDir

    %% Click Events
    click Preprocess "https://github.com/nancy123a/ldsl-winter-school/blob/main/MSCtask_MASC_EN.ipynb"
    click ModelDef "https://github.com/nancy123a/ldsl-winter-school/blob/main/MSCtask_MASC_EN.ipynb"
    click TrainLoop "https://github.com/nancy123a/ldsl-winter-school/blob/main/MSCtask_MASC_EN.ipynb"
    click Eval "https://github.com/nancy123a/ldsl-winter-school/blob/main/MSCtask_MASC_EN.ipynb"
    click LogsDir "https://github.com/nancy123a/ldsl-winter-school/tree/main/log/"
    click LogFile "https://github.com/nancy123a/ldsl-winter-school/tree/main/log_file"
    click YOLO "https://github.com/nancy123a/ldsl-winter-school/tree/main/yolo/"

    %% Styles
    classDef data fill:#D0E6FF,stroke:#0366D6,color:#0366D6,stroke-width:1px
    classDef compute fill:#DFFFD6,stroke:#028A0F,color:#028A0F,stroke-width:1px
    classDef artifact fill:#FFE8A1,stroke:#E57200,color:#E57200,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555,stroke-width:1px
```
