ada.short.unified — ADA 1.0.3 documentation

Skip to main content
`Ctrl`+`K`

# 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)

  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)

    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')

  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')

    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)

  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)