# Advanced features
WARNING
The advanced features are only available on request!
# Mutable Values (a.k.a. Variables)
With mutable values the sampling scheme can be even more flexible. It is very useful, but can also introduce errors, if the sampling scheme is not correctly designed.
- Make sure you use the movisensXS Android app version 0.6.3412 or newer.
- Go into the preferences of your study (wrench icon), select movisensXS Library v3357 or newer and save the changes.
- Enter sampling, new sampling blocks are available now in the Advanced tab (Check Mutable Value, Check Mutable Value Action and Change Mutable Value) and in the Time tab (Participant Time Trigger).
With these blocks it is possible to activate or deactivate different parts of your sampling in dependency of previous actions. They also make it possible to react to answers of participants and change the outcome depending on them. The only difference between Check Mutable Value and Check Mutable Value Action is their color, which lets them get placed in different situations.
# Items storable as Mutable Value
- Select One
- Likert Scale
- Visual Analog
- Decimal
- Number
- Text
- Time
- Date & Time
# Random alarms only when a mutable value is true
The following example demonstrates on how to activate a random triggering if a participant filled out an "Out of bed" questionnaire.
1: When the form "Out of bed" is completed, the mutable Value "MorningCompleted" is set to true.
2: Only once the mutable value "MorningCompleted" is set to true, the random alarms will be active.
3: At a set time (21:00) the mutable value "MorningCompleted" is set to false, so the "Out of bed"-form will have to be completed again the next day.
# Random alarms when a participant is not asleep
The following example demonstrates on how to activate a random triggering if a participant is not asleep.
1: When the mutable value "Sleeping" is still true and the participant pressed the button to start the "Out of bed"-form, the mutable value "Sleeping" is set to false.
2: In case the participant forgets to fill out the "Out of bed"-form, the mutable value "Sleeping" will automatically changed to false at a fixed time (14:00).
3: As long as the mutable value "Sleeping" is set to false, the participant receives random triggers or can manually start a form.
4: When the participant is going to bed, he can press the button that starts the form "Going to bed". Finishing the form will set the mutable value "Sleeping" to true.
# Show a button only when a form is not completed yet
The following example demonstrates on how to show a button if the participant has not completed this form yet.
1: When the mutable value "Completed" is false, the participant can manually start and complete the form after which the mutable value "Completed" will be set to true.
2: If the participant didn't complete the form until a set time (14:00) the mutable value "Completed" will be set to true and the button to start the form manually will not appear anymore.
3: At the end of the day on a specific time (22:00) the mutable value "Completed" will be set to false so that the button appears again the next day.
# How to implement a Do-not-disturb-button
The following example demonstrates on how to implement a Do-not-disturb-button, that the participant can use if he does not want any alarms in the next hour.
1: When the mutable value "DoNotDisturb" is set to false, the participant can press the button named "Do not disturb for 1 hour" and the mutable value "DoNotDisturb" is set to true. After a delay of 3600 seconds (1 hour) the mutable value "DoNotDisturb" is set back to false.
2: During the time in which the mutable value "DoNotDisturb" is set to true the participant only sees a button named "Activate alarms". By pressing that button the mutable value "DoNotDisturb" is set back to false and the participant will receive random alarms again.
# Mutable Values: Sampling blocks
(Category: Advanced) Change Mutable Value On request
This action can change a mutable value.
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Mutable Value On request | Name of the mutable value | String | Counter |
| Operation On request | Operation to perform (set, increment, decrement) | String | increment |
| Value On request | Value of the operation (If operation='set' the mutable value is changed to this value. If operation='increment/decrement' the variable is changed by this amount). | String | 1 |
(Category: Advanced) Check Mutable Value Action On request
This action can check a mutable value and blocks following nodes if defined condition not applies.
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Mutable Value On request | Name of the Mutable Value. [Predefined Mutable Values are SamplingDay, SamplingNumber] | String | Counter |
| Comparison Operator On request | Comparison operators between Mutable Value and Compare Value, e.g. is true if Mutable Value is 'greater' than Compare Value (equal, unequal, greater, less) | String | equal |
| Compare Value On request | Value to compare the mutable value to (Not case sensitive). | String | 1 |
(Category: Advanced) Check Mutable Value On request
This condition is true if the mutable value is equal to the compare value.
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Mutable Value On request | Name of the Mutable Value. [Predefined Mutable Values are SamplingDay, SamplingNumber] | String | Counter |
| Comparison Operator On request | Comparison operators between Mutable Value and Compare Value, e.g. is true if Mutable Value is 'greater' than Compare Value (equal, unequal, greater, less) | String | equal |
| Compare Value On request | Value to compare the mutable value to (Not case sensitive). | String | 1 |
(Category: Time) Participant Time Trigger On request
This event fires if the time of the mutable value is reached and triggers the successor nodes. The mutable value can be set by the participant with the time item format in a form.
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Mutable Value On request | Name of the Mutable Value. | String | Time_1 |
| Repeated On request | Trigger should be repeated every day. | Boolean | true |
# Mutable Values: Form items
(Category: Output) Display Mutable Value On request
Displays the content of a mutable value.
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Mutable Value Name On request | The name of the mutable value that will be shown. | String | answer1 |
# Geocoder 3
The geocoder 3 is a feature which detects static locations of a participant and allows them to label those locations by given or self-defined tags. It will only allow the user to label new static locations, not overwrite previous entries.
Only new labeled static locations will be written into the results Excel file.
If you want to monitor the locations of a participant over time, you have to use the “Log Location” block in parallel.
The feature consists of the Log Static Locations block and the Label Static Locations item format.
# Geocoder 3: Sampling block
(Category: Logging) Log Static Locations On request
This logs static locations which were detected by the location functionality of movisensXS. It will only save new static location. They can be labeled via the 'Label Static Location' item.
You can customize the recording using:
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Tags On request | Potential tags which can be used in 'Label Static Location' item. (Separated by ';') | String |
# Geocoder 3: Form item
(Category: Geo) Label Static Locations On request
The Label Static Locations item format is an item format which shows the last unlabeled static locations and lets the user label them with the given predefined tags (or customizable tags if “Allow Adding Tags“ is active) of the Log Static Locations block.
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Allow Multi Tag Selection On request | If this value is true, a participant can select multiple tags to describe the location. If not, only one tag at a time can be selected. | Boolean | false |
| Allow Adding Tags On request | If this value is true, a participant can add new tags if there is no tag which fits him. If not, only tags can be used which are specified in 'Log Static Location'. | Boolean | false |
You have different options to customize the item format:
- Required: Should the item format be required.
- Allow Multi Tag Selection: Allow the user to select multiple tags per static location.
- Allow Adding Tags: Allow the user to add new tags to the predefined tag list.
# Data
The data will be saved inside the results Excel file. It contains a JSON list of the newly labeled locations. If a participant reenters an already marked location it will not be visible in the Excel file.
| Participant | Trigger | Trigger_date | Trigger_time | Trigger_counter | Form | Form_start_date | Form_start_time | Form_finish_date | Form_finish_time | Form_upload_date | Form_upload_time | Missing | item_185 |
| 1 | Button Pressed: Start form | 2024-04-09 | 11:24:09 | 1 | New form | 2024-04-09 | 11:24:09 | 2024-04-09 | 11:25:55 | 2024-04-09 | 11:27:48 | [{"accuracy":5.0,"id":1,"latitude":37.4219983,"longitude":-122.084,"name":"work","radius":100,"timeStamp":1712654358996}] | |
| 1 | Button Pressed: Start form | 2024-04-09 | 11:25:56 | 2 | New form | 2024-04-09 | 11:25:56 | 2024-04-09 | 11:25:57 | 2024-04-09 | 11:27:48 | [] |
The JSON will contain the following attributes:
- accuracy: Accuracy of the locations in meters.
- id: Numerical identifier which ascends from 1.
- latitude: Latitude of the location.
- longitude: Longitude of the location.
- name: Tag(s) which were added to the static location. If multiple then separated by ";".
- radius: The radius of the static locations.
- timestamp: The timestamp of recording.
[
{
"accuracy": 5.0,
"id": 1,
"latitude": 37.4219983,
"longitude": -122.084,
"name": "work",
"radius": 100,
"timeStamp": 1712654358996
}
]
# Gamification
The gamification feature on movisensXS is a feature that adds points for each successfully completed form or subtracts points for missing forms. You can freely choose the level limits and streaks as well as the points gained per completion and points subtracted for missing forms. It is designed to increase the engagement of participants using your study.
It consists of several blocks and options to freely adjust all variables.
# Gamification: Sampling blocks
(Category: Gamification) Change Gamification Score On request
This action lowers or highers the total gamification score.
You can customize the recording using:
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Score delta On request | Count which should be added or removed (negative values allowed) from gamification score. | Integer | 5 |
(Category: Gamification) Log Gamification Score On request
Adds Gamification capabilities to movisensXS.
You can customize the recording using:
| Label | Description | Type | Default-Value |
|---|---|---|---|
| Added Score for Form completed On request | Count which should be added to gamification score when a form will be completed. | Integer | 5 |
| Subtracted Score for Form incomplete On request | Count which should be subtracted from gamification score when a form will be incomplete. | Integer | 1 |
| Subtracted Score for Alarm dismissed On request | Count which should be subtracted from gamification score when a alarm will be dismissed. | Integer | 2 |
| Subtracted Score for Alarm missed On request | Count which should be subtracted from gamification score when a alarm will be missed. | Integer | 1 |
| Active Streaks as JSON On request | Describes which streaks are active, which names they have, which multiplier they give and how many forms should be completed. | String | |
| Active Level as JSON On request | Count which should be subtracted from gamification score when a alarm will be missed. | String | |
| Gamification Notifications On request | Enables notifications for gamification events. | Boolean | true |
# Active Streaks
A streak is a named multiplier awarded for positive points. It is awarded on the basis of consecutive completed forms.
Each streak is defined by:
- name: Name of the streak.
- multiplier: Float of the multiplier. Each positive score will be multiplied by this multiplier.
- consecutiveFormCompleteCount: Number of consecutive form completions before this streak becomes active.
This field will contain a list of possible streaks or null if you don't want any streaks.
[
{ "name": "On Fire!", "multiplier": 2, "consecutiveFormCompleteCount": 5 },
{ "name": "Rampage!", "multiplier": 3, "consecutiveFormCompleteCount": 10 },
{ "name": "Unstoppable!", "multiplier": 4, "consecutiveFormCompleteCount": 20 }
]
# Active Level
A level is like a level in a video game. It is specified with a name and two boundaries.
- name: Name of the level.
- lowerLevelLimit: The lower boundary of a level as integer.
- upperLevelLimit: The upper boundary of a level as integer.
This field contains a list of possible levels or can be left empty if you plan to use the default level.
If you don't add a level, we will use a default level called "Only Level" which goes from 0 to 2147483647.
Even if your upper limit is exceeded, XS will fall back to the default level.
[
{ "name": "Beginner", "lowerLevelLimit": 0, "upperLevelLimit": 200 },
{ "name": "Novice", "lowerLevelLimit": 201, "upperLevelLimit": 700 },
{ "name": "Intermediate", "lowerLevelLimit": 701, "upperLevelLimit": 2000 },
{ "name": "Expert", "lowerLevelLimit": 2001, "upperLevelLimit": 5000 }
]
# Form block with gamification
The Form block will contain a new option "Include Form to Gamification". Selecting this option will include this form to gamification.
# Gamification: Form item
(Category: Output) Display Gamification Score On request
An item format that displays the current gamification score and any unseen changes to the score since the last time it was viewed.
⇒
← Mobile Sensing FAQ →