labda 0.0.2__py3-none-any.whl

labda/structure/validation/domains.py

@@ -0,0 +1,37 @@
+from pandera import Column, DataFrameSchema
+
+# TODO: Refactor...
+
+SCHEMA = DataFrameSchema(
+    columns={
+        "subject_id": Column(
+            dtype="string",
+            description="Unique ID of the dataframe (participant)",
+            required=False,
+            nullable=True,
+        ),
+        "domain": Column(
+            dtype="string",
+            description="Name of the domain",
+        ),
+        "start": Column(
+            dtype="datetime64[ns]",
+            description="Start time of the domain",
+            required=False,
+            nullable=True,
+        ),
+        "end": Column(
+            dtype="datetime64[ns]",
+            description="End time of the domain",
+            required=False,
+            nullable=True,
+        ),
+        "geometry": Column(
+            dtype="geometry",
+            description="Geometry of the domain",
+            required=False,
+            nullable=True,
+        ),
+    },
+    coerce=True,
+)

labda/structure/validation/linkage.py

@@ -0,0 +1,28 @@
+from pandera import Check, Column, DataFrameSchema
+
+# TODO: Maybe just one linkage also for domains (timetable, geometries), information about the subjects etc.
+# TODO: Refactor...
+
+SCHEMA = DataFrameSchema(
+    columns={
+        "subject_id": Column(
+            dtype="string",
+            description="Unique ID of the dataframe (subject)",
+        ),
+        "sensor_id": Column(
+            dtype="string",
+            description="ID of the device (e.g. MAC address, serial number)",
+        ),
+        "start": Column(
+            dtype="datetime64[ns]",
+            description="Start time of the recording",
+            required=False,
+        ),
+        "end": Column(
+            dtype="datetime64[ns]",
+            description="End time of the recording",
+            required=False,
+        ),
+    },
+    coerce=True,
+)

labda/structure/validation/subject.py

@@ -0,0 +1,323 @@
+from enum import StrEnum
+
+import pandera as pr
+
+
+class Column(StrEnum):
+    SUBJECT_ID = "subject_id"
+    DATETIME = "datetime"
+    WEAR = "wear"
+    TIMEDELTA = "timedelta"
+    # ---
+    VERTICAL_COUNTS = "vertical_counts"
+    HORIZONTAL_COUNTS = "horizontal_counts"
+    PERPENDICULAR_COUNTS = "perpendicular_counts"
+    VM_COUNTS = "vm_counts"
+    POSITION = "position"
+    STEPS = "steps"
+    # ---
+    LATITUDE = "latitude"
+    LONGITUDE = "longitude"
+    NSAT_VIEWED = "nsat_viewed"
+    NSAT_USED = "nsat_used"
+    NSAT_RATIO = "nsat_ratio"
+    SNR_VIEWED = "snr_viewed"
+    SNR_USED = "snr_used"
+    PDOP = "pdop"
+    HDOP = "hdop"
+    VDOP = "vdop"
+    # ---
+    DISTANCE = "distance"
+    ELEVATION = "elevation"
+    SPEED = "speed"
+    ACCELERATION = "acceleration"
+    DIRECTION = "direction"
+    ENVIRONMENT = "environment"
+    # ---
+    SEGMENT_ID = "segment_id"
+    TRIP_ID = "trip_id"
+    TRIP_STATUS = "trip_status"
+    TRIP_MODE = "trip_mode"
+    STATIONARY_ID = "stationary_id"
+    # ---
+    HEART_RATE = "heart_rate"
+    LUX = "lux"
+    # ---
+    ACTIVITY_INTENSITY = "activity_intensity"
+
+
+SCHEMA = pr.DataFrameSchema(
+    index=pr.Index(
+        name=Column.DATETIME,
+        dtype="datetime64[ns]",
+        description="Datetime in timezone where data was collected.",
+    ),
+    columns={
+        Column.SUBJECT_ID: pr.Column(
+            dtype="string",
+            description="Unique ID of the subject.",
+            required=False,
+            nullable=False,
+        ),
+        Column.WEAR: pr.Column(
+            dtype="boolean",
+            description="Devices worn or not.",
+            required=False,
+            nullable=True,
+        ),
+        Column.TIMEDELTA: pr.Column(
+            dtype="timedelta",
+            description="Time since last fix.",
+            required=False,
+            nullable=True,
+        ),
+        Column.VERTICAL_COUNTS: pr.Column(
+            dtype="UInt16",
+            description="Vertical counts.",
+            required=False,
+            nullable=True,
+        ),
+        Column.HORIZONTAL_COUNTS: pr.Column(
+            dtype="UInt16",
+            description="Horizontal counts.",
+            required=False,
+            nullable=True,
+        ),
+        Column.PERPENDICULAR_COUNTS: pr.Column(
+            dtype="UInt16",
+            description="Perpendicular counts.",
+            required=False,
+            nullable=True,
+        ),
+        Column.VM_COUNTS: pr.Column(
+            dtype="Float32",
+            description="Vector magnitude based on axes counts.",
+            required=False,
+            nullable=True,
+        ),
+        Column.POSITION: pr.Column(
+            dtype="category",
+            description="Position of subject.",
+            required=False,
+            nullable=True,
+            checks=[
+                pr.Check(
+                    lambda s: s[s.notna()].isin(
+                        [
+                            "standing",
+                            "sitting",
+                            "lying",
+                        ]
+                    ),
+                )
+            ],
+        ),
+        Column.STEPS: pr.Column(
+            dtype="UInt16",
+            description="Steps since last fix.",
+            required=False,
+            nullable=True,
+        ),
+        Column.LATITUDE: pr.Column(
+            dtype="Float64",
+            description="Latitude in appropriate coordinate system where data was collected.",
+            required=False,
+            nullable=True,
+            # checks=[Check.ge(-90), Check.le(90)],
+        ),
+        Column.LONGITUDE: pr.Column(
+            dtype="Float64",
+            description="Longitude in appropriate coordinate system where data was collected.",
+            required=False,
+            nullable=True,
+            # checks=[Check.ge(-180), Check.le(180)],
+        ),
+        Column.NSAT_VIEWED: pr.Column(
+            dtype="UInt8",
+            description="Number of satellites viewed by device.",
+            required=False,
+            nullable=True,
+        ),
+        Column.NSAT_USED: pr.Column(
+            dtype="UInt8",
+            description="Number of satellites used by device.",
+            required=False,
+            nullable=True,
+        ),
+        Column.NSAT_RATIO: pr.Column(
+            dtype="Float32",
+            description="Satellites ratio (used/viewed).",
+            required=False,
+            nullable=True,
+        ),
+        Column.SNR_VIEWED: pr.Column(
+            dtype="UInt16",
+            description="Sum of satellites SNR.",
+            required=False,
+            nullable=True,
+        ),
+        Column.SNR_USED: pr.Column(
+            dtype="UInt16",
+            description="Sum of used satellites SNR.",
+            required=False,
+            nullable=True,
+        ),
+        Column.PDOP: pr.Column(
+            dtype="Float32",
+            description="GNSS PDOP (Position of Dilution of Precision).",
+            required=False,
+            nullable=True,
+        ),
+        Column.HDOP: pr.Column(
+            dtype="Float32",
+            description="GNSS HDOP (Horizontal Dilution of Precision).",
+            required=False,
+            nullable=True,
+        ),
+        Column.VDOP: pr.Column(
+            dtype="Float32",
+            description="GNSS VDOP (Vertical Dilution of Precision).",
+            required=False,
+            nullable=True,
+        ),
+        Column.ACCELERATION: pr.Column(
+            dtype="Float32",
+            description="Acceleration in m/s².",
+            nullable=True,
+            required=False,
+        ),
+        Column.DIRECTION: pr.Column(
+            dtype="Float32",
+            description="Direction (bearing) in degrees",
+            required=False,
+            nullable=True,
+        ),
+        Column.DISTANCE: pr.Column(
+            dtype="Float32",
+            description="Distance taken since last fix in metres.",
+            required=False,
+            nullable=True,
+        ),
+        Column.ELEVATION: pr.Column(
+            dtype="Float32",
+            description="Elevation in metres",
+            required=False,
+            nullable=True,
+        ),
+        Column.ENVIRONMENT: pr.Column(
+            dtype="category",
+            description="Type of environment",
+            required=False,
+            nullable=True,
+            checks=[
+                pr.Check(
+                    lambda s: s[s.notna()].isin(
+                        [
+                            "indoor",
+                            "outdoor",
+                            "vehicle",
+                            "mixed",
+                        ]
+                    ),
+                )
+            ],
+        ),
+        Column.SPEED: pr.Column(
+            dtype="Float32",
+            description="Speed in km/h.",
+            required=False,
+            nullable=True,
+        ),
+        Column.SEGMENT_ID: pr.Column(
+            dtype="UInt32",
+            description="ID of segment based on missing data or other criteria.",
+            required=False,
+            nullable=False,
+        ),
+        Column.TRIP_ID: pr.Column(
+            dtype="UInt16",
+            description="ID of trip.",
+            required=False,
+            nullable=True,
+        ),
+        Column.TRIP_MODE: pr.Column(
+            dtype="category",
+            description="Type of transportation mode.",
+            required=False,
+            nullable=True,
+            checks=[
+                pr.Check(
+                    lambda s: s[s.notna()].isin(
+                        [
+                            "walk",
+                            "run",
+                            "bicycle",
+                            "scooter",
+                            "vehicle",
+                            "train",
+                        ]
+                    ),
+                )
+            ],
+        ),
+        Column.TRIP_STATUS: pr.Column(
+            dtype="category",
+            description="Status of trip",
+            required=False,
+            nullable=True,
+            checks=[
+                pr.Check(
+                    lambda s: s[s.notna()].isin(
+                        [
+                            "start",
+                            "end",
+                            "start-end",
+                            "transport",
+                            "pause",
+                            "stationary",
+                        ]
+                    ),
+                )
+            ],
+        ),
+        Column.STATIONARY_ID: pr.Column(
+            dtype="UInt16",
+            description="ID of stationary.",
+            required=False,
+            nullable=True,
+        ),
+        Column.HEART_RATE: pr.Column(
+            dtype="UInt8",
+            description="Heart rate in beats per minute.",
+            required=False,
+            nullable=True,
+        ),
+        Column.LUX: pr.Column(
+            dtype="UInt16",
+            description="Ambient light in lux.",
+            required=False,
+            nullable=True,
+        ),
+        Column.ACTIVITY_INTENSITY: pr.Column(
+            dtype="category",
+            description="Intensity of activity.",
+            required=False,
+            nullable=True,
+            checks=[
+                pr.Check(
+                    lambda s: s[s.notna()].isin(
+                        [
+                            "sedentary",
+                            "light",
+                            "moderate",
+                            "moderate-vigorous",
+                            "vigorous",
+                        ]
+                    ),
+                )
+            ],
+        ),
+    },
+    coerce=True,
+    strict=False,
+)

labda/utils.py

@@ -0,0 +1,240 @@
+import secrets
+
+import geopandas as gpd
+import pandas as pd
+import pyproj
+from timezonefinder import TimezoneFinder
+
+from .structure.validation.subject import Column
+
+
+def columns_exists(
+    df: pd.DataFrame,
+    columns: list[Column | str],
+) -> None:
+    """
+    Checks if the given columns exist in the DataFrame.
+
+    This function iterates over the list of columns and checks if each column exists in the DataFrame.
+    If a column does not exist, it raises a ValueError.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to check.
+        columns (list[str]): A list of column names to check for existence in the DataFrame.
+
+    Raises:
+        ValueError: If a column does not exist in df.
+    """
+
+    missing_columns = [col for col in columns if col not in df.columns]
+
+    if missing_columns:
+        raise ValueError(
+            f"The following columns do not exist in the DataFrame: {', '.join(missing_columns)}"
+        )
+
+
+def columns_not_exists(
+    df: pd.DataFrame,
+    columns: list[Column | str],
+    *,
+    overwrite: bool = False,
+) -> None:
+    """
+    Checks if the specified columns do not exist in the DataFrame. If 'overwrite' is True,
+    existing columns will be dropped. If 'overwrite' is False, an error will be raised for existing columns.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to check.
+        columns (List[str]): A list of column names to check.
+        overwrite (bool, optional): Whether to drop existing columns. Defaults to False.
+
+    Raises:
+        ValueError: If 'overwrite' is False and any of the specified columns exist in the DataFrame.
+
+    Returns:
+        None
+    """
+    existing_columns = [col for col in columns if col in df.columns]
+
+    if existing_columns:
+        if overwrite:
+            df.drop(columns=existing_columns, inplace=True)
+        else:
+            raise ValueError(
+                f"The following columns already exist in the DataFrame: {', '.join(existing_columns)}"
+            )
+
+
+def get_unique_column_name(df: pd.DataFrame) -> str:
+    """
+    Generates a unique column name that is not present in the given list of columns.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to check.
+
+    Returns:
+        str: A unique column name.
+    """
+    hex = 4
+    colname = secrets.token_hex(hex)
+    while colname in df.columns.tolist():
+        colname = secrets.token_hex(hex)
+
+    return colname
+
+
+def get_sampling_frequency(df: pd.DataFrame) -> float:
+    # TODO: Check that index is a datetime index.
+
+    frequencies = df.index.to_series().diff().value_counts()
+    dominant_frequency = frequencies.idxmax()
+
+    if len(frequencies) > 1 and frequencies[dominant_frequency] == frequencies.iloc[1]:
+        raise ValueError(
+            "We are uncertain about the frequency sampling. Please verify the data manually."
+        )
+
+    seconds = dominant_frequency.total_seconds()  # type: ignore
+    if seconds < 1:
+        raise NotImplementedError(
+            "Sub-second sampling frequencies are not supported yet."
+        )
+
+    return seconds
+
+
+def convert_to_geodataframe(
+    df: pd.DataFrame,
+    *,
+    crs: str | None = None,
+) -> gpd.GeoDataFrame:
+    """
+    Converts a DataFrame to a GeoDataFrame by creating a geometry column from latitude and longitude columns.
+
+    Args:
+        df (pd.DataFrame): The DataFrame to be converted.
+        crs (str | None, optional): The coordinate reference system (CRS) of the GeoDataFrame. Defaults to None.
+
+    Returns:
+        gpd.GeoDataFrame: The converted GeoDataFrame.
+    """
+
+    columns_exists(df, [Column.LATITUDE, Column.LONGITUDE])
+
+    return gpd.GeoDataFrame(
+        df, geometry=gpd.points_from_xy(df.longitude, df.latitude), crs=crs
+    )  # type: ignore
+
+
+def convert_to_dataframe(gdf: gpd.GeoDataFrame) -> pd.DataFrame:
+    """
+    Converts a GeoDataFrame to a DataFrame by extracting the latitude and longitude
+    coordinates from the geometry column. The geometry column is dropped in the process.
+
+    Args:
+        gdf (gpd.GeoDataFrame): The input GeoDataFrame.
+
+    Returns:
+        pd.DataFrame: The converted DataFrame with latitude and longitude columns.
+    """
+    gdf[Column.LATITUDE] = gdf.geometry.y
+    gdf[Column.LONGITUDE] = gdf.geometry.x
+    gdf.drop(columns=["geometry"], inplace=True)
+
+    return pd.DataFrame(gdf)
+
+
+def get_crs(df: pd.DataFrame) -> str:
+    """
+    Guesses the coordinate reference system (CRS) of a DataFrame containing spatial data. The CRS is estimated using the WGS84 ellipsoid.
+
+    Args:
+        df (pd.DataFrame): The DataFrame containing spatial data.
+
+    Returns:
+        str: The estimated CRS of the DataFrame.
+    """
+
+    gdf = convert_to_geodataframe(df, crs="WGS84")  # type: ignore
+    estimated_crs = gdf.geometry.estimate_utm_crs()
+
+    return str(estimated_crs)
+
+
+def get_timezone(df: pd.DataFrame, sample_size: int = 5) -> str:
+    """
+    Guesses the dominant timezone based on latitude and longitude coordinates in a DataFrame. The timezone is estimated using the TimezoneFinder package.
+
+    Args:
+        df (pd.DataFrame): The DataFrame containing latitude and longitude columns.
+        sample_size (int, optional): The number of coordinates to sample for timezone estimation. Defaults to 5.
+
+    Raises:
+        ValueError: If there are multiple timezones with the same highest count.
+
+    Returns:
+        str: The dominant timezone as a string.
+    """
+
+    columns_exists(df, [Column.LATITUDE, Column.LONGITUDE])
+
+    coords = df[df[Column.LATITUDE].notna() & df[Column.LONGITUDE].notna()]
+    sample = coords.sample(sample_size)
+
+    tz_finder = TimezoneFinder()
+    sample["timezone"] = sample.apply(
+        lambda row: tz_finder.timezone_at(lat=row.latitude, lng=row.longitude),  # type: ignore
+        axis=1,
+    )
+
+    timezones = sample["timezone"].value_counts()
+    dominant_timezone = timezones.idxmax()
+    if len(timezones) >= 2 and timezones[dominant_timezone] == timezones.iloc[1]:
+        raise ValueError(
+            "We are uncertain about the timezone. Please verify the data manually."
+        )
+
+    return str(dominant_timezone)
+
+
+def convert_distance_parameter(param: int | float, sampling_frequency: float) -> float:
+    """
+    Converts a distance parameter to meters.
+
+    This function accepts a distance parameter as an integer or float in meters per minute.
+    The function then converts the distance to proper value based on sampling frequency.
+
+    Args:
+        distance (int | float): The distance in meters per minute to convert.
+        sampling_frequency (float): The sampling frequency in seconds.
+    Returns:
+        float: The converted distance in meters per minute based on sampling frequency.
+    """
+    meters = param / (60 / sampling_frequency)
+    return meters
+
+
+def align_datetimes(df: pd.DataFrame, sampling_frequency: float) -> pd.DataFrame:
+    df = df.copy()
+    # TODO: Add docstring
+    diff = get_unique_column_name(df)
+    rounded = get_unique_column_name(df)
+
+    df[rounded] = df.index.round(f"{sampling_frequency}s")  # type: ignore
+    df[diff] = (df.index - df[rounded]).dt.total_seconds().abs()  # type: ignore
+    df = df.sort_values([rounded, diff])
+    df.drop(columns=[diff], inplace=True)
+
+    df = df.drop_duplicates(subset=rounded, keep="first")
+    df.set_index(rounded, inplace=True, drop=True)
+    df.index.name = Column.DATETIME
+
+    return df
+
+
+def get_crs_units(crs: str) -> str:
+    crs = pyproj.CRS(crs)  # type: ignore
+    units = crs.axis_info[0].unit_name  # type: ignore
+
+    return units

labda-0.0.2.dist-info/METADATA

@@ -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..