# terry07/instance-based-zsl architecture

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

- Interactive diagram: https://gitdiagram.com/terry07/instance-based-zsl
- Repository: https://github.com/terry07/instance-based-zsl

## Overview

##### Project Type and Purpose
- This is a research-code pipeline (no web front end) implementing an online zero-shot-learning algorithm (IBZSL) for semi-automatic MeSH indexing.
- It processes biomedical abstracts, computes embeddings and similarities, applies various oracle and baseline scenarios, and produces evaluation metrics and pickled results.

##### Top-Level Components
A. Source Data
– Raw text files (MeSH abstracts, label frequency CSVs, zero-shot test set)
B. Pre-processing Stage
– obtain_text_embeddings.py → bioBERT embeddings of each sentence
– calculate_similarities.py → cosine similarities between embeddings and labels
– compute_label_similarities_per_pair.py → pre-compute similarity dictionaries
– add_noisy_labels.py → generate noisy-label dictionary for imperfect oracle
C. Pre-computed Files Store
– Embedding pickles (known, novel, MTI labels)
– Similarity dictionaries (novel↔known, novel↔MTI)
– Label occurrence predictions
D. Core IBZSL Pipeline
1. record_label_similaritiy_scores.py
- Loads pre-computed similarities and known label vectors
- Produces per-instance DataFrames of novel-vs-existing label similarity scores
2. compute_weights_per_instance.py
- Applies Eq.6: extracts max similarity per novel label per instance
3. weighted_unweighted_approaches.py
- Implements weighted vs. unweighted RankScore (Eq.3)
4. occurence.py
- Checks actual label names in text segments → occurrence predictions
5. apply_occurence.py
- Merges ranking scores with occurrence filter to produce final label set
6. IBZSL_evaluate.py
- Computes Coverage and 1-error metrics, generates histograms and stats
E. Alternative/Supporting Pipelines
– On-the-fly Baseline (NN_baseline_preprocess.py, NN_summary.py, NN_bioBERT_evaluate.py)
– MTI Tool integration (mti_output_manipulation.py → mti_predictions.pickle)
– Supervised Predictions Evaluator (Supervised predictions/evaluate_modes.py)
– Artificial Predictions for mode3 (CSV/Excel, noisy-labels pickles)
F. Results Archive
– “Results” folder organized by oracle type and baselines, storing final .pickle outputs
G. External Dependencies
– bioBERT (for embeddings)
– MTI online tool (for realistic oracle)
– Python 3.7.6, Numpy, Pandas, Spacy, Seaborn, Matplotlib

##### Relationships and Data Flow
Source Data → Pre-processing scripts → Pre-computed Files
Pre-computed Files → Core IBZSL Pipeline (record_… → compute_… → weighted_… → occurence → apply_occurrence → evaluate) → Results Archive
Parallel branches:
– On-the-fly Baseline branch uses embeddings & distances → NN_summary → NN_bioBERT_evaluate → Results/baselines
– MTI Tool branch: raw MTI output → mti_output_manipulation → mti_predictions.pickle → record_label_similarity_scores (realistic oracle scenario)
– Supervised Predictions branch → evaluate_modes.py → metrics
- Reuse: pre-computed dictionaries are consumed by multiple scripts.

##### Architectural Patterns and Principles
- Pipeline/Stage decomposition: each script is a self-contained stage producing pickles.
- Data-driven modularity: interchangeable oracles and baselines all plug into the same evaluate scripts.
- Avoid recomputation: large similarity/embedding computations are done once and stored.
- Clear separation of concerns: embedding, similarity, scoring, occurrence, evaluation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Sources"
        direction TB
        SourceData["Source Data"]:::data
        RawAbstracts["Raw MeSH abstracts"]:::data
        FrequencyCSV["Frequency CSV"]:::data
        ZeroShotSet["Zero-shot test set"]:::data
    end

    subgraph "Pre-processing Stages"
        direction TB
        ObtainEmbeddings["obtain_text_embeddings.py"]:::pre
        CalcSimilarities["calculate_similarities.py"]:::pre
        ComputePairs["compute_label_similarities_per_pair.py"]:::pre
        AddNoisy["add_noisy_labels.py"]:::pre
    end

    PrecomputedStore(("Pre-computed Files Store")):::datastore
    KnownEmb["known_labels_embeddings.pickle"]:::datastore
    NovelEmb["novel_labels_embeddings.pickle"]:::datastore
    MTIEmb["MTI_labels_embeddings.pickle"]:::datastore
    DictNovelKnown["dict_similarities_novel_known_labels.pickle"]:::datastore
    DictNovelMTI["dict_similarities_novel_MTI_labels.pickle"]:::datastore
    OccPred["predictions_label_occurence.pickle"]:::datastore

    subgraph "Core IBZSL Pipeline"
        direction TB
        RecordScores["record_label_similaritiy_scores.py"]:::core
        ComputeWeights["compute_weights_per_instance.py"]:::core
        RankScore["weighted_unweighted_approaches.py"]:::core
        Occurrence["occurence.py"]:::core
        ApplyOcc["apply_occurence.py"]:::core
        Evaluate["IBZSL_evaluate.py"]:::core
    end

    subgraph "On-the-fly Baseline Pipeline"
        direction TB
        NNPreprocess["NN_baseline_preprocess.py"]:::alt
        NNSummary["NN_summary.py"]:::alt
        NNEvaluate["NN_bioBERT_evaluate.py"]:::alt
    end

    subgraph "MTI Integration"
        direction TB
        MTITool["MTI Tool"]:::external
        MTIManip["mti_output_manipulation.py"]:::alt
        MTIPred["mti_predictions.pickle"]:::datastore
    end

    subgraph "Supervised Predictions"
        direction TB
        SupEval["evaluate_modes.py"]:::alt
        SupPickles["known_y_mode*.pickle"]:::datastore
    end

    Artificial["Artificial Predictions"]:::alt

    CoverageMetric["coverage_custom_metric.py"]:::alt

    ResultsArchive(("Results Archive")):::datastore

    %% Data flow
    SourceData --> RawAbstracts
    SourceData --> FrequencyCSV
    SourceData --> ZeroShotSet
    RawAbstracts --> ObtainEmbeddings
    FrequencyCSV --> CalcSimilarities
    ZeroShotSet --> ComputePairs
    RawAbstracts --> ComputePairs
    ObtainEmbeddings --> PrecomputedStore
    CalcSimilarities --> PrecomputedStore
    ComputePairs --> PrecomputedStore
    AddNoisy --> PrecomputedStore
    PrecomputedStore --> KnownEmb
    PrecomputedStore --> NovelEmb
    PrecomputedStore --> MTIEmb
    PrecomputedStore --> DictNovelKnown
    PrecomputedStore --> DictNovelMTI
    PrecomputedStore --> OccPred

    PrecomputedStore --> RecordScores
    RecordScores --> ComputeWeights
    ComputeWeights --> RankScore
    RankScore --> Occurrence
    Occurrence --> ApplyOcc
    ApplyOcc --> Evaluate
    Evaluate --> ResultsArchive

    %% On-the-fly baseline
    PrecomputedStore --> NNPreprocess
    NNPreprocess --> NNSummary
    NNSummary --> NNEvaluate
    NNEvaluate --> ResultsArchive

    %% MTI branch
    MTITool --> MTIManip
    MTIManip --> MTIPred
    MTIPred --> RecordScores

    %% Supervised branch
    SupPickles --> SupEval
    SupEval --> ResultsArchive

    %% Artificial
    Artificial --> SupEval

    %% Coverage metric
    CoverageMetric --> Evaluate

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000;
    classDef pre fill:#FFA500,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef alt fill:#DDA0DD,stroke:#000;
    classDef datastore fill:#D3D3D3,stroke:#000,stroke-dasharray: 5 5;
    classDef external fill:#FFFFE0,stroke:#000;

    %% Click Events
    click SourceData "https://github.com/terry07/instance-based-zsl/tree/master/source data/"
    click RawAbstracts "https://github.com/terry07/instance-based-zsl/blob/master/source data/abstracts from MeSH 2020 with top100 labels appeared.7z"
    click FrequencyCSV "https://github.com/terry07/instance-based-zsl/blob/master/source data/frequency_novel_labels_test_set_MeSH2020.csv"
    click ZeroShotSet "https://github.com/terry07/instance-based-zsl/blob/master/source data/pure_zero_shot_test_set_top100.7z"
    click ObtainEmbeddings "https://github.com/terry07/instance-based-zsl/blob/master/Pre-processing stages/obtain_text_embeddings.py"
    click CalcSimilarities "https://github.com/terry07/instance-based-zsl/blob/master/Pre-processing stages/calculate_similarities.py"
    click ComputePairs "https://github.com/terry07/instance-based-zsl/blob/master/Pre-processing stages/compute_label_similarities_per_pair.py"
    click AddNoisy "https://github.com/terry07/instance-based-zsl/blob/master/Pre-processing stages/add_noisy_labels.py"
    click PrecomputedStore "https://github.com/terry07/instance-based-zsl/tree/master/pre-computed files/"
    click KnownEmb "https://github.com/terry07/instance-based-zsl/blob/master/pre-computed files/known_labels_embeddings.pickle"
    click NovelEmb "https://github.com/terry07/instance-based-zsl/blob/master/pre-computed files/novel_labels_embeddings.pickle"
    click MTIEmb "https://github.com/terry07/instance-based-zsl/blob/master/pre-computed files/MTI_labels_embeddings.pickle"
    click DictNovelKnown "https://github.com/terry07/instance-based-zsl/blob/master/pre-computed files/dict_similarities_novel_known_labels.pickle"
    click DictNovelMTI "https://github.com/terry07/instance-based-zsl/blob/master/pre-computed files/dict_similarities_novel_MTI_labels.pickle"
    click OccPred "https://github.com/terry07/instance-based-zsl/blob/master/pre-computed files/predictions_label_occurence.pickle"
    click RecordScores "https://github.com/terry07/instance-based-zsl/blob/master/IBZSL/record_label_similaritiy_scores.py"
    click ComputeWeights "https://github.com/terry07/instance-based-zsl/blob/master/IBZSL/compute_weights_per_instance.py"
    click RankScore "https://github.com/terry07/instance-based-zsl/blob/master/IBZSL/weighted_unweighted_approaches.py"
    click Occurrence "https://github.com/terry07/instance-based-zsl/blob/master/IBZSL/occurence.py"
    click ApplyOcc "https://github.com/terry07/instance-based-zsl/blob/master/IBZSL/apply_occurence.py"
    click Evaluate "https://github.com/terry07/instance-based-zsl/blob/master/IBZSL/IBZSL_evaluate.py"
    click NNPreprocess "https://github.com/terry07/instance-based-zsl/blob/master/on-the-fly baseline/NN_baseline_preprocess.py"
    click NNSummary "https://github.com/terry07/instance-based-zsl/blob/master/on-the-fly baseline/NN_summary.py"
    click NNEvaluate "https://github.com/terry07/instance-based-zsl/blob/master/on-the-fly baseline/NN_bioBERT_evaluate.py"
    click MTIManip "https://github.com/terry07/instance-based-zsl/blob/master/MTI/mti_output_manipulation.py"
    click MTIPred "https://github.com/terry07/instance-based-zsl/blob/master/MTI/mti_predictions.pickle"
    click SupEval "https://github.com/terry07/instance-based-zsl/blob/master/Supervised predictions/evaluate_modes.py"
    click SupPickles "https://github.com/terry07/instance-based-zsl/blob/master/Supervised predictions/known_y_mode*.pickle"
    click CoverageMetric "https://github.com/terry07/instance-based-zsl/blob/master/coverage metric/coverage_custom_metric.py"
    click ResultsArchive "https://github.com/terry07/instance-based-zsl/tree/master/Results/"
```
