Config

.gitignore

@@ -237,4 +237,8 @@ $RECYCLE.BIN/
 # Include the HTML build folder
 !docs/_build
 docs/_build/*
-!docs/_build/html
+!docs/_build/html
+
+.python-version
+
+.datasets.dev.json

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) (+ the Migration Guide),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2023-30-01
+
+### Added
+- It is now possible to create a global config file containing the local path to the datasets.
+  This allows you to use the datasets without having to specify the path to the dataset every time.
+  Further, it means that you don't have to modify source code (just a config file) to run the examples and tests during 
+  development.
+  See the README for more details.
+  (https://github.com/mad-lab-fau/gaitmap-datasets/pull/8)
+
 ## [0.7.0] - 2023-23-01
 
 ### Added

README.md

@@ -55,19 +55,87 @@ individual dataset classes.
 | PyShoe2019 | https://github.com/utiasSTARS/pyshoe/  | https://ieee-dataport.org/open-access/university-toronto-foot-mounted-inertial-navigation-dataset (or bash script in github repo) |
 
 
-## Testing
+## Working with datasets
+
+Each dataset is represented by a class.
+To load the dataset, the path to the dataset folder needs to be provided.
+There are multiple ways to do this:
+
+1. You can provide the path directly in the constructor of the dataset class.
+
+```python
+from gaitmap_datasets import EgaitSegmentationValidation2014
+
+dataset = EgaitSegmentationValidation2014("/path/to/dataset")
+```
+
+2. Alternatively, you can avoid hard-coding path in one location by creating a json config file:
+```python
+# Run the following once, to create the config file
+from gaitmap_datasets import create_config_template
+
+create_config_template("/path/to/config.json")
+```
+Then open the config file and add the path to the dataset folders you have downloaded.
+You can just leave the values as `null` if you don't need a dataset.
+
+```json
+// file: /path/to/config.json
+{
+    "datasets": {
+        "egait_parameter_validation_2013": null,
+        "egait_segmentation_validation_2014": "/path/to/egait_segmentation_validation_2014/dataset",
+        "pyshoe_2019": null,
+        "sensor_position_comparison_2019": null,
+        "stair_ambulation_healthy_2021": null
+    }
+}
+```
+
+Then you can set the global config for gaitmap-datsets to point to the config file:
+
+```python
+from gaitmap_datasets import EgaitSegmentationValidation2014, set_config
+
+set_config("/path/to/config.json")
+# Now you can load the dataset without providing the path
+
+dataset = EgaitSegmentationValidation2014()
+```
+
+
+## Dev setup
+
+First clone the repo and install the dependencies using `poetry` (note this project only supports poetry >=1.2).
+
+```
+git clone https://github.com/mad-lab-fau/gaitmap-datasets.git
+cd gaitmap-datasets
+poetry install
+```
+
+### Downloading and linking datasets
+
+The datasets are not included in the package, and you need to download them manually (see above).
+Store the datasets you need in whatever folder you like.
+
+Then run `poetry run poe create_dev_config`.
+This should create a `.datasets.dev.json` file in the root of the repo.
+Modify this file to point to the folders of the respective datasets.
+
+With that setup, all tests and examples should work without any modification to the code.
+
+### Testing
 
 The `/tests` directory contains a set of tests to check the functionality of the library.
 However, most tests rely on the existence of the respective datasets in certain folders outside the library.
 Therefore, the tests can only be run locally and not on the CI server.
 
-To run them locally, make sure datasets are downloaded into the correct folders and then run `poe test`.
+To run them locally, make sure you completed the dataset setup (see above) then run `poe test`.
 
-## Documentation (build instructions)
+### Documentation (build instructions)
 
-Like the tests, the documentation requires the datasets to be downloaded into the correct folders to execute the 
-examples.
-Therefore, we can not build the docs automatically on RTD.
+As the docs need the datasets to be available, we can not build them automatically on RTD.
 Instead, we host the docs via github pages.
 The HTML source can be found in the `gh-pages` branch of this repo.
 

docs/modules/index.rst

@@ -28,3 +28,22 @@ interface.
     PyShoe2019Vicon
     PyShoe2019Hallway
     PyShoe2019Stairs
+
+Config API
+----------
+
+.. autosummary::
+   :toctree: generated
+   :template: function.rst
+
+    config
+    set_config
+    reset_config
+    create_config_template
+    get_dataset_path
+
+.. autosummary::
+   :toctree: generated
+   :template: class_no_inherited.rst
+
+    DatasetsConfig

examples/egait_parameter_validation_2013.py

@@ -29,21 +29,19 @@
 """
 
 # %%
-# .. warning:: For this example to work, you need to modify the dataset path in the following line to point to the
-#             location of the data on your machine.
+# .. warning:: For this example to work, you need to have a global config set containing the path to the dataset.
+#              Check the `README.md` for more information.
 from pathlib import Path
 
 import pandas as pd
 
 from gaitmap_datasets import EgaitParameterValidation2013
 
-dataset_path = Path("/home/arne/Documents/repos/work/datasets/eGaIT_database/")
-
 # %%
 # First we will create a simple instance of the dataset class.
 # We can see that it contains a single recording per participant for 101 participants.
 
-dataset = EgaitParameterValidation2013(data_folder=dataset_path)
+dataset = EgaitParameterValidation2013()
 dataset
 
 # %%

examples/egait_segmentation_validation_2014.py

@@ -19,28 +19,26 @@
     :alt: coordinate system definition
     :figclass: align-center
 
-.. warn:: The calibration files distributed with the dataset are likely of low quality.
-          We recommend to only use this dataset for validation of stride segmentation algorithms.
-          Algorithms for spatial parameters that depend on the exact values of the IMU, might not provide good results
-          with this dataset.
+.. warning:: The calibration files distributed with the dataset are likely of low quality.
+             We recommend to only use this dataset for validation of stride segmentation algorithms.
+             Algorithms for spatial parameters that depend on the exact values of the IMU, might not provide good
+             results with this dataset.
 
 """
 
 # %%
-# .. warning:: For this example to work, you need to modify the dataset path in the following line to point to the
-#             location of the data on your machine.
+# .. warning:: For this example to work, you need to have a global config set containing the path to the dataset.
+#              Check the `README.md` for more information.
 from pathlib import Path
 
 import pandas as pd
 
 from gaitmap_datasets import EgaitSegmentationValidation2014
 
-dataset_path = Path("/home/arne/Documents/repos/work/datasets/eGaIT_database_segmentation/")
-
 # %%
 # First we will create a simple instance of the dataset class.
 
-dataset = EgaitSegmentationValidation2014(data_folder=dataset_path)
+dataset = EgaitSegmentationValidation2014()
 dataset
 
 # %%

examples/pyshoe_2019.py

@@ -32,19 +32,15 @@
 
 """
 # %%
-# .. warning:: For this example to work, you need to modify the dataset path in the following line to point to the
-#             location of the data on your machine.
-from pathlib import Path
-
-dataset_path = Path("/home/arne/Documents/repos/work/datasets/2019-pyshoe/")
-
-# %%
+# .. warning:: For this example to work, you need to have a global config set containing the path to the dataset.
+#              Check the `README.md` for more information.
+#
 # Vicon Dataset
 # -------------
 # First we will create a simple instance of the dataset class.
 from gaitmap_datasets.pyshoe_2019 import PyShoe2019Vicon
 
-dataset = PyShoe2019Vicon(data_folder=dataset_path)
+dataset = PyShoe2019Vicon()
 dataset
 
 # %%
@@ -93,7 +89,7 @@
 # combined).
 from gaitmap_datasets.pyshoe_2019 import PyShoe2019Hallway
 
-dataset = PyShoe2019Hallway(data_folder=dataset_path)
+dataset = PyShoe2019Hallway()
 dataset
 
 # %%
@@ -148,7 +144,7 @@
 # First we will create a simple instance of the dataset class.
 from gaitmap_datasets.pyshoe_2019 import PyShoe2019Stairs
 
-dataset = PyShoe2019Stairs(data_folder=dataset_path)
+dataset = PyShoe2019Stairs()
 dataset
 
 # %%

examples/sensor_position_comparison_2019.py

@@ -34,16 +34,9 @@
 
 """
 # %%
-# .. warning:: For this example to work, you need to modify the dataset path in the following line to point to the
-#              location of the data on your machine.
-from pathlib import Path
-
-dataset_path = Path(
-    "/home/arne/Documents/repos/work/projects/sensor_position_comparison/sensor_position_main_analysis/data/raw"
-)
-
-
-# %%
+# .. warning:: For this example to work, you need to have a global config set containing the path to the dataset.
+#              Check the `README.md` for more information.
+#
 # SensorPositionComparison2019Segmentation
 # ========================================
 # This version of the dataset contains one recording per participant with all tests and movement between the tests.
@@ -58,7 +51,6 @@
 from gaitmap_datasets.sensor_position_comparison_2019 import SensorPositionComparison2019Segmentation
 
 dataset = SensorPositionComparison2019Segmentation(
-    data_folder=dataset_path,
     memory=Memory("../.cache"),
 )
 dataset
@@ -133,7 +125,6 @@
 from gaitmap_datasets.sensor_position_comparison_2019 import SensorPositionComparison2019Mocap
 
 dataset = SensorPositionComparison2019Mocap(
-    data_folder=dataset_path,
     memory=Memory("../.cache"),
 )
 dataset
@@ -260,7 +251,6 @@
 # This ensures that the time axis of the IMU data and the mocap data are still aligned, even tough no mocap data
 # exists in the padded region.
 dataset = SensorPositionComparison2019Mocap(
-    data_folder=dataset_path,
     memory=Memory("../.cache"),
     data_padding_s=3,
 )

examples/stair_ambulation_healthy_2021.py

@@ -26,13 +26,9 @@
 In the following we will show the usage of both classes and the data that is contained within.
 """
 # %%
-# .. warning:: For this example to work, you need to modify the dataset path in the following line to point to the
-#              location of the data on your machine.
-from pathlib import Path
-
-dataset_path = Path("/home/arne/Documents/repos/work/datasets/stair_ambulation_dataset/")
-
-# %%
+# .. warning:: For this example to work, you need to have a global config set containing the path to the dataset.
+#              Check the `README.md` for more information.
+#
 # StairAmbulationHealthy2021PerTest
 # =================================
 # First we can simple create an instance of the dataset class and directly see the contained data points.
@@ -43,7 +39,6 @@
 from gaitmap_datasets import StairAmbulationHealthy2021PerTest
 
 dataset = StairAmbulationHealthy2021PerTest(
-    data_folder=dataset_path,
     include_pressure_data=True,
     include_baro_data=True,
     include_hip_sensor=True,
@@ -186,7 +181,6 @@
 from gaitmap_datasets import StairAmbulationHealthy2021Full
 
 dataset = StairAmbulationHealthy2021Full(
-    data_folder=dataset_path,
     include_pressure_data=True,
     include_baro_data=True,
     include_hip_sensor=True,

gaitmap_datasets/__init__.py

@@ -1,5 +1,13 @@
 # -*- coding: utf-8 -*-
 """Methods to access the open source gait datasets of the MaD-Lab."""
+from gaitmap_datasets._config import (
+    DatasetsConfig,
+    config,
+    create_config_template,
+    get_dataset_path,
+    reset_config,
+    set_config,
+)
 from gaitmap_datasets.egait_parameter_validation_2013 import EgaitParameterValidation2013
 from gaitmap_datasets.egait_segmentation_validation_2014 import EgaitSegmentationValidation2014
 from gaitmap_datasets.pyshoe_2019 import PyShoe2019Hallway, PyShoe2019Stairs, PyShoe2019Vicon
@@ -22,5 +30,11 @@
     "PyShoe2019Vicon",
     "PyShoe2019Hallway",
     "PyShoe2019Stairs",
+    "DatasetsConfig",
+    "set_config",
+    "reset_config",
+    "config",
+    "create_config_template",
+    "get_dataset_path",
 ]
 __version__ = "0.7.0"