API reference

actipy.read_device(input_file, lowpass_hz=20, calibrate_gravity=True, detect_nonwear=True, resample_hz='uniform', start_time=None, end_time=None, skipdays=0, cutdays=0, start_first_complete_minute=False, calibrate_gravity_kwargs=None, flag_nonwear_kwargs=None, verbose=True)

Read and process accelerometer device file.

This is the main entry point for reading device files. It performs the full processing pipeline: file parsing, quality control, lowpass filtering, gravity calibration, nonwear detection, and resampling.

Parameters

  • input_file (str) – Path to accelerometer file (.cwa, .gt3x, .bin). Compressed files (.gz, .zip) are automatically decompressed.

  • lowpass_hz (int or False, optional) – Cutoff frequency (Hz) for Butterworth lowpass filter. Defaults to 20 Hz. Pass None or False to disable filtering.

  • calibrate_gravity (bool, optional) – Whether to perform gravity calibration using the method of van Hees et al. 2014. Defaults to True.

  • detect_nonwear (bool, optional) – Whether to detect and flag non-wear periods (long stationary periods). Defaults to True.

  • resample_hz (str or int or False, optional) – Target frequency (Hz) to resample the signal. If “uniform”, uses the device’s sample rate to fix sampling errors. Pass None or False to disable. Defaults to “uniform”.

  • start_time (str or datetime, optional) – Start time to read data (ISO format: “YYYY-MM-DD HH:MM:SS”). Pass None to read from the beginning. Defaults to None.

  • end_time (str or datetime, optional) – End time to read data (ISO format: “YYYY-MM-DD HH:MM:SS”). Pass None to read until the end. Defaults to None.

  • skipdays (int, optional) – Number of days to skip from the beginning. Defaults to 0.

  • cutdays (int, optional) – Number of days to cut from the end. Defaults to 0.

  • start_first_complete_minute (bool, optional) – Whether to start data from the first complete minute (with 1 second tolerance). Useful for aligning data to minute boundaries. Defaults to False.

  • calibrate_gravity_kwargs (dict, optional) – Additional keyword arguments for the calibrate_gravity function (e.g., {‘stdtol_min’: 0.01}). Defaults to None.

  • flag_nonwear_kwargs (dict, optional) – Additional keyword arguments for the flag_nonwear function (e.g., {‘patience’: ‘60m’}). Defaults to None.

  • verbose (bool, optional) – Print progress messages. Defaults to True.

Returns

A tuple (data, info) where:

  • data (pandas.DataFrame): Processed acceleration time-series with DateTimeIndex and columns for x, y, z acceleration (in g), plus optional temperature and light data depending on device type.

  • info (dict): Processing metadata including device information, quality metrics, calibration results, and processing parameters. See GLOSSARY.md for complete field descriptions.

Return type

tuple(pandas.DataFrame, dict)

Basic usage with default processing:

>>> import actipy
>>> data, info = actipy.read_device("sample.cwa.gz")
>>> print(data.head())
                             x         y         z  temperature    light
time
2014-05-07 13:29:50.430 -0.514     0.070     1.672        20.0    78.42
2014-05-07 13:29:50.440 -0.234    -0.587     0.082        20.0    78.42
...

With custom processing options:

>>> data, info = actipy.read_device(
...     "sample.cwa.gz",
...     lowpass_hz=20,
...     calibrate_gravity=True,
...     detect_nonwear=True,
...     resample_hz=50
... )

Time filtering and alignment:

>>> data, info = actipy.read_device(
...     "sample.cwa.gz",
...     start_time="2014-05-07 18:00:00",
...     end_time="2014-05-09 18:00:00",
...     skipdays=1,
...     cutdays=2,
...     start_first_complete_minute=True
... )

Custom calibration parameters:

>>> data, info = actipy.read_device(
...     "sample.cwa.gz",
...     calibrate_gravity=True,
...     calibrate_gravity_kwargs={'stdtol_min': 0.01, 'calib_cube': 0.5}
... )

process : Apply processing pipeline to existing DataFrame actipy.processing : Individual processing functions for fine-grained control

  • Supported formats: Axivity (.cwa), Actigraph (.gt3x), GENEActiv (.bin), Matrix (.bin)

  • Processing is memory-efficient using chunked operations for large files

  • The info dict is progressively updated as each processing step completes

  • Non-wear periods are set to NaN if detect_nonwear=True

actipy.process(data, sample_rate, lowpass_hz=20, calibrate_gravity=True, detect_nonwear=True, resample_hz='uniform', start_first_complete_minute=False, calibrate_gravity_kwargs=None, flag_nonwear_kwargs=None, verbose=True)

Apply processing pipeline to acceleration time-series DataFrame.

This function applies the same processing steps as read_device() but to an existing pandas DataFrame. Useful for processing custom CSV files or data from sources not directly supported by read_device().

Parameters

  • data (pandas.DataFrame) – A pandas.DataFrame of acceleration time-series. Must contain at least columns ‘x’, ‘y’, ‘z’ (acceleration in g) and the index must be a DateTimeIndex.

  • sample_rate (int or float) – The data’s sample rate in Hz.

  • lowpass_hz (int or False, optional) – Cutoff frequency (Hz) for Butterworth lowpass filter. Defaults to 20 Hz. Pass None or False to disable filtering.

  • calibrate_gravity (bool, optional) – Whether to perform gravity calibration using the method of van Hees et al. 2014. Defaults to True.

  • detect_nonwear (bool, optional) – Whether to detect and flag non-wear periods (long stationary periods). Defaults to True.

  • resample_hz (str or int or False, optional) – Target frequency (Hz) to resample the signal. If “uniform”, uses the provided sample_rate to fix sampling errors. Pass None or False to disable. Defaults to “uniform”.

  • start_first_complete_minute (bool, optional) – Whether to start data from the first complete minute (with 1 second tolerance). Useful for aligning data to minute boundaries. Defaults to False.

  • calibrate_gravity_kwargs (dict, optional) – Additional keyword arguments for the calibrate_gravity function (e.g., {‘stdtol_min’: 0.01}). Defaults to None.

  • flag_nonwear_kwargs (dict, optional) – Additional keyword arguments for the flag_nonwear function (e.g., {‘patience’: ‘60m’}). Defaults to None.

  • verbose (bool, optional) – Print progress messages. Defaults to True.

Returns

A tuple (data, info) where:

  • data (pandas.DataFrame): Processed acceleration time-series

  • info (dict): Processing metadata. See GLOSSARY.md for field descriptions.

Return type

tuple(pandas.DataFrame, dict)

Process a CSV file:

>>> import pandas as pd
>>> import actipy
>>> data = pd.read_csv("custom_data.csv", parse_dates=['time'], index_col='time')
>>> data, info = actipy.process(data, sample_rate=100)

Apply specific processing steps:

>>> data, info = actipy.process(
...     data,
...     sample_rate=100,
...     lowpass_hz=20,
...     calibrate_gravity=True,
...     detect_nonwear=False,
...     resample_hz=50
... )

read_device : Read and process device file in one step actipy.processing : Individual processing functions for more control

  • Input data must have DateTimeIndex and columns ‘x’, ‘y’, ‘z’

  • Optional columns ‘temperature’, ‘light’ are preserved if present

  • Processing is memory-efficient using chunked operations

actipy.processing.quality_control(data, sample_rate)

Perform basic quality control on the provided data.

This function performs the following tasks: 1. Returns a dictionary with general information about the data. 2. Checks for non-increasing timestamps and corrects them if necessary, returning the corrected data.

Parameters

  • data (pandas.DataFrame) – A pandas.DataFrame of acceleration time-series. The index must be a DateTimeIndex.

  • sample_rate (int or float) – Target sample rate (Hz) to achieve.

Returns

A tuple containing the processed data and a dictionary with general information about the data. The dictionary contains the following:

  • NumTicks: Total number of ticks (samples) in the data.

  • StartTime: First timestamp of the data.

  • EndTime: Last timestamp of the data.

  • WearTime(days): Total wear time, in days. This is simply the total duration of valid (non-NaN) data and does not account for potential nonwear segments. See find_nonwear_segments and flag_nonwear to find and flag nonwear segments in the data.

  • DataSpan(days): Time span of the data (difference between last and first timestamps).

  • NumInterrupts: The number of interruptions in the data (gaps or NaNs between samples).

  • ReadErrors: The number of data errors (if non-increasing timestamps are found).

  • Covers24hOK: Whether the data covers all 24 hours of the day.

Return type

(pandas.DataFrame, dict)

actipy.processing.lowpass(data, data_sample_rate, cutoff_rate=20, chunksize=1000000)

Apply Butterworth low-pass filter.

Parameters

  • data (pandas.DataFrame.) – A pandas.DataFrame of acceleration time-series. The index must be a DateTimeIndex.

  • data_sample_rate (int or float) – The data’s original sample rate.

  • cutoff_rate (int, optional) – Cutoff (Hz) for low-pass filter. Defaults to 20.

  • chunksize (int, optional) – Chunk size for chunked processing. Defaults to 1_000_000 rows.

Returns

Processed data and processing info.

Return type

(pandas.DataFrame, dict)

actipy.processing.calibrate_gravity(data, calib_cube=0.3, calib_min_samples=50, window='10s', stdtol=0.015, stdtol_min=None, return_coeffs=True, chunksize=1000000)

Gravity calibration method of van Hees et al. 2014 (https://pubmed.ncbi.nlm.nih.gov/25103964/)

Parameters

  • data (pandas.DataFrame.) – A pandas.DataFrame of acceleration time-series. It must contain at least columns x,y,z and the index must be a DateTimeIndex.

  • calib_cube (float, optional.) – Calibration cube criteria. See van Hees et al. 2014 for details. Defaults to 0.3.

  • calib_min_samples (int, optional.) – Minimum number of stationary samples required to run calibration. Defaults to 50.

  • window (str, optional) – Rolling window to use to check for stationary periods. Defaults to 10 seconds (“10s”).

  • stdtol (float, optional) – Standard deviation under which a window is considered stationary. Defaults to 15 milligravity (0.015).

  • stdtol_min (float, optional) – Minimum standard deviation above which a window is considered valid. Defaults to None (no filtering).

  • chunksize (int, optional) – Chunk size for chunked processing. Defaults to 1_000_000 rows.

Returns

Processed data and processing info.

Return type

(pandas.DataFrame, dict)

actipy.processing.flag_nonwear(data, patience='90m', window='10s', stdtol=0.015)

Flag nonwear episodes in the data by setting them to NA. Non-wear episodes are inferred from long periods of no movement.

Parameters

  • data (pandas.DataFrame.) – A pandas.DataFrame of acceleration time-series. The index must be a DateTimeIndex.

  • patience (str, optional) – The minimum duration that a stationary episode must have to be classified as non-wear episode. Defaults to 90 minutes (“90m”).

  • window (str, optional) – Rolling window to use to check for stationary periods. Defaults to 10 seconds (“10s”).

  • stdtol (float, optional) – Standard deviation under which the window is considered stationary. Defaults to 15 milligravity (0.015).

Returns

Processed data and processing info.

Return type

(pandas.DataFrame, dict)

actipy.processing.find_nonwear_segments(data, patience='90m', window='10s', stdtol=0.015)

Find nonwear episodes based on long periods of no movement.

Parameters

  • data (pandas.DataFrame.) – A pandas.DataFrame of acceleration time-series. The index must be a DateTimeIndex.

  • patience (str, optional) – The minimum duration that a stationary episode must have to be classified as non-wear episode. Defaults to 90 minutes (“90m”).

  • window (str, optional) – Rolling window to use to check for stationary periods. Defaults to 10 seconds (“10s”).

  • stdtol (float, optional) – Standard deviation under which the window is considered stationary. Defaults to 15 milligravity (0.015).

Returns

A Series where the DatetimeIndex indicates the start times of each non-wear segment and the values are the length of each segment, in timedelta64[ns].

Return type

pandas.Series

actipy.processing.resample(data, sample_rate, dropna=False, start_first_complete_minute=False, chunksize=1000000)

Nearest neighbor resampling. For downsampling, it is recommended to first apply an antialiasing filter (e.g. a low-pass filter, see lowpass).

Parameters

  • data (pandas.DataFrame.) – A pandas.DataFrame of acceleration time-series. The index must be a DateTimeIndex.

  • sample_rate (int or float) – Target sample rate (Hz) to achieve.

  • dropna (bool, optional) – Whether to drop NaN values after resampling. Defaults to False.

  • start_first_complete_minute (bool, optional) – Whether to start data from the first complete minute. Uses 1 second tolerance - if within 1 second of minute boundary, uses that minute, otherwise advances to next minute. Defaults to False.

  • chunksize (int, optional) – Chunk size for chunked processing. Defaults to 1_000_000 rows.

Returns

Processed data and processing info.

Return type

(pandas.DataFrame, dict)