Merge pull request #50 from RADAR-CNS/v0.2-alpha.2_release

RADAR-Schemas version 0.2-alpha.2

README.md

@@ -15,9 +15,12 @@ In addition, schemas in the `commons` directory should follow the following guid
 - Try to avoid abbreviations in the field names and write out the field name instead.
 - There should be no need to add `value` at the end of a field name.
 - Enumerator items should be written in uppercase characters separated by underscores.
-- Add documentation (the `doc` property) to each schema and each field. The documentation should show in text what is being measured, how, and what units or ranges are applicable. Abbreviations and acronyms in the documentation should be written out.
-- Prefer a categorical specification (an Avro enum) over a free string. This disambiguates the possible values for analysis.
+- Add documentation (the `doc` property) to each schema, each field, and each enum. The documentation should show in text what is being measured, how, and what units or ranges are applicable. Abbreviations and acronyms in the documentation should be written out.
+- Prefer a categorical specification (an Avro enum) over a free string if that categorization is expected to remain very stable. This disambiguates the possible values for analysis. If a field is expected to be extended outside this project or very often within this project, use a free string instead.
 - Prefer a flat record over a hierarchical record. This simplifies the organization of the data downstream, for example, when mapping to CSV.
 - Prefer written out fields to arrays. This simplifies the organization of the data downstream, for example, when mapping to CSV.
 - Give each schema a proper namespace, preferably `org.radarcns.deviceproducer` fully in lowercase, without any numbers, uppercase letters or symbols (except `.`). For the Empatica E4, the producer is Empatica, so the namespace is `org.radarcns.empatica`. For generic types, like a phone, Android Wear device or Android application, the namespace could just be `org.radarcns.phone`, `org.radarcns.wear`, or `org.radarcns.application`.
 - In the schema name, use upper camel case and name the device explicitly (for example, `EmpaticaE4Temperature`).
+- For fields that are inherent to a record, and will never be removed or renamed, no default value is needed. For all other fields:
+  - if the type is an enum, use an `UNKNOWN` symbol as default value
+  - otherwise, set the type to a union of `["null", <intended type>]` and set the default value to `null`.

commons/application/application_external_time.avsc

@@ -6,9 +6,14 @@
   "fields": [
     {"name": "time", "type": "double", "doc": "device timestamp in UTC (s)"},
     {"name": "timeReceived", "type": "double", "doc": "device receiver timestamp in UTC (s)"},
-    {"name": "externalTime", "type": "double", "doc": "timestamp in UTC according to an external source (s)", "default": "NaN"},
+    {"name": "externalTime", "type": "double", "doc": "timestamp in UTC according to an external source (s)"},
     {"name": "host", "type": ["null", "string"], "doc": "hostname or IP address that time was polled from", "default": null},
-	{"name": "protocol", "type": {"name": "ExternalTimeProtocol", "type": "enum", "symbols": ["SNTP", "NTP"], "doc": "SNTP (Simple Network Time Protocol) synchronizes with a single server once, NTP (Network Time Protocol) may synchronize with multiple servers and derive some continuous measures."}, "doc": "protocol for external time synchronization", "default": "SNTP"},
-    {"name": "delay", "type": "double", "doc": "delay between sending and receiving a message from the host (s). The lower this delay, the more precise the external timestamp is expected to be.", "default": "NaN"}
+	  {"name": "protocol", "type": {
+      "name": "ExternalTimeProtocol",
+      "type": "enum",
+      "symbols": ["SNTP", "NTP", "UNKNOWN"],
+      "doc": "SNTP (Simple Network Time Protocol) synchronizes with a single server once, NTP (Network Time Protocol) may synchronize with multiple servers and derive some continuous measures."
+    }, "doc": "protocol for external time synchronization", "default": "UNKNOWN"},
+    {"name": "delay", "type": ["null", "double"], "doc": "delay between sending and receiving a message from the host (s). The lower this delay, the more precise the external timestamp is expected to be.", "default": null}
   ]
-}
+}

commons/phone/phone_battery_level.avsc

@@ -8,6 +8,11 @@
     {"name": "timeReceived", "type": "double", "doc": "device receiver timestamp in UTC (s)"},
     {"name": "batteryLevel", "type": "float", "doc": "battery level from 0 to 1"},
     {"name": "isPlugged", "type": "boolean", "doc": "whether the phone is connected to a power source"},
-    {"name": "status", "type": {"name": "BatteryStatus", "type": "enum", "symbols": ["UNKNOWN", "CHARGING", "DISCHARGING", "NOT_CHARGING", "FULL"]}, "doc": "Android battery states", "default": "UNKNOWN"}
+    {"name": "status", "type": {
+      "name": "BatteryStatus",
+      "type": "enum",
+      "doc": "Android device battery states",
+      "symbols": ["UNKNOWN", "CHARGING", "DISCHARGING", "NOT_CHARGING", "FULL"]
+      }, "doc": "Android battery states", "default": "UNKNOWN"}
   ]
 }

commons/phone/phone_call.avsc

@@ -6,9 +6,14 @@
   "fields": [
     {"name": "time", "type": "double", "doc": "device timestamp in UTC (s)"},
     {"name": "timeReceived", "type": "double", "doc": "device receiver timestamp in UTC (s)"},
-    {"name": "duration", "type": "float", "doc": "duration of the call (s)", "default": "NaN"},
+    {"name": "duration", "type": ["null", "float"], "doc": "duration of the call (s)", "default": null},
     {"name": "target", "type": ["null", "bytes"], "doc": "HMAC SHA-256 one-way source/target of the call. This hash of a given phone number will be the same unless the app is reinstalled. If the number is unknown or anonymous, this contains null.", "default": null},
-    {"name": "type", "type": {"name": "PhoneCallType", "type": "enum", "symbols": ["INCOMING", "OUTGOING", "MISSED", "VOICEMAIL", "UNKNOWN"]}, "doc": "direction of phone call", "default": "UNKNOWN"},
+    {"name": "type", "type": {
+      "name": "PhoneCallType",
+      "type": "enum",
+      "doc": "Type of Android call",
+      "symbols": ["INCOMING", "OUTGOING", "MISSED", "VOICEMAIL", "UNKNOWN"]
+    }, "doc": "direction of phone call", "default": "UNKNOWN"},
     {"name": "targetIsContact", "type": ["null","boolean"], "doc": "call to/from a known contact, null if unknown", "default": null},
     {"name": "targetIsNonNumeric", "type": "boolean", "doc": "sms sender ID is replaced by text, e.g. a company name", "default": false},
     {"name": "targetLength", "type": "int", "doc": "length of the target phone number, -1 if not collected.", "default": -1}

commons/phone/phone_relative_location.avsc

@@ -6,12 +6,17 @@
   "fields": [
     {"name": "time", "type": "double", "doc": "device timestamp in UTC (s)"},
     {"name": "timeReceived", "type": "double", "doc": "device receiver timestamp in UTC (s)"},
-    {"name": "provider", "type": {"name": "LocationProvider", "type": "enum", "symbols": ["GPS", "NETWORK", "OTHER"]}, "doc": "Android provider of the location data"},
-    {"name": "latitude", "type": "double", "doc": "relative latitude from an initial random reference latitude (degrees with range [-90, 90])", "default": "NaN"},
-    {"name": "longitude", "type": "double", "doc": "relative longitude from an initial reference longitude (degrees with range [-180, 180])", "default": "NaN"},
-    {"name": "altitude", "type": "float", "doc": "height above the WGS 84 reference ellipsoid (m)", "default": "NaN"},
-    {"name": "accuracy", "type": "float", "doc": "The estimated horizontal accuracy of this location, radial (m). We define horizontal accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.", "default": "NaN"},
-    {"name": "speed", "type": "float", "doc": "speed over ground (m/s)", "default": "NaN"},
-    {"name": "bearing", "type": "float", "doc": "the horizontal direction of travel of this device (degrees with range (0, 360])", "default": "NaN"}
+    {"name": "provider", "type": {
+      "name": "LocationProvider",
+      "type": "enum",
+      "doc": "Type of provider of location data.",
+      "symbols": ["GPS", "NETWORK", "OTHER"]
+      }, "doc": "Android provider of the location data"},
+    {"name": "latitude", "type": ["null", "double"], "doc": "relative latitude from an initial random reference latitude (degrees with range [-90, 90])", "default": null},
+    {"name": "longitude", "type": ["null", "double"], "doc": "relative longitude from an initial reference longitude (degrees with range [-180, 180])", "default": null},
+    {"name": "altitude", "type": ["null", "float"], "doc": "height above the WGS 84 reference ellipsoid (m)", "default": null},
+    {"name": "accuracy", "type": ["null", "float"], "doc": "The estimated horizontal accuracy of this location, radial (m). We define horizontal accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.", "default": null},
+    {"name": "speed", "type": ["null", "float"], "doc": "speed over ground (m/s)", "default": null},
+    {"name": "bearing", "type": ["null", "float"], "doc": "the horizontal direction of travel of this device (degrees with range (0, 360])", "default": null}
   ]
-}
+}

commons/phone/phone_sms.avsc

@@ -7,7 +7,12 @@
     {"name": "time", "type": "double", "doc": "device timestamp in UTC (s)"},
     {"name": "timeReceived", "type": "double", "doc": "device receiver timestamp in UTC (s)"},
     {"name": "target", "type": ["null", "bytes"], "doc": "HMAC SHA-256 one-way source/target of the SMS. This hash of a given phone number will be the same unless the app is reinstalled. If the number is unknown or anonymous, this contains null.", "default": null},
-    {"name": "type", "type": {"name": "PhoneSmsType", "type": "enum", "symbols": ["INCOMING", "OUTGOING", "OTHER", "UNKNOWN"]}, "doc": "direction of the SMS", "default": "UNKNOWN"},
+    {"name": "type", "type": {
+      "name": "PhoneSmsType",
+      "type": "enum",
+      "doc": "Direction of an SMS",
+      "symbols": ["INCOMING", "OUTGOING", "OTHER", "UNKNOWN"]
+      }, "doc": "direction of the SMS", "default": "UNKNOWN"},
     {"name": "length", "type": ["null","int"], "doc": "number of characters in the message (null if unknown)", "default": null},
     {"name": "targetIsContact", "type": ["null","boolean"], "doc": "sms sender is a known contact, null if unknown", "default": null},
     {"name": "targetIsNonNumeric", "type": "boolean", "doc": "sms sender ID is replaced by text, e.g. a company name", "default": false},

commons/phone/phone_usage_event.avsc

@@ -9,8 +9,11 @@
     {"name": "packageName", "type": "string", "doc": "package name of the launched app"},
     {"name": "categoryName", "type": ["null", "string"], "doc": "app category as given by the play store, null if a category is not listed or unable to be fetched", "default": null},
     {"name": "categoryNameFetchTime", "type": ["null", "double"], "doc": "timestamp in UTC when the category was attempted to fetch from the play store (s), null if not fetched", "default": null},
-    {"name": "eventType", "type":
-      {"name": "UsageEventType", "type": "enum", "symbols": ["FOREGROUND", "BACKGROUND", "CONFIG", "SHORTCUT", "INTERACTION", "NONE"]},
-      "doc": "whether the event brought app to foreground or background or neither", "default": "NONE"}
+    {"name": "eventType", "type": {
+      "name": "UsageEventType",
+      "type": "enum",
+      "doc": "Android activity usage event type.",
+      "symbols": ["FOREGROUND", "BACKGROUND", "CONFIG", "SHORTCUT", "INTERACTION", "UNKNOWN"]
+      }, "doc": "whether the event brought app to foreground or background or neither", "default": "NONE"}
   ]
 }

commons/phone/phone_user_interaction.avsc

@@ -6,6 +6,11 @@
   "fields": [
     {"name": "time", "type": "double", "doc": "device timestamp in UTC (s)"},
     {"name": "timeReceived", "type": "double", "doc": "device receiver timestamp in UTC (s)"},
-    {"name": "interactionState", "type": {"name": "PhoneInteractionState", "type": "enum", "symbols": ["STANDBY", "UNLOCKED","SHUTDOWN","BOOTED"]}, "doc": "what interaction state the phone has"}
+    {"name": "interactionState", "type": {
+      "name": "PhoneInteractionState",
+      "type": "enum",
+      "doc": "Interaction type with an Android device",
+      "symbols": ["STANDBY", "UNLOCKED", "SHUTDOWN", "BOOTED"]
+      }, "doc": "what interaction state the phone has"}
   ]
 }

commons/questionnaire/questionnaire.avsc

@@ -6,7 +6,12 @@
   "fields": [
     { "name": "time", "type": "double", "doc": "timestamp in UTC (s) when the questionnaire is submitted to the subject" },
     { "name": "timeCompleted", "type": "double", "doc": "timestamp in UTC (s) when subject marks the questionnaire as" },
-    { "name": "name", "type": {"name": "QuestionnaireType", "type": "enum", "symbols": ["PHQ8", "ESM", "UNKNOWN"]}, "doc": "Questionnaire names", "default": "UNKNOWN" },
+    { "name": "name", "type": {
+      "name": "QuestionnaireType",
+      "type": "enum",
+      "doc": "Types of supported questionnaires",
+      "symbols": ["PHQ8", "ESM", "UNKNOWN"]
+      }, "doc": "Questionnaire names", "default": "UNKNOWN" },
     { "name": "version", "type": "string", "doc": "It reports the questionnaire version stated in the JSON specification" },
     { "name": "answers",
       "type": {

java-sdk/README.md

@@ -9,13 +9,13 @@ repositories {
 
 dependencies {
     // Commons schemas (backend, passive remote monitoring app)
-    compile 'org.radarcns:radar-schemas-commons:0.1'
+    compile 'org.radarcns:radar-schemas-commons:0.2-alpha.2'
 
     // REST API schemas (REST API, testing)
-    compile 'org.radarcns:radar-schemas-restapi:0.1'
+    compile 'org.radarcns:radar-schemas-restapi:0.2-alpha.2'
 
     // Questionnaire schemas (active remote monitoring app)
-    compile 'org.radarcns:radar-schemas-questionnaire:0.1'
+    compile 'org.radarcns:radar-schemas-questionnaire:0.2-alpha.2'
 }
 ```
 Usually, you only need to include the schemas you actually need in your dependencies.

java-sdk/build.gradle

@@ -15,7 +15,7 @@ subprojects {
     apply plugin: 'maven-publish'
 
     // Configuration
-    version = '0.2-alpha.1'
+    version = '0.2-alpha.2'
     group = 'org.radarcns'
     ext.githubRepoName = 'RADAR-CNS/RADAR-Schemas'
 
@@ -114,6 +114,6 @@ subprojects {
 }
 
 task wrapper(type: Wrapper) {
-    gradleVersion = '3.4.1'
-    distributionUrl distributionUrl.replace("bin", "all")
+    gradleVersion = '4.1'
+    distributionType 'all'
 }

java-sdk/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,5 @@
-#Tue Apr 04 09:32:46 CEST 2017
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-3.4.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.1-all.zip

java-sdk/gradlew

@@ -33,11 +33,11 @@ DEFAULT_JVM_OPTS=""
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD="maximum"
 
-warn ( ) {
+warn () {
     echo "$*"
 }
 
-die ( ) {
+die () {
     echo
     echo "$*"
     echo
@@ -155,7 +155,7 @@ if $cygwin ; then
 fi
 
 # Escape application args
-save ( ) {
+save () {
     for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
     echo " "
 }