Skip to content

📑 API Reference

Jump to bottom
João Saraiva edited this page Jul 24, 2022 · 3 revisions

The LTBio framework is divided into 7 packages to facilitate navigation:

  • ❶ biosignals
  • ❷ clinical
  • ❸ processing
  • ❹ features
  • ❺ ml
  • ❻ decision
  • ❼ pipeline

It works just like a grocery store with 7 sections, so you grab whatever you need from each of them to conduct your analysis.

❶ biosignals

Timeseries

Initializer

Timeseries(samples, initial_datetime, sampling_frequency, units = None, name = None)

Instantiates a Timeseries with a contiguous sequence of samples.

Parameters:

  • samples (ndarray | list | tuple) : The samples to store, without interruptions.

  • initial_datetime (datetime): The date and time of the first sample.

  • sampling_frequency (float | Frequency): The frequency at which the samples where sampled.

  • units (Unit): The physical units of the variable measured.

  • name (str): A symbolic name for the Timeseries. It is mentioned in plots, reports, error messages, etc.

Alternative Initializer

Timeseries.withDiscontiguousSegments(segments_by_time, sampling_frequency, units = None, name = None)

Instantiates a Timeseries with discontiguous sequences of samples.

Parameters:

  • segments_by_time ( dict [ datetime, ndarray | list | tuple ] ): The sequence of samples to store as separate Segments, in the format { datetime: [, ... ], ... }.

  • initial_datetime (datetime): The date and time of the first sample.

  • sampling_frequency (float | Frequency): The frequency at which the samples where sampled.

  • units (Unit): The physical units of the variable measured.

  • name (str): A symbolic name for the Timeseries. It is mentioned in plots, reports, error messages, etc.

Properties

Read only:

  • samples (ndarray): Contiguous or discontiguous sequence of samples.

  • sampling_frequency (float): The frequency at which the samples were acquired, in Hz.

  • units (Unit): The physical unit at which the samples should be interpreted.

  • events (tuple[Event]): The events timely associated to the Timeseries.

  • initial_datetime (datetime): The date and time of the first sample.

  • final_datetime (datetime): The date and time of the last sample.

  • duration (timedelta): The total time of acquired samples, excluding interruptions.

  • domain (tuple[DateTimeRange]): The intervals of date and time in which the Timeseries is defined, i.e., samples were acquired.

  • is_equally_segmented (bool): The logic value stating if each interval in the domain has the same duration.

  • segment_duration (timedelta): Duration of all segments, if is_equally_segmented is True.

Read and Write:

  • name (str): The name of the Timeseries, if any.

append

append(initial_datetime, samples)

Appends a new sequence of samples in a separate Segment.

Parameters:

  • initial_datetime (datetime): The date and time of the first sample in samples.
  • samples (ndarray | list | tuple): The sequence of samples to add as a separate Segment.

Returns: None

Raises:

  • AssertionError: If the given initial_datetime comes before the date and time of the last sample in the timeseries.

associate

associate(events)

Timely associates an Event with the Timeseries. Events have names that serve as keys. If keys are given, i.e. if events is a dict, then the Event names are override.

Parameters:

  • events (Event | Collection[Event] | Dict[str, Event]): One or multiple Event objects..

Returns: None

Raises:

  • ValueError: If an Event of events is outside of the timeseries' domain.
  • NameError: If an Event of events has name already associated with another Event. Cannot have two Events with the same name.

dissociate

dissociate(event_name)

Removes any association the Timeseries has with an Event with the given name.

Parameters:

  • event_name (str): The name of the Event to dissociate.

Returns: None

Raises:

  • NameError: If there's no Event named event_name associated to the Timeseries.

to_array

to_array()

Converts Timeseries to numpy.ndarray, only if it contains just one Segment.

Returns:

samples (ndarray): An array with the Timeseries' samples.

Raises:

  • AssertionError: If it contains more than one Segment.

Event

Event(name, onset)
Event(name, offset)
Event(name, onset, offset)

Parameters:

  • name (str): A short label associated to the meaning of the event.
  • onset (datetime, str), optional: When the event starts.
  • offset (datetime, str), optional: When the event ends.

Raises:

  • AssertionError: Neither an onset nor an offset were given.
  • AssertionError: If the offset comes before the onset.

Properties

Read only:

  • has_onset (bool): True if an onset was declared.

  • has_offset (bool): True if an offset was declared.

  • duration (timedelta): The amount of time between onset and offset.

  • domain (DateTimeRange): The time interval [onset, offset[.

  • name (str): The label associated at instantiation. Cannot be changed.

Read and Write:

  • onset (datetime): When the event starts.

  • offset (datetime): When the event ends.

modalities

Biosignal

In the following, X is any type of Biosignal, namely: ACC, ECG, EDA, EEG, EMG, HR, PPG, RESP, or TEMP.

Instantiation with Ad-hoc Timeseries

X(timeseries, source = None, patient = None, acquisition_location = None, name = None)

Parameters:

  • timeseries (dict[str|BodyLocation, Timeseries]): Collection of channels (Timeseries) keyed by a channel name (str or BodyLocation).
  • source (BiosignalSource), optional: From which institution or device did the biosignal came from.
  • patient (Patient), optional: From whom the biosignal was acquired.
  • acquisition_location (BodyLocation), optional: Where in the body was the biosignal was acquired.
  • name (str), optional: A name to be associated to the biosignal.

Instantiation from data files

X(timeseries, source, patient = None, acquisition_location = None, name = None)

Parameters:

  • timeseries (str): The path to the directory containing all the files to read.
  • source (BiosignalSource): From which institution or device did the biosignal came from.
  • patient (Patient), optional: From whom the biosignal was acquired.
  • acquisition_location (BodyLocation), optional: Where in the body was the biosignal was acquired.
  • name (str), optional: A name to be associated to the biosignal.

Raises:

  • ValueError: If no valid source is given.

Instantiation from .biosignal file

Biosignal.load(filepath)

Parameters:

  • filepath (str): The path (directory + name) the biosignal is.

Properties

Read only:

  • channel_names (tuple [str | BodyLocation]): Returns a tuple with the labels associated to every channel.

  • patient_code (str | int): Returns the code of the associated Patient, or 'n.d.' if none was provided.

  • patient_conditions (set[MedicalCondition]): Returns the set of medical conditions of the associated Patient, or None if no Patient was associated.

  • acquisition_location (BodyLocation): Returns the associated acquisition location, or None if none was provided.

  • source (BiosignalSource): Returns where the data was read, or None if was not specified.

  • type (subclass of Biosignal): Returns the biosignal modality class. E.g.: ECG, EMG, EDA, ...

  • initial_datetime (datetime): The initial datetime of the channel that starts the earliest.

  • final_datetime (datetime): The final datetime of the channel that ends the latest.

  • domain (tuple[DateTimeRange]): The union of time intervals in which a channel is defined. Attributes only exists for 1-channel Biosignals.

  • events (tuple[Event]): The associated Events, ordered by datetime.

  • sampling_frequency (float): Returns the sampling frequency of all channels, if equal. Attribute does not exist if all channels don't share the same sampling frequency.

Read and Write:

  • name (datetime): The associated name.

set_channel_name

set_channel_name(current, new)

Allows to rename the name of an existing channel.

Parameters:

  • current (str | BodyLocation): The current channel name.
  • new (str | BodyLocation): To which the channel name should be changed.

Returns: None

Raises:

  • AttributeError: No channel named current exists.

set_event_name

set_event_name(current, new)

Allows to rename the name of an associated Event.

Parameters:

  • current (str): The current Event name.
  • new (str): To which the Event name should be changed.

Returns: None

Raises:

  • AttributeError: There is no Event named current associated.

delete_events

delete_events()

Removes the association it has with any Event.

Returns: None

filter

filter(filter_design)

Filters every channel with the filter design given.

Parameters:

  • filter_design (Filter): A Filter object describing the digital filter design.

Returns:

code (int): 0 if the filtering is applied successfully.

undo_filters

undo_filters()

Restores the raw samples of every channel, eliminating the action of any applied filter.

Returns: None

resample

resample(frequency)

Resamples every channel to the new sampling frequency given, using Fourier method.

Parameters:

  • frequency (float): Description.

Returns: None

plot

plot(show = True, save_to = None)

Plots the amplitude in time of every channel.

Parameters:

  • show (bool): True if plot is to be immediately displayed; False otherwise.
  • save_to (str): A path to save the plot as an image file; If none is provided, it is not saved.

Returns: None

plot_spectrum

plot_spectrum(show = True, save_to = None)

Plots the Bode plot of every channel.

Parameters:

  • show (bool): True if plot is to be immediately displayed; False otherwise.
  • save_to (str): A path to save the plot as an image file; If none is provided, it is not saved.

Returns: None

plot_summary

plot_summary(show = True, save_to = None)

Plots a summary of relevant aspects of common analysis of each Biosignal modality.

Parameters:

  • show (bool): True if plot is to be immediately displayed; False otherwise.
  • save_to (str): A path to save the plot as an image file; If none is provided, it is not saved.

Returns: None

apply_operation

apply_operation(operation, **kwargs)

Applies operation in-place to every channel's samples.

Parameters:

  • operation (Callable): Any procedure that receives a ndarray of samples as first argument, and returns a ndarray fo the same size as well.
  • **kwargs (dict): Other arguments to be passed to operation.

Returns: None

invert

invert(channel_name=None)

Inverts the amplitude axis of all channels or of a specific channel.

Parameters:

  • channel_name (str), optional: If given, applies the inversion only to the channel of this name.

Returns: None

associate

associate(events)

Timely associates an Event with the biosignal. Events have names that serve as keys. If keys are given, i.e. if events is a dict, then the Event names are overridden.

Parameters:

  • events (Event | Collection[Event] | Dict[str, Event]): One or multiple Event objects.

Returns: None

Raises:

  • ValueError: If any Event is outside every channel's domain.
  • NameError: If any Event has a name already associated with another Event. Cannot have two Events with the same name.

dissociate

dissociate(event_name)

Removes any association the biosignal has with an Event with the given name.

Parameters:

  • event_name (str): The name of the Event to dissociate.

Returns: None

Raises:

  • NameError: If there's no Event named event_name associated to the biosignal.

save

save(save_to)

Serializes the biosignal in a .biosignal file.

Parameters:

  • save_to (str): The path (directory + name) where to save the biosignal.

Returns: None

Raises:

  • SomeError: Describe when and why.

name

signature

Description

Parameters:

  • 1 (type): Description.
  • 2 (type): Description.

Returns:

what (type): Description.

Raises:

  • SomeError: Describe when and why.
Clone this wiki locally