Programming Reference:Signals

GenericSignal Class

Location

src/shared/types

Synopsis

Many classes in both Data Acquisition and Signal Processing work on signals, i.e., continuously flowing data organized into channels and samples. The GenericSignal class contains floating point data organized as a matrix of channels and "elements" (a generalized notion of samples -- e.g., spectrally analyzed data might contain the spectrum of each channel as a list of "elements").

Methods

GenericSignal(int Channels, int Elements, SignalType=int16)

Initializes a GenericSignal object to the specified number of channels and elements. The signal type argument may be one of

• SignalType::int16,
• SignalType::int32,
• SignalType::float32,
• SignalType::float24.

GenericSignal(SignalProperties)

Initializes a GenericSignal object to the properties defined by the SignalProperties object.

WriteToStream(ostream)/ReadFromStream(istream)

Read/write from/to std::iostream streams in human-readable ASCII format.

WriteBinary(ostream)/ReadBinary(istream)

Read/write from/to std::iostream streams as a BCI2000 signal message.

WriteValueBinary(ostream, channel, element)/ReadValueBinary(istream, channel, element)

Binary I/O of individual values, depending on the signal's type. These functions are provided for use in FileWriter components, and components that read data from input files.

Properties

SignalProperties Properties (rw)

The signal's properties, contained in a SignalProperties object.

int Channels (r)

The number of channels.

int Elements (r)

The number of elements.

SignalType Type (r)

The signal type.

number Value(Channel, Element) (rw)

The signal's value at the specified channel/element combination. Access to signal values is also possible (and recommended) using parentheses notation on the signal object itself:

GenericSignal mySignal( 5, 4 );
mySignal( 2, 3 ) = 4.5;

SignalProperties Class

Location

src/shared/types

Synopsis

Sometimes, the number of channels, elements, and bytes required for storing values, are referred to as "Signal Properties". There is a separate class, SignalProperties, for expressing those values, and determining whether a given signal "fits" into another one, i.e., whether the values contained in one signal may be copied into another signal without loss of information. GenericSignal class uses a SignalProperties member to maintain information about its properties.

Methods

SignalProperties(Channels, Elements, SignalType=int16)

Initializes a SignalProperties object to the specified number of channels and elements. The signal type argument may be one of

• SignalType::int16,
• SignalType::int32,
• SignalType::float32,
• SignalType::float24.

bool Accommodates(SignalProperties)

True if a signal of the argument's properties can be represented by a signal with the object's properties without data loss, i.e. the number of channels and elements must at least match the argument's, and the numeric range defined by the signal's type must at least equal the argument's.

float ChannelIndex(string Address), ElementIndex(string Address)

Returns a zero-based channel or element index corresponding to the specified address. The address may be

• a label contained in the ChannelLabels or ElementLabels property,
• a value in physical units, with a unit matching the one from the ChannelUnit or ElementUnit property, or
• a plain number, which is treated as a one-based index.

These interpretations are tried in the above order; if none matches, a negative index is returned, indicating failure to interpret the address.

This function is provided to simplify conversion of parameter values into indices, allowing users to use labels, physical units, or one-based indices as appropriate for the signal that is to be addressed.

Properties

int Channels, Elements (rw)

The number of channels and elements.

SignalType Type (rw)

The signal's numeric type.

string Name (rw)

The signal's name. When a signal is sent to the operator module via a GenericVisualization object, its name is used as a visualization window title.

LabelIndex ChannelLabels, ElementLabels (rw)

Labels of channels and elements, represented as LabelIndex objects.

float SamplingRate (r)

The sampling rate of the signal, given in Hz, or 0 when the dimension in element direction is not time. SamplingRate is a readonly property; to adapt a signal's sampling rate, set its ElementUnit's Gain property to the inverse of the desired sampling rate.

float UpdateRate (rw)

The update rate of the signal, given in Hz. This number shows how often a signal is updated with new values, irrespective of its dimensions. Note that in general SamplingRate is not equal to UpdateRate*Elements.

PhysicalUnit ChannelUnit, ElementUnit, ValueUnit (rw)

Physical units associated with respective dimensions. Typically, there is no physical unit in the channel dimension; in the element dimension, the physical unit would be temporal, measured in seconds, or a frequency, measured in Hz; in the value dimension, the physical unit would be a voltage, or a power thereof. Physical units are represented as objects of type PhysicalUnit.

bool IsEmpty

True if at least one of channels and elements is zero.