==============================================================================
University of Kassel, Department of Agricultural and Biosystems Engineering

Statistical Framework not only for Precision Livestock Management and Ethology
MSA for Ordinal Scoring Data using Cohen's Kappa & Gwet's AC
Attributive Gage R&R and Generation of “Noisy Labels” for Machine Learning

Authors: Kulig, Schäfer, Addo, Lange, Wilczek, Hensel, Jung
License: http://creativecommons.org/licenses/by-sa/4.0/
         CC BY-SA 4.0
Cite:
DOI:     https://doi.org/10.48662/daks-542

HOWTO: Use the Attributive Gage R&R Framework (MSA & Noisy Labels)
==============================================================================

OVERVIEW
This framework performs a deep Measurement System Analysis (MSA) for ordinal 
scoring data. It partitions human measurement error into Repeatability 
(intra-rater) and Reproducibility (inter-rater). Furthermore, it identifies 
systematic bias using dynamic control limits (Variability Charts) and exports 
a "Global Consensus" dataset (Noisy Labels) optimized for training Machine 
Learning algorithms or validating sensor systems.

FILE STRUCTURE
1. GageRR_Config.R          <- THE ONLY FILE YOU NEED TO EDIT.
2. GageRR_Report.qmd        <- The Quarto document that generates the PDF.
3. GageRR_Functions.R       <- Backend logic (do not edit).
4. GageRR_Simulation.R      <- Generates test data with specific fatigue/bias.
5. References.bib / *.csl   <- Bibliography and citation styles.

HOW TO USE THE FRAMEWORK

STEP 1: Prepare Your Data
* The framework accepts standard Excel (.xlsx) or CSV files.
* Format: One column must contain the unique Item/Animal ID. The remaining 
  columns should contain the scores, with each column representing a specific 
  trial of a specific rater (e.g., "RaterA_Trial1", "RaterA_Trial2").

STEP 2: Configure the Analysis
* Open `GageRR_Config.R` in RStudio.
* Provide the `file_path` and specify the `item_id_column`.
* MAP YOUR RATERS: In the `rater_mapping` list, exactly assign your column 
  names to the respective raters. The framework automatically adapts to the 
  number of raters and trials provided.
* Define your scale and weighting matrix.
* (Optional) Activate Chapter 3 (`expert_benchmark`) to test all raters 
  against a defined standard/senior appraiser.
* Save the configuration file.

STEP 3: Generate the Report and ML-Export
* Open `GageRR_Report.qmd` in RStudio.
* Click the "Render" button at the top of the script window (or press 
  Ctrl+Shift+K / Cmd+Shift+K).
* The framework will automatically install any missing R packages.
* OUTPUT 1: A highly detailed PDF report featuring drill-down bias charts, 
  automated Kendall-vs-Kappa bias detection, and reproducibility metrics.
* OUTPUT 2: A new CSV/Excel file ("GageRR_Noisy_Labels_Export") containing 
  your raw data merged with the calculated Global Consensus (Median) and 
  rater-specific Mean Absolute Errors.

TESTING WITH SIMULATED DATA
Run `GageRR_Simulation.R` to generate a dataset featuring three archetypal 
raters (an expert, a drifting rater, and a guessing rater). Process this 
file to see how the framework detects and visualizes these specific errors.
==============================================================================