as_mask

openseize.file_io.annotations.as_mask(annotations, size, fs, include=True)

Creates a boolean mask from a sequence of annotation dataclass instances..

Producers of EEG data may receive an optional boolean array mask. This function creates a boolean mask from a sequence of annotations and is therefore useful for filtering EEG data by annotation label during processing.

Parameters:

Name	Type	Description	Default
annotations	Sequence[Annotation]	A sequence of annotation dataclass instances to convert to a mask.	required
size	int	The length of the boolean array to return.	required
fs	float	The sampling rate in Hz of the digital system.	required
include	bool	Boolean determining if annotations should be set to True or False in the returned array. True means all values are False in the returned array except for samples where the annotations are located.	True

Returns:

Type	Description
npt.NDArray[np.bool_]	A 1-D boolean array of length size.

Examples:

>>> # read the annotations from the demo annotation file
>>> from openseize.demos import paths
>>> filepath = paths.locate('annotations_001.txt')
>>> from openseize.io.annotations import Pinnacle
>>> # read the 'rest' annotations
>>> with Pinnacle(filepath, start=6) as pinnacle:
>>>     annotations = pinnacle.read(labels=['rest'])
>>> # create a mask measuring 3700 secs at 5000 Hz
>>> mask = as_mask(annotations, size=3700*5000, fs=5000)
>>> # measure the total time in secs of 'rest' annotation
>>> print(np.count_nonzero(mask) / 5000)
15.0

Source code in openseize/file_io/annotations.py

def as_mask(annotations: Sequence[Annotation],
            size: int,
            fs: float,
            include: bool = True,
) -> npt.NDArray[np.bool_]:
    """Creates a boolean mask from a sequence of annotation dataclass
    instances..

    Producers of EEG data may receive an optional boolean array mask.  This
    function creates a boolean mask from a sequence of annotations and is
    therefore useful for filtering EEG data by annotation label during
    processing.

    Args:
        annotations:
            A sequence of annotation dataclass instances to convert to a 
            mask.
        size:
            The length of the boolean array to return.
        fs:
            The sampling rate in Hz of the digital system.
        include:
            Boolean determining if annotations should be set to True or
            False in the returned array. True means all values
            are False in the returned array except for samples where the
            annotations are located.

    Returns:
        A 1-D boolean array of length size.

    Examples:
        >>> # read the annotations from the demo annotation file
        >>> from openseize.demos import paths
        >>> filepath = paths.locate('annotations_001.txt')
        >>> from openseize.io.annotations import Pinnacle
        >>> # read the 'rest' annotations
        >>> with Pinnacle(filepath, start=6) as pinnacle:
        >>>     annotations = pinnacle.read(labels=['rest'])
        >>> # create a mask measuring 3700 secs at 5000 Hz
        >>> mask = as_mask(annotations, size=3700*5000, fs=5000)
        >>> # measure the total time in secs of 'rest' annotation
        >>> print(np.count_nonzero(mask) / 5000)
        15.0
    """

    epochs = [(ann.time, ann.time + ann.duration) for ann in annotations]
    samples = np.round(np.array(epochs) * fs).astype(int)
    slices = [slice(*pts) for pts in samples]
    result = arraytools.filter1D(size, slices)
    result = result if include else ~result
    return cast(np.ndarray, result)

openseize.file_io.bases.Annotation dataclass

An object for storing a predefined set of annotation attributes that can be updated with user defined attributes after object creation.

Attributes:

Name	Type	Description
label	str	The string name of this annotation.
time	float	The time this annotation was made in seconds relative to the recording start.
duration	float	The duration of this annotation in seconds.
channel	Any	The string name or integer index of the channel this annotation created from.

Source code in openseize/file_io/bases.py

@dataclass
class Annotation:
    """An object for storing a predefined set of annotation attributes that
    can be updated with user defined attributes after object creation.

    Attributes:
        label (str):
            The string name of this annotation.
        time (float):
            The time this annotation was made in seconds relative to the
            recording start.
        duration (float):
            The duration of this annotation in seconds.
        channel (Any):
            The string name or integer index of the channel this annotation
            created from.
    """

    label: str
    time: float
    duration: float
    channel: typing.Any