UL Use Documentation#

uluse.py is a module containing different classes, and functions for quantifying the UL use construct - instantaneous and average use.

The current version of the module contains the following instantaneous UL use algorithms:

Vector magnitude from the Actigraph sensor (with and without hysterisis)
GMAC (Gross Movement + Activity Counts)

monalysa.ulfunc.uluse.average_uluse(usesig: array, windur: float, winshift: float, fs: float) → tuple[numpy.array, numpy.array]#

Computes the average upper-limb use from the given UL use signal. The current version only supports causal averaging.

Parameters:

usesig (np.array) – 1D numpy array of the UL use (binary) signal whose average is to be computed.
windur (float) – Duration in seconds over which the UL use signal is to be averaged.
winshift (float) – Time shift between two consecutive averaging windows.
fs (float) – Sampling frequency of the usesig signal.

Returns:

A tuple of 1D numpy arrays. The first 1D array is the list of time indices of the computed average UL use signal. The second 1D array is the average UL use signal.

Return type:

tuple[np.array, np.array]

monalysa.ulfunc.uluse.detector_with_hystersis(x: array, th: float, th_band: float) → array#

Implements a binary detector with hystersis.

Parameters:

x (np.array) – 1D numpy array containing the input signal.
th (float) – Upper threshold for the detector to output 1.
th_band (float) – Hystersis band for the detector. The output of the detector will be 1 as long as the input signal is greater than or equal to (th - th_band). If the input signal is less than (th - th_band), the output of the detector will be 0.

Returns:

1D numpy array containing the output of the detector.

Return type:

np.array

monalysa.ulfunc.uluse.estimate_accl_mag(accl: array, fs: float, fc: float = 0.01, nc: int = 2, nam: Optional[int] = None) → array#

Computes the magnitude of the accelerometer signal.

Parameters:

accl (np.array) – 2D numpy array containing the acceleration data with columns corresponding to different components (at most 3), and rows corresponding to sampling instants.
fs (float) – Sampling frequency of the acceleration data.
fc (float, default = 0.01) – Cutoff frequency for the highpass filter used for filtering the acceleration data.
nc (int, default = 2) – Order of the highpass filter used for filtering the acceleration data.
nam (int, default = fs / 2) – Number of samples to use for moving averaging. Must be a positive integer.

Returns:

1D numpy array containing the magnitude of the acceleration data.

Return type:

np.array

monalysa.ulfunc.uluse.estimate_accl_pitch(accl: array, fs: float, accl_farm_inx: int, elb_to_farm: bool, nwin: Optional[int] = None) → array#

Estimates the pitch angle of the forearm from the accelerometer data.

Parameters:

accl (np.array) – 2D numpy array containing the acceleration data with columns corresponding to different components (at most 3), and rows corresponding to sampling instants.
fs (float) – Sampling frequency of the acceleration data. Must be a positive number.
accl_farm_inx (int) – Index of the forearm component of the acceleration data. Must be an integer between 0 and the number of columns in accl.
elb_to_farm (bool) – Indicates if the axis points from the elbow to forearm, or the other way around.
nwin (int) – Number of samples to use for moving averaging. Must be a positive integer. Half of the sampling frequency is recommended.

Returns:

1D numpy array containing the pitch angle of the forearm estimated from the accelerometer data.

Return type:

np.array

monalysa.ulfunc.uluse.from_gmac(accl: array, fs: float, accl_farm_inx: int, elb_to_farm: bool, nwin: Optional[int] = None, fc: float = 0.01, nc: int = 2, nam: Optional[int] = None, p_th: float = 10, p_th_band: float = 40, am_th: float = 0.1, am_th_band: float = 0) → tuple[numpy.array, numpy.array, numpy.array, numpy.array]#

Computes UL use using the GMAC algorithm with pitch and acceleration magnitude estimated only from acceleration.

The current version computes UL use at every time instance. Future versions might include options for computing UL use are specificed regular intervals.

The default values of the parameters are the optimal values found for the generic (inter-subject, inter-limb) model for GMAC in the following paper: Balasubramanian, Sivakumar. “GMAC–A simple measure to quantify upper limb use from wrist-worn accelerometers.” IEEE Transactions on Neural Systems and Rehabilitation Engineering (2024).

Parameters:

accl (np.array) – 2D numpy array containing the acceleration data with columns corresponding to different components (at most 3), and rows corresponding to sampling instants.
fs (float) – Sampling frequency of the acceleration data. Must be a positive number.
accl_farm_inx (int) – Index of the forearm component of the acceleration data. Must be an integer between 0 and and the number of columns in accl.
elb_to_farm (bool) – Indicates if the axis points from the elbow to forearm, or the other way around.
nwin (int, default = fs) – Number of samples to use for moving averaging for estimating the pitch angle of the forearm. Must be a positive integer.
fc (float, default = 0.01) – Cutoff frequency for the highpass filter used for filtering the acceleration data. Must be a positive number.
nc (int, default = 2) – Order of the highpass filter used for filtering the acceleration data. Must be a positive integer.
nam (int, default = fs/2) – Number of samples to use for moving averaging for computing the magnitude of the acceleration. Must be a positive integer.
p_th (float, default = 10) – Upper threshold for the pitch angle in degrees.
p_th_band (float, default = 40) – Hystersis band for the pitch angle in degrees.
am_th (float, default = 0.1) – Upper threshold for the acceleration magnitude.
am_th_band (float, default = 0) – Hystersis band for the acceleration magnitude.

Returns:

A tuple of 1D numpy arrays. The first 1D array is the list of time indices of the computed UL use signal. The second 1D array is the UL use signal, which is a binary signal indicating the presence or absence of a “functional” movement any time instant. The third and fourth 1D arrays are the pitch angle and acceleration magnitude estimated from the acceleration data, respectively.

Return type:

tuple[np.array, np.array, np.array, np.array]

monalysa.ulfunc.uluse.from_vec_mag(vecmag: array, thresh: float) → tuple[numpy.array, numpy.array]#

A single threshold based algorithm for computing UL use from activity counts.

The current version computes UL use at every time instance. Future versions might include options for computing UL use are specificed regular intervals.

Parameters:

vecmag (np.array) – 1D numpy array containing the activity counts time series.
thresh (float) – Threshold for generating the binary UL use output time series.

Returns:

Return type:

tuple[np.array, np.array]

monalysa.ulfunc.uluse.from_vec_mag_dblth(vecmag: array, thresh_l: float, thresh_h: float) → tuple[numpy.array, numpy.array]#

A hysteresis based based algorithm for computing UL use from activity counts.

The current version computes UL use at every time instance. Future versions might include options for computing UL use are specificed regular intervals.

Note: Since this method requires information about the past value of UL use, you must ensure that the activity counts input is from a continuous time segment.

Parameters:

vecmag (np.array) – 1D numpy array containing the activity counts time series.
thresh_l (float) – Low threshold below which UL use signal is 0.
thresh_h (float) – High threshold above which UL use signal is 1.

Returns:

A tuple of 1D numpy arrays. The first 1D array is the list of time indices of the computed UL use signal. The second ID array is the UL use signal, which is a binary signal indicating the presence or absence of a “functional” movement any time instant.

Return type:

tuple[np.array, np.array]