Adaptive sensing docs.

DocFX/articles/adaptive-sensing.md

@@ -5,52 +5,56 @@ uid: adaptive_sensing
 # Adaptive Sensing
 An essential trade off within all mobile sensing apps is between (a) data density (high sampling
 rates) and continuity (no data gaps) and (b) battery drain. It is easy to configure Sensus to 
-optimize either of these objectives, but striking a balance between them poses significant 
+optimize either of these objectives in isolation, but striking a balance between them poses significant 
 challenges. For example, one might wish to sample high-density accelerometry when the device
-is likely to be used in particular ways (e.g., while walking). One might wish to sample light 
-and temperature data in particular geographic locations. No single, static sensing configuration 
-would satisfy such objectives. Rather, dynamic sensing configurations that adapt to the context
-of use are required. This article describes the way in which Sensus supports adaptive sensing.
+is likely to be used in particular ways (e.g., while walking). Similarly, one might wish to sample light 
+and temperature data, but only in particular geographic locations. No single, static sensing configuration 
+would satisfy such objectives while also having minimal impact on the battery. Such use cases require
+dynamic sensing configurations that adapt to usage contexts.
 
 ## Adaptive Control
-The figure below depicts the adaptive sensing state diagram.
+The figure below depicts concepts that drive adaptive sensing within Sensus.
 
 ![image](/sensus/images/adaptive-sensing-state-diagram.png)
 
-The following key concepts are indicated:
+The following concepts are indicated:
 
-* Opportunistic observation:  Sensing agents can be configured to observe state information (i.e.,
-data) actively or opportunistically. Opportunistic observation will capture any 
-<xref:Sensus.IDatum> object generated by Sensus during normal operation. In this mode, the app
-will not take any extra actions to observe data. This has the effect of reducing battery drain at 
-the expense of weaker state estimates and sensing control.
+* Sensing agent:  An entity that controls sensing parameters (e.g., sampling rates and continuity) on
+the basis of observed state (i.e., <xref:Sensus.IDatum> objects).
+
+* Opportunistic observation:  Sensing agents can be configured to observe state information actively 
+or opportunistically. Opportunistic observation captures any <xref:Sensus.IDatum> object generated 
+by Sensus during normal operation. In this mode, the app will not take any extra actions to observe 
+data. This has the effect of minimizing battery drain at the expense of weaker state estimates and 
+sensing control.
 
 * Opportunistic control:  In response to opportunistically observed data, the sensing agent
 may decide to control sensing in a particular way (e.g., by enabling continuous sensing or
-increasing sampling rates). Such decisions will only be possible upon the arrival of 
-opportunistic data.
+increasing sampling rates). Such decisions are only possible upon the arrival of opportunistic data.
 
-* Action interval:  In contrast with opportunistic sensing, sensing agents can be configured to 
-take extra actions to observe data. This has the effect of strengthening state estimates and sensing 
-control at the expense of increased battery drain. The action interval indicates how frequently Sensus 
-should actively observe data for state estimation.
+* Action interval:  In contrast with opportunistic sensing, sensing agents can be configured to actively
+seek out data. This has the effect of strengthening state estimates and sensing control at the expense 
+of increased battery drain. The action interval indicates how frequently Sensus should actively observe 
+data for state estimation.
 
 * Active observation duration:  Once the action interval elapses, Sensus will begin to actively
-observe each <xref:Sensus.IDatum> generated by the app. This parameter governs how long the
+observe each <xref:Sensus.IDatum> generated by the app. This parameter governs how long active
 observation should continue before checking the control criterion.
 
 * Control criterion:  Regardless of whether Sensus is observing opportunistically or actively, 
-the control criterion defines state estimate values that trigger sensing control. For example,
-a control criterion might specify that sensing control should occur when the average acceleration 
+the control criterion defines state estimates that trigger sensing control. For example, a 
+criterion might specify that sensing control should occur when the average acceleration 
 magnitude exceeds a critical threshold. This is demonstrated in the 
 [example](https://github.com/predictive-technology-laboratory/sensus/blob/develop/ExampleSensingAgent.Shared/ExampleAccelerationSensingAgent.cs)
-sensing agent.
+sensing agent. This agent also demonstrates a control criterion based on proximity of the phone
+to a surface (e.g., face).
 
 * Control completion check interval:  Once sensing control is invoked, the app will periodically 
-recheck the control criterion to determine whether or not it is still met. If it is not, then
-sensing control ends and the sensing agent returns to its idle state. If it is, then sensing 
-control continues until the next control completion check occurs. This parameter governs how
-long Sensus should wait between each completion check.
+recheck the control criterion to determine whether it is still met. If the criterion is not met, 
+then sensing control ends, the sensing agent transitions sensing settings as needed (e.g., reducing
+sampling rates), and the sensing agent returns to its idle state. If the criterion is still met, 
+then sensing control continues unabated until the next completion check occurs. This parameter governs 
+how long Sensus should wait between each completion check.
 
 ## Android
 

DocFX/index.md

@@ -15,11 +15,13 @@ Sensus's key features include the following:
   of smartphone users. Sensus runs on Android and iOS and emphasizes a uniform user experience.
 * **Comprehensive sensing** A complete list of internal hardware and software sensors, as well as external wearable 
   and beacon-based sensors, can be found [here](xref:Sensus.Probes.Probe).
-* **Device-initiated custom surveys** Sensus can prompt users to complete custom surveys that are scheduled or triggered 
+* **Device-initiated surveys** Sensus can prompt users to complete surveys that are scheduled or triggered 
   by sensed data. For example, surveys can be triggered on the basis of GPS location, proximity to points of interest, 
   speed, acceleration, light levels, sound levels, after phone calls or text messages, and so on. Virtually 
   any [probed data](xref:Sensus.Probes.Probe) can be used to trigger surveys, or you can schedule surveys to run during 
   particular time blocks.
+* **Support for adaptive sensing and surveys** Sensus is designed to support research into adaptive data collection, both
+  for [passive sensing](xref:adaptive_sensing) and [survey sensing](xref:adaptive_surveys).
 * **Fine-grained anonymization controls** Each type of sensed data has several fine-grained facets that can be individually anonymized.
 * **Minimal infrastructure requirements** Sensus is entirely self-contained. No external servers are required unless you 
   would like to push data to the cloud (e.g., Amazon) for centralized storage, which is supported with minimal effort through 

docs/api/Sensus.Protocol.html

@@ -256,7 +256,7 @@ <h3 id="properties">Properties
 
   <a id="Sensus_Protocol_Agent_" data-uid="Sensus.Protocol.Agent*"></a>
   <h4 id="Sensus_Protocol_Agent" data-uid="Sensus.Protocol.Agent">Agent</h4>
-  <div class="markdown level1 summary"><p>Gets or sets the sensing control agent. See <a href="xref:sensing_agent">here</a> for more information.</p>
+  <div class="markdown level1 summary"><p>Gets or sets the sensing control agent. See <a class="xref" href="../articles/adaptive-sensing.html">here</a> for more information.</p>
 </div>
   <div class="markdown level1 conceptual"></div>
   <h5 class="decalaration">Declaration</h5>

docs/articles/adaptive-sensing.html

@@ -81,49 +81,53 @@ <h1 id="adaptive-sensing">Adaptive Sensing</h1>
 
 <p>An essential trade off within all mobile sensing apps is between (a) data density (high sampling
 rates) and continuity (no data gaps) and (b) battery drain. It is easy to configure Sensus to 
-optimize either of these objectives, but striking a balance between them poses significant 
+optimize either of these objectives in isolation, but striking a balance between them poses significant 
 challenges. For example, one might wish to sample high-density accelerometry when the device
-is likely to be used in particular ways (e.g., while walking). One might wish to sample light 
-and temperature data in particular geographic locations. No single, static sensing configuration 
-would satisfy such objectives. Rather, dynamic sensing configurations that adapt to the context
-of use are required. This article describes the way in which Sensus supports adaptive sensing.</p>
+is likely to be used in particular ways (e.g., while walking). Similarly, one might wish to sample light 
+and temperature data, but only in particular geographic locations. No single, static sensing configuration 
+would satisfy such objectives while also having minimal impact on the battery. Such use cases require
+dynamic sensing configurations that adapt to usage contexts.</p>
 <h2 id="adaptive-control">Adaptive Control</h2>
-<p>The figure below depicts the adaptive sensing state diagram.</p>
+<p>The figure below depicts concepts that drive adaptive sensing within Sensus.</p>
 <p><img src="/sensus/images/adaptive-sensing-state-diagram.png" alt="image"></p>
-<p>The following key concepts are indicated:</p>
+<p>The following concepts are indicated:</p>
 <ul>
-<li><p>Opportunistic observation:  Sensing agents can be configured to observe state information (i.e.,
-data) actively or opportunistically. Opportunistic observation will capture any 
-<a class="xref" href="../api/Sensus.IDatum.html">IDatum</a> object generated by Sensus during normal operation. In this mode, the app
-will not take any extra actions to observe data. This has the effect of reducing battery drain at 
-the expense of weaker state estimates and sensing control.</p>
+<li><p>Sensing agent:  An entity that controls sensing parameters (e.g., sampling rates and continuity) on
+the basis of observed state (i.e., <a class="xref" href="../api/Sensus.IDatum.html">IDatum</a> objects).</p>
+</li>
+<li><p>Opportunistic observation:  Sensing agents can be configured to observe state information actively 
+or opportunistically. Opportunistic observation captures any <a class="xref" href="../api/Sensus.IDatum.html">IDatum</a> object generated 
+by Sensus during normal operation. In this mode, the app will not take any extra actions to observe 
+data. This has the effect of minimizing battery drain at the expense of weaker state estimates and 
+sensing control.</p>
 </li>
 <li><p>Opportunistic control:  In response to opportunistically observed data, the sensing agent
 may decide to control sensing in a particular way (e.g., by enabling continuous sensing or
-increasing sampling rates). Such decisions will only be possible upon the arrival of 
-opportunistic data.</p>
+increasing sampling rates). Such decisions are only possible upon the arrival of opportunistic data.</p>
 </li>
-<li><p>Action interval:  In contrast with opportunistic sensing, sensing agents can be configured to 
-take extra actions to observe data. This has the effect of strengthening state estimates and sensing 
-control at the expense of increased battery drain. The action interval indicates how frequently Sensus 
-should actively observe data for state estimation.</p>
+<li><p>Action interval:  In contrast with opportunistic sensing, sensing agents can be configured to actively
+seek out data. This has the effect of strengthening state estimates and sensing control at the expense 
+of increased battery drain. The action interval indicates how frequently Sensus should actively observe 
+data for state estimation.</p>
 </li>
 <li><p>Active observation duration:  Once the action interval elapses, Sensus will begin to actively
-observe each <a class="xref" href="../api/Sensus.IDatum.html">IDatum</a> generated by the app. This parameter governs how long the
+observe each <a class="xref" href="../api/Sensus.IDatum.html">IDatum</a> generated by the app. This parameter governs how long active
 observation should continue before checking the control criterion.</p>
 </li>
 <li><p>Control criterion:  Regardless of whether Sensus is observing opportunistically or actively, 
-the control criterion defines state estimate values that trigger sensing control. For example,
-a control criterion might specify that sensing control should occur when the average acceleration 
+the control criterion defines state estimates that trigger sensing control. For example, a 
+criterion might specify that sensing control should occur when the average acceleration 
 magnitude exceeds a critical threshold. This is demonstrated in the 
 <a href="https://github.com/predictive-technology-laboratory/sensus/blob/develop/ExampleSensingAgent.Shared/ExampleAccelerationSensingAgent.cs">example</a>
-sensing agent.</p>
+sensing agent. This agent also demonstrates a control criterion based on proximity of the phone
+to a surface (e.g., face).</p>
 </li>
 <li><p>Control completion check interval:  Once sensing control is invoked, the app will periodically 
-recheck the control criterion to determine whether or not it is still met. If it is not, then
-sensing control ends and the sensing agent returns to its idle state. If it is, then sensing 
-control continues until the next control completion check occurs. This parameter governs how
-long Sensus should wait between each completion check.</p>
+recheck the control criterion to determine whether it is still met. If the criterion is not met, 
+then sensing control ends, the sensing agent transitions sensing settings as needed (e.g., reducing
+sampling rates), and the sensing agent returns to its idle state. If the criterion is still met, 
+then sensing control continues unabated until the next completion check occurs. This parameter governs 
+how long Sensus should wait between each completion check.</p>
 </li>
 </ul>
 <h2 id="android">Android</h2>

docs/index.html

@@ -86,11 +86,13 @@
 of smartphone users. Sensus runs on Android and iOS and emphasizes a uniform user experience.</li>
 <li><strong>Comprehensive sensing</strong> A complete list of internal hardware and software sensors, as well as external wearable 
 and beacon-based sensors, can be found <a class="xref" href="api/Sensus.Probes.Probe.html">here</a>.</li>
-<li><strong>Device-initiated custom surveys</strong> Sensus can prompt users to complete custom surveys that are scheduled or triggered 
+<li><strong>Device-initiated surveys</strong> Sensus can prompt users to complete surveys that are scheduled or triggered 
 by sensed data. For example, surveys can be triggered on the basis of GPS location, proximity to points of interest, 
 speed, acceleration, light levels, sound levels, after phone calls or text messages, and so on. Virtually 
 any <a class="xref" href="api/Sensus.Probes.Probe.html">probed data</a> can be used to trigger surveys, or you can schedule surveys to run during 
 particular time blocks.</li>
+<li><strong>Support for adaptive sensing and surveys</strong> Sensus is designed to support research into adaptive data collection, both
+for <a class="xref" href="articles/adaptive-sensing.html">passive sensing</a> and <a class="xref" href="articles/adaptive-surveys.html">survey sensing</a>.</li>
 <li><strong>Fine-grained anonymization controls</strong> Each type of sensed data has several fine-grained facets that can be individually anonymized.</li>
 <li><strong>Minimal infrastructure requirements</strong> Sensus is entirely self-contained. No external servers are required unless you 
 would like to push data to the cloud (e.g., Amazon) for centralized storage, which is supported with minimal effort through 

docs/manifest.json

@@ -4324,15 +4324,12 @@
       "version": ""
     },
     {
-      "log_codes": [
-        "UidNotFound"
-      ],
       "type": "ManagedReference",
       "source_relative_path": "api/Sensus.Protocol.yml",
       "output": {
         ".html": {
           "relative_path": "api/Sensus.Protocol.html",
-          "hash": "/oyNrzmYp0Dl+32Rgp1xZA=="
+          "hash": "hVyC3QxolCzR2DiH2AXSAA=="
         }
       },
       "is_incremental": true,
@@ -6072,7 +6069,7 @@
       "output": {
         ".html": {
           "relative_path": "articles/adaptive-sensing.html",
-          "hash": "buTQRqBynKCJ7obAddM7FQ=="
+          "hash": "97dd60u4m7CfzzZQi5NlIQ=="
         }
       },
       "is_incremental": true,
@@ -6460,7 +6457,7 @@
       "output": {
         ".html": {
           "relative_path": "index.html",
-          "hash": "eNOnnvHqYuIc3IZ8MHhLcw=="
+          "hash": "Xok2oFvHSKPWgW2EZFvpwQ=="
         }
       },
       "is_incremental": true,
@@ -6486,23 +6483,23 @@
         "incrementalPhase": "build"
       },
       "processors": {
-        "ResourceDocumentProcessor": {
-          "can_incremental": false,
-          "details": "Processor ResourceDocumentProcessor cannot support incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.",
-          "incrementalPhase": "build"
-        },
         "TocDocumentProcessor": {
           "can_incremental": false,
           "details": "Processor TocDocumentProcessor cannot support incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.",
           "incrementalPhase": "build"
         },
-        "ManagedReferenceDocumentProcessor": {
+        "ConceptualDocumentProcessor": {
           "can_incremental": true,
           "incrementalPhase": "build"
         },
-        "ConceptualDocumentProcessor": {
+        "ManagedReferenceDocumentProcessor": {
           "can_incremental": true,
           "incrementalPhase": "build"
+        },
+        "ResourceDocumentProcessor": {
+          "can_incremental": false,
+          "details": "Processor ResourceDocumentProcessor cannot support incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.",
+          "incrementalPhase": "build"
         }
       }
     },