How aimbotparce/mds-mud-namedentityrecognition works
Project Type and Purpose
• This is a domain-specific NLP pipeline for Named Entity Recognition (NER) on drug-related text, implementing two parallel approaches:
• A classical ML pipeline under ml/ (feature extraction → model training → prediction → evaluation)
• A neural network pipeline under nn/ (dataset tensorization → model training → prediction → evaluation)
• It operates on XML documents from a Drug-Drug Interaction dataset (split into train, devel, test in data/) and produces BIO-tagged entity labels.
File Structure Analysis
• Top-level directories:
• data/ (raw XML data for train, validation, test)
• ml/ (feature-based pipeline + subfolder src/models/ for CRF, Naive Bayes, custom models)
• nn/ (deep learning pipeline: dataset, codemaps, train/predict/evaluate scripts)
• .github/ (CI workflows and helper scripts)
• Root scripts: run-ml.sh, run-nn.sh (orchestrate the two pipelines)
• requirements.txt (Python dependencies)
• Separation of concerns: data vs. classical-ML vs. NN vs. CI.
README Insights
• Explains B-I-O tagging strategy and entity classes (drug_n, drug, group, brand).
• Describes the sequential steps in each pipeline: extraction → train → predict → evaluate.
• Mentions GitHub Actions workflow (.github/workflows/benchmark-on-pr.yaml) that runs the full pipeline on every PR.
• Preprocessing Modules:
• ML Feature Extractor (ml/extract-features.py)
• NN Dataset Builder (nn/dataset.py)
• Model Training Engines:
• Classical ML Trainer (ml/train.py)
• Neural Net Trainer (nn/train.py)
• Prediction Engines:
• ML Predictor (ml/predict.py)
• NN Predictor (nn/predict.py)
• Evaluation Modules:
• ML Evaluator (ml/evaluator.py)
• NN Evaluator (nn/evaluator.py)
• Orchestration: Shell scripts (run-ml.sh, run-nn.sh) & GitHub Actions (.github/workflows/benchmark-on-pr.yaml)
• Artifacts/Outputs: Model files, code maps, prediction/tag files, evaluation reports.
1. Data Layer → Preprocessing
2. Preprocessing → Model Training
3. Trained Model → Prediction Engine
4. Prediction + Ground Truth → Evaluation
5. Orchestration Layer triggers each step in sequence
6. CI/CD (GitHub Actions) triggers Orchestration on push/PR and captures logs/stats
c. Architectural Patterns & Principles:
• Pipeline (linear workflows for ML and NN)
• Modular separation of preprocessing, training, prediction, evaluation
• Parallel “experiments” branches pattern: ML vs. NN as interchangeable strategies
• Reproducibility via scripts and CI
d. Key Technologies & Frameworks:
• Python 3.x, requirements.txt
• scikit-learn / CRFs for ML (ml/src/models/CRF.py, multinomial_nb.py)
• Custom ML models (ml/src/models/custom.py)
• PyTorch or TensorFlow (implied in nn/)
• Bash scripts (run-ml.sh, run-nn.sh, .github/scripts/read_stats.bash)
• GitHub Actions for CI (.github/workflows/benchmark-on-pr.yaml)