org.g_node.nix

Class DataArray

java.lang.Object

org.bytedeco.javacpp.Pointer

org.g_node.nix.base.ImplContainer

org.g_node.nix.base.Entity

org.g_node.nix.base.NamedEntity

org.g_node.nix.base.EntityWithMetadata

org.g_node.nix.base.EntityWithSources

org.g_node.nix.DataArray

All Implemented Interfaces:

Comparable

@Platform(include="<nix/DataArray.hpp>") @Platform(value="linux",link="nix@.1",preload="hdf5@.7") @Platform(value="windows",link="nix",preload={"hdf5","msvcp120","msvcr120","szip","zlib"})
 @Namespace(value="nix")
public class DataArray
extends EntityWithSources

DataArray

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 setUnit(String) specifies the SI unit of the values stored in the DataArray{} whereas the setLabel(String) 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 setPolynomCoefficients(double[]) and an setExpansionOrigin(double).

Create a new data array

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

     Block b = ...;
     DataArray da = b.createDataArray("array_one", "testdata", DataType.Double, new NDSize(new int[] { 3, 4, 2 }));
 

Remove a data array from a file

Deleting a DataArray.

     Block b = ...;
     boolean deleted = b.deleteDataArray(some_id);
 

See Also:

Block, DataType

Constructor Summary

Constructors

Constructor and Description
DataArray() Constructor that creates an uninitialized DataArray.

Method Summary

Modifier and Type	Method and Description
void	addSource(Source source) Associate a new source with the entity.
void	addSource(String id) Associate a new source with the entity.
RangeDimension	appendAliasRangeDimension() Append a new RangeDimension that uses the data stored in this DataArray as ticks.
RangeDimension	appendRangeDimension(double[] ticks) Append a new RangeDimension to the list of existing dimension descriptors.
SampledDimension	appendSampledDimension(double samplingInterval) Append a new SampledDimension to the list of existing dimension descriptors.
SetDimension	appendSetDimension() Append a new SetDimension to the list of existing dimension descriptors.
RangeDimension	createAliasRangeDimension() Create a new RangeDimension that uses the data stored in this DataArray as ticks.
RangeDimension	createRangeDimension(long id, double[] ticks) Create a new RangeDimension at a specified dimension index.
SampledDimension	createSampledDimension(long id, double samplingInterval) Create a new SampledDimension at a specified dimension index.
SetDimension	createSetDimension(long id) Create a new SetDimension at a specified dimension index.
boolean	deleteDimension(long id) Remove a dimension descriptor at a specified index.
void	forceCreatedAt(Date date) Sets the creation date to the provided value even if the attribute is set.
void	forceUpdatedAt() Sets the time of the last update to the current time.
Date	getCreatedAt() Get the creation date of the data array.
void	getData(byte[] data, NDSize count, NDSize offset) Get stored data.
void	getData(double[] data, NDSize count, NDSize offset) Get stored data.
void	getData(float[] data, NDSize count, NDSize offset) Get stored data.
void	getData(int[] data, NDSize count, NDSize offset) Get stored data.
void	getData(long[] data, NDSize count, NDSize offset) Get stored data.
void	getData(short[] data, NDSize count, NDSize offset) Get stored data.
NDSize	getDataExtent() Get the extent of the data of the DataArray entity.
int	getDataType() Get the data type of the data stored in the DataArray entity.
String	getDefinition() Getter for the definition of the data array.
Dimension	getDimension(long id) Returns the Dimension object for the specified dimension of the data.
long	getDimensionCount() Returns the number of dimensions stored in the DataArray.
List<Dimension>	getDimensions() Get all dimensions associated with this data array.
List<Dimension>	getDimensions(java.util.function.Predicate<Dimension> filter) Get all dimensions associated with this data array.
double	getExpansionOrigin() Returns the expansion origin of the calibration polynom.
String	getId() Get id of the data array.
String	getLabel() Get the label for the values stored in the DataArray.
Section	getMetadata() Get metadata associated with this entity.
String	getName() Getter for the name of the data array.
double[]	getPolynomCoefficients() Returns the polynom coefficients.
Source	getSource(long index) Retrieves an associated source identified by its index.
Source	getSource(String id) Returns an associated source identified by its id.
long	getSourceCount() Get the number of sources associated with this entity.
List<Source>	getSources() Get all sources associated with this entity.
String	getType() Getter for the type of the data array
String	getUnit() Get the unit of the data stored in this data array.
Date	getUpdatedAt() Get the date of the last update.
boolean	hasSource(Source source) Checks if a specific source is associated with this entity.
boolean	hasSource(String id) Checks if a specific source is associated with this entity.
boolean	isNone() Check if entity is null
void	removeMetadata() Removes metadata associated with the entity.
boolean	removeSource(Source source) Remove a source from the list of associated sources.
boolean	removeSource(String id) Remove a source from the list of associated sources.
void	setCreatedAt() Sets the creation time to the current time if the field is not set.
void	setData(byte[] data, NDSize count, NDSize offset) Set byte array data.
void	setData(double[] data, NDSize count, NDSize offset) Set double array data.
void	setData(float[] data, NDSize count, NDSize offset) Set float array data.
void	setData(int[] data, NDSize count, NDSize offset) Set integer array data.
void	setData(long[] data, NDSize count, NDSize offset) Set long array data.
void	setData(short[] data, NDSize count, NDSize offset) Set short array data.
void	setDataExtent(NDSize extent) Set the data extent of the DataArray entity.
void	setDefinition(String definition) Setter for the definition of the data array.
void	setExpansionOrigin(double expansionOrigin) Set the expansion origin for the calibration.
void	setLabel(String label) Set the label for the data stored.
void	setMetadata(Section metadata) Associate the entity with some metadata.
void	setMetadata(String id) Associate the entity with some metadata.
void	setPolynomCoefficients(double[] polynomCoefficients) Set the polynom coefficients for the calibration.
void	setSources(List<Source> sources) Set all sources associations for this entity.
void	setType(String type) Setter for the type of the data array.
void	setUnit(String unit) Set the unit for the values stored in this DataArray.
void	setUpdatedAt() Sets the time of the last update to the current time if the field is not set.
String	toString()

Methods inherited from class org.g_node.nix.base.NamedEntity

compareTo

Methods inherited from class org.g_node.nix.base.Entity

equals, hashCode

Methods inherited from class org.g_node.nix.base.ImplContainer

isInitialized

Methods inherited from class org.bytedeco.javacpp.Pointer

address, asBuffer, asByteBuffer, capacity, capacity, deallocate, deallocate, deallocateReferences, fill, isNull, limit, limit, memchr, memcmp, memcpy, memmove, memset, offsetof, position, position, put, setNull, sizeof, zero

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DataArray

public DataArray()

Constructor that creates an uninitialized DataArray.

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

Method Detail

isNone

@Cast(value="bool")
public boolean isNone()

Description copied from class: ImplContainer

Check if entity is null

Specified by:

isNone in class ImplContainer

Returns:

true if initialized else false

getId

@Name(value="id")
 @StdString
public String getId()

Get id of the data array.

Specified by:

getId in class Entity

Returns:

ID string.

getCreatedAt

public Date getCreatedAt()

Get the creation date of the data array.

Specified by:

getCreatedAt in class Entity

Returns:

The creation date of the data array.

getUpdatedAt

public Date getUpdatedAt()

Get the date of the last update.

Specified by:

getUpdatedAt in class Entity

Returns:

The date of the last update.

setUpdatedAt

public void setUpdatedAt()

Sets the time of the last update to the current time if the field is not set.

Specified by:

setUpdatedAt in class Entity

forceUpdatedAt

public void forceUpdatedAt()

Sets the time of the last update to the current time.

Specified by:

forceUpdatedAt in class Entity

setCreatedAt

public void setCreatedAt()

Sets the creation time to the current time if the field is not set.

Specified by:

setCreatedAt in class Entity

forceCreatedAt

public void forceCreatedAt(Date date)

Sets the creation date to the provided value even if the attribute is set.

Specified by:

forceCreatedAt in class Entity

Parameters:

date - The creation date to set.

setType

@Name(value="type")
public void setType(@StdString
                                        String type)

Setter for the type of the data array.

Specified by:

setType in class NamedEntity

Parameters:

type - The type of the data array.

getType

@Name(value="type")
 @StdString
public String getType()

Getter for the type of the data array

Specified by:

getType in class NamedEntity

Returns:

The type of the data array

getName

@Name(value="name")
 @StdString
public String getName()

Getter for the name of the data array.

Specified by:

getName in class NamedEntity

Returns:

The name of the data array.

setDefinition

public void setDefinition(String definition)

Setter for the definition of the data array. If null is passed definition is removed.

Specified by:

setDefinition in class NamedEntity

Parameters:

definition - definition of data array

getDefinition

public String getDefinition()

Getter for the definition of the data array.

Specified by:

getDefinition in class NamedEntity

Returns:

The definition of the data array.

getMetadata

@Name(value="metadata")
public Section getMetadata()

Get metadata associated with this entity.

Specified by:

getMetadata in class EntityWithMetadata

Returns:

The associated section, if no such section exists null is returned.

See Also:

Section

setMetadata

@Name(value="metadata")
public void setMetadata(@Const @ByRef
                                                Section metadata)

Associate the entity with some metadata.

Calling this method will replace previously stored information.

Specified by:

setMetadata in class EntityWithMetadata

Parameters:

metadata - The Section that should be associated with this entity.

See Also:

Section

setMetadata

@Name(value="metadata")
public void setMetadata(@StdString
                                                String id)

Associate the entity with some metadata.

Calling this method will replace previously stored information.

Specified by:

setMetadata in class EntityWithMetadata

Parameters:

id - The id of the Section that should be associated with this entity.

See Also:

Section

removeMetadata

public void removeMetadata()

Removes metadata associated with the entity.

Specified by:

removeMetadata in class EntityWithMetadata

See Also:

Section

getSourceCount

@Name(value="sourceCount")
public long getSourceCount()

Get the number of sources associated with this entity.

Specified by:

getSourceCount in class EntityWithSources

Returns:

The number sources.

See Also:

Source

hasSource

@Cast(value="bool")
public boolean hasSource(@StdString
                                             String id)

Checks if a specific source is associated with this entity.

Specified by:

hasSource in class EntityWithSources

Parameters:

id - The source id to check.

Returns:

True if the source is associated with this entity, false otherwise.

See Also:

Source

hasSource

@Cast(value="bool")
public boolean hasSource(@Const @ByRef
                                             Source source)

Checks if a specific source is associated with this entity.

Specified by:

hasSource in class EntityWithSources

Parameters:

source - The source to check.

Returns:

True if the source is associated with this entity, false otherwise.

See Also:

Source

getSource

public Source getSource(String id)

Returns an associated source identified by its id.

Specified by:

getSource in class EntityWithSources

Parameters:

id - The id of the associated source.

See Also:

Source

getSource

public Source getSource(long index)

Retrieves an associated source identified by its index.

Specified by:

getSource in class EntityWithSources

Parameters:

index - The index of the associated source.

Returns:

The source with the given id. If it doesn't exist an exception will be thrown.

See Also:

Source

getSources

public List<Source> getSources()

Get all sources associated with this entity.

Specified by:

getSources in class EntityWithSources

Returns:

All associated sources that match the given filter as a list.

See Also:

Source

setSources

public void setSources(List<Source> sources)

Set all sources associations for this entity.

All previously existing associations will be overwritten.

Specified by:

setSources in class EntityWithSources

Parameters:

sources - A list with all sources.

See Also:

Source

addSource

public void addSource(@StdString
                      String id)

Associate a new source with the entity.

If a source with the given id already is associated with the entity, the call will have no effect.

Specified by:

addSource in class EntityWithSources

Parameters:

id - The id of the source.

See Also:

Source

addSource

public void addSource(@Const @ByRef
                      Source source)

Associate a new source with the entity.

Calling this method will have no effect if the source is already associated to this entity.

Specified by:

addSource in class EntityWithSources

Parameters:

source - The source to add.

See Also:

Source

removeSource

@Cast(value="bool")
public boolean removeSource(@StdString
                                                String id)

Remove a source from the list of associated sources.

This method just removes the association between the entity and the source. The source itself will not be deleted from the file.

Specified by:

removeSource in class EntityWithSources

Parameters:

id - The id of the source to remove.

Returns:

True if the source was removed, false otherwise.

See Also:

Source

removeSource

@Cast(value="bool")
public boolean removeSource(@Const @ByRef
                                                Source source)

Remove a source from the list of associated sources.

This method just removes the association between the entity and the source. The source itself will not be deleted from the file.

Specified by:

removeSource in class EntityWithSources

Parameters:

source - The source to remove.

Returns:

True if the source was removed, false otherwise.

See Also:

Source

getLabel

public String getLabel()

Get the label for the values stored in the DataArray.

Returns:

The label of the data array. Returns null if not present.

setLabel

public void setLabel(String label)

Set the label for the data stored. If null is passed the label is removed.

Parameters:

label - The label of the data array.

getUnit

public String getUnit()

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

Returns:

The unit of the data array. null if not present.

setUnit

public void setUnit(String unit)

Set the unit for the values stored in this DataArray. If null is passed the unit is removed.

Parameters:

unit - The unit of the data array.

getExpansionOrigin

public double getExpansionOrigin()

Returns the expansion origin of the calibration polynom.

The expansion origin is 0.0 by default.

Returns:

The expansion origin.

setExpansionOrigin

@Name(value="expansionOrigin")
public void setExpansionOrigin(double expansionOrigin)

Set the expansion origin for the calibration.

Parameters:

expansionOrigin - The expansion origin for the calibration.

setPolynomCoefficients

public void setPolynomCoefficients(double[] polynomCoefficients)

Set the polynom coefficients for the calibration.

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

Parameters:

polynomCoefficients - The new polynom coefficients for the calibration. If null, deletes for the `polynomCoefficients` attribute.

getPolynomCoefficients

public double[] getPolynomCoefficients()

Returns the polynom coefficients.

Returns:

The polynom coefficients for the calibration.

getDimensions

public List<Dimension> getDimensions()

Get all dimensions associated with this data array.

Returns:

The dimensions as a list

See Also:

Dimension

getDimensions

public List<Dimension> getDimensions(java.util.function.Predicate<Dimension> filter)

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.

Returns:

The filtered dimensions as a list

See Also:

Dimension

getDimensionCount

@Name(value="dimensionCount")
 @Cast(value="size_t")
public long getDimensionCount()

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.

See Also:

Dimension

getDimension

public Dimension getDimension(long id)

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

Parameters:

id - The index of the respective dimension.

Returns:

The dimension object.

See Also:

Dimension

appendSetDimension

@ByVal
public SetDimension appendSetDimension()

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

Returns:

The newly created SetDimension.

See Also:

SetDimension

appendRangeDimension

@ByVal
public RangeDimension appendRangeDimension(@StdVector
                                                  double[] ticks)

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

Parameters:

ticks - The ticks of the RangeDimension to create.

Returns:

The newly created RangeDimension

See Also:

RangeDimension

appendAliasRangeDimension

@ByVal
public 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.

Returns:

The created RangeDimension

See Also:

RangeDimension

appendSampledDimension

@ByVal
public SampledDimension appendSampledDimension(double samplingInterval)

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

Parameters:

samplingInterval - The sampling interval of the SetDimension to create.

Returns:

The newly created SampledDimension.

See Also:

SampledDimension

createSetDimension

@ByVal
public SetDimension createSetDimension(@Cast(value="size_t")
                                              long id)

Create a new SetDimension at a specified dimension index.

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

Parameters:

id - The index of the dimension. Must be a value > 0 and <= `dimensionCount + 1`.

Returns:

The created dimension descriptor.

See Also:

SetDimension

createRangeDimension

@ByVal
public RangeDimension createRangeDimension(@Cast(value="size_t")
                                                  long id,
                                                  @StdVector
                                                  double[] ticks)

Create a new RangeDimension at a specified dimension index.

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

Parameters:

id - The index of the dimension. Must be a value > 0 and <= `dimensionCount + 1`.

ticks - Array with RangeDimension.setTicks(double[]).

Returns:

The created dimension descriptor.

See Also:

RangeDimension

createAliasRangeDimension

@ByVal
public RangeDimension createAliasRangeDimension()

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

Returns:

The created dimension descriptor.

See Also:

RangeDimension

createSampledDimension

@ByVal
public SampledDimension createSampledDimension(@Cast(value="size_t")
                                                      long id,
                                                      double samplingInterval)

Create a new SampledDimension at a specified dimension index.

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

Parameters:

id - The index of the dimension. Must be a value > 0 and <= `dimensionCount + 1`.

samplingInterval - The sampling interval of the dimension.

Returns:

The created dimension descriptor.

See Also:

SampledDimension

deleteDimension

@Cast(value="bool")
public boolean deleteDimension(@Cast(value="size_t")
                                                   long id)

Remove a dimension descriptor at a specified index.

Parameters:

id - The index of the dimension. Must be a value > 0 and < `getDimensionCount + 1`.

See Also:

Dimension

getDataExtent

@Name(value="dataExtent")
 @ByVal
public NDSize getDataExtent()

Get the extent of the data of the DataArray entity.

Returns:

The data extent.

See Also:

NDSize

setDataExtent

@Name(value="dataExtent")
public void setDataExtent(@Const @ByRef
                                                    NDSize extent)

Set the data extent of the DataArray entity.

Parameters:

extent - The extent of the data.

See Also:

NDSize

getDataType

@Name(value="dataType")
 @ByVal
 @Cast(value="nix::DataType")
public int getDataType()

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

Returns:

The data type of the DataArray.

See Also:

DataType

getData

public void getData(byte[] data,
                    NDSize count,
                    NDSize offset)

Get stored data. Data is stored in the array passed.

Parameters:

data - byte array

count - dimensions

offset - offset

getData

public void getData(short[] data,
                    NDSize count,
                    NDSize offset)

Get stored data. Data is stored in the array passed.

Parameters:

data - short array

count - dimensions

offset - offset

getData

public void getData(int[] data,
                    NDSize count,
                    NDSize offset)

Get stored data. Data is stored in the array passed.

Parameters:

data - int array

count - dimensions

offset - offset

getData

public void getData(long[] data,
                    NDSize count,
                    NDSize offset)

Get stored data. Data is stored in the array passed.

Parameters:

data - long array

count - dimensions

offset - offset

getData

public void getData(float[] data,
                    NDSize count,
                    NDSize offset)

Get stored data. Data is stored in the array passed.

Parameters:

data - float array

count - dimensions

offset - offset

getData

public void getData(double[] data,
                    NDSize count,
                    NDSize offset)

Get stored data. Data is stored in the array passed.

Parameters:

data - double array

count - dimensions

offset - offset

setData

public void setData(byte[] data,
                    NDSize count,
                    NDSize offset)

Set byte array data.

Parameters:

data - data

count - dimensions

offset - offset

setData

public void setData(short[] data,
                    NDSize count,
                    NDSize offset)

Set short array data.

Parameters:

data - data

count - dimensions

offset - offset

setData

public void setData(int[] data,
                    NDSize count,
                    NDSize offset)

Set integer array data.

Parameters:

data - data

count - dimensions

offset - offset

setData

public void setData(long[] data,
                    NDSize count,
                    NDSize offset)

Set long array data.

Parameters:

data - data

count - dimensions

offset - offset

setData

public void setData(float[] data,
                    NDSize count,
                    NDSize offset)

Set float array data.

Parameters:

data - data

count - dimensions

offset - offset

setData

public void setData(double[] data,
                    NDSize count,
                    NDSize offset)

Set double array data.

Parameters:

data - data

count - dimensions

offset - offset

toString

public String toString()

Overrides:

toString in class org.bytedeco.javacpp.Pointer