From 0eb6aa2b822838ffe4b933d95da5fd4cc89e1902 Mon Sep 17 00:00:00 2001 From: Peter Kok Date: Mon, 8 Jan 2024 14:37:05 +0100 Subject: [PATCH] Remove dbpd-specific documentation It will be moved to the dbpd-toolbox --- docs/tsdf_dbpd_channels_and_units.md | 157 --------------------------- docs/tsdf_dbpd_schemas.md | 66 ----------- docs/tsdf_fields_table.md | 8 +- mkdocs.yml | 6 +- 4 files changed, 6 insertions(+), 231 deletions(-) delete mode 100644 docs/tsdf_dbpd_channels_and_units.md delete mode 100644 docs/tsdf_dbpd_schemas.md diff --git a/docs/tsdf_dbpd_channels_and_units.md b/docs/tsdf_dbpd_channels_and_units.md deleted file mode 100644 index 89ba7da..0000000 --- a/docs/tsdf_dbpd_channels_and_units.md +++ /dev/null @@ -1,157 +0,0 @@ -# Channels and units in Digital Biomarkers for Parkinson's Disease (`DBPD`) schemas - -Within the `DBPD` project, some of the field types are further specialised to provide a better description of the data. These are described in the following sections. - -## Field: `channels` -**Type:** `channel_type[]` -**Description:** Describes the content of the data written. `channel_type` is specific to the `Digital biomarkers for PD` extension. - ---- - -**General types** - -| `channel_type` name | Recommended `unit` | Description -|--------------------------|--------------------|------------------------------------------------------------------------------------| -| `time` | `absolute_ms` | Time corresponding to the start of each window/segment (also see units below). | -| `acceleration_x` | `m/s^2` | Acceleration along the x-axis. | -| `acceleration_y` | `m/s^2` | Acceleration along the y-axis. | -| `acceleration_z` | `m/s^2` | Acceleration along the z-axis. | -| `rotation_x` | `deg/s` | Angular rotation rate around the x-axis. | -| `rotation_y` | `deg/s` | Angular rotation rate around the y-axis. | -| `rotation_z` | `deg/s` | Angular rotation rate around the z-axis. | -| `green` | `deg/s` | Green signal values indicate blood volume changes for physiological analysis. | - - ---- - -
- -PPG-related types - -| `channel_type` name | Recommended `unit` | Description | -|----------------------------|-----------------------|---------------------------------------------------------------------------------------| -| `ppg_quality_post_prob` | `probability` | `[TODO]` Posterior probability that the corresponding PPG signal is of high quality (0 to 1). | - -
- ---- - -
- -Tremor-related types - -| `channel_type` name | Recommended `unit` | Description | -|--------------------------|--------------------|-------------------------------------------------------------------------------------| -| `gyro_tremor_prob` | `probability` | Probability values (0 to 1) indicating the likelihood of tremor activity for each sample. | -| `gyro_tremor_hat` | `boolean_num` | Estimated values representing the presence or absence of tremor activity for each sample. | -| `gyro_arm_actv_prob` | `probability` | Probability values (0 to 1) indicating the likelihood of arm activity for each sample. | -| `gyro_arm_actv_hat` | `boolean_num` | Estimated values representing the presence or absence of arm activity for each sample. | -| `GyMeanDx` | `unitless` | Mean gyro derivative in the x axis. | -| `GyMeanDy` | `unitless` | Mean gyro derivative in the y axis. | -| `GyMeanDz` | `unitless` | Mean gyro derivative in the z axis. | -| `GyLTreDomPowerX` | `unitless` | Gyro Low tremor (range [3.5-8 Hz]) dominant power in the x axis. | -| `GyLTreDomPowerY` | `unitless` | Gyro Low tremor (range [3.5-8 Hz]) dominant power in the y axis. | -| `GyLTreDomPowerZ` | `unitless` | Gyro Low tremor (range [3.5-8 Hz]) dominant power in the z axis. | -| `GyGaitBandPower` | `unitless` | Gyro gait bandpower (range [0.4 – 2] Hz) – PSD: sum of the axes. | -| `GyGaitBandpowerRatio` | `unitless` | Gyro gait bandpower sum / total bandpower sum up to 15 Hz – PSD: sum of the axes. | -| `GyGaitFreqPeak` | `unitless` | Frequency peak of the in the gyro gait range – PSD: sum of the axes. | -| `GyGaitFixedDomPower` | `unitless` | `[TODO]` Gyro dominant power in a fixed range (specific frequency range not provided). | -| `GyGaitFixedDomPowerRatio` | `unitless` | `[TODO]` Ratio of dominant power in the gyro gait range to total power. | -| `GyGaitDomPower` | `unitless` | `[TODO]` Dominant power in the gyro gait range. | -| `GyGaitDomPowerRatio` | `unitless` | `[TODO]` Ratio of dominant power in the gyro gait range to total power. | -| `GyGaitPeakFreqWidth` | `unitless` | `[TODO]` Width of the frequency peak in the gyro gait range. | -| `GyLTreBandPower` | `unitless` | `[TODO]` Low tremor bandpower (specific frequency range not provided). | -| `GyLTreBandpower` | `unitless` | `[TODO]` Low tremor bandpower (specific frequency range not provided). | -| `GyLTreFreqPeak` | `unitless` | `[TODO]` Frequency peak in the low tremor range. | -| `GyLTreFixedDomP` | `unitless` | `[TODO]` Low tremor dominant power in a fixed range (specific frequency range not provided). | -| `GyLTreFixedDomP` | `unitless` | `[TODO]` Low tremor dominant power in a fixed range (specific frequency range not provided). | -| `GyLTreDomPower` | `unitless` | `[TODO]` Low tremor dominant power (specific frequency range not provided). | -| `GyLTreDomPowerR` | `unitless` | `[TODO]` Ratio of low tremor dominant power to total power. | -| `GyLTrePeakFreqW` | `unitless` | `[TODO]` Width of the frequency peak in the low tremor range. | -| `GyHTreBandPower` | `unitless` | `[TODO]` High tremor bandpower (specific frequency range not provided). | -| `GyHTreBandpower` | `unitless` | `[TODO]` High tremor bandpower (specific frequency range not provided). | -| `GyHTreFreqPeak` | `unitless` | `[TODO]` Frequency peak in the high tremor range. | -| `GyHTreFixedDomP` | `unitless` | `[TODO]` High tremor dominant power in a fixed range (specific frequency range not provided). | -| `GyHTreFixedDomP` | `unitless` | `[TODO]` High tremor dominant power in a fixed range (specific frequency range not provided). | -| `GyHTreDomPower` | `unitless` | `[TODO]` High tremor dominant power (specific frequency range not provided). | -| `GyHTreDomPowerR` | `unitless` | `[TODO]` Ratio of high tremor dominant power to total power. | -| `GyHTrePeakFreqW` | `unitless` | `[TODO]` Width of the frequency peak in the high tremor range. | -| `GyMFCC1` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 1. | -| `GyMFCC2` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 2. | -| `GyMFCC3` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 3. | -| `GyMFCC4` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 4. | -| `GyMFCC5` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 5. | -| `GyMFCC6` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 6. | -| `GyMFCC7` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 7. | -| `GyMFCC8` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 8. | -| `GyMFCC9` | `unitless` | `[TODO]` Mel-frequency cepstral coefficient 9. | - - -
- ---- - -
- -Gait-related types - -| `channel_type` name | Recommended `unit` | Description | -|--------------------------|--------------------|-------------------------------------------------------------------------------------| -| `std_accel_norm` | `m/s^2` | Standard deviation of the norm of the accelerometer axes in the temporal domain. | -| `x_accel_grav_mean` | `m/s^2` | Mean of the x-axis acceleration gravity component. | -| `y_accel_grav_mean` | `m/s^2` | Mean of the y-axis acceleration gravity component. | -| `z_accel_grav_mean` | `m/s^2` | Mean of the z-axis acceleration gravity component. | -| `x_accel_grav_std` | `m/s^2` | Standard deviation of the x-axis acceleration gravity component. | -| `y_accel_grav_std` | `m/s^2` | Standard deviation of the y-axis acceleration gravity component. | -| `z_accel_grav_std` | `m/s^2` | Standard deviation of the z-axis acceleration gravity component.. | -| `x_accel_power_below_gait` | `(m/s^2)^2/Hz` | Total power in the [0, 0.7] Hz range of the x-axis accelerometer. | -| `y_accel_power_below_gait` | `(m/s^2)^2/Hz` | Total power in the [0, 0.7] Hz range of the y-axis accelerometer. | -| `z_accel_power_below_gait` | `(m/s^2)^2/Hz` | Total power in the [0, 0.7] Hz range of the z-axis accelerometer. | -| `x_accel_power_gait` | `(m/s^2)^2/Hz` | Total power in the [0.7, 3.5] Hz range of the x-axis accelerometer. | -| `y_accel_power_gait` | `(m/s^2)^2/Hz` | Total power in the [0.7, 3.5] Hz range of the y-axis accelerometer. | -| `z_accel_power_gait` | `(m/s^2)^2/Hz` | Total power in the [0.7, 3.5] Hz range of the z-axis accelerometer. | -| `x_accel_power_tremor` | `(m/s^2)^2/Hz` | Total power in the [3.5, 8] Hz range of the x-axis accelerometer. | -| `y_accel_power_tremor` | `(m/s^2)^2/Hz` | Total power in the [3.5, 8] Hz range of the y-axis accelerometer. | -| `z_accel_power_tremor` | `(m/s^2)^2/Hz` | Total power in the [3.5, 8] Hz range of the z-axis accelerometer. | -| `x_accel_power_above_tremor` | `(m/s^2)^2/Hz` | Total power in the [8, 50] Hz range of the x-axis accelerometer. | -| `y_accel_power_above_tremor` | `(m/s^2)^2/Hz` | Total power in the [8, 50] Hz range of the y-axis accelerometer. | -| `z_accel_power_above_tremor` | `(m/s^2)^2/Hz` | Total power in the [8, 50] Hz range of the z-axis accelerometer. | -| `x_accel_dominant_frequency` | `Hz` | Dominant frequency of the x-axis accelerometer. | -| `y_accel_dominant_frequency` | `Hz` | Dominant frequency of the x-axis accelerometer. | -| `z_accel_dominant_frequency` | `Hz` | Dominant frequency of the x-axis accelerometer. | -| `accel_norm_cc_{n}` | `?` | Cepstral coefficient n with n $\in$ [1,2,...,16] of the accelerometer. | -| `gd_pred_gait_proba` | `probability` | Predicted probability of gait being the predominant activity within the window span. | -| `gyro_norm_cc_{n}` | `?` | Cepstral coefficient n with n $\in$ [1,2,...,16] of the gyroscope. | -| `x_gyro_dominant_frequency` | `Hz` | Dominant frequency of the x-axis gyroscope | -| `y_gyro_dominant_frequency` | `Hz` | Dominant frequency of the x-axis gyroscope | -| `z_gyro_dominant_frequency` | `Hz` | Dominant frequency of the x-axis gyroscope | -| `angle_mean_amplitude` | `deg` | Mean of the sum of consecutive minima and maxima angles (angle amplitude is often referred to as range of motion) | -| `angle_std_amplitude` | `deg` | Std of the sum of consecutive minima and maxima angles | -| `angle_sum_amplitude` | `deg` | Sum of the sum of consecutive minima and maxima angles | -| `ange_perc_95_amplitude` | `deg` | 95th percentile of the sum of consecutive minima and maxima angles | -| `forward_peak_ang_vel_mean` | `deg/s` | Angular velocity mean in forward direction of the first principal component | -| `forward_peak_ang_vel_std` | `deg/s` | Angular velocity standard deviation in forward direction of the first principal component | -| `backward_peak_ang_vel_mean` | `deg/s` | Angular velocity mean in backward direction of the first principal component | -| `backward_peak_ang_vel_std` | `deg/s` | Angular velocity standard deviation in backward direction of the first principal component | -| `angle_perc_power` | `percentage` | Percentage of total power in the arm swing frequency band [0.3 - 3 Hz] | -
- ---- - -## Field: `units` - -**Type:** `unit_type[]` - -**Description:** Describes the format of the data written. `unit_type` is specific to the `Digital biomarkers for PD` extension. - -| `unit_type` | Description | -|-----------------|-----------------------------------------------------------------------------------------------------| -| `relative_ms` | Time (in milliseconds), relative to the `start_iso8601`, i.e., time elapsed since the start time of the recording. | -| `difference_ms` | Time (in milliseconds) elapsed since the previous sample. | -| `absolute_ms` | Absolute time in milliseconds, relative to Unix epoch. | -| `probability` | Probability values (0 to 1) indicating the likelihood of tremor activity for each sample. | -| `boolean_num` | `[TODO]` Integer values (0 or 1) representing the true (1) or false (0) presence of an activity. | -| `unitless` | Numerical values without units. | -| `m/s^2` | Acceleration in meters per second squared. | -| `deg/s` | Angular velocity in degrees per second. | - diff --git a/docs/tsdf_dbpd_schemas.md b/docs/tsdf_dbpd_schemas.md deleted file mode 100644 index f2f7209..0000000 --- a/docs/tsdf_dbpd_schemas.md +++ /dev/null @@ -1,66 +0,0 @@ - -# TSDF fields in Digital Biomarkers for Parkinson's Disease (`DBPD`) schemas - -## Mandatory fields - -This is a preliminary list of mandatory fields (to be shaped into schemas) that are used in the `DBPD` project. The list will be updated based on the upcoming discussions. - -| Field | Type | Description | -|----------------------------|--------------|-----------------------------------------------------------------------------------| -| `window_size_sec` | `float` | Size of the window (in seconds) used in the analysis. | -| `step_size_sec` | `float` | Duration in seconds for each segment in the written data. | -| `freq_sampling` | `int` | Sampling frequency (in Hz) of the input data. | -| `channels` | [channel_type](tsdf_field_types.md)`[]` | Description of the content of the data written. `channel_type` is specific to the `Digital biomarkers for PD` extension. | -| `units` | [unit_type](tsdf_field_types.md)`[]` | Description of the format of the data written. `unit_type` is specific to the `Digital biomarkers for PD` extension. | - - - -## **Tremor** pipeline specific fields - -Non-mandatory fields used in the tremor pipeline. - -| Field | Type | Description | -|----------------------------|--------------|------------------------------------------------------------------------------| -| `mfcc_num_filters` | `int` | Number of filters used for estimating the mel-frequency cepstral coefficients. | -| `mfcc_num_mel_coeff` | `int` | Number of coefficients used for estimating the mel-frequency cepstral coefficients. | -| `mfcc_max_freq_filter` | `float` | Maximum frequency (in Hz) used for filtering in mel-frequency cepstral coefficients. | -| `mfcc_window_size` | `float` | Size of the sub-window in seconds used to estimate the spectrogram used in the evaluation of the mel-frequency cepstral coefficients. | -| `excluded_hours` | `int[]` | `[TODO]` List of the excluded hours from the analysis (vector scaling?) | -| `sum_features_gyro_scale` | `float[]` | `[TODO]` Scaling factors for the sum of tremor-related features (from gyro) | -| `sum_squared_features_gyro_scale` | `float[]` | `[TODO]` Scaling factors for the sum of squared tremor-related features (from gyro) | -| `n_features_gyro_scale` | `int` | `[TODO]` Scaling factor for the number of gyro features | - -## **PPG** pipeline specific fields - -Non-mandatory fields used in the PPG pipeline. - -| Field | Type | Description | -|----------------------------|----------------------|------------------------------------------------------------------------------| -| `segment_number` | `int` | Order number of the analyzed data segment. | -| `freq_sampling_original` | `int` | Sampling frequency (in Hz) of the original data (before adjustments for the analysis). | - -## **Gait** pipeline specific fields - -Non-mandatory fields used in the gait pipeline. We currently do not have information about the fields used in the gait pipeline, but we will update this section as soon as we have more information. - -| Field | Type | Description | -|----------------------------|----------------------|------------------------------------------------------------------------------| -| `side_watch` | `string` | `[TODO]` Possible values: ['left', 'right']. | - -## Additional generic fields - -These fields are non-mandatory, and provide standardised vocabulary for describing the data. - - -| Field | Type | Description | -|------------------------------|--------------|------------------------------------------------------| -| `week_number` | `int` | Denotes the specific study week number used for tracking or comparing data. | -| `columns` | `int` | Number of columns in the data matrix. | -| `interpolated` | `bool` | Indicates whether interpolation was performed on the data. | -| `high_pass_filter_applied` | `bool` | Indicates whether a high-pass filter was applied to remove low-frequency noise. | -| `high_pass_filter_cutoff` | `float` | Cutoff frequency (in Hz) for the high-pass filter, in case it was applied. | -| `z_score_normalised` | `bool` | Indicates whether z-score normalization was applied to the data. | -| `start_datetime_unix_ms` | `string` | UNIX timestamp for the start of the recording (milliseconds). Equivalent to `start_iso8601` in UNIX format. | -| `end_datetime_unix_ms` | `string` | UNIX timestamp for the end of the recording (milliseconds). Equivalent to `end_iso8601` in UNIX format. | - - diff --git a/docs/tsdf_fields_table.md b/docs/tsdf_fields_table.md index 7958af9..322b5ad 100644 --- a/docs/tsdf_fields_table.md +++ b/docs/tsdf_fields_table.md @@ -1,6 +1,7 @@ -# TSDF schema - metadata fields +# TSDF metadata fields + +TSDF metadata is represented as a dictionary (or a JSON object). In this section, we will list the fields within the TSDF format, as described in the [format specification](https://arxiv.org/abs/2211.11294). In addition to the mandatory fields, any custom fields and structures can be added. -TSDF metadata is represented as a dictionary (or a JSON object). In this section, we will comprehensively list the mandatory and optional fields within the TSDF format. ## TSDF v0.1 mandatory fields @@ -23,8 +24,7 @@ TSDF metadata is represented as a dictionary (or a JSON object). In this section | `rows` | `int` | Number of rows in the data matrix. | - -# Legacy fields +## Legacy fields The following table lists the legacy fields from the time when the format was called TSDB, along with their updated counterparts: diff --git a/mkdocs.yml b/mkdocs.yml index 8b9784a..57aef15 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,11 +12,9 @@ theme: readthedocs nav: - Introduction: index.md - Installation: installation.md - + - The format: - - TSDF fields: tsdf_fields_table.md - - DBPD schemas: tsdf_dbpd_schemas.md - - DBPD channels and units: tsdf_dbpd_channels_and_units.md + - TSDF metadata fields: tsdf_fields_table.md - Usage: - Basic reading and writing: basic_reading_and_writing.ipynb