Class DataArray¶

Defined in File DataArray.hpp

Inheritance Relationships¶

Base Types¶

public nix::base::EntityWithSources< base::IDataArray > (Template Class EntityWithSources)
public nix::DataSet (Class DataSet)

Class Documentation¶

class DataArray : public nix::base::EntityWithSources<base::IDataArray>, public nix::DataSet ¶

A class that can store arbitrary n-dimensional data along with further information.

The DataArray is the core entity of the NIX data model, its purpose is to store arbitrary n-dimensional data. In addition to the common fields id, name, type, and definition the DataArray stores sufficient information to understand the physical nature of the stored data.

A guiding principle of the data model is provides enough information to create a plot of the stored data. In order to do so, the DataArray defines a property dataType which provides the physical type of the stored data (for example 16 bit integer or double precision IEEE floatingpoint number). The property unit specifies the SI unit of the values stored in the DataArray{} whereas the label defines what is given in this units. Together, both specify what corresponds to the the y-axis of a plot.

In some cases it is much more efficient or convenient to store data not as floating point numbers but rather as (16 bit) integer values as, for example read from a data acquisition board. In order to convert such data to the correct values, we follow the approach taken by the comedi data-acquisition library (http://www.comedi.org) and provide polynomCoefficients and an expansionOrigin.

Create a new data array with a 10 x 10 float matrix as data

A DataArray can only be created at an existing block. Do not use the DataArrays constructors for this purpose.

Block b = ...;
DataArray da = b.crateDataArray("matrix_10_10", "data");
da.createData(DataType::Float, {10, 10});

Remove a data array from a file

Block b = ...;
bool deleted = da.deleteDataArray(some_id);

Public Functions

inline DataArray()¶

Constructor that creates an uninitialized DataArray.

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

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

inline DataArray(const DataArray &other)¶

Copy constructor.

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

Parameters: other – The data array to copy.

inline DataArray(const std::shared_ptr<base::IDataArray> &p_impl)¶

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

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

inline DataArray(std::shared_ptr<base::IDataArray> &&ptr)¶

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

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

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

Get the label for the values stored in the DataArray.

Returns: The label of the data array.

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

Set the label for the data stored.

Parameters: label – The label of the data array.

inline void label(const none_t t)¶

Deleter for the label attribute.

Parameters: t – None

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

Get the unit of the data stored in this data array.

Returns: The unit of the data array.

inline void unit(const none_t t)¶

Deleter for the unit attribute.

Parameters: t – None

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

Set the unit for the values stored in this DataArray.

Parameters: unit – The unit of the data array.

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

Returns the expansion origin of the calibration polynom.

The expansion origin is 0.0 by default.

Returns: The expansion origin.

inline void expansionOrigin(double expansion_origin)¶

Set the expansion origin for the calibration.

Parameters: expansion_origin – The expansion origin for the calibration.

inline void expansionOrigin(const none_t t)¶

Deleter for the expansion origin.

This will reset the expansion origin for the calibration to its default value which is given with 0.0.

Parameters: t – None

inline void polynomCoefficients(const std::vector<double> &polynom_coefficients, const Compression &compression = Compression::None)¶

Set the polynom coefficients for the calibration.

By default this is set to a two element vector of [0.0, 1.0] for a linear calibration with zero offset.

Parameters

polynom_coefficients – The new polynom coefficients for the calibration.
compression – The nix::Compression flag defining the compression of the dataset.

inline std::vector<double> polynomCoefficients() const¶

Returns the polynom coefficients.

Returns: The polynom coefficients for the calibration.

inline void polynomCoefficients(const none_t t)¶

Deleter for the polynomCoefficients attribute.

Parameters: t – None

std::vector<Dimension> dimensions(const util::Filter<Dimension>::type &filter) const¶

Get all dimensions associated with this data array.

The parameter filter can be used to filter sources by various criteria.

Parameters: filter – A filter function (nix::util::Filter::type)
Returns: The filtered dimensions as a vector

inline std::vector<Dimension> dimensions() const¶

Get all dimensions associated with this data array.

Always uses filter that accepts all sources.

Returns: The filtered dimensions as a vector

inline ndsize_t dimensionCount() const¶

Returns the number of dimensions stored in the DataArray.

This matches the dimensionality of the data stored in this property.

Returns: The number of dimensions.

inline Dimension getDimension(ndsize_t id) const¶

Returns the Dimension object for the specified dimension of the data.

Parameters: id – The index of the respective dimension.
Returns: The dimension object.

inline SetDimension appendSetDimension(const std::vector<std::string> &labels = {})¶

Append a new SetDimension to the list of existing dimension descriptors.

Parameters: labels – The category labels, default: empty std::vector of std::string
Returns: The newly created SetDimension.

inline RangeDimension appendRangeDimension(const std::vector<double> &ticks, const std::string &label = "", const std::string &unit = "")¶

Append a new RangeDimension to the list of existing dimension descriptors.

Parameters

ticks – The ticks of the RangeDimension to create.
label – The label of the dimension (e.g. ‘time’), default: empty
unit – The unit of the ticks, default: empty

Returns

The newly created RangeDimension

inline RangeDimension appendAliasRangeDimension()¶

Append a new RangeDimension that uses the data stored in this DataArray as ticks. This works only(!) if the DataArray in 1D and the stored data is numeric. An Exception of the type nix::InvalidDimension will be thrown otherwise.

Returns: The created RangeDimension

inline SampledDimension appendSampledDimension(double sampling_interval, const std::string &label = "", const std::string &unit = "", double offset = 0.0)¶

Append a new SampledDimension to the list of existing dimension descriptors.

Parameters

sampling_interval – The sampling interval of the SetDimension to create.
label – The label of the dimension (e.g. ‘time’), default: empty
unit – The unit of the dimension, default: empty
offset – The offset with which this dimension starts, default: 0.0

Returns

The newly created SampledDimension.

inline DataFrameDimension appendDataFrameDimension(const DataFrame &frame, unsigned column_index)¶

Append a new nix::DataFrameDimension to the list of dimension descriptors. A DataFrameDimension can be used to specify a dimension of a DataArray as specified by one (or all) column(s) of the linked DataFrame. That is, for each entry in the DataArray there must be a respecive row in the DataFrame. If no column index is specified that whole DataFrame is assumed to describe the DataArray entries along this dimension.

Parameters

frame – The DataFrame
column_index – The index of the column that should be used.

Returns

The new DataFrameDimension

inline DataFrameDimension appendDataFrameDimension(const DataFrame &frame, const std::string &column_name)¶

Append a new nix::DataFrameDimension to the list of dimension descriptors. A DataFrameDimension can be used to specify a dimension of a DataArray as specified by one (or all) column(s) of the linked DataFrame. That is, for each entry in the DataArray there must be a respecive row in the DataFrame. If no column index is specified that whole DataFrame is assumed to describe the DataArray entries along this dimension.

Parameters

frame – The DataFrame
column_name – The name of the column that should be used.

Returns

The new DataFrameDimension

inline DataFrameDimension appendDataFrameDimension(const DataFrame &frame)¶

Append a new nix::DataFrameDimension to the list of dimension descriptors. A DataFrameDimension can be used to specify a dimension of a DataArray as specified by one (or all) column(s) of the linked DataFrame. That is, for each entry in the DataArray there must be a respecive row in the DataFrame. If no column index is specified that whole DataFrame is assumed to describe the DataArray entries along this dimension.

Parameters: frame – The DataFrame
Returns: The new DataFrameDimension

inline DEPRECATED SetDimension createSetDimension (ndsize_t id)

Create a new SetDimension at a specified dimension index.

This adds a new dimension descriptor of the type nix::SetDimension that describes the dimension of the data at the specified index.

Deprecated:: This function is deprecated and ignores the id argument!

Parameters: id – The index of the dimension. Must be a value > 0 and <= dimensionCount + 1.
Returns: The created dimension descriptor.

inline DEPRECATED RangeDimension createRangeDimension (ndsize_t id, const std::vector< double > &ticks)

Create a new RangeDimension at a specified dimension index.

This adds a new dimension descriptor of the type nix::RangeDimension that describes the dimension of the data at the specified index.

Deprecated:: This function is deprecated and ignores the id argument!

Parameters

id – The index of the dimension. Must be a value > 0 and <= dimensionCount + 1.
ticks – Vector with nix::RangeDimension::ticks.

Returns

The created dimension descriptor.

inline DEPRECATED RangeDimension createAliasRangeDimension ()

Create a new RangeDimension that uses the data stored in this DataArray as ticks.

Deprecated:: This function is deprecated and will be removed. Use appendAliasRangeDimension instead!

Returns: The created dimension descriptor.

inline DEPRECATED SampledDimension createSampledDimension (ndsize_t id, double sampling_interval)

Create a new SampledDimension at a specified dimension index.

This adds a new dimension descriptor of the type nix::SampledDimension that describes the dimension of the data at the specified index.

Deprecated:: This function is deprecated and ignores the id argument!

Parameters

id – The index of the dimension. Must be a value > 0 and <= dimensionCount + 1.
sampling_interval – The sampling interval of the dimension.

Returns

The created dimension descriptor.

inline bool deleteDimensions()¶

Remove all dimension descriptors of the nix::DataArray.

Returns: bool indicating if operation succeeded.

inline void getDataDirect(DataType dtype, void *data, const NDSize &count, const NDSize &offset) const¶

inline void setDataDirect(DataType dtype, const void *data, const NDSize &count, const NDSize &offset)¶

inline virtual NDSize dataExtent() const¶

Get the extent of the data of the DataArray entity.

Returns: The data extent.

inline virtual void dataExtent(const NDSize &extent)¶

Set the data extent of the DataArray entity.

Parameters: extent – The extent of the data.

inline virtual DataType dataType(void) const¶

Get the data type of the data stored in the DataArray entity.

Returns: The data type of the DataArray.

void appendData(DataType dtype, const void *data, const NDSize &count, size_t axis)¶

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

inline DataArray &operator=(const DataArray &other)¶: Copy-assignment operator.

Protected Functions

virtual void ioRead(DataType dtype, void *data, const NDSize &count, const NDSize &offset) const¶

virtual void ioWrite(DataType dtype, const void *data, const NDSize &count, const NDSize &offset)¶

Friends

friend NIXAPI friend std::ostream & operator<< (std::ostream &out, const DataArray &ent): Output operator.