Merge pull request #20 from biomarkersParkinson/improve-docs

Improve docs generation and content
biomarkersParkinson · Sep 5, 2023 · 19271dc · 19271dc
2 parents b911cd2 + e32298f
commit 19271dc
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 16 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -5,7 +5,7 @@ name: Python package
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, improve-docs ]
   pull_request:
     branches: [ main ]
 
@@ -19,6 +19,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v2
       with:
@@ -30,6 +32,16 @@ jobs:
     - name: Test with pytest
       run: |
         poetry run pytest
+    - name: Build the docs
+      run: |
+        poetry run mkdocs build
+    - name: Prepare for deploying
+      run: |
+        git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
+    - name: Deploy the docs
+      run: |
+        poetry run mkdocs gh-deploy
+
     #     poetry run coverage xml
     # - name: Upload coverage
     #   if: matrix.python-version == 3.9

diff --git a/docs/index.md b/docs/index.md
@@ -5,6 +5,40 @@ A package to load [TSDF data](https://arxiv.org/abs/2211.11294) into Python.
 ## What is `TSDF data`?
 
 `tsdf` stands for _time series data format_.
-It is a unified, standardized format for storing all types of physiological sensor data.
+It is a unified, standardized format for storing all types of physiological sensor data. It was originally introduced in this [preprint](https://arxiv.org/abs/2211.11294).
 
-More information available in this [preprint](https://arxiv.org/abs/2211.11294).
+### `TSDF data` in a nutshell
+
+The key element of `TSDF data` is a metadata dictionary with the following:
+
+#### Mandatory fields
+
+| Field              | Description                                                                                                     | Type       |
+|:-------------------|:----------------------------------------------------------------------------------------------------------------|:-----------|
+| `subject_id`       | Unique identifier of the subject                                                                                | `string`   |
+| `study_id`         | Unique identifier of the project or experiment                                                                  | `string`   |
+| `device_id`        | Unique identifier of the measurement device                                                                     | `string`   |
+| `endianness`       | [Byte order](https://en.wikipedia.org/wiki/Endianness) for numerical values in binary data ("big" or "little")  | `string`   |
+| `metadata_version` | Format version (used for backwards compatibility)                                                               | `string`   |
+| `start_iso8601`    | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time stamp for the start of the recording, with ms precision | `string`   |
+| `end_iso8601`      | Same as `start_iso8601`, but for the end of the recording                                                       | `string`   |
+| `rows`             | Total amount of samples per channel                                                                             | `uint`     |
+| `filename`         | Name of the file containing the measured data                                                                   | `string`   |
+| `channels`         | Labels for each data channel (_e.g.:_ `["time", "X", "Y", "Z"]` for 3D accelerometry)                           | `string[]` |
+| `units`            | Unit for each channel (_e.g.:_ `["ms"]` for time)                                                               | `string[]` |
+| `data_type`        | Number format of the measured data (_e.g.:_ `"float"`)                                                          | `string`   |
+| `bits`             | Bit-length of the number format                                                                                 | `string`   |
+
+#### Optional fields
+
+| Field                    | Description                                    | Type      |
+|:-------------------------|:-----------------------------------------------|:----------|
+| `source_file_name`       | File containing the raw data                   | `string`  |
+| `start_datetime_unix_ms` | Same as `start_iso8601`, but using UNIX format | `string`  |
+| `end_datetime_unix_ms`   | Same as `end_iso8601`, but using UNIX format   | `string`  |
+| `scale_factors`          | Scale factors applied to each channel          | `float[]` |
+| `columns`                | Total amount of data channels per sample       | `uint`    |
+
+#### Legacy fields
+
+This is work in progress. Sorry for the inconvenience.
diff --git a/docs/processing_example.ipynb b/docs/processing_example.ipynb
@@ -24,7 +24,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 26,
+   "execution_count": 13,
    "metadata": {
     "tags": []
    },
@@ -48,7 +48,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [
     {
@@ -87,7 +87,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 15,
    "metadata": {},
    "outputs": [
     {
@@ -120,7 +120,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 16,
    "metadata": {},
    "outputs": [
     {
@@ -151,7 +151,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 30,
+   "execution_count": 17,
    "metadata": {},
    "outputs": [
     {
@@ -179,7 +179,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 31,
+   "execution_count": 18,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -204,7 +204,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 32,
+   "execution_count": 19,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -222,7 +222,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 33,
+   "execution_count": 20,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -258,7 +258,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 34,
+   "execution_count": 21,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -300,7 +300,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 35,
+   "execution_count": 22,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -310,7 +310,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 36,
+   "execution_count": 23,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -329,7 +329,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 37,
+   "execution_count": 24,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -366,7 +366,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.12"
+   "version": "3.9.16"
   },
   "orig_nbformat": 4,
   "vscode": {