Class Tag¶

Defined in File Tag.hpp

Inheritance Relationships¶

Base Type¶

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

Class Documentation¶

class Tag : public nix::base::EntityWithSources<base::ITag>¶

A tag class that defines a single point or region of interest.

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 position and an optional extent 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 Tag()¶

Constructor that creates an uninitialized Tag.

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:

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

inline Tag(const Tag &other)¶

Copy constructor.

Copying of all NIX front facing objects like Tag 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 Tag(const std::shared_ptr<base::ITag> &p_impl)¶

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

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

inline Tag(std::shared_ptr<base::ITag> &&ptr)¶

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

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

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

Gets 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)¶

Sets the units of a tag.

Parameters: units – All units as a vector.

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

Deleter for the units of a tag.

Parameters: t – None

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

Gets the position of a tag.

The position is a vector that points into referenced DataArrays.

Returns: The position vector.

inline void position(const std::vector<double> &position)¶

Sets the position of a tag.

Parameters: position – The position vector.

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

Gets the extent of a tag.

Given a specified position vector, the extent vector defines the size of a region of interest in the referenced DataArray entities. Position and extent define a closed set, i.e. position >= x <= position + extent.

Returns: The extent of the tag.

inline void extent(const std::vector<double> &extent)¶

Sets the extent of a tag.

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

Parameters: extent – The extent vector.

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

Deleter for the extent of a tag.

Parameters: t – None

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

Checks whether a DataArray is referenced by the tag.

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

bool hasReference(const DataArray &reference) const¶

Checks whether a DataArray is referenced by the tag.

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

inline ndsize_t referenceCount() const¶

Gets the number of referenced DataArray entities of the tag.

Returns: The number of referenced data arrays.

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

Gets a specific referenced DataArray from the tag.

Parameters: id – The id of the referenced DataArray.
Returns: The referenced data array.

DataArray getReference(size_t index) const¶

Gets a referenced DataArray by its index.

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

void addReference(const DataArray &reference)¶

Add a DataArray to the list of referenced data of the tag.

Parameters: reference – The DataArray to add.

void addReference(const std::string &id)¶

Add a DataArray to the list of referenced data of the tag.

Parameters: id – The id of the DataArray to add.

bool removeReference(const DataArray &reference)¶

Remove a DataArray from the list of referenced data of the tag.

This method just removes the association between the data array and the tag, the data array itself will not be removed from the file.

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

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

Remove a DataArray from the list of referenced data of the tag.

This method just removes the association between the data array and the tag, the data array itself will not be removed from the file.

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

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

Get referenced data arrays associated with this tag.

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

Parameters: filter – A filter function.
Returns: A vector containing the matching data arrays.

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

Get all referenced data arrays associated with this tag.

Always uses filter that accepts all sources.

Returns: The filtered dimensions as a vector

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

Sets all referenced DataArray entities.

Previously referenced data arrays, that are not in the references vector will be removed.

Parameters: references – All referenced arrays.

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

Checks if a specific feature exists on the tag.

Parameters: id – The 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¶

Gets the number of features in this block.

Returns: The number of features.

Feature getFeature(const std::string &id) const¶

Retrieves a specific feature from the tag.

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

Feature getFeature(ndsize_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 Features of this 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 the matching features.

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

Create a new feature.

Parameters

data – The data array of this feature.
link_type – The link type of this feature.

Returns

The created feature object.

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

Create a new feature.

Parameters

data_array_id – The id of the data array of this feature.
link_type – The link type of this feature.

Returns

The created feature object.

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

Deletes a feature from the tag.

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

bool deleteFeature(const Feature &feature)¶

Deletes a feature from the tag.

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

DataView taggedData(size_t reference_index) const¶

Returns the data associated with a certain reference.

Parameters: reference_index – The index of the reference of which the data should be returned.
Returns: the data

inline DEPRECATED DataView retrieveData (size_t reference_index) const

Returns the data associated with a certain reference.

Deprecated:: This function has been marked deprecated. Please use taggedData(size_t) instead.

Parameters: reference_index – The index of the reference of which the data should be returned.
Returns: the data

DataView taggedData(const std::string &name_or_id) const¶

Returns the data associated with a certain reference.

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

inline DEPRECATED DataView retrieveData (const std::string &name_or_id) const

Returns the data associated with a certain reference.

Deprecated:: This function has been deprecated. Please use taggedData(std::string) instead.

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

DataView featureData(size_t feature_index) const¶

Returns the data stored in the selected Feature.

Parameters: feature_index – The index of the requested feature.
Returns: The data stored in the Feature.

inline DEPRECATED DataView retrieveFeatureData (size_t feature_index) const

Returns the data stored in the selected Feature.

Deprecated:: This function has been deprecated! Please use featureData(size_t) instead.

Parameters: feature_index – The index of the requested feature.
Returns: The data stored in the Feature.

DataView featureData(const std::string &name_or_id) const¶

Returns the data stored in the selected Feature.

Parameters: name_or_id – The name or id of the feature or the DataArray stored in the feature.
Returns: The data stored in the Feature.

inline DataView retrieveFeatureData(const std::string &name_or_id) const¶

Returns the data stored in the selected Feature.

Deprecated:: This function has been deprecated. Pleas use featureData(std::string) instead.

Parameters: name_or_id – The name or id of the feature or the DataArray stored in the feature.
Returns: The data stored in the Feature.

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

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

Friends

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