Refine model card and add training guidance

README.md

@@ -8,7 +8,7 @@ tags:
 - mr-iqa
 ---
 
-# MR-IQA
+# MR-IQA: A Unified Margin View of Regression and Ranking for Blind Image Quality Assessment
 
 <p align="center">
   <a href="https://github.com/RobinY99/MR-IQA/blob/main/assets/mr_iqa_overview.pdf">
@@ -16,26 +16,10 @@ tags:
   </a>
 </p>
 
-<p align="center">
-  <strong>MR-IQA: A Unified Margin View for Image Quality Assessment</strong><br>
-  A compact vision-language checkpoint for margin-aware no-reference image quality scoring.
-</p>
-
-MR-IQA predicts perceptual image quality scores while preserving calibrated score margins between images. The training objective uses distributional margin consistency: it compares the model's predicted score gap with the human opinion gap normalized by annotation uncertainty. This helps the model learn not only which image should score higher, but also how far apart two scores should be.
+We derive that regression and ranking are approximately equivalent under a unified margin view. Based on this observation, we propose MR-IQA for margin learning in blind image quality assessment.
 
 The overview PDF and repository code are available on [GitHub](https://github.com/RobinY99/MR-IQA).
 
-## Why MR-IQA
-
-MR-IQA is designed for practical image quality assessment when reference images are unavailable. It provides direct perceptual scoring, stable numeric outputs, and simple integration into evaluation pipelines.
-
-Typical use cases include:
-
-- Ranking generated, restored, or compressed images by perceptual quality.
-- Auditing image datasets before training or release.
-- Comparing image enhancement or restoration systems.
-- Adding an interpretable quality signal to automated review workflows.
-
 ## Validation Snapshot
 
 The released checkpoint was evaluated with an 8-shard validation setup on a held-out KONIQ split.
@@ -44,7 +28,7 @@ The released checkpoint was evaluated with an 8-shard validation setup on a held
 | --- | ---: | ---: | ---: | ---: |
 | KONIQ validation | 200 | 0.9251 | 0.9421 | 8 |
 
-Higher SRCC indicates better rank consistency with human judgments. Higher PLCC indicates better linear agreement after score calibration.
+The per-epoch validation curve and sanitized training metadata are available in [`training_guidance/`](training_guidance/).
 
 ## Quick Start
 

training_guidance/README.md

@@ -0,0 +1,11 @@
+# Training Guidance
+
+This folder provides sanitized training-process metadata for the released MR-IQA 2B checkpoint. It is intended as lightweight reproduction guidance, not as a full experiment archive.
+
+Files:
+
+- `training_config.json`: core training hyperparameters and distributed setup.
+- `validation_history.csv`: per-epoch validation curve in table form.
+- `validation_history.json`: the same validation curve with summary metadata.
+
+The validation curve uses a held-out KONIQ split with 200 valid samples and 8 evaluation shards for every epoch. No machine-specific paths, private dataset roots, cache directories, or internal experiment names are included.

training_guidance/training_config.json

@@ -0,0 +1,19 @@
+{
+  "description": "Sanitized training recipe for reproducing the released MR-IQA 2B run.",
+  "model_scale": "2B vision-language backbone",
+  "training_epochs": 10,
+  "per_device_train_batch_size": 48,
+  "num_generations": 6,
+  "num_iterations": 4,
+  "learning_rate": 0.00001,
+  "kl_beta": 0.02,
+  "temperature": 0.7,
+  "max_completion_length": 256,
+  "reward_terms": ["margin_consistency", "format"],
+  "margin_weight": 1.0,
+  "ranking_weight": 0.0,
+  "min_ground_truth_std": 0.0001,
+  "distributed_training": "8 GPUs with ZeRO-3 offload",
+  "validation": "8-shard validation after each epoch",
+  "path_policy": "All paths are intentionally omitted. Bind your own model, image root, manifest, output, and cache directories when launching."
+}

training_guidance/validation_history.csv

@@ -0,0 +1,11 @@
+epoch,srcc,plcc,valid_count,shards
+1,0.8840,0.8894,200,8
+2,0.9213,0.9302,200,8
+3,0.9318,0.9392,200,8
+4,0.9274,0.9340,200,8
+5,0.9271,0.9409,200,8
+6,0.9249,0.9406,200,8
+7,0.9205,0.9408,200,8
+8,0.9288,0.9465,200,8
+9,0.9307,0.9450,200,8
+10,0.9251,0.9421,200,8

training_guidance/validation_history.json

@@ -0,0 +1,24 @@
+{
+  "description": "Validation history for the original released MR-IQA 2B training run.",
+  "validation_split": "KONIQ held-out validation split",
+  "valid_count": 200,
+  "shards": 8,
+  "best_epoch": 3,
+  "best_srcc": 0.9318,
+  "best_plcc": 0.9392,
+  "final_epoch": 10,
+  "final_srcc": 0.9251,
+  "final_plcc": 0.9421,
+  "epochs": [
+    {"epoch": 1, "srcc": 0.8840, "plcc": 0.8894, "valid_count": 200, "shards": 8},
+    {"epoch": 2, "srcc": 0.9213, "plcc": 0.9302, "valid_count": 200, "shards": 8},
+    {"epoch": 3, "srcc": 0.9318, "plcc": 0.9392, "valid_count": 200, "shards": 8},
+    {"epoch": 4, "srcc": 0.9274, "plcc": 0.9340, "valid_count": 200, "shards": 8},
+    {"epoch": 5, "srcc": 0.9271, "plcc": 0.9409, "valid_count": 200, "shards": 8},
+    {"epoch": 6, "srcc": 0.9249, "plcc": 0.9406, "valid_count": 200, "shards": 8},
+    {"epoch": 7, "srcc": 0.9205, "plcc": 0.9408, "valid_count": 200, "shards": 8},
+    {"epoch": 8, "srcc": 0.9288, "plcc": 0.9465, "valid_count": 200, "shards": 8},
+    {"epoch": 9, "srcc": 0.9307, "plcc": 0.9450, "valid_count": 200, "shards": 8},
+    {"epoch": 10, "srcc": 0.9251, "plcc": 0.9421, "valid_count": 200, "shards": 8}
+  ]
+}