Update README.md

README.md

@@ -1,23 +1,242 @@
 # Classical ML — Lithology Sequence Models
 
-Trained on [NoraResearchLab/Lithology-Training-Dataset](https://huggingface.co/datasets/NoraResearchLab/Lithology-Training-Dataset) (400 wells).
+Classical machine-learning baselines for automated lithological sequence identification from well-log data.
+
+The models are trained on the **NoraResearchLab/Lithology-Training-Dataset** containing 400 wells and evaluated on the independent **NoraResearchLab/lithology-sequence-benchmark**.
+
+The workflow performs pointwise lithology classification followed by minimum-thickness segmentation to produce geological sequences. Evaluation therefore considers both individual depth-point predictions and the resulting lithological sequences.
+
+## Research Organization
+
+Developed by **NORA Research Lab** — building intelligence for the real world.
+
+[![GitHub](https://img.shields.io/badge/GitHub-Nora--Research--Lab-181717?logo=github)](https://github.com/Nora-Research-Lab)
+[![Hugging Face](https://img.shields.io/badge/HuggingFace-NoraResearchLab-FFD21E?logo=huggingface\&logoColor=black)](https://huggingface.co/NoraResearchLab)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-NORA%20Research%20Lab-0A66C2?logo=linkedin)](https://www.linkedin.com/company/nora-research-lab)
+[![X](https://img.shields.io/badge/X-@noraresearchlab-000000?logo=x)](https://x.com/noraresearchlab)
+[![Website](https://img.shields.io/badge/Website-noraresearchlab.site-2ea44f)](https://noraresearchlab.site)
+
+---
+
+## Datasets
+
+### Training Dataset
+
+The models were trained using:
+
+**[NoraResearchLab/Lithology-Training-Dataset](https://huggingface.co/datasets/NoraResearchLab/Lithology-Training-Dataset)**
+
+* 400 wells
+* Well-log based lithology data
+* Used exclusively for model development and training
+
+### Independent Benchmark
+
+The trained models were subsequently evaluated on:
+
+**[NoraResearchLab/lithology-sequence-benchmark](https://huggingface.co/datasets/NoraResearchLab/lithology-sequence-benchmark)**
+
+This benchmark provides an independent evaluation of lithology-sequence generalization to wells that were not used during model training.
+
+This separation between the training dataset and benchmark is important because performance on previously unseen wells provides a more realistic indication of model generalization.
+
+---
 
 ## Models
-- `models/random_forest.joblib`
-- `models/xgboost.joblib`
-- `models/lightgbm.joblib`
 
-## Test metrics
+Three classical machine-learning models were trained:
+
+* `models/random_forest.joblib`
+* `models/xgboost.joblib`
+* `models/lightgbm.joblib`
+
+Corresponding hyperparameters are available in:
+
+* `models/random_forest_params.json`
+* `models/xgboost_params.json`
+* `models/lightgbm_params.json`
+
+---
+
+## Input Features
+
+The models use the following well-log features:
+
+* Gamma Ray (`GR`)
+* Bulk Density (`RHOB`)
+* Neutron Porosity (`NPHI`)
+* Photoelectric Factor (`PEF`)
+* Compressional Sonic (`DT`)
+* Log-transformed Resistivity (`log10(RT)`)
+* Caliper (`CALI`)
+* Missingness indicators
+
+The workflow uses these measurements to perform pointwise lithology classification along the well depth axis.
+
+---
+
+## Evaluation Pipeline
+
+The evaluation consists of two main stages:
+
+```text
+Well Logs
+    ↓
+Feature Preparation
+    ↓
+Pointwise Lithology Classification
+    ↓
+Minimum-Thickness Segmentation
+    ↓
+Lithological Sequences
+    ↓
+Depth-Level + Sequence-Level Evaluation
 ```
- n_wells  depth_accuracy  depth_macro_f1  depth_macro_f1_confident  sequence_similarity        model  cv_macro_f1
-      66        0.791402        0.627933                  0.590043             0.592659 RandomForest     0.759859
-      66        0.727141        0.575679                  0.529313             0.517252      XGBoost     0.757091
-      66        0.693573        0.532102                  0.483444             0.481821     LightGBM     0.726568
+
+The minimum-thickness segmentation step converts individual depth predictions into continuous geological intervals, allowing the models to be evaluated not only on individual samples but also on the resulting lithological sequence.
+
+---
+
+# Benchmark Results
+
+The models were evaluated on **66 independent wells** from the lithology sequence benchmark.
+
+| Model             | Depth Accuracy | Depth Macro F1 | Confident Macro F1 | Sequence Similarity | CV Macro F1 |
+| ----------------- | -------------: | -------------: | -----------------: | ------------------: | ----------: |
+| **Random Forest** |     **0.7914** |     **0.6279** |         **0.5900** |          **0.5927** |  **0.7599** |
+| **XGBoost**       |         0.7271 |         0.5757 |             0.5293 |              0.5173 |      0.7571 |
+| **LightGBM**      |         0.6936 |         0.5321 |             0.4834 |              0.4818 |      0.7266 |
+
+### Interpretation
+
+On the independent 66-well benchmark, Random Forest achieved the highest depth-level accuracy, macro F1, confident macro F1, and sequence similarity among the three evaluated models.
+
+The results show that strong cross-validation performance does not necessarily translate directly into equivalent performance on independent wells. This is particularly relevant for subsurface machine learning, where geological setting, depositional environment, logging conditions, and formation properties can vary substantially between wells.
+
+---
+
+# Blind-Well Generalization Test
+
+In addition to the 66-well benchmark, the models were evaluated on a completely unseen blind well (`16_2-7.csv`).
+
+| Model             | Original Training Benchmark | Blind Test Well Accuracy |  Approx. Performance Gap |
+| ----------------- | --------------------------: | -----------------------: | -----------------------: |
+| **Random Forest** |                     ~85–90% |               **60.17%** | ~25–30 percentage points |
+| **XGBoost**       |                     ~88–91% |               **44.95%** | ~43–46 percentage points |
+| **LightGBM**      |                     ~89–92% |               **40.65%** | ~48–51 percentage points |
+
+These values represent a separate blind-well experiment and should not be directly substituted for the 66-well benchmark metrics above.
+
+The blind-well experiment demonstrates the importance of testing lithology models on genuinely unseen geological conditions rather than relying exclusively on conventional validation splits.
+
+---
+
+# Key Research Findings
+
+### 1. Generalization is substantially harder than within-dataset validation
+
+The difference between validation performance and performance on independent wells indicates that the models learn relationships that do not necessarily transfer perfectly across geological settings.
+
+For lithology prediction, this can arise from differences in formation properties, depositional environments, logging tools, acquisition conditions, depth distributions, and the statistical distribution of log responses between wells.
+
+### 2. Random Forest showed stronger independent-well performance
+
+Random Forest produced the strongest results across the principal metrics in the 66-well benchmark:
+
+* **79.14% depth accuracy**
+* **0.628 depth macro F1**
+* **0.590 confident macro F1**
+* **0.593 sequence similarity**
+
+It also achieved the highest accuracy in the separate blind-well experiment at **60.17%**.
+
+This does not establish that Random Forest will universally outperform boosting methods, but it indicates that it was the most robust of the three models under these particular evaluation conditions.
+
+### 3. Boosting models showed larger degradation on the blind well
+
+XGBoost and LightGBM achieved strong cross-validation results but experienced substantial degradation on the independent blind well.
+
+This suggests that the relationships learned from the training wells may not transfer consistently to the feature distributions encountered in the blind well.
+
+### 4. Sandstone remains a significant classification challenge
+
+The blind-well analysis showed particularly weak sandstone recall across the evaluated models despite substantially stronger performance during training/validation.
+
+This suggests that the petrophysical signature of sandstone in the blind well differs from the patterns represented in the training wells.
+
+Potential contributing factors include differences in:
+
+* Gamma Ray response
+* Density
+* Neutron porosity
+* Resistivity
+* Compaction
+* Depositional environment
+* Formation composition
+* Logging/acquisition conditions
+
+This makes sandstone generalization an important area for further investigation.
+
+---
+
+# Research Implications
+
+These experiments highlight an important issue in automated lithology prediction:
+
+> **High validation performance does not necessarily imply strong geological generalization.**
+
+A model can perform well when evaluated on data statistically similar to its training wells while experiencing substantial performance degradation when exposed to a genuinely independent well.
+
+For this reason, future versions of the benchmark should emphasize:
+
+* Well-level separation between training and evaluation data
+* Geographic and geological diversity
+* Cross-basin evaluation
+* Completely held-out wells
+* Class-specific performance
+* Sequence-level similarity
+* Robustness to missing logs
+* Distribution-shift analysis
+* Calibration and uncertainty estimation
+
+The benchmark is therefore intended not simply to measure classification accuracy, but to investigate how well lithology models transfer across independent subsurface environments.
+
+---
+
+# Reproducibility
+
+The trained model artifacts are provided in the `models/` directory.
+
+```text
+models/
+├── random_forest.joblib
+├── random_forest_params.json
+├── xgboost.joblib
+├── xgboost_params.json
+├── lightgbm.joblib
+└── lightgbm_params.json
 ```
 
-## Features
-GR, RHOB, NPHI, PEF, DT, log10(RT), CALI + missingness indicators.
-Pointwise classification → min-thickness segmentation → sequence metrics.
+The training data and independent benchmark are publicly available through the NORA Research Lab Hugging Face organization.
+
+**Training dataset:**
+https://huggingface.co/datasets/NoraResearchLab/Lithology-Training-Dataset
+
+**Evaluation benchmark:**
+https://huggingface.co/datasets/NoraResearchLab/lithology-sequence-benchmark
+
+---
+
+# Citation
+
+If you use these models, datasets, or benchmark results in research, please cite the corresponding NORA Research Lab resources.
+
+## NORA Research Lab
+
+**Building intelligence for the real world.**
 
-## Hyperparameters
-See `models/*_params.json`.
+GitHub: https://github.com/Nora-Research-Lab
+Hugging Face: https://huggingface.co/NoraResearchLab
+LinkedIn: https://www.linkedin.com/company/nora-research-lab
+X: https://x.com/noraresearchlab
+Website: https://noraresearchlab.site