Skip to content

Survey configuration

Jump to bottom
Claudio Bonesana edited this page May 28, 2021 · 11 revisions

Note: check the Adaptive Engine for an explanation of how a survey works.

The configuration of the survey can be done in multiple ways:

  • via database by pre-filling the remote database with everything needed;
  • via code by using, in Java, the Exchange library with the Remote API Key; or
  • by putting a JSON for each survey in a folder called /data in the work directory of the backend.

While the first two ways are explained within the code Javadoc, here we will explain how to build a compatible JSON file.

As reference, consider the content of the data folder in the backend module.

Note: Consider that the structure of the JSON is exactly what you would achieve by dumping the structure of object build using the Exchange Library.

It is strongly suggested to read first the Model structure page in order to better understand all the parameters and keyword used in the following section.

Basic structure

We have 4 mandatory field to fill and one optional:

  • "survey": this contains all the configuration, parameters, thresholds, and descriptions relative to the survey.
  • "skills": this is a list of all the nodes in the models that the adaptive engine will optimize for.
  • "questions": this is a list of all the questions available.
  • "model": this field is a description of the CreMA model used by the adaptive engine.
  • (opt.) "modelData": if the "model" filed is set to null, this field will be used. This is a model written in UAI form. The string to put there can also be produced using the CreMA library (see Model and ModelData field).

Survey field

This field is an object with many fields. We can collect these fields in three groups.

Generic fields:

  • "language": language identifier for the survey.
  • "description": a textual description of the survey.
  • "accessCode": unique identifier. This will be used in the url to initialize a new survey session.
  • "duration": maximum time to perform the survey.

Adaptive control fields:

  • "adaptive": set to true if you want to use the adaptive engine.
  • "simple": set this to true if there is no direct connection in the model between questions and skills.
  • "randomQuestions": (non-adaptive) if true, the questions are asked in a random order.
  • "skillOrder": force the adaptive engine to ask questions connected to the skills and specified in the given order. It is used to avoid jumping between questions of different arguments.
  • "mixedSkillOrder": false if "skillOrder" is set, otherwise true.
  • "scoring": set the type of score to use for the search of the next question. Current valid values are entropy (default) and mode.

Questions control fields:

  • "questionPerSkillMin": force the system to always consider valid a skill until this number of question of this skill has been answered. Each skill has its own count.
  • "questionTotalMin": force the system to always consider valid any skill until this number of question total has been answered.
  • "questionTotalMax": force the system to stop when this number of question total has been answered.
  • "questionPerSkillMax": force the system to stop asking questions of a skill after this value has been reaced. Each skill has its own count.
  • "scoreUpperThreshold": set a stop threshold for the score, it consider the skill completed when above this value.
  • "scoreLowerThreshold": set a stop threshold for the score, it consider the skill completed when below this value.
  • "globalMeanScoreUpperThreshold": set a stop threshold for the mean score across the skills, it consider the survey completed when above this value.
  • "globalMeanScoreLowerThreshold": set a stop threshold for the mean score across the skills, it consider the survey completed when below this value.

Skills field

This filed is an array of the following structure:

{
  "name": "A",
  "states": [
    {
     "name": "low",
     "value": 0
    },
    {
     "name": "high",
     "value": 1
    }
  ]
}

In this case we are describing a skill named A with two states: low with an index of 0 and high with an index of 1.

The value field is in direct connection with the model, so these values must be consistent with them defined in the model.

Questions field

This filed is an array of the following structure:

{
  "skill": "A",
  "question": "Question 1",
  "explanation": "Question of low interest",
  "name": "L",
  "variable": 1,
  "weight": 0,
  "mandatory": false,
  "example": false,
  "randomAnswers": false,
  "answers": [
    {
      "text": "a",
      "state": 0
    },
    {
      "text": "b",
      "state": 1
    },
  ]
}
  • "skill": name of the skill that this question refers to.
  • "question": string containing the text for the question.
  • "explanation": additional string for an explanation of the question.
  • "name": name of the variable in the model associated with this question.
  • "variable": index of the variable in the model associated with this question. This is optional if the field "name" is set.
  • "weight": points given to the answer (not used).
  • "mandatory": if true, this question will be asked before the adaptive engine starts.
  • "example": different kind of mandatory question; if true, answer to this question is not considered.
  • "randomAnswers": just a flag to signal that the answers should be posed in a random order.
  • "answers": list of answers with their "text"s and "state". The "state" refers to the index of the state for the variable of this question in the model.

Model and ModelData field

These two fields are mutually exclusive: the tool prioritize the "modelData" field, if not found will use the "model" field.

The content of "modelData" is just a string in UAI format describing the model. The usual way to produce this string, given a CreMA's DAGModel, is the following:

String modelData = String.join("\n", new BayesUAIWriter(bn, "").serialize());

The content of the "model" field is instead a declarative description fo the model with the following self-explanatory object:

"model": {
  "variables": [
    {
      "name": "A",
      "states": 2,
      "data": [
        0.4,
        0.6
      ]
    },
    {
      "name": "M",
      "states": 2,
      "parents": [
        "A"
      ],
      "data": [
        0.4,
        0.6,
        0.6,
        0.4
      ]
    },
    ...
  ]
}

In the "parents" array you need to put the name of the parent variable.

Note: if you use the "modelData" field you need to put the "variable" field for question and skills, since you don't have the name of the model's variables; instead with the "model" you need to use the "name" field since you don't have the index (built at runtime) of the variables.

Clone this wiki locally