Merge pull request #97 from neurogeriatricskiel/rename_toolbox

Rename toolbox
neurogeriatricskiel · Jul 19, 2024 · 7c24e70 · 7c24e70
2 parents 12ca069 + 6d95021
commit 7c24e70
Show file tree

Hide file tree

Showing 79 changed files with 1,721 additions and 2,687 deletions.
diff --git a/.github/workflows/test-and-lint.yml b/.github/workflows/test-and-lint.yml
@@ -32,7 +32,7 @@ jobs:
           poetry install 
       - name: Testing with coverage
         run: |
-          poetry run pytest ngmt/test/ --cov=ngmt --cov-report=xml
+          poetry run pytest kielmat/test/ --cov=kielmat --cov-report=xml
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v2
         env:

diff --git a/.gitignore b/.gitignore
@@ -1,13 +1,14 @@
 # See: https://git-scm.com/docs/gitignore
 __pycache__/
 projects/
-/ngmt.egg-info
-ngmt/datasets/_*
+/kielmat.egg-info
+# from before the package was renamed
+/ngmt.egg-info 
 
 my_messy_code/mytestconde.py
 
 /my_messy_code/*
-ngmt/examples_gait_sqeuence.py
+kielmat/examples_gait_sqeuence.py
 
 examples/data
 
@@ -21,3 +22,7 @@ examples/data
 # local changelog generator
 create_changelog.py
 changelog.yml
+
+# example data
+kiemat/datasets/_*
+ngmt/datasets/_*
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,35 +6,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.0.4] 
 
-Forth release of NGMT for for JOSS publication.
+Forth release of KielMAT for for JOSS publication.
 
 ### Fixed
-- Gait sequence detection with datetime [[#61]](https://github.com/neurogeriatricskiel/NGMT/pull/61)
+- Gait sequence detection with datetime [[#61]](https://github.com/neurogeriatricskiel/KielMAT/pull/61)
 
 ### Changed
-- Reworked documentation [[#60]](https://github.com/neurogeriatricskiel/NGMT/pull/60)
+- Reworked documentation [[#60]](https://github.com/neurogeriatricskiel/KielMAT/pull/60)
 
 ## [0.0.3] - 2024-02-27
 
-Third unofficial release of NGMT for testing purposes.
+Third unofficial release of KielMAT for testing purposes.
 
 ### Added
-- Pyarrow as dependency [[ADD]](https://github.com/neurogeriatricskiel/NGMT/commit/22e401a5519cc9adde37b5c752a361a07d8166ac)
-- Testing coverage [[ADD]](https://github.com/neurogeriatricskiel/NGMT/commit/f6a919100e7a9d7319a4af77592a78bd6949bb69)
+- Pyarrow as dependency [[ADD]](https://github.com/neurogeriatricskiel/KielMAT/commit/22e401a5519cc9adde37b5c752a361a07d8166ac)
+- Testing coverage [[ADD]](https://github.com/neurogeriatricskiel/KielMAT/commit/f6a919100e7a9d7319a4af77592a78bd6949bb69)
 
 ### Fixed
-- Existing algorithms adapted to new dataclass structure [[FIX]](https://github.com/neurogeriatricskiel/NGMT/commit/3adf7756d9998b36454dccc86d9e2283200d72ed)
+- Existing algorithms adapted to new dataclass structure [[FIX]](https://github.com/neurogeriatricskiel/KielMAT/commit/3adf7756d9998b36454dccc86d9e2283200d72ed)
 
 ## [0.0.2] - 2024-01-22
 
-Second unofficial release of NGMT for testing purposes.
+Second unofficial release of KielMAT for testing purposes.
 
 ### Added
-- Physical acitivity monitoring algorithm [[#29]](https://github.com/neurogeriatricskiel/NGMT/commit/a8d9067cde00f0c9a0dba8b7fc623ba4eeb32d0a)
+- Physical acitivity monitoring algorithm [[#29]](https://github.com/neurogeriatricskiel/KielMAT/commit/a8d9067cde00f0c9a0dba8b7fc623ba4eeb32d0a)
 
 ## [0.0.1] - 2023-11-21
 
-This is the first unofficial release of NGMT.
+This is the first unofficial release of KielMAT.
 Therefore, we do not have a proper changelog for this release.
 
 ### Added

diff --git a/README.md b/README.md
@@ -1,44 +1,46 @@
-[![codecov](https://codecov.io/gh/neurogeriatricskiel/NGMT/graph/badge.svg?token=L578RHZ699)](https://codecov.io/gh/neurogeriatricskiel/NGMT)
-[![build docs](https://github.com/neurogeriatricskiel/NGMT/actions/workflows/mkdocs.yml/badge.svg)](https://github.com/neurogeriatricskiel/NGMT/actions/workflows/mkdocs.yml)
+[![codecov](https://codecov.io/gh/neurogeriatricskiel/KielMAT/graph/badge.svg?token=L578RHZ699)](https://codecov.io/gh/neurogeriatricskiel/KielMAT)
+[![build docs](https://github.com/neurogeriatricskiel/KielMAT/actions/workflows/mkdocs.yml/badge.svg)](https://github.com/neurogeriatricskiel/KielMAT/actions/workflows/mkdocs.yml)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-![GitHub issues](https://img.shields.io/github/issues-raw/neurogeriatricskiel/NGMT)
-![GitHub contributors](https://img.shields.io/github/contributors/neurogeriatricskiel/NGMT)
-[![lint-and-test](https://github.com/neurogeriatricskiel/NGMT/actions/workflows/test-and-lint.yml/badge.svg)](https://github.com/neurogeriatricskiel/NGMT/actions/workflows/test-and-lint.yml)
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ngmt)
+![GitHub issues](https://img.shields.io/github/issues-raw/neurogeriatricskiel/KielMAT)
+![GitHub contributors](https://img.shields.io/github/contributors/neurogeriatricskiel/KielMAT)
+[![lint-and-test](https://github.com/neurogeriatricskiel/KielMAT/actions/workflows/test-and-lint.yml/badge.svg)](https://github.com/neurogeriatricskiel/KielMAT/actions/workflows/test-and-lint.yml)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kielmat)
 
 
-![NGMTLogo](ngmt_logo_transBG.png)
+![KielMATLogo](kielmat_logo_transBG.png)
 
-Welcome to the NeuroGeriatricsMotionToolbox (NGMT). We are a Python based toolbox for processing motion data.
+Welcome to the KielMotionAnalysisToolbox (KielMAT). We are a Python based toolbox for processing motion data.
 
-The toolbox is aimed at motion researchers who want to use python based open source software to process their data.
-We have implemented validated algorithms in modules to process motion data, such as:
-   - Gait sequence detection (GSD)
-   - Inital contact detection (ICD)
-   - Physical activity monitoring (PAM)
-   - Postural transition detection (SSD)
-   - More to follow ...
+The toolbox is aimed at motion researchers who want to use Python-based open-source software to process their data. We have implemented validated algorithms in modules to process motion data, as shown in the table below:
+
+| Module                         | Description                                    | Data                               |
+|--------------------------------|------------------------------------------------|----------------------------------------|
+| Gait sequence detection (GSD)  | Detects gaits                      | 3D accelerations from the lower back   |
+| Initial contact detection (ICD)| Detects initial contact during gait     | 3D accelerations from the lower back   |
+| Postural transition detection (SSD) | Detects sit-to-stand and stand-to-sit movements        | 3D accelerations and gyroscope from the lower back   |
+| Physical activity monitoring (PAM) | Monitors physical activity levels          | 3D accelerations from the wrist        |
+| More to follow...              | Additional modules to be added                |                                        |
 
 The idea is that various motion data can be loaded into our dedicated dataclass which rely on principles from the [Motion-BIDS](https://bids-specification.readthedocs.io/en/latest/modality-specific-files/motion.html) standard.
 
 ## Data classes
 ### Data classes: conceptual framework
 
-Motion data is recorded with many different systems and modalities, each with their own proprietary data format. NGMT deals with this by organizing both data and metadata in a [BIDS-like format](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html). The BIDS format suggests that [motion recording data](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#motion-recording-data) from a single tracking system is organized in a single `*_tracksys-<label>_motion.tsv` file. 
+Motion data is recorded with many different systems and modalities, each with their own proprietary data format. KielMAT deals with this by organizing both data and metadata in a [BIDS-like format](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html). The BIDS format suggests that [motion recording data](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#motion-recording-data) from a single tracking system is organized in a single `*_tracksys-<label>_motion.tsv` file. 
 
 !!! note
 
     A tracking system is defined as a group of motion channels that share hardware properties (the recording device) and software properties (the recording duration and number of samples).
 
-In NGMT, data from a single tracking system is therefore loaded into a single `pandas.DataFrame`. The column headers of this `pandas.DataFrame` refer to the channels, and the corresponding [channels information](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#channels-description-_channelstsv) is likewise available as a `pandas.DataFrame`.
+In KielMAT, data from a single tracking system is therefore loaded into a single `pandas.DataFrame`. The column headers of this `pandas.DataFrame` refer to the channels, and the corresponding [channels information](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#channels-description-_channelstsv) is likewise available as a `pandas.DataFrame`.
 
 Similarly, if any [events](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/task-events.html) are available for the given recording, these are loaded into a single `pandas.DataFrame` for each tracking system as well. The events derived from the toolbox can be exported to a BIDS like '*_events.tsv' file.
 
 ### Data classes: in practice
-These concepts are translated into a NGMT dataclass for each recording: `NGMTRecording`:
+These concepts are translated into a KielMAT dataclass for each recording: `KielMATRecording`:
 ```mermaid
 classDiagram
-   class NGMTRecording {
+   class KielMATRecording {
       data: dict[str, pd.DataFrame]
       channels: dict[str, pd.DataFrame]
       info: None | dict[str, Any] = None
@@ -50,9 +52,9 @@ classDiagram
    }
 
 ```
- A recording consists of the motion data from one or more tracking systems, where each tracking system may consist motion data from one or more tracked points. Therefore, the motion data (`NGMTRecording.data`) are organized as a dictionary where the dictionary keys refer to the tracking systems, and the corresponding values the actual (raw) data as a `pandas.DataFrame`. The description of data channels (`NGMTRecording.channels`) is availabe as a dictionary with the same keys, and the values contain the channels description.
+ A recording consists of the motion data from one or more tracking systems, where each tracking system may consist motion data from one or more tracked points. Therefore, the motion data (`KielMATRecording.data`) are organized as a dictionary where the dictionary keys refer to the tracking systems, and the corresponding values the actual (raw) data as a `pandas.DataFrame`. The description of data channels (`KielMATRecording.channels`) is availabe as a dictionary with the same keys, and the values contain the channels description.
 ```python
->>> from ngmt.datasets import mobilised
+>>> from kielmat.datasets import mobilised
 >>> file_name = "/mnt/neurogeriatrics_data/Mobilise-D/rawdata/sub-3011/Free-living/data.mat"
 >>> recording = mobilised.load_recording(file_name, tracking_systems=["SU", "SU_INDIP"], tracked_points=["LowerBack"])
 >>> recording.data
@@ -106,16 +108,19 @@ classDiagram
 
 !!! note
 
-    In the examples you find a [tutorial (the basics of NGMT)](https://neurogeriatricskiel.github.io/NGMT/examples/00_tutorial_basics/) that explains the basics of the dataclass and how to work with them.
-
+    In the examples you find a [tutorial (the basics of KielMAT)](https://neurogeriatricskiel.github.io/KielMAT/examples/00_tutorial_basics/) that explains the basics of the dataclass and how to work with them.
 
 ## Installation
-The toolbox has been released on [pypi](https://pypi.org/project/ngmt/) and can be installed via pip:
+The toolbox has been released on [pypi](https://pypi.org/project/kielmat/) and can be installed via pip:
 ```bash
-pip install ngmt
+pip install kielmat
 ```
 It requires Python 3.10 or higher.
 
+## Contributing
+We welcome contributions to KielMAT! Please refer to our [contributing guide](https://neurogeriatricskiel.github.io/KielMAT/contributing) for more details.
+
+
 ## Authors
 
 [Masoud Abedinifar](https://github.com/masoudabedinifar), [Julius Welzel](https://github.com/JuliusWelzel), [Walter Maetzler](mailto:[email protected]), [Clint Hansen](mailto:[email protected]) & [Robbin Romijnders](https://github.com/rmndrs89)

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,18 +1,18 @@
 ## Contributing guide
-Thanks for considering contributing to our toolbox! NGMT is an open-source project and we welcome contributions from anyone to further enhance this project
+Thanks for considering contributing to our toolbox! KielMAT is an open-source project and we welcome contributions from anyone to further enhance this project
 
 There are lots of ways to contribute, such as:  
 - Use the software, and when you find bugs, tell us about them! We can only fix the bugs we know about.  
 - Tell us about parts of the documentation that you find confusing or unclear.  
-- Tell us about things you wish NGMT could do, or things it can do but you wish they were easier.  
+- Tell us about things you wish KielMAT could do, or things it can do but you wish they were easier.  
 - Fix bugs.  
 - Implement new features.  
 - Improve existing tutorials or write new ones.
 
-To report bugs, request new features, or ask about confusing documentation, it’s usually best to open a [new issue](https://github.com/neurogeriatricskiel/NGMT/issues/new/choose) on GitHub. For better reproducibility, be sure to include information about your operating system and NGMT version, and (if applicable) include a reproducible code sample that is as short as possible and ideally uses one of [our example datasets](https://neurogeriatricskiel.github.io/NGMT/datasets/).
+To report bugs, request new features, or ask about confusing documentation, it’s usually best to open a [new issue](https://github.com/neurogeriatricskiel/KielMAT/issues/new/choose) on GitHub. For better reproducibility, be sure to include information about your operating system and KielMAT version, and (if applicable) include a reproducible code sample that is as short as possible and ideally uses one of [our example datasets](https://neurogeriatricskiel.github.io/KielMAT/datasets/).
 
 ### Overview
-In general you'll be working with three different copies of the the NGMT codebase: the official remote copy at [https://github.com/neurogeriatricskiel/NGMT](https://github.com/neurogeriatricskiel/NGMT) (usually called ``upstream``), your remote `fork` of the upstream repository (similar URL, but with your username in place of ``NGMT``, and usually called ``origin``), and the local copy of the codebase on your computer. The typical contribution process is to:
+In general you'll be working with three different copies of the the KielMAT codebase: the official remote copy at [https://github.com/neurogeriatricskiel/KielMAT](https://github.com/neurogeriatricskiel/KielMAT) (usually called ``upstream``), your remote `fork` of the upstream repository (similar URL, but with your username in place of ``KielMAT``, and usually called ``origin``), and the local copy of the codebase on your computer. The typical contribution process is to:
 
 1. synchronize your local copy with ``upstream``
 2. make changes to your local copy

diff --git a/docs/dataclass.md b/docs/dataclass.md
@@ -1,12 +1,12 @@
-In the following the NGMT dataclass is described.
+In the following the KielMAT dataclass is described.
 The dataclass is used to store motion data in a standardized way. We provide some small set of import functions, each of which returns a `pandas.DataFrame` or a dict.
 User should easily be able to write their own import functions, to get the their data into the provided dataclass (this step might take some thinking).
 After the data is in the dataclass, running functions on the data from our toolbox should be really straight forward.
 
-## NGMT data class
+## KielMAT data class
 ```mermaid
 classDiagram
-   class NGMTRecording {
+   class KielMATRecording {
       data: dict[str, pd.DataFrame]
       channels: dict[str, pd.DataFrame]
       info: None | dict[str, Any] = None
@@ -19,6 +19,6 @@ classDiagram
 
 ```
 
- A recording consists of the motion data from one or more tracking systems, where each tracking system may consist motion data from one or more tracked points. Therefore, the motion data (`NGMTRecording.data`) are organized as a dictionary where the dictionary keys refer to the tracking systems, and the corresponding values the actual (raw) data as a `pandas.DataFrame`. The description of data channels (`NGMTRecording.channels`) is availabe as a dictionary with the same keys, and the values contain the channels description.
+ A recording consists of the motion data from one or more tracking systems, where each tracking system may consist motion data from one or more tracked points. Therefore, the motion data (`KielMATRecording.data`) are organized as a dictionary where the dictionary keys refer to the tracking systems, and the corresponding values the actual (raw) data as a `pandas.DataFrame`. The description of data channels (`KielMATRecording.channels`) is availabe as a dictionary with the same keys, and the values contain the channels description.
 
-::: utils.ngmt_dataclass
+::: utils.kielmat_dataclass
diff --git a/docs/datasets/keepcontrol.md b/docs/datasets/keepcontrol.md
@@ -2,6 +2,6 @@
 
 The Keep Control dataset derived from the [Keep Control](https://www.keep-control.eu/) project and is a Industrial Academic Initial Training Network working towards specific diagnosis and treatment of age-related gait and balance deficits. Part of the dataset was made publicly available on [figshare](https://figshare.com/articles/dataset/Full-body_mobility_data_to_validate_inertial_measurement_unit_algorithms_in_healthy_and_neurological_cohorts/20238006), and it was published as Warmerdam *et al*., Data, 2022, Full-Body Mobility Data to Validate Inertial Measurement Unit Algorithms in Healthy and Neurological Cohorts, doi: [10.3390/data7100136](https://doi.org/10.3390/data7100136).
 
-For this dataset a simple load function is provided to load the data into the NGMT dataclasses.
+For this dataset a simple load function is provided to load the data into the KielMAT dataclasses.
 
 ::: datasets.keepcontrol