How terry07/instance-based-zsl works
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.