vitabel.timeseries ================== .. py:module:: vitabel.timeseries .. autoapi-nested-parse:: Module holding data structures for (annotated) time series data. .. !! processed by numpydoc !! Attributes ---------- .. autoapisummary:: vitabel.timeseries.logger Classes ------- .. autoapisummary:: vitabel.timeseries.TimeSeriesBase vitabel.timeseries.Channel vitabel.timeseries.Label vitabel.timeseries.IntervalLabel vitabel.timeseries.TimeDataCollection Module Contents --------------- .. py:data:: logger :type: logging.Logger Global package logger. .. !! processed by numpydoc !! .. py:class:: TimeSeriesBase(time_index: numpy.typing.ArrayLike[vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str], time_start: vitabel.typing.Timestamp | None = None, time_unit: str | None = None, offset: vitabel.typing.Timedelta | float | None = None) Base class for time series data. Time data in this class can represent both absolute and relative time. :Parameters: **time_index** The time data. Can be a list of timestamps, timedeltas, numeric values (for which a unit needs to be specified), or datetime strings (which will be parsed by ``pandas``). **time_start** If the specified ``time_index`` holds relative time data (timedeltas or numeric values), this parameter can be used to set an absolute reference time (a timestamp). **time_unit** The unit of the time data as a string. Used for the conversion from numeric values. Defaults to seconds (``"s"``). **offset** An additional time offset specified as a timedelta or a numeric value (which is taken with respect to the given time unit). The offset is applied to :attr:`time_index`, but when the data is exported, the offset is removed (and exported separately). .. !! processed by numpydoc !! .. py:attribute:: time_index :type: pandas.TimedeltaIndex The time data (with the specified offset applied), always stored in relative time. .. !! processed by numpydoc !! .. py:attribute:: time_start :type: vitabel.typing.Timestamp | None If the data of the time series is absolute, this holds the reference time. This is ``None`` for relative time series. .. !! processed by numpydoc !! .. py:attribute:: time_unit :type: str The unit of the time data. .. !! processed by numpydoc !! .. py:property:: offset :type: vitabel.typing.Timedelta The offset applied to the time data. .. !! processed by numpydoc !! .. py:property:: first_entry :type: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None The first (and earliest) entry in the time index of this series. .. !! processed by numpydoc !! .. py:property:: last_entry :type: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None The last (and latest) entry in the time index of this series. .. !! processed by numpydoc !! .. py:method:: is_empty() -> bool Return whether the time data is empty. .. !! processed by numpydoc !! .. py:method:: is_time_relative() -> bool Return whether the time data is relative. .. !! processed by numpydoc !! .. py:method:: is_time_absolute() -> bool Return whether the time data is absolute. .. !! processed by numpydoc !! .. py:method:: numeric_time(time_unit: str | None = None) -> numpy.typing.NDArray Return the relative time data as numeric values. :Parameters: **time_unit** The unit of the time data as a string. If not specified, the unit of the time data at initialization is used. .. !! processed by numpydoc !! .. py:method:: shift_time_index(delta_t: pandas.Timedelta | float, time_unit: str | None = None) Shift the time index by a given time delta. :Parameters: **delta_t** The time delta to shift the time index by. .. !! processed by numpydoc !! .. py:method:: convert_time_input(time_input: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str) Convert a given time input to either a timedelta or a timestamp, whatever is compatible with the time format of this channel. :Parameters: **time_input** The time input to convert. If the channel time is absolute, the input is converted to a timestamp. If it is relative, the input is converted to a timedelta, if possible. .. !! processed by numpydoc !! .. py:method:: get_time_mask(start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, resolution: vitabel.typing.Timedelta | float | str | None = None, include_adjacent: bool = False) Return a boolean mask for the time index. :Parameters: **start** The start time for the mask. If not specified, the mask starts from the beginning. **stop** The stop time for the mask. If not specified, the mask ends at the last time point. **resolution** The resolution for the mask. If specified, the mask is downsampled, by keeping every n-th data point, where n is resolution/ (mean time difference in time_index) Assumes that the time index is sorted. **include_adjacent** If ``True``, the mask includes the time points that are adjacent to (but outside of) the start and stop times; useful for plotting. Defaults to ``False``. .. !! processed by numpydoc !! .. py:method:: scale_time_index(scale_factor: float, reference_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> Self Scale the time index by a given factor while keeping a given reference time fixed. :Parameters: **scale_factor** The factor to scale the time index by. **reference_time** If specified, the time index is scaled with respect to this reference time. If not specified, the time index is scaled relative to the start of the time index. .. !! processed by numpydoc !! .. py:class:: Channel(name: str, time_index: numpy.typing.ArrayLike[pandas.Timestamp | numpy.datetime64 | pandas.Timedelta | numpy.timedelta64 | float | str], data: numpy.typing.ArrayLike[float | numpy.number] | None = None, time_start: pandas.Timestamp | None = None, time_unit: str | None = None, offset: pandas.Timedelta | float | None = None, plotstyle: dict[str, Any] | None = None, metadata: dict[str, Any] | None = None) Bases: :py:obj:`TimeSeriesBase` A time data channel, holding a time series and optional data points. :Parameters: **name** The name of the channel. **time_index** The time data of the channel. Can be a list of timestamps, timedeltas, numeric values (interpreted with respect to the specified time unit), or datetime strings (which will be parsed by ``pandas``). **data** The data points of the channel. If not specified, the channel only holds time data. If specified, the length of the data must match the length of the time index. **time_start** If the specified ``time_index`` holds relative time data (timedeltas or numeric values), this parameter can be used to set an absolute reference time (a timestamp). **time_unit** The unit of the time data as a string. **offset** An additional time offset specified as a timedelta or a numeric value (which is taken with respect to the given time unit). The offset is applied to :attr:`time_index`, but when the data is exported, the offset is removed (and exported separately). **plotstyle** A dictionary of key/value pairs that are passed to ``matplotlib.pyplot.plot`` when plotting channel data. **metadata** A dictionary that can be used to store additional information about the channel. .. !! processed by numpydoc !! .. py:attribute:: name :value: '' The name of the channel. .. !! processed by numpydoc !! .. py:attribute:: labels :value: [] The :class:`Labels <.Label>` attached to the channel. .. !! processed by numpydoc !! .. py:attribute:: data :type: numpy.typing.ArrayLike[float | numpy.number] | None :value: None The data points of the channel, if any. .. !! processed by numpydoc !! .. py:attribute:: plotstyle Keyword arguments passed to the plotting routine. .. !! processed by numpydoc !! .. py:attribute:: metadata Additional channel metadata. .. !! processed by numpydoc !! .. py:method:: data_hash() -> str Return a hash representing the data and the metadata of this channel. .. !! processed by numpydoc !! .. py:method:: attach_label(label: Label) Attach a label to this channel. Modifications to the channel offset also modify the offset of the attached labels. :Parameters: **label** The label to attach. .. !! processed by numpydoc !! .. py:method:: detach_label(label: Label) Detach a label from this channel. .. note:: This method only removes the reference from the channel to the label, as well as the backreference from the label to the channel. While this does not delete the label object itself, the responsibility to manage the label object is with the user. :Parameters: **label** The label to detach. .. !! processed by numpydoc !! .. py:method:: shift_time_index(delta_t: pandas.Timedelta | float, time_unit: str | None = None) Shift the time index by a given time delta. :Parameters: **delta_t** The time delta to shift the time index by. .. !! processed by numpydoc !! .. py:method:: truncate(start_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> Channel Return a new channel that is a truncated version of this channel. :Parameters: **start_time** The start time for the truncated channel. **stop_time** The stop time for the truncated channel. .. !! processed by numpydoc !! .. py:method:: to_dict() -> dict[str, Any] Construct a serializable dictionary that represents this channel. .. !! processed by numpydoc !! .. py:method:: to_csv(filename: str | pathlib.Path | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> None Export the channel data to a CSV file. :Parameters: **filename** The name of the file to export the data to. If not specified, the data is exported to a file with the name of the channel. **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. .. !! processed by numpydoc !! .. py:method:: from_dict(datadict: dict[str, Any]) -> Channel :classmethod: Create a channel from a dictionary representation. .. !! processed by numpydoc !! .. py:method:: is_time_only() -> bool Return whether the channel contains only time data. .. !! processed by numpydoc !! .. py:method:: get_data(start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, resolution: vitabel.typing.Timedelta | float | str | None = None, include_adjacent: bool = False) -> vitabel.typing.DataSlice Return a tuple of time and data values with optional filtering and downsampling. :Parameters: **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. **resolution** The resolution for the data. If specified, the data is downsampled such that the difference between time points of the downsampled data is bounded below by the given resolution. Assumes that the time index is sorted. **include_adjacent** If ``True``, the returned data also includes the time points that are adjacent to (but outside of) the start and stop times; useful for plotting. Defaults to ``False``. .. !! processed by numpydoc !! .. py:method:: plot(plot_axes: matplotlib.pyplot.Axes | None = None, plotstyle: dict[str, Any] | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, resolution: vitabel.typing.Timedelta | float | None = None, time_unit: str | None = None, reference_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None) Plot the channel data on a given axis. :Parameters: **plot_axes** The (matplotlib) axes to plot the data on. If not specified, a new figure will be created. **plotstyle** Overrides for the :attr:`plotstyle` of the channel. **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. **resolution** The resolution for the data. If specified, the data is downsampled such that the median time difference is bounded below by the given resolution. See :meth:`.get_data`. **time_unit** The time unit values used along the x-axis. If ``None`` (the default), the time unit of the channel is used. .. !! processed by numpydoc !! .. py:method:: rename(new_name: str) Change the name of the channel. :Parameters: **new_name** The new name of the channel. .. !! processed by numpydoc !! .. py:class:: Label(name: str, time_index: numpy.typing.ArrayLike[vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str] | None = None, data: numpy.typing.ArrayLike[float | numpy.number] | None = None, text_data: numpy.typing.ArrayLike[str | None] | None = None, time_start: vitabel.typing.Timestamp | None = None, time_unit: str | None = None, offset: vitabel.typing.Timedelta | float | None = None, anchored_channel: Channel | None = None, plotstyle: dict[str, Any] | None = None, metadata: dict[str, Any] | None = None, plot_type: vitabel.typing.LabelPlotType = 'combined', vline_text_source: vitabel.typing.LabelPlotVLineTextSource = 'text_data', annotation_preset_type: vitabel.typing.LabelAnnotationPresetType | None = None) Bases: :py:obj:`TimeSeriesBase` A time data label, holding a time series and optional data points. Where :class:`.Channel` is intended for data extracted from some external, immutable source (e.g., a sensor), :class:`.Label` is intended for data that is annotated or otherwise modified by the user. In particular, :class:`.Label` supports adding and removing data points via :meth:`.add_data` and :meth:`.remove_data`, respectively. :Parameters: **name** The name of the label. **time_index** The time data of the label. Can be a list of timestamps, timedeltas, numeric values (interpreted with respect to the specified time unit), or datetime strings (which will be parsed by ``pandas``). **data** The data points of the label. If not specified, the label only holds time data. If specified, the length of the data must match the length of the time index. Must be numeric, strings are not allowed (use :attr:`text_data` instead for string data). **text_data** If specified, the length of the data must match the length of the time index. Must contain strings or ``None``. **time_start** If the specified ``time_index`` holds relative time data (timedeltas or numeric values), this parameter can be used to set an absolute reference time (a timestamp). **time_unit** The unit of the time data as a string. **offset** An additional time offset specified as a timedelta or a numeric value (which is taken with respect to the given time unit). The offset is applied to :attr:`time_index`, but when the data is exported, the offset is removed (and exported separately). **anchored_channel** The channel the label is attached to. If the offset of the anchored channel is changed, the offset of the label is changed accordingly. **plotstyle** A dictionary of key/value pairs that are passed to ``matplotlib.pyplot.plot`` when plotting label data. **metadata** A dictionary that can be used to store additional information about the label. **plot_type** Determines how entries of the label are plotted. Available options are: - ``'scatter'``: Entries of the label are plotted as points. Requires a label with numeric data. - ``'vline'``: Entries of the label are plotted as vertical lines whose plot labels are determined by ``vline_text_source``. - ``'combined'``: Entries of the label are plotted as points when there is associated numeric data, and as vertical lines otherwise. Defaults to ``'combined'``. **vline_text_source** When plotting label data using vertical lines, this argument controls how text labels for the lines are determined. Available options are: - ``'text_data'``: Uses strings from :attr:`text_data` as line labels. - ``'data'``: Uses string representations of the numeric :attr:`.data` values as line labels. - ``'combined'``: Uses texts from :attr:`text_data` where available and fills the rest with entries from :attr:`.data`. - ``'disabled'``: No text is shown next to the vertical lines. Defaults to ``'text_data'``. The text labels can be customized by modifying the dictionary stored in the :attr:`plot_vline_bbox_settings` attribute of the label. **annotation_preset_type** Specifies the initial preselection of the annotation menu checkboxes when a label is selected. This preset is only applied **if the selected label has no existing data**. If the label already contains data, the menu's preselection will instead reflect the current contents of that label. Available options are: - ``'timestamp'``: Only the *Timestamp* checkbox is selected. - ``'numerical'``: *Timestamp* and *Numerical value* checkboxes are selected. - ``'textual'``: *Timestamp* and *Textual value* checkboxes are selected. - ``'combined'``: All checkboxes are selected. - ``None`` (the default): automatically selects the checkboxes based on other arguements like ``plot_type``. .. note:: - This setting only affects the **initial** state of the annotation menu—users can still modify selections interactively. - There is **no internal consistency check** between this setting and the `plot_type` or `vline_text_source` parameters. For example, you can disable textual input using this argument even if you intend to display vertical lines with text. .. !! processed by numpydoc !! .. py:attribute:: name :value: '' The name of the label. .. !! processed by numpydoc !! .. py:attribute:: anchored_channel :type: Channel | None :value: None The channel the label is attached to, or ``None``. .. !! processed by numpydoc !! .. py:attribute:: data :value: None The data points of the label, if any. .. !! processed by numpydoc !! .. py:attribute:: text_data :value: None Text associated to the individual time data points, if any. .. !! processed by numpydoc !! .. py:attribute:: plotstyle Keyword arguments passed to the plotting routine. .. !! processed by numpydoc !! .. py:attribute:: plot_vline_bbox_settings Settings for the bounding box around the vertical line text. .. !! processed by numpydoc !! .. py:attribute:: metadata Additional label metadata. .. !! processed by numpydoc !! .. py:property:: plot_type :type: vitabel.typing.LabelPlotType | None The type of plot to use to visualize the label. .. !! processed by numpydoc !! .. py:property:: vline_text_source :type: vitabel.typing.LabelPlotVLineTextSource | None The source attribute of the text to be shown next to vertical lines. .. !! processed by numpydoc !! .. py:property:: annotation_preset_type :type: vitabel.typing.LabelAnnotationPresetType | None The preselection of the labels annotation menu. .. !! processed by numpydoc !! .. py:method:: from_channel(channel: Channel) -> Label :classmethod: Create a label from a channel. :Parameters: **channel** The channel to create the label from. The label will have the same name, time index, data, and text data as the channel. .. !! processed by numpydoc !! .. py:property:: first_entry :type: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None The earliest entry in the time index of this label. .. !! processed by numpydoc !! .. py:property:: last_entry :type: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None The latest entry in the time index of this label. .. !! processed by numpydoc !! .. py:method:: add_data(time_data: vitabel.typing.Timestamp | vitabel.typing.Timedelta, value: float | numpy.number | str | None = None, text: str | None = None) Add a data point to the label. :Parameters: **time** The time of the data point. **value** The value of the data point. If not specified, the value is set to ``numpy.nan``. **text** The string to be inserted into :attr:`.Label.text_data`. .. !! processed by numpydoc !! .. py:method:: remove_data(time_data: vitabel.typing.Timestamp | vitabel.typing.Timedelta) Remove a data point from the label given its time. If the data point with the earliest time is removed, the :attr:`time_start` attribute of the label is updated. :Parameters: **time_data** The time of the data point to remove. .. !! processed by numpydoc !! .. py:method:: truncate(start_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> Label Return a new label that is a truncated version of this label. :Parameters: **start_time** The start time for the truncated label. **stop_time** The stop time for the truncated label. .. !! processed by numpydoc !! .. py:method:: from_dict(datadict: dict[str, Any]) -> Label :classmethod: Create a label from a serialized dictionary representation. :Parameters: **datadict** The dictionary representation of the label. .. !! processed by numpydoc !! .. py:method:: to_dict() -> dict[str, Any] A serialization of the label as a dictionary. .. !! processed by numpydoc !! .. py:method:: to_csv(filename: str | pathlib.Path | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> None Export the label data to a CSV file. :Parameters: **filename** The name of the file to export the data to. If not specified, the data is exported to a file with the name of the channel. **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. .. !! processed by numpydoc !! .. py:method:: attach_to(channel: Channel) Attach the label to a channel. :Parameters: **channel** The channel to attach the label to. .. !! processed by numpydoc !! .. py:method:: detach() Detach the label from the channel. .. note:: This method only removes the reference from the channel to the label, as well as the backreference from the label to the channel. While this does not delete the label object itself, the responsibility to manage the label object is with the user. .. !! processed by numpydoc !! .. py:method:: get_data(start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, include_adjacent: bool = False) -> vitabel.typing.DataSlice Return a tuple of time, data, and text data values with optional filtering. :Parameters: **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. **include_adjacent** If ``True``, the returned data also includes the time points that are adjacent to (but outside of) the start and stop times; useful for plotting. Defaults to ``False``. .. !! processed by numpydoc !! .. py:method:: plot(plot_axes: matplotlib.pyplot.Axes | None = None, plotstyle: dict[str, Any] | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, time_unit: str | None = None, reference_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, plot_type: vitabel.typing.LabelPlotType | None = None, vline_text_source: vitabel.typing.LabelPlotVLineTextSource | None = None) Plot the label data. :Parameters: **plot_axes** The (matplotlib) axes used to plot the data on. If not specified, a new figure will be created. **plotstyle** Overrides for the :attr:`plotstyle` of the label. **start** The start time for the data. If not specified, the data starts from the first time point. **stop** The start time for the data. If not specified, the data stops at the last time point. **time_unit** The time unit values used along the x-axis. If ``None`` (the default), the time unit of the channel is used. **plot_type** Override for :attr:`.plot_type`, see :class:`.Label` for details. If ``None`` (the default) is passed, the value from the attribute is used. **vline_text_source** Override for :attr:`.vline_text_source`, see :class:`.Label` for details. If ``None`` (the default) is passed, the value from the attribute is used. .. rubric:: Notes If ``plot_type`` and/or ``vline_text_source`` are inconsistent with the available (text) data, the routine will emit warnings. .. !! processed by numpydoc !! .. py:method:: rename(new_name: str) Change the name of the label. :Parameters: **new_name** The new name of the label. .. !! processed by numpydoc !! .. py:class:: IntervalLabel(name: str, time_index: numpy.typing.ArrayLike[vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str] | None = None, data: numpy.typing.ArrayLike[float | numpy.number] | None = None, text_data: numpy.typing.ArrayLike[str | None] | None = None, time_start: vitabel.typing.Timestamp | None = None, time_unit: str | None = None, offset: vitabel.typing.Timedelta | float | None = None, anchored_channel: Channel | None = None, plotstyle: dict[str, Any] | None = None, metadata: dict[str, Any] | None = None, plot_type: vitabel.typing.IntervalLabelPlotType = 'combined', annotation_preset_type: vitabel.typing.LabelAnnotationPresetType | None = None) Bases: :py:obj:`Label` A special type of label that holds time interval data. :Parameters: **name** The name of the label. **time_index** The time data of the label, interpreted as a alternating sequence of interval start and end points. Must have even length. Can be a list of timestamps, timedeltas, numeric values (interpreted with respect to the specified time unit), or datetime strings (which will be parsed by ``pandas``). **data** The data points of the label. If not specified, the label only holds time data. If specified, the length of the data must match the number of time intervals. Must be numeric, strings are not allowed (use :attr:`text_data` instead for string data). **text_data** If specified, the length of the data must match the number of time intervals. Must contain strings or ``None``. **time_start** If the specified ``time_index`` holds relative time data (timedeltas or numeric values), this parameter can be used to set an absolute reference time (a timestamp). **time_unit** The unit of the time data as a string. **offset** An additional time offset specified as a timedelta or a numeric value (which is taken with respect to the given time unit). The offset is applied to :attr:`time_index`, but when the data is exported, the offset is removed (and exported separately). **anchored_channel** The channel the label is attached to. If the offset of the anchored channel is changed, the offset of the label is changed accordingly. **plotstyle** A dictionary of key/value pairs that are passed to ``matplotlib.pyplot.errorbar`` when plotting label data. **metadata** A dictionary that can be used to store additional information about the label. **plot_type** Determines how entries of the label are plotted. Available options are: - ``'box'``: Entries of the label are plotted as colorized area. Requries no additional data. - ``'hline'``: Entries of the label are plotted as horizontal lines. Requires a label with numeric data. - ``'combined'``: Entries of the label are plotted as horizontal line when there is associated numeric data, and as rectangle lines otherwise. Defaults to ``'combined'``. **annotation_preset_type** Specifies the initial preselection of the annotation menu checkboxes when a label is selected. This preset is only applied **if the selected label has no existing data**. If the label already contains data, the menu's preselection will instead reflect the current contents of that label. Available options are: - ``'timestamp'``: Only the *Timestamp* checkbox is selected. - ``'numerical'``: *Timestamp* and *Numerical value* checkboxes are selected. - ``'textual'``: *Timestamp* and *Textual value* checkboxes are selected. - ``'combined'``: All checkboxes are selected. - ``None`` (the default): automatically selects the checkboxes based on other arguements like ``plot_type``. .. note:: - This setting only affects the **initial** state of the annotation menu—users can still modify selections interactively. - There is **no internal consistency check** between this setting and the `plot_type` or `vline_text_source` parameters. For example, you can disable textual input using this argument even if you intend to display vertical lines with text. .. !! processed by numpydoc !! .. py:property:: plot_type :type: vitabel.typing.IntervalLabelPlotType The type of plot to use to visualize the label. .. !! processed by numpydoc !! .. py:property:: intervals :type: numpy.typing.NDArray A 2D array of interval start and end points representing the time intervals of the label. If the label is absolute in time, the intervals are timestamps. Otherwise, they are timedeltas. .. !! processed by numpydoc !! .. py:method:: truncate(start_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> IntervalLabel Return a new label that is a truncated version of this label. :Parameters: **start_time** The start time for the truncated label. **stop_time** The stop time for the truncated label. .. !! processed by numpydoc !! .. py:method:: from_dict(datadict: dict[str, Any]) -> Label :classmethod: Create a IntervalLabel from a serialized dictionary representation. :Parameters: **datadict** The dictionary representation of the label. .. !! processed by numpydoc !! .. py:method:: to_dict() -> dict[str, Any] A serialization of the label as a dictionary. .. !! processed by numpydoc !! .. py:method:: to_csv(filename: str | pathlib.Path | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None) -> None Export the interval label data to a CSV file. Contains all intervals with a non-empty intersection of the specified data range. :Parameters: **filename** The name of the file to export the data to. If not specified, the data is exported to a file with the name of the channel. **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. .. !! processed by numpydoc !! .. py:method:: get_data(start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None) -> vitabel.typing.DataSlice Return a tuple of interval endpoints and data values with optional filtering. This returns all intervals that intersect with the specified time range, shortening the intervals if necessary. :Parameters: **start** The start time for the data. If not specified, the data starts from the beginning. **stop** The stop time for the data. If not specified, the data ends at the last time point. .. !! processed by numpydoc !! .. py:method:: add_data(time_data: tuple[vitabel.typing.Timestamp, vitabel.typing.Timestamp] | tuple[vitabel.typing.Timedelta, vitabel.typing.Timedelta], value: float | numpy.number | str | None = None, text: str | None = None) Add data to the label. :Parameters: **time_data** A time data tuple specifying an interval. **value** The numeric value of the data point. If not specified, the value is set to ``numpy.nan``. **text** The string to be inserted into :attr:`text_data`. .. !! processed by numpydoc !! .. py:method:: remove_data(time_data: tuple[vitabel.typing.Timestamp, vitabel.typing.Timestamp] | tuple[vitabel.typing.Timedelta, vitabel.typing.Timedelta]) Remove data from the label. :Parameters: **time_data** A time data tuple specifying an interval. .. !! processed by numpydoc !! .. py:method:: contains_time(time_data: numpy.typing.ArrayLike | vitabel.typing.Timestamp | vitabel.typing.Timedelta, include_start: bool = True, include_end: bool = True, interval_require_full_containment: bool = False) -> numpy.typing.NDArray[numpy.bool_] Check which of the specified timestamps or timedeltas are contained in any of the intervals of the label. If the specified time data is provided in a array of shape ``(n, 2)``, each row is interpreted as a start and end point of a time interval, and the containment check is performed for the entire interval. :Parameters: **time_data** A list of timestamps or timedeltas, or an array with time interval endpoints to be checked. **include_start** If ``True``, the start point of each interval is considered to be contained in the interval. Defaults to ``True``. **include_end** If ``True``, the end point of each interval is considered to be contained in the interval. Defaults to ``True``. **interval_require_full_containment** If ``True``, the specified time intervals are only considered to be contained in the label if they are fully contained in any of the label's intervals. Defaults to ``False``. Only has an effect if interval data is provided to ``time_data``. :Returns: A boolean array indicating for each of the specified time points .. whether it is contained in any of the intervals of the label. .. .. !! processed by numpydoc !! .. py:method:: plot(plot_axes: matplotlib.pyplot.Axes | None = None, plotstyle: dict[str, Any] | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, time_unit: str | None = None, reference_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | None = None, plot_type: vitabel.typing.IntervalLabelPlotType | None = None) Plot the label data using an error bar or a filled background region. If the label has (numeric) data, the intervals are plotted as error bars on the height of the data points. If there is no data, the intervals are plotted as a filled background region. Uses ``matplotlib.pyplot.errorbar`` or ``matplotlib.pyplot.axvspan``. :Parameters: **plot_axes** The (matplotlib) axes used to plot the data on. If not specified, a new figure will be created. **plotstyle** Overrides for the :attr:`plotstyle` of the label. **start** The start time for the data. If not specified, the data starts from the first time point. **stop** The start time for the data. If not specified, the data stops at the last time point. **time_unit** The time unit values used along the x-axis. If ``None`` (the default), the time unit of the channel is used. **reference_time** For labels with absolute time, a reference time to subtract from the time data. If not specified, the :attr:`time_start` attribute is used. .. !! processed by numpydoc !! .. py:class:: TimeDataCollection(channels: list[Channel] | None = None, labels: list[Label] | None = None) A collection of channels and labels. :Parameters: **channels** A list of data channels. **labels** A list of labels. Labels that are anchored to a passed channel do not need to be passed separately, they are part of the collection automatically. .. !! processed by numpydoc !! .. py:attribute:: channels :type: list[Channel] :value: [] .. py:attribute:: global_labels :type: list[Label] :value: [] .. py:property:: local_labels :type: list[Label] All labels anchored to some channel in the collection. .. !! processed by numpydoc !! .. py:property:: labels :type: list[Label] All labels in the collection, both global and local ones. .. !! processed by numpydoc !! .. py:method:: is_empty() -> bool Return whether the collection is empty. .. !! processed by numpydoc !! .. py:method:: is_time_absolute() -> bool Return whether the collection contains only absolute time data. .. !! processed by numpydoc !! .. py:method:: is_time_relative() -> bool Return whether the collection contains only relative time data. .. !! processed by numpydoc !! .. py:method:: print_summary() -> None Print a summary of channels and labels in the collection. .. !! processed by numpydoc !! .. py:method:: add_channel(channel: Channel) Add a channel to the collection. :Parameters: **channel** The channel to add. .. !! processed by numpydoc !! .. py:method:: add_global_label(label: Label) Add a label to the collection. :Parameters: **label** The label to add. .. !! processed by numpydoc !! .. py:method:: detach_label_from_channel(*, label: Label | str, channel: Channel | str | None = None, reattach_as_global: bool = True) -> Label Detach a label from a channel in the collection. :Parameters: **label** The label to detach. Can be specified either as a :class:`.Label` object or by its name. **channel** The channel to detach the label from or ``None`` (the default) if the channel should be determined from the label. Can be specified either as a :class:`.Channel` object or by its name. **reattach_as_global** If ``True``, the label is reattached as a global label after detaching it from the channel. If ``False``, the label is removed from the collection. .. !! processed by numpydoc !! .. py:method:: get_channels(name: str | None = None, **kwargs) -> list[Channel] Return a list of channels. :Parameters: **name** The name of the channel to retrieve. Allowed to be passed either as a positional or a keyword argument. **kwargs** Keyword arguments to filter the channels by. The specified arguments are compared to the attributes of the channels. .. !! processed by numpydoc !! .. py:method:: get_channel(name: str | int | None = None, **kwargs) -> Channel Return a channel by name. Raises an error if no unique channel is found. :Parameters: **name** The name of the channel to retrieve. Allowed to be passed either as a positional or a keyword argument. If an integer is passed, it is interpreted as the index of the channel in the collection. **kwargs** Keyword arguments to filter the channels by. .. !! processed by numpydoc !! .. py:method:: channel_data_hash() -> str Return a hash representing the data and metadata of all channels in this collection. .. !! processed by numpydoc !! .. py:method:: get_labels(name: str | None = None, **kwargs) -> list[Label] Return a list of labels. :Parameters: **name** The name of the label to retrieve. Allowed to be passed either as a positional or a keyword argument. **kwargs** Keyword arguments to filter the labels by. The specified arguments are compared to the attributes of the labels. .. !! processed by numpydoc !! .. py:method:: get_label(name: str | int | None = None, **kwargs) -> Label Return a label by name. Raises an error if no unique label is found. :Parameters: **name** The name of the label to retrieve. Allowed to be passed either as a positional or a keyword argument. If an integer is passed, it is interpreted as the index of the label in the collection. **kwargs** Keyword arguments to filter the labels by. The specified arguments are compared to the attributes of the labels. .. !! processed by numpydoc !! .. py:method:: remove_label(*, label: Label | None = None, **kwargs) -> Label Remove a local or global label from the collection. Local labels are removed by detaching them from their corresponding channel. :Parameters: **label** The label object to delete, optional. Alternatively, the label can also be specified by keyword arguments as in :meth:`.get_label`. .. !! processed by numpydoc !! .. py:method:: remove_channel(*, channel: Channel | None = None, **kwargs) -> Channel Remove a channel by name. :Parameters: **channel** The channel object to delete, optional. Alternatively, the channel can also be specified by keyword arguments as in :meth:`.get_channel`. **kwargs** The name of the channel to delete. .. !! processed by numpydoc !! .. py:method:: set_channel_plotstyle(channel_specification: vitabel.typing.ChannelSpecification | None = None, **kwargs) Set the plot style for a channel. :Parameters: **channel_specification** A specification of all channels to set the plot style for. See :meth:`.get_channels` for valid specifications. **\*\*kwargs** The plot style properties to set. Passing ``None`` unsets the key from the plotstyle dictionary. .. !! processed by numpydoc !! .. py:method:: set_label_plotstyle(label_specification: vitabel.typing.LabelSpecification | None = None, **kwargs) Set the plot style for specified labels. :Parameters: **label_specification** A specification of all labels to set the plot style for. See :meth:`.get_labels` for valid specifications. **\*\*kwargs** The plot style properties to set. Passing ``None`` unsets the key from the plotstyle dictionary. .. !! processed by numpydoc !! .. py:method:: to_dict() -> dict[str, Any] Construct a serializable dictionary that represents this collection. .. !! processed by numpydoc !! .. py:method:: from_dict(datadict: dict[str, Any]) -> TimeDataCollection :classmethod: Create a collection from a dictionary representation. :Parameters: **datadict** A dictionary representation of the collection. .. !! processed by numpydoc !! .. py:method:: plot(channels: list[list[vitabel.typing.ChannelSpecification | int]] | None = None, labels: list[list[vitabel.typing.LabelSpecification | int]] | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str | None = None, resolution: vitabel.typing.Timedelta | float | None = None, time_unit: str | None = None, include_attached_labels: bool = False, subplots_kwargs: dict[str, Any] | None = None) Plot the data in the collection. :Parameters: **channels** The channels to plot. If not specified, all channels are plotted. Specified as a list of lists with individual lists containing channels to be collected in one subplot. **labels** The labels to plot. If not specified, all labels are plotted. Specified as a list of lists, same as for the channels. **start** The start time for the plot. If not specified, the plot starts from the first time point. **stop** The stop time for the plot. If not specified, the plot stops at the last time point. **resolution** The resolution of the plot in the time unit of the channels. If not specified, the channel and label data is not downsampled. **time_unit** The time unit in which channel and label data are represented in. If not specified, the time unit of the channels is used. **include_attached_labels** Whether to automatically include labels attached to the specified channels. **subplots_kwargs** Keyword arguments passed to ``matplotlib.pyplot.subplots``. .. !! processed by numpydoc !! .. py:method:: plot_interactive(channels: list[list[vitabel.typing.ChannelSpecification | int]] | None = None, labels: list[list[vitabel.typing.LabelSpecification | int]] | None = None, start: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str | None = None, stop: vitabel.typing.Timestamp | vitabel.typing.Timedelta | float | str | None = None, time_unit: str | None = None, include_attached_labels: bool = False, channel_overviews: list[list[vitabel.typing.ChannelSpecification | int]] | bool = False, limited_overview: bool = False, subplots_kwargs: dict[str, Any] | None = None) Plot the data in the collection using ipywidgets. This allows to annotate the data with labels, and to modify channel offsets interactively. :Parameters: **channels** The channels to plot. If not specified, all channels are plotted. Specified as a list of lists with individual lists containing channels to be collected in one subplot. **labels** The labels to plot. If not specified, all labels are plotted. Specified as a list of lists, same as for the channels. **start** The start time for the plot. If not specified, the plot starts from the first time point. **stop** The stop time for the plot. If not specified, the plot stops at the last time point. **time_unit** The time unit in which channel and label data are represented in. If not specified, the time unit of the channels is used. **include_attached_labels** Whether to automatically include labels attached to the specified channels. **channel_overviews** Similar to ``channel``, but plots the specified channels in a separate subplot in a condensed way including a location map of the main plot. If set to ``True``, all chosen channels are plotted in a single overview. **limited_overview** Whether the time interval of the overview subplot should be limited to the recording interval of the channels being plotted. **subplots_kwargs** Keyword arguments passed to ``matplotlib.pyplot.subplots``. .. !! processed by numpydoc !!