Map Questions, Variables and Topics
Once a questionnaire and dataset have been documented, they go through a process called mapping. This connects questions in the questionnaire to variables in the associated dataset(s), and maps both questions and variables to topics. Some general rules about the mapping process are below.
Ideally, all variables should be mapped to a question or variable
Ideally, all questions and variables should be mapped to a topic
A variable can be mapped to a source question or a source variable, depending on whether the variable is normal or derived
A question can be mapped to multiple variables
It is possible, but not recommended, that a variable can be mapped to multiple questions (ideally they should be mapped to source variables)
A derived variable is expected to have at least two source variables mapped to it (e.g. the derived variable BMI will have the source variables height and weight)
Derived variables and their source variables do not have to have the same topic (although it is preferable, it may not be possible)
Variables and questions which are mapped together must have the same topic (these are inherited, as described below)
A question grid can be mapped to variables as a whole item or to individual grid cells
A question grid can only be mapped as a whole to one topic
Archivist (previously Mapper) provides a graphical user interface to simplify mapping questions, variables and topics, automatically assigning mappings where possible and maintaining constraints.
The steps below can be followed to map questions, variables and topics manually. If you want to do this via text files, please refer to Using Txt Files.
Note: Archivist users must have the correct permissions to apply mappings.
1) Create the dataset XML
1) Run Sledgehammer and DDI-Flavour on the dataset. Note: The prefix used when running Sledgehammer must match the instrument prefix.
2) The CLOSER team will upload this to Archivist and link it to the questionnaire.
2) Link variables/questions to their source
You can either a) link variables to questions (or other variables, if derived) from the dataset, or b) link questions to variables from the questionnaire.
a) Link variables to questions/variables through the dataset
Go to Datasets > search for the dataset prefix or name > under Actions select VIEW.
For a normal variable, enter the question name into Sources. This will auto-populate as you type, so the question can be selected from the drop-down list. More than one question can be mapped to a variable. If there is already a topic applied to the variable, only those questions mapped to that topic, or no topic, will appear in the dropdown list.
For a derived variable, select Derived from the drop-down list under Type. Enter the variable name into Sources. This will auto-populate as you type, so the variable can be selected from the drop-down list. More than one variable can be mapped to the derived variable.
b) Link questions to variables through the questionnaire
Go to Instruments > search for the questionnaire prefix or name > under Actions select MAP.
For single questions, enter the variable name into the Variables space. This will auto-populate as you type, so the variable can be selected from the drop-down list. More than one variable can be mapped to a question.
For question grids, you can either add a variable for each grid cell by entering the variable name into the Add variable space, or enter the variables into the Map whole grid to variables space at the bottom to map to the group of questions.
3) Map to topics
You can either a) map variables to the topics from the dataset, or b) map the questions to the topics from the questionnaire.
a) Map variables to topics through the dataset
Go to Datasets > search for the dataset prefix or name > under Actions select VIEW.
For each variable, select the correct topic from the drop down list. This will auto-populate as you type, so the topic can be selected from the drop-down list. Be careful to distinguish between the COVID and non-COVID topics.
Note: If the variable is linked to a question, the question will automatically inherit the topic. Linked questions and variables must have the same topic. Variables linked to different cells in a question grid also must all have the same topic. If this is not the case, Archivist will show a conflict error in red. For more information, please see Applying Topics.
Note: If the derived variable is linked to a variable, the source variable will have a suggested topic automatically inherited (this can be overwritten). If the derived variable already has a topic applied, these will not be overwritten.
b) Map topics to questions through the questionnaire
Go to Instruments > search for the questionnaire prefix > under Actions select MAP.
You can map questions to a topic and/or map the all questions which have the sequence as a parent to a topic
For question items, select the correct topic from the drop down list. This will auto-populate as you type, so the topic can be selected from the drop-down list.
Variables and questions which are linked must have the same topic mapped to both. If this is not the case, Archivist will show a conflict error in red. For more information please see Applying Topics.
For question grids, only one topic can be applied to a grid as a whole, which is why there is only one drop down box for the question grid topic,
For sequences, whole sections of the questionnaire can be linked to a topic by adding a topic to a sequence. Note: This will only map questions were the direct parent is the sequence, if the question has a condition as their parent, this will not be mapped.
If there are questions that are already mapped to topics (either added or inherited), and they are the first child of the sequence and they are all the same, then the sequence topic is available to update. Where the topics are not the same, the option will not display. If you change the sequence topic, it will change those first child questions to that, unless there is a conflict with the variable. Note: if you apply a topic to the sequence, it will display as 'saving' then 'saved', but you will need to refresh the page to see the topic display.
4) Check mappings in the instrument view
Go to Instruments > search and select View. This will give the questionnaire view with the variable names listed against them. You can click on the variable name to see the variable label.