Class MultiTag¶

Defined in File MultiTag.hpp

Inheritance Relationships¶

Base Type¶

public nix::base::EntityWithSources< base::IMultiTag > (Template Class EntityWithSources)

Class Documentation¶

class MultiTag : public nix::base::EntityWithSources<base::IMultiTag>¶

A tag class that can be used to tag multiple positions or regions in data.

Besides the nix::DataArray the tag entities can be considered as the other core entities of the data model. They are meant to attach annotations directly to the data and to establish meaningful links between different kinds of stored data. Most importantly tags allow the definition of points or regions of interest in data that is stored in other nix::DataArray entities. The data array entities the tag applies to are defined by its property references.

Further the referenced data is defined by an origin vector called positions and an optional extents vector that defines its size with position >= x <= position + extent. Therefore position and extent of a tag, together with the references field defines a group of points or regions of interest collected from a subset of all available nix::DataArray entities.

Further tags have a field called features which makes it possible to associate other data with the tag. Semantically a feature of a tag is some additional data that contains additional information about the points of hyperslabs defined by the tag. This could be for example data that represents a stimulus (e.g. an image or a signal) that was applied in a certain interval during the recording.

Public Functions

inline MultiTag()¶

Constructor that creates an uninitialized MultiTag.

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

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

inline MultiTag(const MultiTag &other)¶

Copy constructor.

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

Parameters: other – The tag to copy.

inline MultiTag(const std::shared_ptr<base::IMultiTag> &p_impl)¶

inline MultiTag(std::shared_ptr<base::IMultiTag> &&ptr)¶

inline DataArray positions() const¶

Getter for the positions of a tag.

The positions of a multi tag are defined in a DataArray. This array has to define a set of origin vectors, each defining a point inside the referenced data or the beginning of a region of interest.

Returns: The DataArray defining the positions of the tag.

inline ndsize_t positionCount() const¶

Returns the number of tagged positions.

Returns: The number of positions tagging the referenced data.

void positions(const std::string &name_or_id)¶

Setter for the positions of the tag.

Parameters: name_or_id – Name or id of the DataArray that defines the positions for this tag.

void positions(const DataArray &positions)¶

Setter for the positions of the tag.

Parameters: positions – The DataArray containing the positions of the tag.

inline bool hasPositions() const¶

Determine whether this DataArray contains positions.

Returns: True if the DataArray has positions, false otherwise.

inline DataArray extents() const¶

Getter for the extents of a tag.

The extents of a multi tag are defined in an associated DataArray. This array has to define a set of extent vectors, each defining the size of the corresponding region of interest. Position and extent define a closed set, i.e. position >= x <= position + extent.

Returns: The DataArray defining the extents of the tag.

void extents(const DataArray &extents)¶

Sets the extents DataArray of the tag.

Position and extent define a closed set, i.e. position >= x <= position + extent.

Parameters: extents – The DataArray containing the extents of the tag.

void extents(const std::string &name_or_id)¶

Setter for the positions of the tag.

Parameters: name_or_id – Name or id of the DataArray that defines the extents of the tag.

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

Deleter for the reference to the extents DataArray.

This function only removes the association between the tag and the data array, but does not delete the data array itself.

Parameters: t – None

inline std::vector<std::string> units() const¶

Gets for the units of the tag.

The units are applied to all values for position and extent in order to calculate the right position vectors in referenced data arrays.

Returns: All units of the tag as a vector.

void units(const std::vector<std::string> &units)¶

Setter for the units of a tag.

All previously defined units will be replaced by the ones passed to the units parameter.

Parameters: units – All units as a vector.

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

Deleter for the units of a tag.

Removes all units from this tag.

Parameters: t – None

bool hasReference(const DataArray &reference) const¶

Checks if the specified DataArray is referenced by the tag.

Parameters: reference – The data array to check.
Returns: True if the data array is referenced, false otherwise.

inline bool hasReference(const std::string &name_or_id) const¶

Checks if the specified DataArray is referenced in this tag.

Parameters: name_or_id – Name or id of the data array to check.
Returns: True if a data array with the given id is referenced, false otherwise.

inline ndsize_t referenceCount() const¶

Get the number of DataArray entities that are referenced by the tag.

Returns: The number of referenced data arrays.

inline DataArray getReference(const std::string &name_or_id) const¶

Get a referenced DataArray by its name or id.

Parameters: name_or_id – Name or id of the data array.
Returns: The referenced data array.

DataArray getReference(size_t index) const¶

Get a referenced DataArray by its index.

Parameters: index – The index of the data array.
Returns: The referenced data array.

inline void addReference(const std::string &name_or_id)¶

Add a new DataArray to the list of referenced data.

Parameters: name_or_id – Name or id of the data array.

void addReference(const DataArray &reference)¶

Adds a new DataArray to the list of referenced data.

Parameters: reference – The DataArray that should be referenced.

inline bool removeReference(const std::string &name_or_id)¶

Remove a DataArray from the list of referenced data.

This function only removes the association between the tag and the data array, but does not delete the data array itself.

Parameters: name_or_id – Name or id of the data array.
Returns: True if the data array was removed, false otherwise.

bool removeReference(const DataArray &reference)¶

Remove a DataArray from the list of referenced data.

This function only removes the association between the tag and the data array, but does not delete the data array itself.

Parameters: reference – The DataArray to remove.
Returns: True if the data array was removed, false otherwise.

std::vector<DataArray> references(const util::Filter<DataArray>::type &filter) const¶

Get all referenced data arrays associated with the tag.

The parameter filter can be used to filter data arrays by various criteria.

Parameters: filter – A filter function.
Returns: A vector containing all filtered DataArray entities.

inline std::vector<DataArray> references() const¶

Get all referenced data arrays associated with the tag.

Always uses filter that accepts all sources.

Returns: A vector containing all filtered DataArray entities.

inline void references(const std::vector<DataArray> &references)¶

Setter for all referenced DataArrays.

Previously referenced data will be replaced. removed.

Parameters: references – All referenced arrays.

DataView taggedData(size_t position_index, size_t reference_index) const¶

Retrieves the data slice tagged by a certain position and extent of a certain reference.

Parameters

position_index – the index of the requested position.
reference_index – the index of the requested reference.

Returns

the requested data.

inline DEPRECATED DataView retrieveData (size_t position_index, size_t reference_index) const

Retrieves the data slice tagged by a certain position and extent of a certain reference.

Parameters

position_index – the index of the requested position.
reference_index – the index of the requested reference.

Returns

the requested data.

std::vector<DataView> taggedData(std::vector<ndsize_t> &position_indices, ndsize_t reference_index) const¶

inline DEPRECATED std::vector< DataView > retrieveData (std::vector< ndsize_t > &position_indices, ndsize_t reference_index) const

std::vector<DataView> taggedData(std::vector<ndsize_t> &position_indices, const std::string &name_or_id) const¶

inline DEPRECATED std::vector< DataView > retrieveData (std::vector< ndsize_t > &position_indices, const std::string &name_or_id) const

DataView taggedData(size_t position_index, const std::string &name_or_id) const¶

Retrieves the data slice tagged by a certain position and extent of a certain reference.

Parameters

position_index – The index of the requested position.
name_or_id – The name or id of the requested DataArray.

Returns

the requested data.

inline DataView retrieveData(size_t position_index, const std::string &name_or_id) const¶

Retrieves the data slice tagged by a certain position and extent of a certain reference.

Parameters

position_index – The index of the requested position.
name_or_id – The name or id of the requested DataArray.

Returns

the requested data.

inline bool hasFeature(const std::string &name_or_id) const¶

Checks if a specific feature exists on the tag.

Parameters: name_or_id – Name or id of a feature.
Returns: True if the feature exists, false otherwise.

bool hasFeature(const Feature &feature) const¶

Checks if a specific feature exists on the tag.

Parameters: feature – The Feature to check.
Returns: True if the feature exists, false otherwise.

inline ndsize_t featureCount() const¶

Returns the number of features in this block.

Returns: The number of features.

inline Feature getFeature(const std::string &name_or_id) const¶

Retrieves a specific feature from the tag.

Parameters: name_or_id – Name or id of the feature.
Returns: The feature with the specified name or id. If it doesn’t exist an exception will be thrown.

inline Feature getFeature(size_t index) const¶

Retrieves a specific feature from the tag.

Parameters: index – The index of the feature.
Returns: The feature with the specified index.

std::vector<Feature> features(const util::Filter<Feature>::type &filter = util::AcceptAll<Feature>()) const¶

Get all Feature entities contained in the tag.

The parameter filter can be used to filter features by various criteria. By default a filter is used that accepts all features.

Parameters: filter – A filter function.
Returns: A vector containing all filtered Feature entities.

inline Feature createFeature(const DataArray &data, LinkType link_type)¶

Create a new feature.

Parameters

data – The data array that is part of the new feature.
link_type – The link type of this feature.

Returns

The created feature object.

inline Feature createFeature(const std::string &name_or_id, LinkType link_type)¶

Create a new feature.

Parameters

name_or_id – Name or id of the data array that is part of the new feature.
link_type – The link type of this feature.

Returns

The created feature object.

inline bool deleteFeature(const std::string &name_or_id)¶

Delete a feature from the tag.

Parameters: name_or_id – Name or id of the feature to remove.
Returns: True if the feature was removed, false otherwise.

bool deleteFeature(const Feature &feature)¶

Delete a feature from the tag.

Parameters: feature – The feature to remove.
Returns: True if the feature was removed, false otherwise.

DataView featureData(size_t position_index, size_t feature_index) const¶

Retrieves the data stored in a feature related to a certain position of this tag.

Parameters

position_index – The index of the requested position
feature_index – The index of the selected feature

Returns

The data

inline DEPRECATED DataView retrieveFeatureData (size_t position_index, size_t feature_index) const

Retrieves the data stored in a feature related to a certain position of this tag.

Deprecated:: This function has been deprecated. Use featureData(size_t, size_t) instead.

Parameters

position_index – The index of the requested position
feature_index – The index of the selected feature

Returns

The data

DataView featureData(size_t position_index, const std::string &name_or_id) const¶

Retrieves the data stored in a feature related to a certain position of this tag.

Parameters

position_index – The index of the requested position.
name_or_id – The name or id of the feature that is requested.

Returns

The data

inline DEPRECATED DataView retrieveFeatureData (size_t position_index, const std::string &name_or_id) const

Retrieves the data stored in a feature related to a certain position of this tag.

Deprecated:: This function has been deprecated! Use featureData(size_t, std::string) instead.

Parameters

position_index – The index of the requested position.
name_or_id – The name or id of the feature that is requested.

Returns

The data

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

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

Friends

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