Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename toolbox #97

Merged
merged 23 commits into from
Jul 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
adc9258
Declaration of Helsinki
masoudabedinifar Jul 17, 2024
8f60c7b
data used for each module
masoudabedinifar Jul 17, 2024
75636bf
Contributing
masoudabedinifar Jul 17, 2024
a62e731
summary revision
masoudabedinifar Jul 17, 2024
66176ff
Statement of need revision
masoudabedinifar Jul 17, 2024
d8f471f
State of the Field revision & remove unsued files
masoudabedinifar Jul 17, 2024
32d62a3
name changed to KMAT
masoudabedinifar Jul 17, 2024
2a11cda
name changed to Kiel Motion Analysis Toolbox (KMAT)
masoudabedinifar Jul 17, 2024
b151fe5
name changed to KMAT
masoudabedinifar Jul 17, 2024
90604e8
name changed to kamt
masoudabedinifar Jul 17, 2024
ca7785d
name chanegd to kmat
masoudabedinifar Jul 17, 2024
e66f4cc
Revert "name chanegd to kmat"
masoudabedinifar Jul 17, 2024
6cb2567
Revert "name changed to kamt"
masoudabedinifar Jul 17, 2024
e4a406c
Revert "name changed to KMAT"
masoudabedinifar Jul 17, 2024
b6ab3ae
Revert "name changed to Kiel Motion Analysis Toolbox (KMAT)"
masoudabedinifar Jul 17, 2024
97a79fd
Revert "name changed to KMAT"
masoudabedinifar Jul 17, 2024
0fd4bc5
renaming to Kiel Motion Analysis Toolbox
masoudabedinifar Jul 17, 2024
a01523a
renamed to kielmat
masoudabedinifar Jul 17, 2024
4e793bb
renamed to KielMotionAnalysisToolbox
masoudabedinifar Jul 17, 2024
a319895
update gitignore for example datasets
JuliusWelzel Jul 18, 2024
4b6d054
[ADD] new logo
JuliusWelzel Jul 19, 2024
092e19d
[ADD] new logo to docs
JuliusWelzel Jul 19, 2024
6d95021
Merge branch 'development-main' of https://github.com/neurogeriatrics…
JuliusWelzel Jul 19, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/test-and-lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
11 changes: 8 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -21,3 +22,7 @@ examples/data
# local changelog generator
create_changelog.py
changelog.yml

# example data
kiemat/datasets/_*
ngmt/datasets/_*
20 changes: 10 additions & 10 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 30 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down
8 changes: 4 additions & 4 deletions docs/contributing.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
10 changes: 5 additions & 5 deletions docs/dataclass.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
2 changes: 1 addition & 1 deletion docs/datasets/keepcontrol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading