Rules: a closer look
Introduction.
Rules are one of the main concepts on the ODIN system. They allow a researcher to define the conditions under which questions should be shown to a participant.
When in doubt, you can always select a rule and read the description of its logic, e.g.:
Rule platforms.
When you create any rule, the ODIN website will ask you to choose a platform. This parameter simply determines where that rule will be registered and evaluated, either on the ODIN server or on the participants' phones.
As you may expect, rules registered on the user's phone tend to be more responsive, since they are locally computed and thus don't require the device to communicate with our servers to work.
Additionally, some types of rules can only be registered on one platform, due to inherent constraints.
Common parameters.
Each rule has a set of parameters that are specific to it, as well as some common, predefined ones that apply to all of them, namely:
- Maximum number of seconds to show the question for: determines for how long a question fired by the given rule is going to remain available for the participant to answer. After this period expires, the question will be considered expired.
- Groups (comma-separated integers): When you print coupons for a study, you have to add them to one or more groups. Using this parameter, you can make rules target different groups.
Commonly used rules.
Below you'll find a list of the most common types of rules.
Upon recurring time interval.
This rule describes a recurrent schedule for a question to fire; that is, it reacts to the current time on the user's phone.
Follow-ups.
Follow-up rules allow you to trigger a question as a follow-up to another question's reply.
There are multiple types of follow-up rule, but they all follow the same type of logic: "fire question A whenever question B is answered with/out any of these replies".
A follow-up rule can be react to any answer (including expired, skipped or unset).
Location-based rules.
Location rules allow you to react to the participants' position.
Note that, in order to use these rules, your study has to have the GPS sensor enabled. When adding a sensor, you have to define a sensor interval, which determines how often should the ODIN app record data for that sensor.
- Upon arrival to specified location: fires if the user has been away from the radius of the target lat/long for two sensor intervals ([2*SI]), and immediately after gets two GPS readings within the target lat/long-radius.
- Upon departure from specified location: fires if the user has been within radius of the target lat/long for two sensor intervals ([2*SI]), and immediately after gets two GPS readings within radius of the target lat/long.
- Upon arrival at any of the specified locations: equivalent to the aforementioned arrival rule, but applicable to multiple locations provided on a multilocation CSV.
- Upon departure from any of the specified locations: equivalent to the aforementioned arrival rule, but applicable to multiple locations provided on a multilocation CSV.
- While at specified location: fires if the user has been within radius of the target lat/long for at least two sensor intervals ([2*SI]), and then keeps firing every X seconds (configurable) as long as this condition remains met.
- While NOT at specified location: fires if the user has not been within radius of the target lat/long for at least two sensor intervals ([2*SI]), and then keeps firing every X seconds (configurable) as long as this condition remains met.
Multilocation CSV.
In order to provide multiple locations for a single rule, multi-location arrival and departure rules allow you to input a file with comma-separated values (CSV).
Each row has to define a latitude, longitude and radius (meters), just like a regular location rule. Additionally, each row has to provide a cronstring and duration field.
The radius is in meters; lat should be between -90 and 90, and long between -180 and 180.
The duration (minutes) and cron string together define the schedule; that is, at which days/times and for how long you want the location to be checked for by the rule.
The cron string gives you the recurring starting point (e.g., every day at 10 AM, "0 9 * * *"; the duration gives you the recurring ending point.
Let's look at an example, consider this row:
latitude
longitude
radius
cronstring
duration
-34.6467
-58.5834
50
0 8 * * *
1440
It has the cron expression "0 11 * * 0-4" (remember that you can refer to our cron expressions introduction for more info on those), and a duration of 600 minutes. That means we want to check for the given lat/long/radius starting at 11 AM from Sunday through Thursday, and for a duration of 10 hours.
A more concrete example: say you want to fire a question when the participant goes to a bar. You may have a file with lat/lon/rad for 20 bars you're interested in; but you don't want to ask the question if the participant just happens to be around the bar while it's closed. So you would define a schedule (cronstring+duration) for each bar, according to the place's working hours.
E.g., if one of the bars is open every day from 9 AM to 9 PM, the cron string would be "0 9 * * *", the duration 720... and the bar a very boring place.
Lastly, here's an example multilocation CSV that you can modify according to your needs and upload to ODIN:
LocationsExample.csv
92Bytes, Uploaded 3 years ago
And these are some helpful tools we recommend:
- To figure out the radius visually: Draw a circle with a radius on a map
- To deal with cron strings: Crontab.guru - The cron schedule expression generator
Time windows CSV.
The time windows CSV is used to specify the brackets within which times an "Upon random time within provided windows" rule is allowed to fire.
The file has only two columns: "min" and "max", both of which can have any integer in the range 0-23 (i.e., a valid hour of the day on a 24-hour clock).You can have up to 50 rows in a single file, and time overlaps are allowed.
Here's an example that defines two valid windows (from 10AM to noon, and from 4PM to 6PM):
10
12
16
18
To avoid any formatting issues when creating this rule, we suggest you download the following file and modify it according to your needs:
random.time.window_example.csv
23Bytes, Uploaded last year
Forecasting rules
ODIN provides an interface for researchers to plug-in their own ML modules (from now on, "consumers"), so as to react to their predictions of the data. This type of integration has roughly three steps:
The researcher flags a question as "forecast-enabled", by attaching a forecasting rule to it. Alongside this rule, the researcher may add a configuration JSON file, and a set of "custom keys", which he knows beforehand the consumer will send (i.e., define the expected output of the consumer).
The researcher's consumer uses our Data Analysis API to pull the study data, as well as the information about the forecast-enabled questions, and performs data analysis/predictions on them.
The researcher's consumer uses the same API to push up the results of its forecasts to ODIN.
The researcher uses a forecast_reaction rule to react to the forecastings made by the consumer, using the custom keys as operands in a comparison.
Forecasting rule.
The forecasting rule is essentially an interface for you to communicate with your consumers. There are three pieces of information the researcher can communicate through this rule's configuration:
By adding a forecasting rule to a question, you are "flagging it" as forecasting-enabled. A well-behaved consumer will only ever operate on these questions.
Using the rule's parameters, you can provide two JSON files:
A configuration JSON. This is a completely arbitrary file that ODIN will blindly pass back to your consumer.
A JSON file with a set of "custom keys", in the following format:{ "keys": ["somethingElse", "something"]}This file simply defines a list of expected outputs from your consumer. ODIN will use this file to populate the inputs of the forecast_reaction rule type, which in turn will allow you to react to forecasting made by your consumer, triggering questions.
keysexample.json
48Bytes, Uploaded 7 months ago
configexample.json
2KB, Uploaded 3 months ago
Forecast_reaction rule.
A forecast_reaction rule is similar to a cron rule, in that they both instruct the ODIN system to run some task periodically.
In the case of the cron rule, that task is simply to show a question to the user.
In the case of a forecast_reaction rule, that task is to take a look at the forecasts pushed by the consumer for a specific rule, and show a question to the user if a specified comparison is true.
The forecast_reaction rule thus always refers back to a forecasting rule.
At the time of writing, the forecast_reaction rule can only be attached to random prompt questions; that means that your reaction to predicted participant behavior can only be of that type.
To create a forecast_reaction rule, simply go to the ODIN
For instance, you may want to show an encouraging prompt to a participant if the forecasted answer for a given question Q for 6 hours into the future is above a certain threshold. In that case, you would:
Add a forecasting rule to Q, so that you can instruct your consumer to predict the future value of that answer.