Skip to content

Parsers

labda.parsers.Actigraph dataclass

Parses ActiGraph accelerometer data from binary and CSV formats.

This parser supports two distinct ActiGraph file types:

  1. .gt3x (Binary): High-frequency raw acceleration data.
  2. .csv (Export): Aggregated "epoch" data (counts), often containing derived metrics like steps or lux.

The parser automatically handles the manufacturer's proprietary header formats, timestamp decoding, and timezone conversion to UTC.

from_gt3x 

from_gt3x(
    path: Path | str,
    idle: Literal["ffill", "zero"] = "ffill",
) -> pd.DataFrame

Parses a raw binary .gt3x file.

Extracts x, y, z acceleration data. If the file contains timezone information, the datetime index is converted to UTC.

Parameters:

Name Type Description Default
path Path | str

Path to the .gt3x file.

 required
idle Literal['ffill', 'zero']

Strategy for handling samples flagged as "Idle Sleep Mode" by the device.

 'ffill'
`'ffill'` default

Preserves the raw values recorded by the device (often the last known value repeated).

 required
`'zero'`

Overwrites acceleration values with 0 during idle periods.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: Standardized raw accelerometer data.

from_csv 

from_csv(
    path: str | Path,
    datetime_format: str = "ISO8601",
    header_rows: int = 10,
) -> pd.DataFrame

Parses an ActiGraph CSV export (Epoch/Count data).

ActiGraph CSVs typically contain aggregated "counts" rather than raw acceleration. This method parses the metadata header to reconstruct the correct datetime index.

Parameters:

Name Type Description Default
path str | Path

Path to the .csv file.

 required
datetime_format str

Format string for parsing the header date/time. Defaults to "ISO8601".

 'ISO8601'
header_rows int

Number of header lines to skip before data begins. Defaults to 10 (standard ActiGraph export).

 10

Returns:

Type Description
DataFrame

pd.DataFrame: A DataFrame containing epoch-level data.

labda.parsers.Axivity dataclass

Parses Axivity .cwa files into a standardized DataFrame format.

This parser handles the binary reading of Axivity files (.cwa), extracting tri-axial acceleration and temperature data. It ensures the resulting data is properly indexed with datetimes and validated against corruption.

Attributes:

Name Type Description
timezone ZoneInfo | str | None

The timezone to which the resulting datetime index will be localized. If None (default), the index remains timezone-naive.

from_cwa 

from_cwa(path: Path | str) -> pd.DataFrame

Parses a .cwa file and returns a standardized accelerometer DataFrame.

This method wraps the skdh reader logic, adding specific validation checks for data corruption (negative timestamps) and normalizing column names to the package standard.

Parameters:

Name Type Description Default
path Path | str

The file system path to the .cwa file.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: Standardized accelerometer data.

labda.parsers.Sens dataclass

Parses proprietary 'Sens' binary accelerometer files.

This parser handles custom binary files containing 48-bit timestamps (milliseconds) and 16-bit Big-Endian accelerometer readings. It supports loading data from both physical files on disk and in-memory byte buffers.

Attributes:

Name Type Description
normalize bool

Controls data normalization. If True (default), converts raw integer counts to physical acceleration units (g) using the factor -4/512. If False, returns the raw sensor counts cast to float.

from_bin 

from_bin(path: str | Path) -> pd.DataFrame

Parses a Sens binary file from disk.

Parameters:

Name Type Description Default
path str | Path

The system path to the binary file.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: Standardized accelerometer data. Note: If self.normalize is True, units are g. Otherwise, units are raw ADC counts.

from_buffer 

from_buffer(buffer: bytes | bytearray) -> pd.DataFrame

Parses Sens binary data directly from an in-memory buffer.

Useful for processing data received over network streams or extracted from larger container files without writing to disk.

Parameters:

Name Type Description Default
buffer bytes | bytearray

The raw binary data.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: Standardized accelerometer data. See [FileParser][labda.parsers.Sens.from_buffer.parser.FileParser] for column specification.