updated readme with test files and more explaining text

README.md

@@ -27,9 +27,31 @@ git clone https://github.com/dwslab/assDataMiningQuestion
 ```
 As ILIAS administrator, install and activate the plugin in the ILIAS Plugin Administration menu:
 1) Administration->Plugins
-2) Search for "assDataMiningQuestion" and click on "Actions", then "Install"
-
-### Screenshots
+2) Search for Plugin "assDataMiningQuestion" (ID is "dataminingqu") and click on "Actions", then "Install"
+3) Click on Actions again and choose "Activate"
+
+### Creating a question
+
+To create a data mining question, select a course and add a new test by clicking on "Add New Item" -> "Test" (below category Assessment).
+Choose a title for the test (which can contain multiple questions) and click on "Add test" to actually create it.
+To add a question, click on the "Questions" tab on the left side and then "Create question".
+Select the question type "Data Mining Question" and click on "Create".
+Now you can change the properties of the question (each property is described in more detail in the below section "Description of Data Mining settings").
+Example files for train and test can be found in the [doc/exampleFiles](doc/exampleFiles) directory.
+These are generated with the [python file](doc/create_train_test_files.py) in the doc folder.
+Afterwards click on "Save" and check the message on the top (blue background) if the parsing of the file works as expected.
+The test itself also has settings with can be modified. They also have an impact on the data mining question.
+The settings can be found in the test menu at tab "Settings". Some of the important settings are explained below in the section "Important settings of test".
+For testing the question you have to activate the test at "Settings", "General" tab, "Availability" category, "Online" checkbox.
+If you also finished editing these settings, you can try out the test by clicking on the "Info" tab of the test and then "Start the test".
+You should now see the question text and a possibility to upload a file.
+If you uploaded a valid file, click on "Finish the Test" and afterwards you see the results.
+If you click on "Detailed Results" you also see the points per question.
+For the data mining question you see the uploaded file as well as the best solution which shows a link to the uploaded gold standard.
+If you want to change this behaviour, you have to change the test settings.
+
+
+#### Screenshots
 
 Creating a Data Mining Question:
 
@@ -40,7 +62,7 @@ Take a test:
 ![Take a test](doc/takeTest.png?raw=true "Take a test")
 
 
-### Description of Data Mining settings
+#### Description of Data Mining settings
 
 - Title
     - The title of the question (shown at the top of the test)
@@ -58,33 +80,34 @@ If the first non empty line is not valid it is assumed to be the header.
 - Working Time
     - the time available to do the test
 - Training file
-    - a file with training data (it should contain the features as well as the target which is to predict).
+    - a file with training data (it should contain the features as well as the target which should be predicted).
     This is optional because the training data can also be provided within the test or just as a link to an external file in the test question.
-    If a file is provided a link to this file will be shown when a particpant takes this test.
+    If a file is provided, a link to this file will be shown when a particpant takes this test.
 - Test file containing features
-    - a file with test data (it should only contain the features and not the target values). It is optional because you could provide it also in a different way.
+    - a file with test data (it should only contain the features and not the target values). 
+    It is optional because you could provide it also in a different way (similar to the training file).
 - Test file containing target
     - the only required file which should contain only the target values.
 - Skip first line
     - if the first non empty line of the test file with target should be skipped or not.
 - Evaluation measure
     - Currently nine evaluation measure are implemented (see Available evaluation measures)
 - Expected filename ending
-    - The expected file name ending of files which the participant should upload. During upload only the files with such an extension are shown. 
-      The field can be also left empty for no file extension restriction.
+    - The expected file name ending of files which the participant should upload. During upload only the files with such an extension are shown.
+    It is a comma speparated list of wile extensions without the dot (e.g. doc,xls,odt).
+    The field can be also left empty for no file extension restriction.
 - Maximum upload size
     - The maximum upload size in KB for the participants file (solution / file with participants predictions).
 - Points
-    - The number of points for this question. Depending on much weight you want to give to this question.
+    - The number of points for this question. Depending on how much weight you want to give to this question.
 
 #### Available evaluation measures
 
 - Classification
+    - for each of the following measures (except accuracy), an average has to be selected (micro, macro, weighted or binary). 
+      If binary is selected additionally the positive label has to be provided.
     - Accuracy
-        - The usual accuracy value which also works for multiclass
     - Precision
-        - for precision as well as recall and f measure, the average has to be selected (micro, macro weighted or binary). 
-          If binary is selected addittionally the positive label has to be provided.
     - Recall
     - F-Measure
 - Regression

doc/exampleFiles/classificaton_iris_test_features.csv

@@ -0,0 +1,31 @@
+sepal length (cm),sepal width (cm),petal length (cm),petal width (cm)
+4.4,3.0,1.3,0.2
+6.1,3.0,4.9,1.8
+4.9,2.4,3.3,1.0
+5.0,2.3,3.3,1.0
+4.4,3.2,1.3,0.2
+6.3,3.3,4.7,1.6
+4.6,3.6,1.0,0.2
+5.4,3.4,1.7,0.2
+6.5,3.0,5.2,2.0
+5.4,3.0,4.5,1.5
+7.3,2.9,6.3,1.8
+6.9,3.1,5.1,2.3
+6.5,3.0,5.8,2.2
+6.4,3.2,4.5,1.5
+5.0,3.4,1.5,0.2
+5.0,3.3,1.4,0.2
+5.8,4.0,1.2,0.2
+5.6,2.5,3.9,1.1
+6.1,2.9,4.7,1.4
+6.0,3.0,4.8,1.8
+5.4,3.7,1.5,0.2
+6.7,3.1,5.6,2.4
+6.6,2.9,4.6,1.3
+6.1,2.6,5.6,1.4
+6.4,2.8,5.6,2.2
+6.7,3.0,5.0,1.7
+6.6,3.0,4.4,1.4
+5.7,3.8,1.7,0.3
+6.5,3.0,5.5,1.8
+5.2,3.4,1.4,0.2

doc/exampleFiles/classificaton_iris_test_gold.csv

@@ -0,0 +1,31 @@
+target
+setosa
+virginica
+versicolor
+versicolor
+setosa
+versicolor
+setosa
+setosa
+virginica
+versicolor
+virginica
+virginica
+virginica
+versicolor
+setosa
+setosa
+setosa
+versicolor
+versicolor
+virginica
+setosa
+virginica
+versicolor
+virginica
+virginica
+versicolor
+versicolor
+setosa
+virginica
+setosa

doc/exampleFiles/classificaton_iris_train.csv

@@ -0,0 +1,121 @@
+sepal length (cm),sepal width (cm),petal length (cm),petal width (cm),target
+4.4,2.9,1.4,0.2,setosa
+4.9,2.5,4.5,1.7,virginica
+6.8,2.8,4.8,1.4,versicolor
+4.9,3.1,1.5,0.1,setosa
+5.5,2.5,4.0,1.3,versicolor
+6.3,2.5,5.0,1.9,virginica
+5.6,2.7,4.2,1.3,versicolor
+6.3,2.8,5.1,1.5,virginica
+7.7,3.0,6.1,2.3,virginica
+7.7,3.8,6.7,2.2,virginica
+7.6,3.0,6.6,2.1,virginica
+6.0,2.9,4.5,1.5,versicolor
+5.0,2.0,3.5,1.0,versicolor
+5.8,2.7,4.1,1.0,versicolor
+5.8,2.6,4.0,1.2,versicolor
+4.7,3.2,1.6,0.2,setosa
+5.1,3.8,1.5,0.3,setosa
+6.7,2.5,5.8,1.8,virginica
+6.4,3.1,5.5,1.8,virginica
+5.4,3.4,1.5,0.4,setosa
+6.3,2.5,4.9,1.5,versicolor
+5.1,3.8,1.6,0.2,setosa
+7.9,3.8,6.4,2.0,virginica
+5.0,3.0,1.6,0.2,setosa
+5.5,2.4,3.7,1.0,versicolor
+6.3,2.9,5.6,1.8,virginica
+6.4,2.7,5.3,1.9,virginica
+5.0,3.4,1.6,0.4,setosa
+5.6,2.8,4.9,2.0,virginica
+5.0,3.5,1.3,0.3,setosa
+5.1,3.7,1.5,0.4,setosa
+6.1,2.8,4.0,1.3,versicolor
+6.1,3.0,4.6,1.4,versicolor
+5.7,4.4,1.5,0.4,setosa
+6.9,3.1,5.4,2.1,virginica
+6.2,3.4,5.4,2.3,virginica
+5.7,2.6,3.5,1.0,versicolor
+5.2,2.7,3.9,1.4,versicolor
+6.7,3.3,5.7,2.5,virginica
+5.9,3.2,4.8,1.8,versicolor
+4.6,3.4,1.4,0.3,setosa
+7.0,3.2,4.7,1.4,versicolor
+5.4,3.9,1.3,0.4,setosa
+7.4,2.8,6.1,1.9,virginica
+4.9,3.0,1.4,0.2,setosa
+5.1,3.5,1.4,0.3,setosa
+5.8,2.7,5.1,1.9,virginica
+5.0,3.2,1.2,0.2,setosa
+4.5,2.3,1.3,0.3,setosa
+4.8,3.0,1.4,0.1,setosa
+4.8,3.0,1.4,0.3,setosa
+5.6,2.9,3.6,1.3,versicolor
+6.3,3.3,6.0,2.5,virginica
+5.7,2.8,4.5,1.3,versicolor
+5.1,3.5,1.4,0.2,setosa
+5.9,3.0,5.1,1.8,virginica
+5.7,2.8,4.1,1.3,versicolor
+6.3,3.4,5.6,2.4,virginica
+4.6,3.2,1.4,0.2,setosa
+5.8,2.7,5.1,1.9,virginica
+5.5,3.5,1.3,0.2,setosa
+5.5,2.3,4.0,1.3,versicolor
+5.7,2.5,5.0,2.0,virginica
+4.8,3.4,1.9,0.2,setosa
+6.0,2.7,5.1,1.6,versicolor
+5.5,2.6,4.4,1.2,versicolor
+7.7,2.8,6.7,2.0,virginica
+5.6,3.0,4.5,1.5,versicolor
+6.5,2.8,4.6,1.5,versicolor
+6.4,3.2,5.3,2.3,virginica
+5.1,3.4,1.5,0.2,setosa
+5.1,3.3,1.7,0.5,setosa
+5.0,3.6,1.4,0.2,setosa
+6.0,2.2,5.0,1.5,virginica
+5.8,2.7,3.9,1.2,versicolor
+7.2,3.0,5.8,1.6,virginica
+5.5,2.4,3.8,1.1,versicolor
+6.7,3.0,5.2,2.3,virginica
+6.3,2.7,4.9,1.8,virginica
+6.0,3.4,4.5,1.6,versicolor
+4.9,3.1,1.5,0.2,setosa
+5.8,2.8,5.1,2.4,virginica
+6.2,2.2,4.5,1.5,versicolor
+5.0,3.5,1.6,0.6,setosa
+6.9,3.2,5.7,2.3,virginica
+5.2,4.1,1.5,0.1,setosa
+7.2,3.6,6.1,2.5,virginica
+5.1,2.5,3.0,1.1,versicolor
+6.7,3.1,4.7,1.5,versicolor
+4.8,3.1,1.6,0.2,setosa
+6.2,2.9,4.3,1.3,versicolor
+6.5,3.2,5.1,2.0,virginica
+5.1,3.8,1.9,0.4,setosa
+4.3,3.0,1.1,0.1,setosa
+6.7,3.3,5.7,2.1,virginica
+7.7,2.6,6.9,2.3,virginica
+6.8,3.0,5.5,2.1,virginica
+6.3,2.3,4.4,1.3,versicolor
+6.2,2.8,4.8,1.8,virginica
+5.4,3.9,1.7,0.4,setosa
+6.8,3.2,5.9,2.3,virginica
+5.7,2.9,4.2,1.3,versicolor
+7.2,3.2,6.0,1.8,virginica
+7.1,3.0,5.9,2.1,virginica
+5.3,3.7,1.5,0.2,setosa
+6.4,2.9,4.3,1.3,versicolor
+6.1,2.8,4.7,1.2,versicolor
+5.7,3.0,4.2,1.2,versicolor
+5.6,3.0,4.1,1.3,versicolor
+6.7,3.1,4.4,1.4,versicolor
+5.2,3.5,1.5,0.2,setosa
+6.4,2.8,5.6,2.1,virginica
+6.0,2.2,4.0,1.0,versicolor
+5.9,3.0,4.2,1.5,versicolor
+4.8,3.4,1.6,0.2,setosa
+4.9,3.6,1.4,0.1,setosa
+4.7,3.2,1.3,0.2,setosa
+5.5,4.2,1.4,0.2,setosa
+6.9,3.1,4.9,1.5,versicolor
+4.6,3.1,1.5,0.2,setosa