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. Returns a pandas.DataFrame with the processed data and a dict with processing info.

Parameters

  • input_file (str) – Path to accelerometer file.

  • lowpass_hz (int, optional) – Cutoff (Hz) for low-pass filter. Defaults to 20. Pass None or False to disable.

  • calibrate_gravity (bool, optional) – Whether to perform gravity calibration. Defaults to True.

  • detect_nonwear (bool, optional) – Whether to perform non-wear detection. Defaults to True.

  • resample_hz (str or int, optional) – Target frequency (Hz) to resample the signal. If “uniform”, use the implied frequency (use this option to fix any device sampling errors). Pass None to disable. Defaults to “uniform”.

  • start_time (str or datetime, optional) – Start time to read data. Pass None to read from the beginning. Defaults to None.

  • end_time (str or datetime, optional) – End time to read data. 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. Defaults to False.

  • calibrate_gravity_kwargs (dict, optional) – Additional keyword arguments to pass to calibrate_gravity function. Defaults to None.

  • flag_nonwear_kwargs (dict, optional) – Additional keyword arguments to pass to flag_nonwear function. Defaults to None.

  • verbose (bool, optional) – Verbosity, defaults to True.

Returns

Processed data and processing info.

Return type

(pandas.DataFrame, dict)

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)

Process a pandas.DataFrame of acceleration time-series. Returns a pandas.DataFrame with the processed data and a dict with processing info.

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.

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

  • lowpass_hz (int, optional) – Cutoff (Hz) for low-pass filter. Defaults to 20. Pass None or False to disable.

  • calibrate_gravity (bool, optional) – Whether to perform gravity calibration. Defaults to True.

  • detect_nonwear (bool, optional) – Whether to perform non-wear detection. Defaults to True.

  • resample_hz (str or int, optional) – Target frequency (Hz) to resample the signal. If “uniform”, use the implied frequency (use this option to fix any device sampling errors). Pass None to disable. Defaults to “uniform”.

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

  • calibrate_gravity_kwargs (dict, optional) – Additional keyword arguments to pass to calibrate_gravity function. Defaults to None.

  • flag_nonwear_kwargs (dict, optional) – Additional keyword arguments to pass to flag_nonwear function. Defaults to None.

  • verbose (bool, optional) – Verbosity, defaults to True.

Returns

Processed data and processing info.

Return type

(pandas.DataFrame, dict)

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)