update docs for first public release

neurogeriatricskiel · Oct 19, 2023 · fdbe066 · fdbe066
1 parent 0489fbc
commit fdbe066
Show file tree

Hide file tree

Showing 8 changed files with 149 additions and 87 deletions.
diff --git a/README.md b/README.md
@@ -1,35 +1,16 @@
 # NGMT
 
-## NeuroGeriatricMotionToolbox
-
-Python based toolbox for processing motion data
-
-## Structure
-
-```markdown
-│ngmt                <- Main folder. It is initialized as a Git
-│                       repository with a reasonable .gitignore file.
-│
-├── examples         <- Various scripts, e.g. simulations, plotting, analysis,
-│                       The scripts use the `ngmt` folder for their base code.
-|
-├── info             <- Slides, Paper, basically any document related to the work in progress.
-│
-├── ngmt             <- Source code for use in this project. Contains functions,
-│                       structures and modules that are used throughout
-│                       the project and in multiple scripts.
-│
-├── test             <- Folder containing tests for `ngmt`.
-│
-├── README.md        <- Top-level README. 
-├── LICENSE
-├── requirements.txt <- The requirements file for reproducing the analysis environment, e.g.
-│                       generated with `pip freeze > requirements.txt`. Might be replaced by
-│                       a `environment.yml` file for Anaconda.
-├── setup.py         <- makes project pip installable (pip install -e .) so src can be imported
-|
-└── .gitignore       <- focused on Python VS Code
-```
+Welcome to the NeuroGeriatricMotionToolbox (NGMT). We are a Python based toolbox for processing motion data.
+
+> The toolbox is currently under development and is not yet ready for use.
+
+The toolbox is aimed at a wide variety of motion researchers who want to use open souce software to process their data.
+We have implemented a wide variety of functions to process motion data, such as:
+-   Gait sequence detection (GSD)
+-   Inital contact detection (ICD)
+-   More to follow ...
+
+The idea is that various motion data can be loaded into our dedicated dataclasses which rely on principles from the [Motion-BIDS](https://bids-specification.readthedocs.io/en/latest/modality-specific-files/motion.html) standard.
 
 ## Relation of data classes
 ```mermaid
@@ -99,10 +80,27 @@ The `RecordingData` object can also contain information about events. The `Event
 
 The `ChannelData` object is used to store the channel name, the channel type, the channel units and the tracked point.
 
-## Formatting
-The code uploaded here follows the latest black style guide. Please make sure to format your code accordingly before uploading it.
-To do this, install black with `pip install black` and run `black .` in the root directory of the project.
+## Documentation
+The full documentation can be found here.
+
+## Installation
+After the first release, the toolbox can be installed via pip
+
+For now, the toolbox can be installed via the following steps:
+1. Clone the repository
+2. Create a virtual environment
+3. Install the requirements
+4. Install the toolbox
+
+```bash
+git clone https://github.com/neurogeriatricskiel/NGMT.git
+cd NeuroGeriatricMotionToolbox
+python -m venv venv_ngmt
+source venv_ngmt/bin/activate
+pip install -r environment.yml
+pip install -e .
+```
 
 ## Authors
 
-[Masoud Abedinifar](https://github.com/masoudabedinifar), [Robbin Romijnders](https://github.com/rmndrs89) & [Julius Welzel](https://github.com/JuliusWelzel)
+[Masoud Abedinifar](https://github.com/masoudabedinifar), [Clint Hansen](mailto:[email protected]), [Robbin Romijnders](https://github.com/rmndrs89) & [Julius Welzel](https://github.com/JuliusWelzel)
diff --git a/docs/dataclasses.md b/docs/dataclasses.md
@@ -0,0 +1,74 @@
+In the following the NGMT dataclasses are described.
+The dataclasses are used to store motion data in a standardized way. We provide some small set of import functions, each of which returns a dataclass.
+User should easily be able to write their own import functions, to get the their data into the provided dataclasses (this step might take some thinking).
+After the data is in the dataclasses, running functions on the data from our toolbox should be really straight forward.
+
+## Relation of data classes
+```mermaid
+classDiagram
+    class RawData {
+        FilePath: str
+        FileName: str
+    }
+
+    class FileInfo {
+        SubjectID: str
+        TaskName: str
+        DatasetName: str
+        FilePath: str
+    }
+
+    class ChannelData {
+        name: List[str]
+        component: List[str]
+        ch_type: List[str]
+        tracked_point: List[str]
+        units: List[str]
+        get_channel_units()
+    }
+
+    class EventData {
+        name: List[str]
+        onset: List[float]
+        duration: List[float]
+        trial_type: Optional[List[str]] = None
+    }
+
+    class RecordingData {
+        name: str
+        data: np.ndarray
+        sampling_frequency: float
+        times: np.1darray
+        channels: ChannelData
+        start_time: float
+        types: List[str]
+        GSD()
+        ICD()
+    }
+
+    class MotionData {
+        data: List[RecordingData]
+        times: np.ndarray  # Can be a 1D array representing timestamps
+        info: List[FileInfo]
+        ch_names: List[str]  # Can be a list of channel names
+        synchronise_recordings(self, systems: List[RecordingData]):
+    }
+
+    RecordingData --> MotionData: raw data with same sampling rate
+    ChannelData --> RecordingData: info per channel
+    EventData --> RecordingData: info about potential events
+    FileInfo --> MotionData: indent on disk
+    FileInfo --> ChannelData: info per channel 
+    FileInfo --> RecordingData: raw time series data
+    FileInfo --> EventData: Include events if available in raw data
+    RawData --> FileInfo: Get info from file
+```
+
+This is the planned class structure for motion data. Data from any file format can ultimately be imported into the `MotionData` class. The `MotionData` object contains a `FileInfo` object. The `FileInfo` object contains information about the file, such as the subject ID, the task name, the project name and the file path. The `MotionData` class also contains a list of `RecordingData` objects. 
+
+Each `RecordingData` object contains the raw data, the sampling rate, the time stamps and the channel info (`ChannelData`) of a tracking system. It is up to the user how to group the source data into a tracking system.
+The `RecordingData` object can also contain information about events. The `EventData` objects stores information about events such as onset or duration.
+
+The `ChannelData` object is used to store the channel name, the channel type, the channel units and the tracked point.
+
+::: utils.ngmt_data_classes
diff --git a/docs/datasets.md b/docs/datasets.md
@@ -1,11 +1,13 @@
 This part of the project documentation focuses on
 the avaliable **datasets**.
 
+## KeepControl
 The keepcontrol dataset derived from the [keepcontrol project](https://www.keep-control.eu/) and is a Industrial Academic Initial Training Network working towards specific diagnosis and treatment of age-related gait and balance deficits.
 
 For this dataset a simple load function is provided to load the data into the NGMT dataclasses.
 ::: datasets.keepcontrol
 
+## Mobilise-D
 The mobilse-D dataset is publish form the [mobilise-D consortuium](https://www.imi.europa.eu/projects-results/project-factsheets/mobilise-d)and is a European project that aims to improve the assessment of Parkinson’s disease using wearable sensors.
 
 For this dataset a simple load function is provided to load the data into the NGMT dataclasses.

diff --git a/docs/index.md b/docs/index.md
@@ -2,32 +2,16 @@
 
 Welcome to the NeuroGeriatricMotionToolbox (NGMT). We are a Python based toolbox for processing motion data.
 
-## Structure
-
-```markdown
-│ngmt                <- Main folder. It is initialized as a Git
-│                       repository with a reasonable .gitignore file.
-│
-├── examples         <- Various scripts, e.g. simulations, plotting, analysis,
-│                       The scripts use the `ngmt` folder for their base code.
-|
-├── info             <- Slides, Paper, basically any document related to the work in progress.
-│
-├── ngmt             <- Source code for use in this project. Contains functions,
-│                       structures and modules that are used throughout
-│                       the project and in multiple scripts.
-│
-├── test             <- Folder containing tests for `ngmt`.
-│
-├── README.md        <- Top-level README. 
-├── LICENSE
-├── requirements.txt <- The requirements file for reproducing the analysis environment, e.g.
-│                       generated with `pip freeze > requirements.txt`. Might be replaced by
-│                       a `environment.yml` file for Anaconda.
-├── setup.py         <- makes project pip installable (pip install -e .) so src can be imported
-|
-└── .gitignore       <- focused on Python VS Code
-```
+> The toolbox is currently under development and is not yet ready for use.
+
+The toolbox is aimed at a wide variety of motion researchers who want to use open souce software to process their data.
+We have implemented a wide variety of functions to process motion data, such as:
+
+-   Gait sequence detection (GSD)
+-   Inital contact detection (ICD)
+-   More to follow ...
+
+The idea is that various motion data can be loaded into our dedicated dataclasses which rely on principles from the [Motion-BIDS](https://bids-specification.readthedocs.io/en/latest/modality-specific-files/motion.html) standard.
 
 ## Relation of data classes
 ```mermaid
@@ -97,10 +81,27 @@ The `RecordingData` object can also contain information about events. The `Event
 
 The `ChannelData` object is used to store the channel name, the channel type, the channel units and the tracked point.
 
-## Formatting
-The code uploaded here follows the latest black style guide. Please make sure to format your code accordingly before uploading it.
-To do this, install black with `pip install black` and run `black .` in the root directory of the project.
+## Documentation
+The full documentation can be found here.
+
+## Installation
+After the first release, the toolbox can be installed via pip
+
+For now, the toolbox can be installed via the following steps:
+1. Clone the repository
+2. Create a virtual environment
+3. Install the requirements
+4. Install the toolbox
+
+```bash
+git clone https://github.com/neurogeriatricskiel/NGMT.git
+cd NeuroGeriatricMotionToolbox
+python -m venv venv_ngmt
+source venv_ngmt/bin/activate
+pip install -r environment.yml
+pip install -e .
+```
 
 ## Authors
 
-[Masoud Abedinifar](https://github.com/masoudabedinifar), [Robbin Romijnders](https://github.com/rmndrs89) & [Julius Welzel](https://github.com/JuliusWelzel)
+[Masoud Abedinifar](https://github.com/masoudabedinifar), [Clint Hansen](mailto:[email protected]), [Robbin Romijnders](https://github.com/rmndrs89) & [Julius Welzel](https://github.com/JuliusWelzel)
diff --git a/docs/utils.md b/docs/utils.md
@@ -7,6 +7,3 @@ This part from the utilities documentation focuses on comon preprocessing steps.
 
 This part from the utilities documentation focuses on comon load functions for different hardwares.
 ::: utils.importers
-
-In the following the NGMT dataclasses are described.
-::: utils.ngmt_data_classes
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,6 +22,7 @@ theme:
 nav:
   - index.md
   - Datasets: datasets.md
+  - Dataclasses: dataclasses.md
   - Modules: modules.md
   - Utilities: utils.md
 

diff --git a/ngmt/utils/ngmt_data_classes.py b/ngmt/utils/ngmt_data_classes.py
@@ -114,30 +114,21 @@ class RecordingData:
     recording. For example, a recording of a participant walking on a treadmill.
 
     Attributes:
-
         name (str): A name for the recording data.
-
         data (np.ndarray): A nD numpy array of shape (n_samples, n_channels) containing
             the motion data. Channels MUST have the same sampling frequency.
-
         sampling_frequency (float): The sampling frequency of the motion data.
-
         times (np.ndarray): A 1D numpy array of shape (n_samples,) containing the
             timestamps of the motion data. If no time stamps are provided from the
             system, timestamps are relative to the start of the recording.
-
         channels (ChannelData): A ChannelData object containing information about the
             channels in the data.
-
         start_time (float): The start time of the recording in seconds. 0 if no time
             stamps are provided from the system.
-
         types (List[str]): A list of strings describing the type of data in each channel.
             For example, "acceleration", "angular velocity", "position", etc.
-
         ch_names (Optional[List[str]]): An optional list of channel names (default is None).
             If None, the channel names will be set to the channel numbers.
-
         events (Optional[EventData]): An optional EventData object containing information
             about events during the recording (default is None).
     """

diff --git a/ngmt/utils/preprocessing.py b/ngmt/utils/preprocessing.py
@@ -56,7 +56,7 @@ def apply_continuous_wavelet_transform(
         sampling_frequency (float): Sampling frequency of the data.
 
     Returns:
-        numpy.ndarray: Transformed data.
+        data (numpy.ndarray): Transformed data.
     """
     sampling_period = 1 / sampling_frequency
     coefficients, _ = pywt.cwt(data, np.arange(1, scales + 1), wavelet, sampling_period)
@@ -72,7 +72,7 @@ def apply_successive_gaussian_filters(data):
         data (numpy.ndarray): Input data.
 
     Returns:
-        numpy.ndarray: Filtered data.
+        data (numpy.ndarray): Filtered data.
     """
     sigma_params = [2, 2, 3, 2]
     kernel_size_params = [10, 10, 15, 10]
@@ -97,17 +97,15 @@ def fir_lowpass_filter(data, fir_file="ngmt/utils/FIR_2_3Hz_40.mat"):
     the filter to the input data using the `scipy.signal.filtfilt` function.
 
     Args:
-    ----------
-    data : array-like
-        The input data to be filtered.
-    fir_file : str, optional
-        The filename of the FIR filter coefficients MAT file.
-        Default is "FIR_2_3Hz_40.mat".
+        data (array-like):
+            The input data to be filtered.
+        fir_file (str, optional):
+            The filename of the FIR filter coefficients MAT file.
+            Default is "FIR_2_3Hz_40.mat".
 
     Returns:
-    -------
-    filtered_signal : array
-        The filtered signal after applying the FIR low-pass filter.
+        filtered_signal (array):
+            The filtered signal after applying the FIR low-pass filter.
 
     Notes:
     -----