Class SampledDimension¶

Defined in File Dimensions.hpp

Inheritance Relationships¶

Base Type¶

public nix::base::ImplContainer< base::ISampledDimension > (Template Class ImplContainer)

Class Documentation¶

class SampledDimension : public nix::base::ImplContainer<base::ISampledDimension>¶

Dimension descriptor for regularly sampled dimensions.

Instances of the SampledDimension Class are used to describe a dimension of data in a DataArray that has been sampled in regular intervals. For example this can be a time axis.

Sampled dimensions are characterized by the label for the dimension, the unit in which the sampling interval is given. If not specified otherwise the dimension starts with zero offset.

Create a sampled dimension

The following example will create a sampled dimension on a data array. The dimension has a sampling rate of 10kHz and represents the time axis of a recording.

DataArray da = ...;
SampledDimension sd = da.appendSampledDimension(0.1);

sd.unit("ms");
sd.label("time")
sd.offset(10000)

Public Functions

SampledDimension()¶

Constructor that creates an uninitialized SampledDimension.

Calling any method on an uninitialized dimension will throw a nix::UninitializedEntity exception. The following code illustrates how to check if a dimension is initialized:

SampledDimension e = ...;
if (e) {
    // e is initialised
} else {
    // e is uninitialized
}

SampledDimension(const std::shared_ptr<base::ISampledDimension> &p_impl)¶

Constructor that creates a new dimension from a shared pointer to an implementation instance.

This constructor should only be used in the back-end.

SampledDimension(std::shared_ptr<base::ISampledDimension> &&ptr)¶

Constructor with move semantics that creates a new dimension from a shared pointer to an implementation instance.

This constructor should only be used in the back-end.

SampledDimension(const SampledDimension &other)¶

Copy constructor.

Copying of all NIX front facing objects like SampledDimension is a rather cheap operation. Semantically this is equivalent to the creation of another reference to the original object.

Parameters: other – The dimension to copy.

inline ndsize_t index() const¶

The actual dimension that is described by the dimension descriptor.

The index of the dimension entity representing the dimension of the actual data that is defined by this descriptor.

Returns: The dimension index of the dimension.

inline DimensionType dimensionType() const¶

The type of the dimension.

This field indicates whether the dimension is a SampledDimension, SetDimension or RangeDimension.

Returns: The dimension type.

inline boost::optional<std::string> label() const¶

Getter for the label of the dimension.

The label of a SampledDimension corresponds to the axis label in a plot of the respective dimension.

Returns: The label of the dimension.

void label(const std::string &label)¶

Sets the label of the dimension.

Parameters: label – The label of the dimension.

inline void label(const none_t t)¶

Removes the label from a dimension.

Parameters: t – None

inline boost::optional<std::string> unit() const¶

Gets the unit of a dimension.

The unit describes which SI unit applies to this dimension and to its sampling interval.

Returns: The unit of the dimension.

void unit(const std::string &unit)¶

Sets the unit of a dimension.

Parameters: unit – The unit to set.

inline void unit(const none_t t)¶

Removes the unit from a dimension.

Parameters: t – None

inline double samplingInterval() const¶

Gets the sampling interval of the dimension.

The unit of measure in which the sampling interval must be provided is defined by the unit of the SampledDimension.

Returns: The sampling interval.

void samplingInterval(double interval)¶

Sets the sampling interval of the dimension.

Parameters: interval – The sampling interval to set.

inline boost::optional<double> offset() const¶

Gets the offset of the dimension.

The offset defines at which position the sampling was started. The offset is interpreted in the same unit as the sampling interval.

By default the offset is 0.

Returns: The offset of the SampledDimension.

inline void offset(double offset)¶

Sets the offset of the dimension.

Parameters: offset – The offset of the dimension.

inline void offset(const boost::none_t t)¶

Removes the offset from the dimension.

This resets the offset to the default which is 0.

Parameters: t – None

DEPRECATED ndsize_t indexOf (const double position) const

Returns the index of the given position.

This method returns the index of the given position. Use this method for example to find out which data point (index) relates to a given time. Note: This method does not check if the position is within the extent of the data! Nevertheless, an OutOfBounds exception is thrown if the position is less than the offset of the dimension.

Deprecated:: This function has been deprecated use SampledDimension::indexOf instead.

Parameters: position – The position, e.g. a time
Returns: The respective index.

boost::optional<ndsize_t> indexOf(const double position, PositionMatch match) const¶

Returns the index of the given position.

This method returns the index of the given position. Use this method for example to find out which data point (index) relates to a given time. If the position is invalid, an invalid optional is returned.

Parameters

position – The position, e.g. a time
strict – Defines whether an exception should be thrown if the position is invalid

Returns

An optional containing the respective index.

boost::optional<std::pair<ndsize_t, ndsize_t>> indexOf(const double start, const double end, RangeMatch match) const¶

Returns a pair of indices of the start and end positions within this dimension.

This method returns the index of the given position. Use this method for example to find out which data point (index) relates to a given time. Note: This method does not check if the position is within the extent of the data! Nevertheless, an OutOfBounds exception is thrown if the start position is less than the offset of the dimension.

Parameters

start – The start position, e.g. a time
end – The end position
match – RangeMatch enum to control whether the range should be including the end position or exclusive, i.e. without the end position, default is RangeMatch::Inclusive

Returns

The respective index.

DEPRECATED std::pair< ndsize_t, ndsize_t > indexOf (const double start, const double end) const

Deprecated:: This function has been deprecated please use SampledDimension::indexOf(const double, const double&, const RangeMatch) instead

boost::optional<std::pair<ndsize_t, ndsize_t>> indexOf(double start, double end, const double sampling_interval, const double offset, const RangeMatch match) const¶

Returns the index of the given position.

This method returns the index of the given position. Use this method for example to find out which data point (index) relates to a given time. Note: This method does not check if the position is within the extent of the data! Nevertheless, an OutOfBounds exception is thrown if the start position is less than the offset of the dimension.

Parameters

start – The start position, e.g. a time
end – The end position
sampling_interval – The sampling interval of the dimension.
offset – The offset of the dimension.
match – RangeMatch enum to control whether the range should be including the end position or exclusive, i.e. without the end position.

Returns

The a boost::optional containing the pair of start and end indices.

std::vector<boost::optional<std::pair<ndsize_t, ndsize_t>>> indexOf(const std::vector<double> &start_positions, const std::vector<double> &end_positions, const RangeMatch match) const¶

Returns a vector of start and end indices of given start and end positions. This method does not check whether the index is in the extent of the data. Nevertheless, an OutOfBounds exception is thrown if the start position is less than the offset of the dimension.

Parameters

start_positions – Vector of start positions
end_positions – Vector of end positions
match – RangeMatch enum to control whether the range should be including the end position or exclusive, i.e. without the end position.

Returns

Vector of optionals containing pairs of start and end indices.

DEPRECATED std::vector< std::pair< ndsize_t, ndsize_t > > indexOf (const std::vector< double > &start_positions, const std::vector< double > &end_positions) const

Deprecated:: This function has been deprecated please use SampledDimension::indexOf(const std::vector<double>&, const std::vector<double>&, const RangeMatch) instead

double positionAt(const ndsize_t index) const¶

Returns the position of this dimension at a given index.

This method returns the position at a given index. Use this method for example to find the position that relates to a certain index. Note: This method does not check if the index is the extent of the data!

Parameters: index – The index.
Returns: The respective position, e.g. a time.

std::vector<double> axis(const ndsize_t count, const ndsize_t startIndex = 0) const¶

Returns a vector containing the positions defined by this dimension.

Returns an axis vector defined by this dimension.

Parameters

count – The number of indices
startIndex – The start index, default = 0

Returns

A vector of doubles containing the respective dimension.

SampledDimension &operator=(const SampledDimension &other)¶

Assignment operator.

Parameters: other – The dimension to assign.

SampledDimension &operator=(const Dimension &other)¶

Assignment operator that converts a Dimension to a SampledDimension.

Parameters: other – The dimension to assign.

inline SampledDimension &operator=(const none_t &t)¶: Assignment operator for none.

inline double operator[](const ndsize_t index)¶

Returns the position at the given index.