README updated for new functionality: Evaluation output

README_DE.md

@@ -47,7 +47,7 @@ Dabei müssen die folgende Informationen in der **richtigen Reihenfolge** und mi
 1) **Question**: Die gestellte Frage
 2) **referenceAnswer**: Eine korrekte Antwort / Musterlösung / Referenzantwort
 3) **studentAnswer**: Die vom Prüfling gegebene Antwort, die bewertet werden soll.
-5) (optional) **observed grade**: Hier kann die tatsächliche Bewertung durch die Lehrkraft eingetragen werden, um Kennzahlen über die Richtigkeit der Vorhersagen zu bekommen.
+5) **observed grade**: Hier kann die tatsächliche Bewertung durch die Lehrkraft eingetragen werden, um Kennzahlen über die Richtigkeit der Vorhersagen zu bekommen. Wenn keine Bewertungen existieren, tragen Sie NONE ein.
 
 Die Beispieltabelle finden Sie unter <a href="https://transfer.hft-stuttgart.de/gitlab/ulrike.pado/ASYST/-/blob/main/DE_Demo_Daten.xlsx">DE_Demo_Daten.xlsx</a>. Sie enthält einige Fragen und Antworten aus dem CSSAG-Korpus (Computer Science Short Answers in German) der HFT Stuttgart. Das Korpus is CC-BY-NC lizenziert.
 
@@ -70,17 +70,14 @@ Anschließend kann über einen Klick auf das Feld "Input File" die zu verarbeite
 Hierbei sollten die Daten wie oben beschrieben angeordnet sein. 
 Nach einem Klick auf das "Start"-Feld beginnt ASYST mit der Verarbeitung der Daten. Dies kann wiederum eine Weile dauern (1-2 Minuten, relativ unabhängig von der Menge der zu verarbeitenden Daten). 
 
-Sobald das Programm alle Einträge verarbeitet und Vorhersagen getroffen hat, öffnet sich eine Tabellenansicht mit der Überschrift "Results" (Ergebnisse). 
+Sobald das Programm alle Einträge verarbeitet und Vorhersagen getroffen hat, öffnet sich ein Fenster, das Ihnen erlaubt, die Ergebnisse wiederum im Excel-Format .xlsx zu speichern. Nach dem Speichern öffnet sich die Datei automatisch, so dass Sie die Bewertungsvorschläge bearbeiten können. 
 
-Die Ergebnistabelle enthält alle Spalten der eingelesenen Tabelle, sowie zusätzlich in der Spalte "predicted grade" die von ASYST vorgeschlagene Bewertung der Antworten. Die "incorrect"-Einträge der als falsch eingestuften Antworten sind rot hinterlegt. Sie können in dieser Tabelle allerdings noch keine Bewertungen verändern. Speichern Sie hierzu über einen Klick auf "Save as" die erzeugte Tabelle und öffnen Sie sie dann mit einem Tabellenkalkulationsprogramm. 
-
-![table_results.png](images%2Ftable_results.png)
+Die Ergebnistabelle enthält alle Spalten der eingelesenen Tabelle, sowie zusätzlich in der Spalte **predicted grade** die von ASYST vorgeschlagene Bewertung der Antworten. Die "incorrect"-Einträge der als falsch eingestuften Antworten sind rot hinterlegt. 
 
 Sobald die Ergebnistabelle angezeigt wird, kann ASYST die nächste Tabelle einlesen und verarbeiten. 
 
-**ACHTUNG: Die Ergebnistabelle wird nicht automatisch gespeichert.** Werden die Ergebnisse nicht gespeichert, 
-wird die Erbgebnistabelle im nächsten Durchlauf überschrieben.
-Daher sollte, um die Ergebnisse zu sichern, auf den **"Save as"**- Button geklickt und die Ausgabetabelle am gewünschten Ort gespeichert werden.
+Sie sehen in der Ergebnistabelle auch eine Evaluation der ASYST-Ausgaben, falls Sie in der Spalte **observed grade** die tatsächliche Bewertung eingegeben haben. Hier ist besonders die Ausgabe in Spalte **precision** für die beiden Bewertungen "correct" und "incorrect" wichtig: Eine hoher Wert für "precision" (ca. 0.8 und höher) bedeutet, dass die Vorhersage von ASYST für diese Bewertung voraussichtlich verlässlich ist. S. auch Abschnitt "Wie arbeitet man mit der Ausgabe von ASYST weiter?"
+
 
 
 <h2 id=6>Wie arbeitet man mit der Ausgabe von ASYST weiter?</h2>
@@ -109,18 +106,18 @@ Wir empfehlen die folgende **Vorgehensweise** beim Einsatz von ASYST:
 
    Hierzu werden die Fragen und Antworten aus dem Testdatensatz von ASYST verarbeitet und anschließend die erhaltene Klassifikation mit der manuellen Bewertung abgeglichen (z.B. in einer Tabellenkalkulation wie Excel oder Libre Office Calc).
    
-   Dabei kann der Anteil der korrekt klassifizierten Antworten im gesamten Datensatz ermittelt werden - dieser sollte 85% oder höher betragen (das entspricht einer Fehlerquote von 15% oder weniger). 
+   Dabei kann der Anteil der korrekt klassifizierten Antworten im gesamten Datensatz (Kennzahl "Accurady") ermittelt werden - dieser sollte für rein automaticshe Korrektur 85% oder höher betragen (das entspricht einer Fehlerquote von 15% oder weniger). 
    
    Sie können auch für die einzelnen Bewertungen (richtig/falsch) berechnen, wie groß die Präzision für die verschiedenen Bewertungen jeweils ist. Die Präzision misst, wie viele Vorhersagen einer bestimmten Bewertung tatsächlich richtig waren, d.h. wie vertrauenswürdig die Vorhersagen des Bewerters für ein bestimmtes Label sind. So bedeutet eine Präzision von 75% für die Bewertung "korrekt", dass drei Viertel aller Vorhersagen von "korrekt" gestimmt haben, aber in einem Viertel der Fälle die Antwort laut der manuellen Bewertung falsch war.
 
-   _(Die Funktion, diese Kenngrößen der Zuverlässigkeit automatisch in einem Testmodus zu generieren soll in Zukunft dem Programm noch hinzugefügt werden.)_
+ Wie oben unter "Wie verwendet man ASYST?" beschrieben, werden diese Kenngrößen automatisch berechnet, sobald Sie zu den zu bewertenden Fragen **observed grades** liefern.
 
 5) **Entscheidung** wie der Ansatz genutzt werden soll.
    
    Anhand der erhobenen Kenngrößen zur Zuverlässigkeit für die oben genannten Kriterien kann nun eine Entscheidung getroffen werden. 
    <ul>
    <li> Wie groß ist der Anteil der korrekt vorhergesagten Bewertungen? Beträgt er >85%, können Sie die ASYST-Vorhersagen sogar unverändert übernehmen, falls Sie dies wünschen. </li>
-   <li> Wie ist die Präzision der einzelnen Bewertungsklassen (richtig/falsch)? Wenn eine der Klassen deutlich zuverlässiger vorhergesagt wird, können Sie entscheiden, diese Vorhersagen ungeprüft zu übernehmen und <b>nur</b> die Vorhersagen für die weniger verlässlich erkannte Klasse zu überprüfen. Dies führt in der Praxis zu einer deutlichen Zeitersparnis. </li>
+   <li> Wie ist die Präzision der einzelnen Bewertungsklassen (richtig/falsch)? Wenn eine der Klassen deutlich zuverlässiger vorhergesagt wird, können Sie entscheiden, diese Vorhersagen ungeprüft zu übernehmen und <b>nur</b> die Vorhersagen für die weniger verlässlich erkannte Klasse zu überprüfen. Dies führt in der Praxis zu einer deutlichen Zeitersparnis.  Ein Richtwert ist eine Präzision von 0,8 oder höher. </li>
    <li>Wie ist der Bewertungsfehler verteilt? Werden übermäßig viele korrekte Antworten als falsch bewertet, oder umgekehrt? Ist dies für Ihre Situation akzeptabel? </li>
    <li> Wie viel Bewertungsaufwand hätten Sie für den Beispieldatensatz eingespart, z.B. indem Sie die verlässlichere Bewertungsklasse ungeprüft akzeptieren?
    </ul>

README_EN.md

@@ -48,7 +48,7 @@ The following information needs to be included in the **correct order** and with
 1) **question**: The question that was asked
 2) **referenceAnswer**: A correct answer /  reference answer
 3) **studentAnswer**: The student answer that is to be evaluated
-5) (optional) **observed grade**: The grade given by the teacher can be entered here in order to evaluate the accuracy of the ASYST predictions.
+5) **observed grade**: The grade given by the teacher can be entered here in order to evaluate the accuracy of the ASYST predictions. If no grades exist, enter NONE.
 
 The example table can be found at <a href="https://transfer.hft-stuttgart.de/gitlab/ulrike.pado/ASYST/-/blob/main/DE_Demo_Daten.xlsx">DE_Demo_Daten.xlsx</a>. It contains some questions and answers from the CSSAG corpus (Computer Science Short Answers in German) of HFT Stuttgart. The corpus is licensed as CC-BY-NC.
 
@@ -70,17 +70,13 @@ After the program has been started, a window appears. First, select the language
 The table to be processed can then be selected by clicking on the “Input File” field. The data should be arranged as described above.
 After clicking on the “Start” field, ASYST begins processing the data. Again, this can take a while (1-2 minutes, relatively independent of the amount of data being processed).
 
-Once the program has processed all answers and made predictions, a table view headed "Results" opens.
+Once the program has processed all answers and made predictions, a window opens that allows you to save the results as another Excel file in .xslx format. After saving, the file opens automatically, so the grade predictions can be edited.
 
-The results table contains all columns of the input table, as well as the grades suggested by ASYST -- see the the "predicted grade" column. The grades for answers classified as incorrect are highlighted in red. You cannot make change in this table. Instead, save the data by clicking on “Save as” and then open the resulting .xlsx file with a spreadsheet program.
-
-![table_results.png](images%2Ftable_results.png)
+The results table contains all columns of the input table, as well as the grades suggested by ASYST -- see the the "predicted grade" column. The grades for answers classified as incorrect are highlighted in red. 
 
 As soon as the result table is displayed, ASYST can read and process the next input table.
 
-**ATTENTION: The results table is not saved automatically.** 
-Therefore, to save the results, the **"Save as"** button should be clicked and the output table should be saved at the desired location.
-
+In the results table, you also find evaluation output for the ASYST predictions if you provided **observed grades**. The most important information is in column **precision** for the grades "correct" and "incorrect". A high precision value (ca. 0.8 and higher) means that the ASYST predictions for this grade are probably reliable. See also seciton "How do I continue with the output from ASYST?"
 
 <h2 id=6>How do I continue with the output from ASYST?</h2>
 
@@ -108,18 +104,16 @@ We recommend the following **process** when using ASYST:
 
     For this purpose, process the questions and answers from the test data set using ASYST and compare the grade predictions with the manual assessment (e.g. in a spreadsheet such as Excel or Libre Office Calc).
 
-    The proportion of correctly classified answers in the entire data set gives you the system accuracy (which should be at around 85% or higher, which means disagreement between the manual and machine grades of 15% or less). 
-    
-    You can also calculate the precision for each grade ("correct"/"incorrect"). Precision measures how many predictions of a given grade were actually correct, i.e. how trustworthy the ASYST's predictions are for a given label. A precision of 75% for the rating "correct" means that three quarters of all predictions of "correct" were in fact right, but for a quarter of the cases the answer was actually wrong according to the manual grades.
+    The proportion of correctly classified answers in the entire data set gives you the system accuracy (which should be at around 85% or higher for fully automated grading, which means disagreement between the manual and machine grades of 15% or less). 
     
-    _(We plan to add functionality to automatically generate these reliability parameters in the future.)_
+    ASYST also calculates the precision for each grade ("correct"/"incorrect") as soon as observed grades are provided. Precision measures how many predictions of a given grade were actually correct, i.e. how trustworthy the ASYST's predictions are for a given label. A precision of 75% for the rating "correct" means that three quarters of all predictions of "correct" were in fact right, but for a quarter of the cases the answer was actually wrong according to the manual grades.
 
 5) **Decide** how to use ASYST's predictions.
    
     A usage decision can now be made based on the reliability parameters collected for the criteria mentioned above.
     <ul>
     <li> How large is the proportion of correctly predicted reviews? If it is >85%, you can even adopt the ASYST predictions unchanged if you wish. </li>
-    <li> What is the precision of the grade labels ("correct"/"incorrect")? If one of the grade labels is likely to be significantly more reliable, you can decide to accept these predictions without review and <b>only</b> check the predictions for the less reliable grade predictions. In practice, this leads to significant time savings. </li>
+    <li> What is the precision of the grade labels ("correct"/"incorrect")? If one of the grade labels is likely to be significantly more reliable, you can decide to accept these predictions without review and <b>only</b> check the predictions for the less reliable grade predictions. In practice, this leads to significant time savings. As a rule of thumb, a precision of 0.8 or higher may be chosen.</li>
     <li>How is the grading error distributed? Are correct answers frequently predicted to be incorrect, or vice versa? Is this acceptable for your situation? </li>
     <li> How much evaluation effort would you have saved for the example data set, e.g. by accepting the more reliable grade label without review?
     </ul>