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

Statistical Framework not only for Precision Livestock Management and Ethology
Concordance Analysis Framework for Scoring Data
Annotated Report with Decision-Making Guidance based on Standard Methods

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 Concordance Analysis Framework for Scoring Data
==============================================================================

OVERVIEW
This framework is designed for the broad evaluation of inter-rater and 
intra-rater reliability for scoring data. It handles categorical, ordinal,
and metric data, offering robust chance-corrected metrics (Cohen's Kappa, 
Gwet's AC, Krippendorff's Alpha, PABAK), metric equivalence tests (Deming
Regression, Bland-Altman, TOST), and asymmetric confidence intervals via 
bootstrapping.

FILE STRUCTURE
1. Concordance_Config.R       <- THE ONLY FILE YOU NEED TO EDIT.
2. Concordance_Report.qmd     <- The Quarto document that generates the PDF.
3. Concordance_Functions.R    <- Backend logic (do not edit).
4. Concordance_Simulation.R   <- Generates test data to explore the framework.
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: Each column represents one rater (or one timepoint). Each row 
  represents one evaluated subject (e.g., an animal, a video).
* Ensure there are no empty columns and that your scores match your 
  theoretical scale (e.g., only 1 to 5). 

STEP 2: Configure the Analysis
* Open `Concordance_Config.R` in RStudio.
* Define your data path (`file_path`).
* Define your scale (`scale_level`, `min_score`, `max_score`).
* Choose your weighting method (e.g., "linear", "quadratic", "unweighted" or
  "custom").
* Save the configuration file.

STEP 3: Generate the Report
* Open `Concordance_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 upon its 
  first run.
* A comprehensive PDF report containing all descriptive statistics, 
  concordance metrics, bias analyses, and methodological explanations will 
  be generated.

TESTING WITH SIMULATED DATA
If you want to test the framework before using real data, simply run the 
`Concordance_Simulation.R` script. It will generate a file named 
"Data_Simulated_for_Agreement_Analysis.csv" with realistic rater noise, which 
you can immediately analyze.
==============================================================================