Sampling

Warning!

If you edit anything in your sampling while your study is already running, the changes won't propagate automatically to your participants' devices.

To fetch the changes on your participants' devices, they need to follow the steps described in the chapter App usage.

Sampling Graph

The sampling defines in a visual language when an action will be performed. With this visual language several sampling blocks can be combined to design a sampling scheme that fits nearly every study.

You can drag the blocks from the left side to the white sampling document on the right side. You can rearrange the blocks by dragging them around. You can adjust the view of the sampling document by dragging the white background.

After placing the blocks you can configure them. You can do so by double-clicking the block or clicking on the edit pen in the right top corner of the block. In the appearing window you need to configure the block. As soon as you saved the block configuration the block shows its configuration in an abbreviated version. The "Form" block only shows the internal id of the form. With the root block Sampling Running you can configure the study like the pin code or the lockout mode.

The sampling blocks can be combined in a specific order (the grammar of the visual language). This order is represented through the colors of a traffic light (red, yellow, green).

1. One or more red conditions. These conditions narrow down the range of the sampling.
2. One yellow trigger. This trigger defines when the actions below start.
3. One or more green actions. These actions execute as soon as the trigger applies.

As soon as you have placed some blocks in the sampling document you can connect them. Do this by dragging the handle on the bottom of the block to the top of the subsequent block. The handle of the block (square or circle) assures that you only place one trigger in each path.

You can save your sampling by pressing the save button in the top right corner.

WARNING

If you leave the sampling page without saving, your changes will be lost!

Alarm Configuration

The alarm block triggers the participant to e.g. fill out a form. In the default configuration the alarm reminds the participant over five minutes.

By changing the Sound/Vibration duration, the Display duration and the Number of alarms, you can configure how often and how long the participant will be reminded. You can also allow the participant to delay or dismiss the alarm if he is currently busy.

Random Time Trigger

The random time trigger follows a stratified randomization instead of allowing random prompts at any possible time. It takes the set time frame and divides it equally to accommodate the number of required prompts. It’s within these smaller chunks that the random prompt appears, only governed by the minimum time between prompts.

For Example, you set the Start Time to 8:00 and the End Time to 20:00, the Number of Prompts to 6 and the Minimum Time Between Prompts to 0:30 (30 minutes). The random time trigger will now divide the 12 hour time frame between start time and end time into 6 chunks of 2 hours. So the 6 prompts appear randomly in the following time frames:

Note: If a prompt occurs near the end of its time frame, the next prompt actually falls in a smaller time frame due to the minimum time between prompts. E.g. in the example above, if the first prompt occurs at 09:50 and the minimum time between prompts is set to 0:30, the second prompt triggers sometime between 10:20 and 12:00.

WARNING

There are 2 different messages which could be displayed by the smartphone after starting a study with the random time trigger:

1. Configuration warning in 'Random Time': 'Minimum Time Between Prompts' is too high to get a good random distribution.
   This message will be displayed, when two times the Minimum Time Between Prompts is higher than the potential time frame. This may lead to a bad randomization.
2. Configuration error in 'Random Time': 'Number of Prompts' do not fit into day because of 'Minimum Time Between Prompts'.
   This message will be displayed when the configured Minimum Time Between Prompts is higher than the potential time frame. This will lead to a non-functional randomization.

Best practice

Simple Scheme

Sampling every day between 08:00 and 20:00, 8 alarms with one form. If you have a SIM-Card and mobile data contract installed in your smartphone you can instantly upload the collected forms by adding an upload block. For simplicity we only added this block to this example.

Simple Scheme + Participant Can Start the Form

The same scheme as before, but now the participant starts a form himself by pressing the button Start form. An alarm is not necessary if the participant triggered the form himself.

Weekday/Weekend Sampling Scheme

In this scheme we added two weekday blocks and two fixed time blocks. From Monday to Friday, the random sampling is active. At the weekend only at the fixed time 14:00 and 18:00 o’clock an alarm comes up.

Different Forms at Different Days

If you want to have different forms to appear at different days of the study you can use the Sampling Day blocks. In the example below the first path is only executed at day one, the second path is executed at day two.

Different Forms at Different Times

If you want to have different forms to appear at different times you can have a different path (with an alarm block and a form block) for each time.

Mixed Scheme

Of course you can also mix all the examples above, but we recommend keeping it as simple as possible.

Different Start Dates for Each Participant

It is very common, that you run a study with multiple participants that start at different days. Please try to keep your sampling scheme as date independent as possible and try not to use the Date Range block. Instead just define a start and end date for each participant in the Participants tab of your study.

In the example below the sampling for the first participant starts at 2013-03-12 and ends at 2013-03-19 (both days included). The sampling for the second participant starts one day later but does not end until you stop it on the smartphone. The sampling for the third participant starts as soon as you start the sampling on the device and will only stop if you stop it on the smartphone.

Mutable Values (a.k.a. Variables)

With mutable values the sampling scheme can be even more flexible. It is very powerful, but can also introduce errors, if the sampling scheme is not correctly designed. This feature is currently in beta, please contact us, if you want to test this feature!

1. Make sure you use the movisensXS Android app version 0.6.3412 or newer.
2. Go into the preferences of your study (wrench icon), select movisensXS Library v3357 or newer and save the changes.
3. Go into the sampling, there are now new sampling blocks available in the Advanced tab (Check Mutable Value and Change Mutable Value).

With these two blocks it is possible to activate/deactivate different parts of your sampling in dependency of previous actions.

Random alarms only when a mutable value is true

The following example demonstrates on how to activate a random triggering only, 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 when 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 only, 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 only, if the participant has not yet completed this form today.

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.

Sampling Blocks Library version 7365

Sampling blocks or features which are marked "On request" can be requested by contacting our support team.

Study Running

This node is active if the study is running.

Label	Description	Type	Default-Value
Enable Messaging	Allow participant to write/receive messages to/from the study supervisor.	Boolean	true
Full Screen	movisensXS runs in fullscreen during the study.	Boolean	false
Lock other Applications	If you activate this other applications are not accessible for the participant.	Boolean	false
Allowed Apps On request	Specify apps that are allowed to run (e.g. 'com.yourApp'). This is required if you are using your own apps in the forms. This functionality may not work on Android 5.0 or higher.	String	com.yourApp
Not Allowed Apps On request	Specify apps that are not allowed to run (e.g. 'com.yourApp').	String
PIN code	This pin code allows the supervisor to control the study. The pin code '0' enables accessing the study control without pin.	Integer	2486
Log Node Status and Variables On request	Logging of node status changes into the unisens file format under /sdcard/movisensXS/logs/	Boolean	false
Mutable Value Editor On request	Enables mutable value editor which is accessible via study management screen.	Boolean	false
Form Starter On request	Enables form starter which is accessible via study management screen.	Boolean	false
Disable home screen On request	Disables the home screen from showing. Only necessary if movisensXS is used to trigger actions in the background.	Boolean	false

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

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

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

Delay

This event delays the previous event for the specified time and then triggers the successor nodes.

Label	Description	Type	Default-Value
Delay	Time to delay the source signal in seconds	Integer	10

Frequency Limit On request

This action prevents too much triggers.

Label	Description	Type	Default-Value
Time between triggers On request	Minimal time between triggers in seconds	Integer	3600

Context

App Used On request

This trigger fires if the specified app or activity is opened/closed. This functionality may not work on Android 5.0 or higher.

Label	Description	Type	Default-Value
Type On request	Defines if triggers on open or close of the application (AppOpened, AppClosed).	String	AppClosed
Package or activity identifier On request	The identifier of an app (e.g. com.android.settings) or of an activity (e.g. com.android.settings/.Settings) to trigger on.	String	com.android.settings/.Settings

Nearby Devices Condition On request

This condition will be true when at least one matching beacon is in range. It will send a bluetooth advertisement through IBeacon standard on supported devices and will take all other devices which are broadcasting with a beacon standard into account.

An IBeacon consists of three parts:

ID	Description	movisensXS broadcast content
ID1	UUID	7ab97c36-b634-11e6-80f5-76304dec7eb7
ID2	Major value	StudyId
ID3	Minor value	ParticipantID

movisensXS always broadcasts the UUID 7ab97c36-b634-11e6-80f5-76304dec7eb7 and uses the StudyId as the Major value and the ParticipantID as the Minor value. This feature can e.g. be used to identify situations where partners are close to each other by specifying the movisensXS UUID in ID1, the StudyID in ID2 and the ParticipantID of e.g. participant 1 in the ID3 field of participant 2. You find the StudyId in the browser url of movisensXS e.g. https://xs.movisens.com/studies/111. This block is typically used in conjunction with the Log Nearby Devices mobile sensing block to log the nearby devices seen.

Label	Description	Type	Default-Value
Broadcast Signal On request	Enable to broadcast nearby signal.	Boolean	true
Scanning interval On request	Determines how long the scan should last. Beacon scanning consumes power, a practical value is 10 seconds.	Integer	10
Time Between Scans On request	Interval between scans if a beacon is around in seconds. Beacon scanning consumes power, a practical value is 300 seconds.	Integer	300
ID1/URL Regex On request	Regex of ID1 or URL in case of Eddystone URL	String	[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}
ID2 Regex On request	Regex of ID2	String	.*
ID3 Regex On request	Regex of ID3	String	.*

Geofence Trigger On request

This event fires if a given geofence was entered, left or the participant is staying in it over some time.

Label	Description	Type	Default-Value
Latitude On request	Latitude of the geofence.	Double	0
Longitude On request	Longitude of the geofence.	Double	0
Radius On request	Radius of the given geofence in meter.	Integer	100
Geofence Type On request	Specifies if the trigger will be triggered by entering, leaving or staying in the bounds of the geofence. Options [Enter, Stay, Exit].	String	Enter
Duration of Stay On request	Specifies how long the participant must stay in the geofence in seconds to trigger it. Only needed if the geofence type is 'Stay'.	Integer	300
Initial Trigger On request	Specifies if the geofence should trigger the initial location of the participant dependent on the geofence.	Boolean	false

GIS Trigger On request

This trigger fires if the GIS returns a trigger.

Label	Description	Type	Default-Value
GIS url On request	GIS url	String
Distance On request	Distance the device must travel to check the GIS. Distance in meters.	Integer	100

Location Changed On request

This trigger fires if the location changed.

Label	Description	Type	Default-Value
Distance On request	Distance the device must travel to trigger a location change. Distance in meters. Accuracy varies between 10 and 1000 meters.	Integer	1000

Multi Geofence Trigger On request

This event fires if a given geofence was entered, left or the participant is staying in it over some time.

The geofences have to be specified in the following csv format:

id,name,latitude,longitude,radius,mode,durationOfStay
0,Mensa,49.0118868,8.4168792,100,enter
1,Oxford,49.0098936,8.4144250,100,stay
2,Studierendenwerk,49.01136560000001,8.4172656,100,exit
3,Fachschaft Informatik,49.0143397,8.4178346,100,stay,600

• id integer value which should be ascending. No duplicates allowed.
• name or description of the geofence in alphanumerical characters.
• latitude latitude of the geofence. Ranges between -90 and 90.
• longitude longitude of the geofence. Ranges between -180 and 180.
• radius integervalue in meter.
• modus one of stay, enter or exit.
• durationOfStay integer value in seconds(optional, default=300).

Label	Description	Type	Default-Value
Geofences (CSV) On request	Geofences in a CSV format ('id,name,latitude,longitude,radius,mode,durationOfStay'). The mode requires one of 'stay', 'enter' or 'exit'.	String

Notification Trigger On request

Trigger when a notification arrives. Please note: Notifications arrive very often, keep in mind to not bother your participants to often.

Label	Description	Type	Default-Value
Filter On request	Only react to the given packages (Separated with ';')	String	com.whatsapp

Location Accuracy On request

This action changes the location accuracy.

Label	Description	Type	Default-Value
Accuracy On request	Requested Accuracy (Auto, High, Passive)	String	Auto

Deprecated

SensorTrigger: Sensor Disconnected On request

Triggers when the coupled sensor of the 'Sensor Trigger' was disconnected from the smartphone.

SensorTrigger: Sensor Stopped On request

Triggers when the coupled sensor of the 'Sensor Trigger' was stopped.

SensorTrigger: Stop Sensor On request

This action stops the coupled sensor of the 'Sensor Trigger'

SensorTrigger: Trigger On request

Triggers when the 'Sensor Trigger' triggers.

Development

Send Intent On request

This action executes an android intent operation. An Android intent is an abstract description of an operation to be performed.

Label	Description	Type	Default-Value
Action On request	The general action to be performed, such as 'android.intent.action.VIEW'.	String	com.yourApp.YourReceiverName
Data On request	The data to operate on, such as a web url.	String
Type On request	The type of intent [App, Activity, Broadcast, StartSerice or StopService].	String	Broadcast

Intent Received On request

This condition listens to an android broadcast intent operation.

Label	Description	Type	Default-Value
Intent On request	An Android broadcast intent is an abstract description of an operation to listen on.	String	com.yourApp.YourBroadcastName

Forms

Alarm

This notifies the participant about a task he has to perform e.g. fill out a form.

Label	Description	Type	Default-Value
Title	Title text of the alarm.	String	Alarm
Sound/Vibration duration	How long the sound and vibration lasts per alarm in seconds.	Integer	10
Display duration	How long one alarm will be shown after sound and vibration in seconds.	Integer	50
Number of alarms	How often a alarm shows.	Integer	5
Maximum delay time	How long the participant can delay the alarm in minutes (0=disabled).	Integer	20
Dismissable	The participant can dismiss the alarm.	Boolean	true

Form

This action runs the specified form. Place an alarm before to notifiy the participant about the form!

More information about randomization and page indicators can be found here

Label	Description	Type	Default-Value
Form ID	Id of the form to run	String
Timeout Interval	After how many seconds of inactivity a timeout warning will be shown. (0 = disable)	Integer	60
Timeout Length	Length of the timeout alarm in seconds.	Integer	20
Display back button	Allows the user to go back to the previous question.	Boolean	true
Show Page Indicator	Shows a small page indicator at the top of the form.	Boolean	true
Screen orientation	Locks the screen orientation [Free, Portrait, Landscape].	String	Free
Randomized On request	If marked, the questions are displayed in a random order.	Boolean	false
Include Form to Gamification On request	If marked, the the completions or incompletions will be used in gamification score calculation.	Boolean	true
Count of random items On request	Shows only the given count of all items in a stratified randomized order (if randomized is activated). If 0 all items will be randomized.	Integer	0

Upload Results

This action uploads the collected results to the server.

Label	Description	Type	Default-Value
Automatic upload retry	Retry upload automatically if no internet connection was available. WARNING: All upload blocks will automatically using the highest choosen option. Please don't mix Wlan and Any (None will be ignored in the future). Options [None, Wlan, Any]	String	Wlan

Logging

Record Audio On request

This action records the audio of the microphone for the specified duration. Files are stored on the sdcard in the folder 'movisensXS/EAR'. Please Note: If you use this, you shouldn't use other item formats which connect to the microphone (video, audio).

Label	Description	Type	Default-Value
Duration On request	Time to record audio in seconds	Integer	45
Uncompressed On request	The files are saved as uncompressed .wav foles	Boolean	false

Smartphone

Battery Low On request

This condition is true if the battery level is below the configured level.

Label	Description	Type	Default-Value
Level On request	The low battery level.	Integer	20

Study

Number of Responses On request

This condition is true if the number of responses are in the defined range (Response number starts with 0 and increments if a form is completed).

Label	Description	Type	Default-Value
Minimum responses	Minimum responses to be true	Integer	0
Maximum responses	Maximum responses to be true	Integer	50

Button pressed

This event fires if the participant presses a presented button and triggers the successor nodes. A.k.a. Event-contingent.

Label	Description	Type	Default-Value
Button label	Label of the button that is shown in the home screen	String	Start form
Button order	The order of the buttons on the home screen. The higher the order/weight, the deeper it sinks.	Integer	1
One time button	If you activate this the button is only once clickable.	Boolean	false
Button Group On request	Button will be added to the defined button group and can be minimized.	String

Time

Date Range

This condition is true if the current date is in the selected range. Start and end date is included.

Label	Description	Type	Default-Value
Start date	Start date of the condition. Dates must be formatted as yyyy-MM-dd	Date
End date	End date of the condition. Dates must be formatted as yyyy-MM-dd	Date

Fixed Time

This event fires if the specified time is reached and triggers the successor nodes. A.k.a. Interval-contingent.

Label	Description	Type	Default-Value
Time	Time in the format HH:mm	Date	14:00

Immediately

This event fires as soon as the previous node is true.

Initial

This event fires only once after the previous node is true.

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

Random Time

This event fires randomly a specified number of prompts in the specified time period and triggers the successor nodes. A.k.a. Signal-contingent.

Label	Description	Type	Default-Value
Start Time	Time in the format HH:mm	Date	08:00
End Time	Time in the format HH:mm	Date	20:00
Mutable Value Name for Start Time On request	Name of mutable value which defines the start time.	String
Mutable Value Name for End Time On request	Name of mutable value which defines the end time.	String
Number of Prompts	Number of Prompts between start and end time	Integer	8
Minimum Time Between Prompts	Time in the format HH:mm	Date	00:30

Repeated

This trigger fires in the configured interval as long as the previous condition stays true.

Label	Description	Type	Default-Value
Repeat interval	Interval to trigger in seconds. 3600 = 1 hour.	Integer	3600
Reset time, when other triggers happen On request	When enabled, the interval time is reset, if another trigger happened during the interval time.	Boolean	false
Randomization time On request	Time to randomize the repeat interval in seconds. e.g. 600 = ±10 minutes.	Integer	0

Sampling Day

This condition is true if the sampling day is in the defined range (Sampling day starts with day 1 and increments at midnight if sampling is running).

Label	Description	Type	Default-Value
Start day	Start day as number	Integer	1
End day	End day as number	Integer	2

Time Range

This condition is true if the current time is between the specified time range.

Label	Description	Type	Default-Value
Start Time	Time in the format HH:mm	Date	08:00
End Time	Time in the format HH:mm	Date	20:00
Mutable Value Name for Start Time On request	Name of mutable value which defines the start time.	String
Mutable Value Name for End Time On request	Name of mutable value which defines the end time.	String

Weekday

This condition is true if the enabled weekday is reached.

Label	Description	Type	Default-Value
Weekdays	Comma-seperated list of enabled weekdays. [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]	String	Monday, Tuesday