ada.short.unified#

Classes#

`Dummy`	A dummy class for scoring actigraphic data using without any filtration.
`GenericUnified`	A class for scoring actigraphic data using using a custom filter, designed via scipy.iirdesign.
`UFA`	A class for scoring actigraphic data using Unified Filter Approach (for details see Biegański et al. 2026).

Functions#

matthews_corrcoef(psg, acti)

Module Contents#

class Dummy(threshold)[source]#

A dummy class for scoring actigraphic data using without any filtration.

threshold#

Threshold value separating sleep and wake.

Type:: float
Parameters:: threshold (float)

fit_threshold(acti_psg, thresholds=(0.001, 0.03), n_thresholds=1000, full_data=False)#

Fit a threshold that is maximazing mean correlation between PSG scorings and actigraphic scorings.

Parameters:

acti_psg (list[ActiPSG]) – List of objects containing actigraphic data and PSG sleep/wake scorings.
thresholds (Tuple[float, float], optional) – Range of thresholds to fit. Defaults to (.001, .03).
n_thresholds (int, optional) – Number of thresholds to fit. Defaults to 1000.
full_data (bool, optional) – If True, list with all correlations will be returned. If False, the maximal correlation will be returned. Defaults to False.

Returns:

List of all correlations (with corresponding thresholds) or maximal correlation.

Return type:

float | list[Tuple[float, float]]

to_score(acti_data)[source]#

Apply scoring algorithm to the input data.

Parameters:: acti_data (_Epoched | GenericData | _Raw) – Epoched data to be scored by the algorithm. Scoring by unified filter does not require previous epoching.
Returns:: Object containng scored data.
Return type:: ScoredShort

transmittance(n_points=2048, db=True, fs=1 / 30)#

Transmittance of filter used in the algorithm.

Parameters:

n_points (int, optional) – Number of point at which filter will be evaluated. Defaults to 2048.
db (bool, optional) – Whether to return in dB scale. Defaults to True.
fs (float, optional) – Sampling frequency for which transmittance will be created.

Returns:

Vector of frequencies and vector of frequency responses.

Return type:

Tuple[np.ndarray, np.ndarray]

property filter: list[dict]#

Characteristics of the filters used by scoring algorithm.

Return type:: list[dict]

property scoring_method_metadata: dict#

Metadata asssociated with the scoring algorithm and its parameters.

Return type:: dict

class GenericUnified(threshold, wp, ws, gpass, gstop, analog=False, ftype='ellip')[source]#

A class for scoring actigraphic data using using a custom filter, designed via scipy.iirdesign.

threshold#

Threshold value separating sleep and wake.

Type:

float

Parameters:

threshold (float)
wp (float | tuple[float, float])
ws (float | tuple[float, float])
gpass (float)
gstop (float)
analog (bool)
ftype (str)

wp, ws

Passband and stopband edge frequencies. Possible values are scalars (for lowpass and highpass filters) or ranges (for bandpass and bandstop filters). For digital filters, these are in the same units as fs. By default, fs is 2 half-cycles/sample, so these are normalized from 0 to 1, where 1 is the Nyquist frequency.

Type:

float | tuple[float, float]

Parameters:

threshold (float)
wp (float | tuple[float, float])
ws (float | tuple[float, float])
gpass (float)
gstop (float)
analog (bool)
ftype (str)

gpass#

The maximum loss in the passband (dB).

Type:

float

Parameters:

threshold (float)
wp (float | tuple[float, float])
ws (float | tuple[float, float])
gpass (float)
gstop (float)
analog (bool)
ftype (str)

gstop#

The minimum attenuation in the stopband (dB).

Type:

float

Parameters:

threshold (float)
wp (float | tuple[float, float])
ws (float | tuple[float, float])
gpass (float)
gstop (float)
analog (bool)
ftype (str)

analog#

When True, return an analog filter, otherwise a digital filter is returned. Defaults to False.

Type:

bool

Parameters:

threshold (float)
wp (float | tuple[float, float])
ws (float | tuple[float, float])
gpass (float)
gstop (float)
analog (bool)
ftype (str)

ftype#

The type of IIR filter to design.

Type:

str

Parameters:

threshold (float)
wp (float | tuple[float, float])
ws (float | tuple[float, float])
gpass (float)
gstop (float)
analog (bool)
ftype (str)

add_filter(wp, ws, gpass, gstop, analog=False, ftype='ellip')[source]#

Add filter to the filter algorithm. Data will be filtered using all the filters provided.

Parameters:

wp (float | tuple[float, float]) – Passband edge frequency.
ws (float | tuple[float, float]) – Stopband edge frequency.
gpass (float) – The maximum loss in the passband (dB).
gstop (float) – The minimum attenuation in the stopband (dB)/
analog (bool, optional) – When True, return an analog filter, otherwise a digital filter is returned. Defaults to False.
ftype (str, optional) – The type of IIR filter to design. Defaults to ‘ellip’.

fit_threshold(acti_psg, thresholds=(0.001, 0.03), n_thresholds=1000, full_data=False)#

Fit a threshold that is maximazing mean correlation between PSG scorings and actigraphic scorings.

Parameters:

acti_psg (list[ActiPSG]) – List of objects containing actigraphic data and PSG sleep/wake scorings.
thresholds (Tuple[float, float], optional) – Range of thresholds to fit. Defaults to (.001, .03).
n_thresholds (int, optional) – Number of thresholds to fit. Defaults to 1000.
full_data (bool, optional) – If True, list with all correlations will be returned. If False, the maximal correlation will be returned. Defaults to False.

Returns:

List of all correlations (with corresponding thresholds) or maximal correlation.

Return type:

float | list[Tuple[float, float]]

to_score(acti_data)#

Apply scoring algorithm to the input data.

Parameters:: acti_data (_Epoched | GenericData | _Raw) – Epoched data to be scored by the algorithm. Scoring by unified filter does not require previous epoching.
Returns:: Object containng scored data.
Return type:: ScoredShort

transmittance(n_points=2048, db=True, fs=1 / 30)#

Transmittance of filter used in the algorithm.

Parameters:

n_points (int, optional) – Number of point at which filter will be evaluated. Defaults to 2048.
db (bool, optional) – Whether to return in dB scale. Defaults to True.
fs (float, optional) – Sampling frequency for which transmittance will be created.

Returns:

Vector of frequencies and vector of frequency responses.

Return type:

Tuple[np.ndarray, np.ndarray]

property filter: list[dict]#

Characteristics of the filters used by scoring algorithm.

Return type:: list[dict]

property scoring_method_metadata: dict#

Metadata asssociated with the scoring algorithm and its parameters.

Return type:: dict

class UFA(threshold=None)[source]#

A class for scoring actigraphic data using Unified Filter Approach (for details see Biegański et al. 2026).

threshold#

Threshold value separating sleep and wake. Autodetected based on input data if None. Defaults to None.

Type:: float | None = None
Parameters:: threshold (float | None)

fit_threshold(acti_psg, thresholds=(0.001, 0.03), n_thresholds=1000, full_data=False)#

Fit a threshold that is maximazing mean correlation between PSG scorings and actigraphic scorings.

Parameters:

acti_psg (list[ActiPSG]) – List of objects containing actigraphic data and PSG sleep/wake scorings.
thresholds (Tuple[float, float], optional) – Range of thresholds to fit. Defaults to (.001, .03).
n_thresholds (int, optional) – Number of thresholds to fit. Defaults to 1000.
full_data (bool, optional) – If True, list with all correlations will be returned. If False, the maximal correlation will be returned. Defaults to False.

Returns:

List of all correlations (with corresponding thresholds) or maximal correlation.

Return type:

float | list[Tuple[float, float]]

to_score(acti_data)#

Apply scoring algorithm to the input data.

Parameters:: acti_data (_Epoched | GenericData | _Raw) – Epoched data to be scored by the algorithm. Scoring by unified filter does not require previous epoching.
Returns:: Object containng scored data.
Return type:: ScoredShort

transmittance(n_points=2048, db=True, fs=1 / 30)#

Transmittance of filter used in the algorithm.

Parameters:

n_points (int, optional) – Number of point at which filter will be evaluated. Defaults to 2048.
db (bool, optional) – Whether to return in dB scale. Defaults to True.
fs (float, optional) – Sampling frequency for which transmittance will be created.

Returns:

Vector of frequencies and vector of frequency responses.

Return type:

Tuple[np.ndarray, np.ndarray]

property filter: list[dict]#

Characteristics of the filters used by scoring algorithm.

Return type:: list[dict]

property scoring_method_metadata: dict#

Metadata asssociated with the scoring algorithm and its parameters.

Return type:: dict

matthews_corrcoef(psg, acti)[source]#