Update README.md

README.md

@@ -12,4 +12,90 @@ base_model:
 pipeline_tag: image-classification
 tags:
 - geotechnics
----
+---
+
+# 🪨 Core Sample Secondary Fraction Classifier
+
+This multi-label classification model was fine-tuned for automated visual analysis of soil core samples, and trained / validated / tested on the `grano1/core_sample_image_data` dataset available via the HuggingFace eco-system. The model aims to predict one of the following nine class labels - termed in accordance with DIN 4023 - from cropped core sample images (300x300 pixels):
+- very gravelly | gravelly (g* | g)
+- very sandy | sandy (s* | s)
+- very silty | silty (u* | u)
+- very clayey | clayey (t* | t)
+- stony (x)
+
+## 📊 Metrics
+
+The following table summarizes selected metrics quantifying the model performance on the test set:
+
+| 📈 Metric                          | Value  |
+|------------------------------------|--------|
+| Binary Cross-Entropy Loss          | 0.1146 |
+| Subset Accuracy                    | 0.7606 |
+| F1-score (macro, aggregated)       | 0.7734 |
+| F1-score (weighted, aggregated)    | 0.8124 |
+| Hamming Loss                       | 0.0363 |
+
+## ⚙️ Hyperparameters
+
+The following table summarizes selected hyperparameters used for training the model:
+
+| Metric                    | Value    |
+|---------------------------|----------|
+| Batch size                | 16       |
+| Optimizer                 | AdamW    |
+| Warm-up ratio             | 0.1      |
+| Metric for best model     | Bin. CE  |
+| Early stopping patience   | 3        |
+| Threshold                 | 0.3      |
+
+## 🚀 Usage
+
+```python
+# Load the dataset
+data_dataset = load_dataset("grano1/core_sample_image_data")
+
+# Load image processor and model
+processor = AutoImageProcessor.from_pretrained("grano1/core_sample_image_secondary_fraction_model")
+model = AutoModelForImageClassification.from_pretrained("grano1/core_sample_image_secondary_fraction_model")
+model.eval()  # Set model to evaluation mode
+
+# Show sample features
+data_dataset["test"].features
+
+# Select sample from test set
+split = "test"
+sample = data_dataset[split][5]  # Pick one sample
+image = sample["image"]
+
+# Prepare input for model
+inputs = processor(images=image, return_tensors="pt")
+
+# Run inference
+with torch.no_grad():
+    outputs = model(**inputs)
+    logits = outputs.logits
+    predicted_class = logits.argmax(dim=1).item()
+print(sample)
+
+# Get predicted and true label name
+id2label = model.config.id2label
+label2id = model.config.label2id
+predicted_label_name = id2label[predicted_class]
+
+# Show result
+print(f"✅ Predicted label: {predicted_label_name}")
+print(f"🧾 True label:      {sample['NB']}")
+
+# Display image
+plt.imshow(sample['image'])
+plt.axis('off')  # Hide axes
+plt.show()
+```
+
+## 🔒 Limitations
+The `grano1/core_sample_image_data` dataset includes more `NB` labels than the nine identified by this model. This may require data cleansing procedures, e.g., s' (slightly sandy) label has been removed. Instructions can be found in the citation documented below.
+
+## ✨ Citation
+If you use this model, please cite:
+
+@thesis{Granitzer2025, author = {Andreas-Nizar Granitzer}, title = {Data-centric core sample classification and constitutive model selection in geotechnics}, school = {University of Applied Sciences Kufstein}, year = {2025}, type = {Master's thesis} }