labda 0.0.2__tar.gz

labda-0.0.2/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Parser: Qstarz
+- Basic subject and collection manipulaton.
+- Expanding data with timedelta, speed, acceleration, distance, direction.
+- Getting sampling frequency, CRS and timezone automatically from dataset.
+- Initial documentation with mkdocs and material theme.

labda-0.0.2/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.1
+Name: labda
+Version: 0.0.2
+Summary: Library for Advanced Behavioural Data Analysis
+Home-page: https://labda.josefheidler.cz
+License: 	CC-BY-SA-4.0
+Keywords: analysis,health,behaviour,data,spatial,temporal
+Author: Josef Heidler
+Author-email: jheidler@health.sdu.dk
+Maintainer: Josef Heidler
+Maintainer-email: jheidler@health.sdu.dk
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: geopandas (>=0.14.2,<0.15.0)
+Requires-Dist: openpyxl (>=3.1.2,<4.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: pandera (>=0.18.0,<0.19.0)
+Requires-Dist: pyarrow (>=15.0.0,<16.0.0)
+Requires-Dist: pydeck (>=0.8.0,<0.9.0)
+Requires-Dist: sqlalchemy (>=2.0.25,<3.0.0)
+Requires-Dist: timezonefinder (>=6.2.0,<7.0.0)
+Project-URL: Documentation, https://labda.josefheidler.cz
+Project-URL: Repository, https://github.com/josefheidler/labda
+Description-Content-Type: text/markdown
+
+# LABDA: Library for Advanced Behavioural Data Analysis
+
+**LABDA is currently under development and may undergo significant API changes that could result in breaking changes.**
+
+## What is it?
+
+TO-DO...
+
+## Main Features
+
+TO-DO...
+
+## License
+<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://labda.josefheidler.cz/">Library for Advanced Behavioural Data Analysis</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://josefheidler.cz/">Josef Heidler</a> is licensed under <a href="http://creativecommons.org/licenses/by/4.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1"><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1"></a></p>
+
+## Documentation
+
+TO-DO...
+
+## Getting Help, Discussion and Development
+
+TO-DO...
+
+## Contributing to labda
+
+TO-DO..

labda-0.0.2/README.md

@@ -0,0 +1,26 @@
+# LABDA: Library for Advanced Behavioural Data Analysis
+
+**LABDA is currently under development and may undergo significant API changes that could result in breaking changes.**
+
+## What is it?
+
+TO-DO...
+
+## Main Features
+
+TO-DO...
+
+## License
+<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://labda.josefheidler.cz/">Library for Advanced Behavioural Data Analysis</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://josefheidler.cz/">Josef Heidler</a> is licensed under <a href="http://creativecommons.org/licenses/by/4.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1"><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1"></a></p>
+
+## Documentation
+
+TO-DO...
+
+## Getting Help, Discussion and Development
+
+TO-DO...
+
+## Contributing to labda
+
+TO-DO..

labda-0.0.2/labda/__init__.py

@@ -0,0 +1 @@
+from .structure import Collection, Column, Subject, merge_collections, merge_subjects

labda-0.0.2/labda/assets/__init__.py

@@ -0,0 +1,2 @@
+from .counts_cut_points import CUT_POINTS as COUNTS_CUT_POINTS
+from .transportation_cut_points import CUT_POINTS as TRANSPORTATION_CUT_POINTS

labda-0.0.2/labda/assets/counts_cut_points.py

@@ -0,0 +1,35 @@
+from ..structure.validation.subject import Column
+
+CUT_POINTS = [
+    {
+        "id": 1,
+        "name": "Freedson Adult (1998)",
+        "reference": "https://journals.lww.com/acsm-msse/fulltext/1998/05000/calibration_of_the_computer_science_and.21.aspx",
+        "sampling_frequency": 60,
+        "category": "adult",
+        "placement": "hip",
+        "required_data": Column.VERTICAL_COUNTS,
+        "cut_points": [
+            {"name": "sedentary", "max": 99},
+            {"name": "light", "max": 1951},
+            {"name": "moderate", "max": 5724},
+            {"name": "vigorous", "max": 9498},
+            {"name": "very_vigorous", "max": float("inf")},
+        ],
+    },
+    {
+        "id": 2,
+        "name": "Freedson Adult VM3 (2011)",
+        "reference": "https://doi.org/10.1016/j.jsams.2011.04.003",
+        "sampling_frequency": 60,
+        "category": "adult",
+        "placement": "hip",
+        "required_data": Column.VM_COUNTS,
+        "cut_points": [
+            {"name": "light", "max": 2689},
+            {"name": "moderate", "max": 6166},
+            {"name": "vigorous", "max": 9642},
+            {"name": "very_vigorous", "max": float("inf")},
+        ],
+    },
+]

labda-0.0.2/labda/assets/transportation_cut_points.py

@@ -0,0 +1,16 @@
+from ..structure.validation.subject import Column
+
+CUT_POINTS = [
+    {
+        "id": 1,
+        "name": "Carlson PALMS Validation (2015)",
+        "reference": "https://doi.org/10.1249/MSS.0000000000000446",
+        "required_data": Column.SPEED,
+        "units": "km/h",
+        "cut_points": [
+            {"name": "walking/running", "max": 9},
+            {"name": "bicycle", "max": 35},
+            {"name": "vehicle", "max": float("inf")},
+        ],
+    },
+]

labda-0.0.2/labda/expanders/__init__.py

@@ -0,0 +1,8 @@
+from .extras import add_timedelta
+from .spatial import (
+    add_acceleration,
+    add_direction,
+    add_distance,
+    add_elevation,
+    add_speed,
+)

labda-0.0.2/labda/expanders/accelerometer.py

@@ -0,0 +1,29 @@
+import numpy as np
+import pandas as pd
+
+from ..structure.validation.subject import Column
+from ..utils import columns_exists, columns_not_exists
+
+
+def add_counts_vector_magnitude(
+    df: pd.DataFrame,
+    *,
+    name: str = Column.VM_COUNTS,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    counts_cols = [
+        Column.VERTICAL_COUNTS,
+        Column.HORIZONTAL_COUNTS,
+        Column.PERPENDICULAR_COUNTS,
+    ]
+
+    columns_exists(df, counts_cols)  # type: ignore
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+    df[name] = np.linalg.norm(
+        df[counts_cols].astype(float),
+        axis=1,
+    )
+
+    return df

labda-0.0.2/labda/expanders/extras.py

@@ -0,0 +1,33 @@
+import pandas as pd
+
+from ..structure.validation.subject import Column
+from ..utils import columns_not_exists
+
+
+def add_timedelta(
+    df: pd.DataFrame,
+    *,
+    name: str = Column.TIMEDELTA,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Adds a timedelta column to the DataFrame.
+
+    This function calculates the time difference between each row and the previous row and adds it as a new column to the DataFrame.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to which to add the timedelta column.
+        name (str, optional): The name of the new timedelta column. Defaults to "timedelta".
+        overwrite (bool, optional): Whether to overwrite the existing timedelta column if it exists. Defaults to False.
+
+    Returns:
+        pd.DataFrame: The DataFrame with the added timedelta column.
+    """
+
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+
+    df[name] = df.index.diff()  # type: ignore
+
+    return df

labda-0.0.2/labda/expanders/spatial.py

@@ -0,0 +1,242 @@
+import numpy as np
+import pandas as pd
+
+from ..structure.validation.subject import Column
+from ..utils import (
+    columns_exists,
+    columns_not_exists,
+    convert_to_geodataframe,
+    get_crs,
+    get_crs_units,
+    get_unique_column_name,
+)
+from .extras import add_timedelta
+
+__all__ = [
+    "add_speed",
+    "add_distance",
+    "add_acceleration",
+    "add_direction",
+    "add_elevation",
+    # "add_weather",
+    # "add_address",
+]
+
+
+def add_speed(
+    df: pd.DataFrame,
+    *,
+    crs: str | None = None,
+    name: str = Column.SPEED,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Adds a speed column to the DataFrame by calculating the speed based on the distance and time.
+    Units are based on the CRS. If CRS is not specified, the CRS will be guessed based on the coordinates (WGS84 by default).
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        crs (str | None, optional): The coordinate reference system. Defaults to None.
+        name (str, optional): The name of the speed dataframe.Column. Defaults to "speed".
+        overwrite (bool, optional): Whether to overwrite the existing speed column if it already exists.
+            Defaults to False.
+
+    Returns:
+        pd.DataFrame: The DataFrame with the speed column added.
+
+    Raises:
+        ValueError: If the speed column already exists in the DataFrame and overwrite is set to False.
+    """
+
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+
+    timedelta_colname = get_unique_column_name(df)
+    df = add_timedelta(df, name=timedelta_colname)
+
+    distance_colname = get_unique_column_name(df)
+    df = add_distance(df, crs=crs, name=distance_colname)
+
+    df[name] = df[distance_colname] / df[timedelta_colname].dt.total_seconds()
+
+    # TODO: This is temporary fix for changing m/s to km/h for now.
+    if crs:
+        units = get_crs_units(crs)
+
+        if units == "metre":
+            df[name] = df[name] * 3.6
+
+    return df.drop(columns=[timedelta_colname, distance_colname])
+
+
+def add_distance(
+    df: pd.DataFrame,
+    *,
+    crs: str | None = None,
+    name: str = Column.DISTANCE,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Adds a column to the DataFrame with the distance between consecutive points.
+    Units are based on the CRS. If CRS is not specified, the CRS will be guessed based on the coordinates (WGS84 by default).
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        crs (str | None, optional): The coordinate reference system of the DataFrame. Defaults to None.
+        name (str, optional): The name of the new dataframe.Column. Defaults to "distance".
+        overwrite (bool, optional): Whether to overwrite the existing column with the same name. Defaults to False.
+
+    Returns:
+        pd.DataFrame: The DataFrame with the added distance dataframe.Column.
+
+    Raises:
+        ValueError: If the column with the specified name already exists in the DataFrame and overwrite is False.
+    """
+
+    columns_exists(df, [Column.LATITUDE, Column.LONGITUDE])
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+    gdf = convert_to_geodataframe(df, crs=crs)
+    if gdf.crs is None:
+        crs = get_crs(gdf)
+        gdf = gdf.set_crs(crs)
+
+    df[name] = gdf.distance(gdf.shift(1))  # type: ignore
+
+    return df
+
+
+def add_acceleration(
+    df: pd.DataFrame,
+    *,
+    crs: str | None = None,
+    name: str = Column.ACCELERATION,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Adds a column to the DataFrame with the acceleration between consecutive points.
+    Acceleration is calculated based on the change in speed over time.
+    Units are based on the CRS. If CRS is not specified, the CRS will be guessed based on the coordinates (WGS84 by default).
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        crs (str | None, optional): The coordinate reference system of the DataFrame. Defaults to None.
+        name (str, optional): The name of the new dataframe.Column. Defaults to "acceleration".
+        overwrite (bool, optional): Whether to overwrite the existing column with the same name. Defaults to False.
+
+    Returns:
+        pd.DataFrame: The DataFrame with the added acceleration dataframe.Column.
+
+    Raises:
+        ValueError: If the column with the specified name already exists in the DataFrame and overwrite is False.
+    """
+
+    # TODO: Needs to be tested.
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+
+    speed_colname = get_unique_column_name(df)
+    df = add_speed(df, crs=crs, name=speed_colname)
+
+    timedelta_colname = get_unique_column_name(df)
+    df = add_timedelta(df, name=timedelta_colname)
+
+    df[name] = (df[speed_colname] - df[speed_colname].shift()) / df[
+        timedelta_colname
+    ].dt.total_seconds()
+
+    return df.drop(columns=[speed_colname, timedelta_colname])
+
+
+def add_direction(
+    df: pd.DataFrame,
+    *,
+    name: str = Column.DIRECTION,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Adds a column to the DataFrame with the direction between consecutive points.
+    Direction is calculated based on the change in longitude and latitude.
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        name (str, optional): The name of the new dataframe.Column. Defaults to "direction".
+        overwrite (bool, optional): Whether to overwrite the existing column with the same name. Defaults to False.
+
+    Returns:
+        pd.DataFrame: The DataFrame with the added direction dataframe.Column.
+
+    Raises:
+        ValueError: If the column with the specified name already exists in the DataFrame and overwrite is False.
+    """
+
+    # TODO: Needs to be tested.
+    columns_exists(df, [Column.LATITUDE, Column.LONGITUDE])
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+
+    # Convert to radians
+    lon1, lat1 = np.radians(df[Column.LONGITUDE]), np.radians(df[Column.LATITUDE])
+    lon2, lat2 = (
+        np.radians(df[Column.LONGITUDE].shift()),
+        np.radians(df[Column.LATITUDE].shift()),
+    )
+
+    dlon = lon2 - lon1
+
+    x = np.cos(lat2) * np.sin(dlon)
+    y = np.cos(lat1) * np.sin(lat2) - np.sin(lat1) * np.cos(lat2) * np.cos(dlon)
+
+    direction = np.arctan2(x, y)
+    direction = np.degrees(direction)
+    direction = (direction + 360) % 360
+
+    df[name] = direction
+
+    return df
+
+
+def add_elevation(
+    df: pd.DataFrame,
+    *,
+    name: str = Column.ELEVATION,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    # TODO: Add elevation.
+
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    raise NotImplementedError("This method needs to be implemented.")
+
+
+# def add_weather(
+#     df: pd.DataFrame,
+#     *,
+#     name: str = "weather",
+#     overwrite: bool = False,
+# ) -> pd.DataFrame:
+#     # TODO: https://open-meteo.com/en/docs/historical-weather-api/
+#     # TODO: Add weather.
+
+#     if not overwrite:
+#         check_columns_existence(df, [name], exists=False)
+
+#     raise NotImplementedError("This method needs to be implemented.")
+
+
+# def add_address(
+#     df: pd.DataFrame,
+#     *,
+#     name: str = "address",
+#     overwrite: bool = False,
+# ) -> pd.DataFrame:
+#     # TODO: Add address.
+
+#     if not overwrite:
+#         check_columns_existence(df, [name], exists=False)
+
+#     raise NotImplementedError("This method needs to be implemented.")

labda-0.0.2/labda/parsers/__init__.py

@@ -0,0 +1,4 @@
+from . import gadgetbridge as Gadgetbridge
+from . import qstarz as Qstarz
+from . import actigraph as Actigraph
+from .bulk import bulk_parser