Merge pull request #12 from Watz-Inc/docs-update

Trace creation examples added

docs/conversions.md

@@ -18,7 +18,7 @@ The following types are supported, but serialize to json-compatible types destru
 | `datetime.datetime`              | `str`     | `time(12, 0, 0)`                    | `"12:00:00"`                  |                                                                                       |
 | `datetime.date`                  | `str`     | `date(2021, 1, 1)`                  | `"2021-01-01"`                |                                                                                       |
 | `datetime.time`                  | `str`     | `datetime(2021, 1, 1)`              | `"2021-01-01T00:00:00+00:00"` | [RFC 3339](https://tools.ietf.org/html/rfc3339) format, compatible with `isoformat()` |
-| `datetime.timedelta`             | `float`   | `timedelta(days=1, milliseconds=1)` | `86400.001`                   |                                                                                       |
+| `datetime.timedelta`             | `float`   | `timedelta(days=1, milliseconds=1)` | `86400.001`                   | Total seconds                                                                         |
 | `np.array`                       | `list`    | `np.array([1, 2, 3])`               | `[1, 2, 3]`                   |                                                                                       |
 | `set`                            | `list`    | `{"a", "b", "c"}`                   | `["a", "b", "c"]`             |                                                                                       |
 | `tuple`                          | `list`    | `(1, 2, 3)`                         | `[1, 2, 3]`                   |                                                                                       |

docs/examples/creating_traces.md

@@ -0,0 +1,173 @@
+The input of data into the system is only restricted to the types on the [Conversions Page](conversions.md), how the data is structured is left mostly up to the user.
+
+Data relating to individuals and activities is often temporal, and falls into some standard patterns outlined below.
+
+## Initialization
+
+Let's create a client, subject and activity to work with:
+
+```py title="Initialization"
+import watz
+
+client = watz.Client(secret="my api key")
+
+client.subject_create([
+    watz.models.NewSubject(email="[email protected]"),
+])
+
+activities = client.activity_create([
+    watz.models.NewActivity(subject_uid="[email protected]")
+])
+
+act_uid = activities[0].uid
+```
+
+## Static Data
+
+Some data is static, meaning it is not recorded over time.
+
+Examples include:
+
+- A subject's date of birth
+- A subject's height
+- Calories burnt during an activitiy
+- Information about sensors recording during an activity
+
+The data can be structured arbitrarily, some examples are shown below:
+
+```py title="Static Data"
+import datetime as dt
+
+client.trace_create([
+
+    # <-- Subject traces
+
+    watz.models.NewTrace(
+        parent_uid="[email protected]",
+        name="profile",
+        data={
+            "name": "foo bar",
+            "dob": dt.date(1990, 1, 1),
+            "height": {
+                "value": 180,
+                "unit": "cm",
+            },
+            "gender": "m",
+        },
+    ),
+
+    # <-- Activity traces
+
+    watz.models.NewTrace(
+        parent_uid=act_uid,
+        name="calories",
+        data=678,
+    ),
+    watz.models.NewTrace(
+        parent_uid=act_uid,
+        name="sensors",
+        data=[
+        {
+            "name": "accelerometer",
+            "id": "123",
+        }, 
+        {
+            "name": "gyroscope",
+            "id": "456",
+        }],
+    ),
+])
+```
+
+## Temporal Data
+A lot of data is temporal, meaning it is recorded over time, where each recording is associated with a timestamp.
+
+Examples include:
+
+- A subject's weight
+- A subject's resting heart rate
+- Heart rate or power output during an activity
+- GPS coordinates during an activity
+
+The data can be structured arbitrarily, some examples are shown below:
+
+```py title="Temporal Data"
+import datetime as dt
+
+client.trace_create([
+
+    # <-- Subject traces
+
+    watz.models.NewTrace(
+        parent_uid="[email protected]",
+        name="weight",
+        data={
+            "unit": "kg",
+            "values": [
+                (65.3, dt.datetime(2021, 1, 1)), 
+                (65.2, dt.datetime(2021, 1, 2)), 
+            ],
+        },
+    ),
+    watz.models.NewTrace(
+        parent_uid="[email protected]",
+        name="resting_heart_rate",
+        data={
+            "unit": "bpm",
+            "values": [65, 64],
+            "timestamps": [
+                dt.datetime(2021, 1, 1), 
+                dt.datetime(2021, 1, 2), 
+            ],
+        },
+    ),    
+
+    # <-- Activity traces
+
+    # If attributes share a temporal trace, they could be stored together:
+    watz.models.NewTrace(
+        parent_uid=act_uid,
+        name="hr/power",
+        data={
+            "unit": "bpm",
+            "hr": [102, 110],
+            "power": [200, 210],
+            "timestamps": [
+                dt.datetime(2021, 1, 1), 
+                dt.datetime(2021, 1, 2), 
+            ],
+        },
+    ),
+
+    # Alternatively, traces could reference a shared temporal trace:
+    watz.models.NewTrace(
+        parent_uid=act_uid,
+        name="coord_ts",
+        data=[
+            dt.datetime(2021, 1, 1), 
+            dt.datetime(2021, 1, 2), 
+        ]
+    ),
+    watz.models.NewTrace(
+        parent_uid=act_uid,
+        name="lat",
+        data={
+            "values": [1.234, 1.235],
+            "ts_trace_name": "coord_ts",
+        },
+    ),
+    watz.models.NewTrace(
+        parent_uid=act_uid,
+        name="long",
+        data={
+            "values": [1.234, 1.235],
+            "ts_trace_name": "coord_ts",
+        },
+    ),    
+])
+```
+!!! note
+    `datetime.datetime` is used here for simplicity, using pre-serialized timestamps would make no difference.
+
+!!! note
+    Support for updating & deleting existing traces coming soon.

docs/examples/index.md

@@ -0,0 +1 @@
+- [Creating Traces](creating_traces.md)