labda 0.0.2__py3-none-any.whl

labda/processing/accelerometer/activity_intensity.py

@@ -0,0 +1,57 @@
+import copy
+from typing import Any
+
+import pandas as pd
+
+from ...structure.validation.subject import Column
+from ...utils import columns_exists, columns_not_exists
+
+
+def scale_cut_points(
+    cut_points: dict[str, Any], sampling_frequency: float
+) -> dict[str, Any]:
+    cut_points = copy.deepcopy(cut_points)
+    from_sf = cut_points["sampling_frequency"]
+    for cp in cut_points["cut_points"]:
+        if cp.get("max") is not None:
+            cp["max"] = cp["max"] / (from_sf / sampling_frequency)
+
+    return cut_points
+
+
+def apply_cut_points(
+    df: pd.DataFrame, on: Column | str, cut_points: dict[str, Any], name: str
+):
+    # Extract min and max values from cut_points
+    bins = [-float("inf")]
+    bins += [cp["max"] for cp in cut_points["cut_points"]]
+
+    # Extract names from cut_points
+    labels = [cp["name"] for cp in cut_points["cut_points"]]
+
+    # Apply cut points
+    df[name] = pd.cut(df[on], bins=bins, labels=labels)
+
+
+def detect_activity_intensity(
+    df: pd.DataFrame,
+    cut_points: dict[str, Any],
+    sampling_frequency: float,
+    *,
+    name: str = Column.ACTIVITY_INTENSITY,
+    overwrite: bool = False,
+):
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    required_column = cut_points["required_data"]
+    columns_exists(df, [required_column])
+
+    df = df.copy()
+
+    # Check sampling frequency if needed scale cut points
+    if cut_points["sampling_frequency"] != sampling_frequency:
+        cut_points = scale_cut_points(cut_points, sampling_frequency)
+
+    apply_cut_points(df, required_column, cut_points, name)
+
+    return df

labda/processing/accelerometer/steps.py

@@ -0,0 +1,24 @@
+import pandas as pd
+
+from ...structure.validation.subject import Column
+from ...utils import columns_exists, columns_not_exists
+
+# TODO: Refactor...
+
+
+def detect_mvpa_from_steps(
+    df: pd.DataFrame,
+    sampling_frequency: float,
+    name: str = Column.ACTIVITY_INTENSITY,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    columns_exists(df, [Column.STEPS])
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+    cut_off = (sampling_frequency / 60) * 100
+
+    df[name] = pd.NA
+    df.loc[df[Column.STEPS] >= cut_off, name] = "moderate-vigorous"
+
+    return df.astype({name: "category"})

labda/processing/accelerometer/wear.py

@@ -0,0 +1,38 @@
+from datetime import timedelta
+
+import pandas as pd
+
+from ...expanders.accelerometer import add_counts_vector_magnitude
+from ...processing.bouts import get_bouts
+from ...structure.validation.subject import Column
+from ...utils import columns_not_exists
+
+
+def detect_wear(
+    df: pd.DataFrame,
+    sampling_frequency: float,
+    min_duration: timedelta,
+    *,
+    interruption_duration: timedelta | None = None,
+    name: str = Column.WEAR,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    if Column.VM_COUNTS not in df.columns:
+        df = add_counts_vector_magnitude(df)
+
+    df = get_bouts(
+        df,
+        Column.VM_COUNTS,
+        sampling_frequency,
+        min_duration,
+        0,
+        0,
+        interruption_duration=interruption_duration,
+        name=name,
+        overwrite=overwrite,
+    )
+    df[name] = ~df[name]
+
+    return df

labda/processing/bouts.py

@@ -0,0 +1,85 @@
+from datetime import timedelta
+
+import pandas as pd
+
+from ..utils import columns_not_exists, get_unique_column_name
+
+
+def _get_duration(g):
+    return g.index[-1] - g.index[0]
+
+
+def get_bouts(
+    df: pd.DataFrame,
+    column: str,
+    sampling_frequency: float,
+    min_duration: timedelta,
+    min_value: float,
+    max_value: float,
+    *,
+    interruption_duration: timedelta | None = None,
+    name: str = "bout",
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    if interruption_duration and min_duration <= interruption_duration:
+        raise ValueError(
+            "The interruption duration must be less than the bout duration"
+        )
+
+    bout = get_unique_column_name(df)
+    bout_id = get_unique_column_name(df)
+    possibly_bout = get_unique_column_name(df)
+
+    temp_df = df[[column]].copy()
+    temp_df = temp_df.resample(f"{sampling_frequency}s").asfreq()
+    # TODO: Bouts should be more based on column with True/False values only, so user needs to preprocess the data.
+    # TODO: So it should be this column as input, not the min/max values.
+    temp_df[bout] = (temp_df[column] >= min_value) & (temp_df[column] <= max_value)
+
+    temp_df[bout_id] = (temp_df[bout] != temp_df[bout].shift(1)).cumsum()
+
+    if interruption_duration:
+        # All rows are possible bouts
+        temp_df[possibly_bout] = True
+
+        # Calculate the duration of the interruptions
+        interruption = (
+            temp_df[temp_df[bout] == False]
+            .groupby(bout_id)
+            .apply(_get_duration, include_groups=False)
+        )
+
+        # Get consecutive interruptions where the duration is over the specific time
+        interruption_rows = interruption[interruption >= interruption_duration].index
+
+        # Set possibility of bout to False because interruption is too long
+        temp_df.loc[temp_df[bout_id].isin(interruption_rows), possibly_bout] = False
+
+        # Recreate the bout_id with the interruptions
+        temp_df[bout_id] = (
+            temp_df[possibly_bout] != temp_df[possibly_bout].shift(1)
+        ).cumsum()
+    else:
+        temp_df[possibly_bout] = temp_df[bout]
+
+    # Create the final column with the bouts. Default to False
+    temp_df[name] = False
+
+    # Calculate the duration of the bouts
+    bout_duration = (
+        temp_df[temp_df[possibly_bout]]
+        .groupby(bout_id)
+        .apply(_get_duration, include_groups=False)
+    )
+
+    # Get consecutive bouts where the duration is over the specific time
+    bout_rows = bout_duration[bout_duration >= min_duration].index
+
+    # Set bout to True for the rows where the duration is over the specific time
+    temp_df.loc[temp_df[bout_id].isin(bout_rows), name] = True
+
+    df = df.join(temp_df[[name]], how="left")
+
+    return df

labda/processing/domains.py

@@ -0,0 +1,32 @@
+import pandas as pd
+
+from ..utils import columns_not_exists
+
+# TODO: Possibility to specify if point should be INSIDE or OUTSIDE the domain. Maybe?
+# TODO: Get domains
+
+
+def detect_domains(
+    df: pd.DataFrame,
+    domains: pd.DataFrame,
+    *,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    df = df.copy()
+    unique_domains = domains.groupby("domain")
+
+    for domain in unique_domains:
+        name = f"domain_{domain[0]}"
+
+        columns_not_exists(df, [name], overwrite=overwrite)
+
+        domain_df = domain[1]
+        df[name] = False
+
+        for interval in domain_df.itertuples():
+            df.loc[
+                (df.index >= interval.start) & (df.index <= interval.end),
+                name,
+            ] = True
+
+    return df

labda/processing/manipulations.py

@@ -0,0 +1,22 @@
+from datetime import timedelta
+
+import pandas as pd
+
+from ..utils import columns_not_exists
+
+
+def gap_splitter(
+    df: pd.DataFrame,
+    *,
+    min_duration: timedelta,
+    name: str = "gap",
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+
+    df[name] = df.index.diff() > min_duration  # type: ignore
+    df[name] = df[name].apply(lambda x: 1 if x else 0).cumsum() + 1
+
+    return df.astype({name: "UInt16"})

labda/processing/spatial/__init__.py

@@ -0,0 +1,4 @@
+from .manipulations import max_speed_filter, min_distance_filter, stop_splitter
+from .timeline import get_timeline
+from .transportation import detect_transportation
+from .trips import detect_trips

labda/processing/spatial/environment.py

@@ -0,0 +1,50 @@
+import pandas as pd
+
+# TODO: Refactor...
+
+
+def detect_environment(
+    df: pd.DataFrame,
+    algorithm: str = "palms",
+    *,
+    name: str = "environment",
+    overwrite: bool = False,
+    **kwargs,
+) -> pd.DataFrame:
+    if name in df.columns and not overwrite:
+        raise ValueError(f"Column '{name}' already exists in dataframe")
+
+    df = df.copy()
+    algorithms = {
+        "palms": palms_environment_detection,
+    }
+
+    if algorithm not in algorithms:
+        raise ValueError(f"Method must be one of {list(algorithms.keys())}.")
+
+    df = algorithms[algorithm](df, name, **kwargs)
+
+    return df.astype({name: "category"})
+
+
+def palms_environment_detection(
+    df: pd.DataFrame,
+    name: str,
+    method: str,
+    limit: int | float | None = None,
+) -> pd.DataFrame:
+    if not limit:
+        raise ValueError("Limit must be specified.")
+
+    methods = ["snr_total", "nsat_ratio"]
+    if method not in methods:
+        raise ValueError(f"Method must be one of {methods}.")
+
+    if method not in df.columns:
+        raise ValueError(f"Column '{method}' not found in DataFrame.")
+
+    df = df[df[method].notna()]
+    df[name] = "outdoor"
+    df.loc[df[method] <= limit, name] = "indoor"
+
+    return df

labda/processing/spatial/manipulations.py

@@ -0,0 +1,186 @@
+from collections import deque
+from datetime import timedelta
+
+import pandas as pd
+
+from ...expanders import add_speed
+from ...utils import (
+    columns_exists,
+    columns_not_exists,
+    convert_to_geodataframe,
+    get_crs,
+    get_unique_column_name,
+)
+
+
+def stop_splitter(
+    df: pd.DataFrame,
+    *,
+    max_radius: int | float,
+    min_duration: timedelta,
+    crs: str | None = None,
+    name: str = "stop",
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Splits a DataFrame into stop segments based on a maximum radius and minimum duration.
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        max_radius (int | float): The maximum radius within which points are considered part of a stop segment.
+        min_duration (timedelta): The minimum duration required for a stop segment.
+        crs (str | None, optional): The coordinate reference system of the input DataFrame. Defaults to None.
+        name (str, optional): The name of the column to be added to the DataFrame to indicate stop segments. Defaults to "stop".
+
+    Returns:
+        pd.DataFrame: The modified DataFrame with the added stop column. The stop column is True for stop segments and False otherwise.
+
+    Raises:
+        ValueError: If the specified column name already exists in the DataFrame and overwrite is set to False.
+    """
+
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    df = df.copy()
+    df[name] = False
+
+    gdf = convert_to_geodataframe(df, crs=crs)
+    if gdf.crs is None:
+        crs = get_crs(gdf)
+        gdf = gdf.set_crs(crs)
+
+    buffer = deque()
+    for dt in gdf.index:
+        buffer.append(dt)
+        if dt - buffer[0] >= min_duration:
+            selected_rows = gdf.loc[buffer[0] : dt]
+            centroid = selected_rows.geometry.unary_union.centroid
+
+            for row in selected_rows.geometry:
+                distance = centroid.distance(row)
+                if distance > max_radius:
+                    break
+            else:
+                df.loc[selected_rows.index, name] = True
+
+            buffer.popleft()
+
+    return df.astype({name: "boolean"})
+
+
+def min_distance_filter(
+    df: pd.DataFrame,
+    *,
+    min_distance: int | float,
+    crs: str | None = None,
+    name: str = "min_distance",
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Filters a DataFrame based on the minimum distance between consecutive points.
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        min_distance (int | float): The minimum distance threshold.
+        crs (str | None, optional): The coordinate reference system of the DataFrame. Defaults to None.
+        name (str, optional): The name of the new column to be added. Defaults to "min_distance".
+        overwrite (bool, optional): Whether to overwrite the existing column with the same name. Defaults to False.
+
+    Returns:
+        pd.DataFrame: The filtered DataFrame with an additional column indicating whether each point meets the minimum distance requirement. The column is True if the point meets the requirement and False otherwise.
+
+    Raises:
+        ValueError: If the specified column name already exists in the DataFrame and overwrite is set to False.
+    """
+
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    gdf = convert_to_geodataframe(df, crs=crs)
+    if gdf.crs is None:
+        crs = get_crs(gdf)
+        gdf = gdf.set_crs(crs)
+
+    keep_pts = [gdf.index[0]]  # Keep first point, always.
+    prev_pt = gdf.geometry.iloc[0]
+
+    for idx, pt in gdf.geometry.items():
+        dist = pt.distance(prev_pt)
+        if dist >= min_distance:
+            keep_pts.append(idx)
+            prev_pt = pt
+
+    keep_pts.append(gdf.index[-1])
+
+    df = df.copy()
+    df[name] = False
+    df.loc[keep_pts, name] = True
+
+    return df.astype({name: "boolean"})
+
+
+def max_speed_filter(
+    df: pd.DataFrame,
+    *,
+    max_speed: int | float | None = None,
+    crs: str | None = None,
+    name: str = "max_speed",
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    """
+    Filters the DataFrame based on the maximum speed value.
+
+    Args:
+        df (pd.DataFrame): The input DataFrame.
+        max_speed (int | float): The maximum speed value to filter by.
+        crs (str | None, optional): The coordinate reference system. Defaults to None.
+        name (str, optional): The name of the new column to store the filter result. Defaults to "max_speed".
+        overwrite (bool, optional): Whether to overwrite the existing column with the same name. Defaults to False.
+
+    Returns:
+        pd.DataFrame: The filtered DataFrame with the new column added. The column is True if the point meets the requirement and False otherwise.
+
+    Raises:
+        ValueError: If the specified column name already exists in the DataFrame and overwrite is set to False.
+    """
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    if max_speed is None:
+        # TODO: Should be 95th percentile of the speed.
+        raise NotImplementedError("max_speed=None is not yet implemented.")
+
+    gdf = convert_to_geodataframe(df, crs=crs)
+    if gdf.crs is None:
+        crs = get_crs(gdf)
+        gdf = gdf.set_crs(crs)
+
+    prev = gdf.iloc[0]
+    prev = (prev.name, prev.geometry)
+
+    # TODO: The invalid point logic is working that if the point is invalid, and the next point is the same, then it should be skipped as well.
+    # invalid_pt = None
+
+    keep_idx = [prev[0]]  # Keep first point, always.
+
+    for idx, pt in gdf.geometry.iloc[1:].items():
+        dist = pt.distance(prev[1])
+
+        # if invalid_pt and invalid_pt.equals(pt):
+        #     continue
+
+        delta_dt = (idx - prev[0]).total_seconds()  # type: ignore
+        speed = (dist / delta_dt) * 3.6
+
+        if speed <= max_speed:
+            keep_idx.append(idx)
+            prev = (idx, pt)
+        #     invalid_pt = None
+        # else:
+        #     invalid_pt = pt
+
+    keep_idx.append(gdf.index[-1])
+
+    df = df.copy()
+    df[name] = False
+    df.loc[keep_idx, name] = True
+
+    return df.astype({name: "boolean"})

labda/processing/spatial/timeline.py

@@ -0,0 +1,99 @@
+import pandas as pd
+from shapely.geometry import LineString
+
+from ...expanders import add_distance
+from ...structure.validation.subject import Column
+from ...utils import convert_to_geodataframe, get_unique_column_name
+
+
+def get_information(df: pd.DataFrame, crs: str) -> pd.Series:
+    df = df.copy()
+    start = df.index.min()
+    end = df.index.max()
+    duration = end - start
+
+    distance_col = get_unique_column_name(df)
+    df = add_distance(df, crs=crs, name=distance_col)
+    distance = df[distance_col].sum()
+
+    gdf = convert_to_geodataframe(df[[Column.LATITUDE, Column.LONGITUDE]], crs=crs)
+    geometry = gdf["geometry"]
+
+    # Add status and IDs based on trip_id and location_id.
+    if df[Column.TRIP_ID].notna().all():
+        trip_id = df[Column.TRIP_ID].iloc[0]
+        if df["stationary_id"].notna().all():
+            status = "pause"
+            mode = pd.NA
+            location_id = df["stationary_id"].iloc[0]
+        else:
+            status = "transport"
+            mode = df["trip_mode"].iloc[0]
+            location_id = pd.NA
+    else:
+        status = "stationary"
+        trip_id = pd.NA
+        mode = pd.NA
+        location_id = df["stationary_id"].iloc[0]
+
+    if status == "transport":
+        geometry = LineString(geometry.tolist())  # type: ignore
+
+    else:
+        geometry = geometry.unary_union  # type: ignore
+
+    return pd.Series(
+        {
+            "trip_id": trip_id,
+            "stationary_id": location_id,
+            "start": start,
+            "end": end,
+            "duration": duration,
+            "distance": distance,
+            "status": status,
+            "mode": mode,
+            "geometry": geometry,
+        }
+    )
+
+
+def get_transport_information(df: pd.DataFrame, crs: str):
+    df = df.copy()
+    helper_id_col = get_unique_column_name(df)
+    df.loc[~df["trip_status"].isin(["stationary", "pause"]), helper_id_col] = (
+        df["trip_status"] == "start"
+    ).cumsum()
+
+    partial_trip_summaries = (
+        df.groupby(helper_id_col)
+        .apply(lambda x: get_information(x, crs=crs))
+        .reset_index(drop=True)
+    )
+
+    return partial_trip_summaries
+
+
+def get_timeline(df: pd.DataFrame, crs: str) -> pd.DataFrame:
+    # TODO: Add a check for specific trip columns.
+    df = df.copy()
+
+    trips = (
+        df.groupby("trip_id")
+        .apply(lambda x: get_transport_information(x, crs=crs))
+        .reset_index(drop=True)
+    )
+
+    stops = df.groupby("stationary_id", as_index=False).apply(
+        lambda x: get_information(x, crs=crs)
+    )
+
+    summary = pd.concat([trips, stops], ignore_index=True).sort_values(["start", "end"])
+
+    return summary.astype(
+        {
+            "status": "category",
+            "mode": "category",
+            "trip_id": "UInt16",
+            "stationary_id": "UInt16",
+        }
+    )

labda/processing/spatial/transportation.py

@@ -0,0 +1,80 @@
+from typing import Any
+
+import pandas as pd
+from pandas.core.groupby import DataFrameGroupBy
+
+from ...expanders.spatial import add_speed
+from ...structure.validation.subject import Column
+from ...utils import columns_exists, columns_not_exists, get_unique_column_name
+
+
+def _set_trip_mode(df: pd.DataFrame, name: str):
+    modes = df[name].value_counts()
+    dominant_mode = modes.idxmax()
+    df[name] = dominant_mode
+
+
+def _get_partial_trips(df: pd.DataFrame) -> DataFrameGroupBy:
+    helper_column = get_unique_column_name(df)
+    df.loc[~df["trip_status"].isin(["stationary", "pause"]), helper_column] = (
+        df["trip_status"] == "start"
+    ).cumsum()
+
+    return df.groupby(["trip_id", helper_column])
+
+
+def _detect_partial_transport(
+    df: pd.DataFrame,
+    on: Column | str,
+    cut_points: dict[str, Any],
+    window: int | None = None,
+    name: str = "trip_mode",
+) -> pd.DataFrame:
+    if window:
+        df[on] = df[on].rolling(window=window, min_periods=1).mean()
+
+    # Extract max values from cut_points
+    bins = [-float("inf")]
+    bins += [cp["max"] for cp in cut_points["cut_points"]]
+
+    # Extract names from cut_points
+    labels = [cp["name"] for cp in cut_points["cut_points"]]
+
+    # Apply cut points
+    df[name] = pd.cut(df[on], bins=bins, labels=labels)
+
+    _set_trip_mode(df, name)
+
+    return df
+
+
+def detect_transportation(
+    df: pd.DataFrame,
+    crs: str,
+    cut_points: dict[str, Any],
+    *,
+    window: int | None = None,
+    name: str = Column.TRIP_MODE,
+    overwrite: bool = False,
+) -> pd.DataFrame:
+    columns_not_exists(df, [name], overwrite=overwrite)
+
+    required_column = cut_points["required_data"]
+    columns_exists(df, [Column.TRIP_ID, Column.TRIP_STATUS, required_column])
+
+    temp_df = df.copy()
+
+    if required_column == Column.SPEED:
+        temp_df = add_speed(temp_df, crs=crs, overwrite=True)
+
+    partials = _get_partial_trips(temp_df)
+    partials = partials.apply(
+        lambda x: _detect_partial_transport(
+            x, required_column, cut_points, window, name
+        ),
+        include_groups=False,
+    ).reset_index(level=[0, 1])
+
+    df = df.merge(partials[name], on=Column.DATETIME, how="left")
+
+    return df