org.virbo.dataset
Interface QDataSet

All Known Subinterfaces:

MutablePropertyDataSet, WritableDataSet

All Known Implementing Classes:

AbstractDataSet, BDataSet, DDataSet, FDataSet, IDataSet, IndexGenDataSet, JoinDataSet, SDataSet, Slice0DataSet, Slice1DataSet, SortDataSet, TagGenDataSet, TransposeRank2DataSet, TransposeRankNDataSet, TrimStrideWrapper, WeightsDataSet

public interface QDataSet

QDataSets are less abstract and more flexible data model for das2. das2's current data model was developed to deliver spectrogram time series data sets where the dataset structure would change over time, and the interface is highly optimized for that environment. It's difficult to express many datasets in these terms, so the simpler "quick" QDataSet was introduced.

The QDataSet can be thought of as a fast java array that has name-value metadata attached to it. These arrays of data can have arbitrary rank, although currently the interface limits rank to 1,2, and 3. (Rank 0 and Rank N are proposed but not developed.) Each dimension's length can vary, like java arrays, and datasets where the dimensions do not vary in length are colloquially called "Qubes."

QDataSets can have other QDataSets as property values, for example the property QDataSet.DEPEND_0 indicates that the values are dependend parameters of the "tags" QDataSet found there. This how how we get to the same abstraction level of the legacy das2 dataset.

This is inspired by the CDF data model and PaPCo's dataset model.

See http://www.das2.org/wiki/index.php/Das2_DataSet_Abstraction_3.0

Field Summary

static java.lang.String	CACHE_TAG CacheTag, to be attached to tags datasets.
static java.lang.String	CADENCE Double, the expected distance between successive measurements where it is valid to make inferences about the data.
static java.lang.String	COORDINATE_FRAME String representing the coordinate frame of the vector index.
static java.lang.String	DELTA_MINUS QDataSet of rank 0 or correlated plane limits limits accuracy.
static java.lang.String	DELTA_PLUS QDataSet of rank 0 or correlated plane that limits accuracy.
static java.lang.String	DEPEND_0 type QDataSet.
static java.lang.String	DEPEND_1 type QDataSet.
static java.lang.String	DEPEND_2 type QDataSet.
static java.lang.String	FILL_VALUE Double, Double value to be considered fill (invalid) data.
static java.lang.String	LABEL String, Concise Human-consumable label suitable for a plot label.
static int	MAX_PLANE_COUNT this is the maximum number of allowed planes.
static int	MAX_RANK this is the highest rank supported by the library.
static java.lang.String	MONOTONIC Boolean, Boolean.TRUE if dataset is monotonically increasing.
static java.lang.String	NAME String a java identifier that should can be used when an identifier is needed.
static java.lang.String	PLANE_0 type QDataSet.
static java.lang.String	QUBE Boolean.TRUE indicates that the dataset is a "qube," meaning that all dimensions have fixed length and certain optimizations and operators are allowed.
static java.lang.String	RENDER_TYPE Hint as to preferred rendering method.
static java.lang.String	SCALE_TYPE String "linear" or "log"
static java.lang.String	TITLE String, Human-consumable string suitable for a plot title.
static java.lang.String	TYPICAL_MAX type double.
static java.lang.String	TYPICAL_MIN type double.
static java.lang.String	UNITS type Units.
static java.lang.String	USER_PROPERTIES Map representing additional properties used by client codes.
static java.lang.String	VALID_MAX type double.
static java.lang.String	VALID_MIN type double.
static java.lang.String	WEIGHTS_PLANE QDataSet, dataset of same geometry that indicates the weights for each point.

Method Summary

int	length() return the length of the first dimension
int	length(int i) return the length of the second dimension, for the ith element of the first dimension
int	length(int i, int j) return the length of the third dimension, for the ith element of the first dimension and jth element of the second dimension.
java.lang.Object	property(java.lang.String name) accessor for properties attached to the dataset.
java.lang.Object	property(java.lang.String name, int i) accessor for properties attached to the dataset's first index.
java.lang.Object	property(java.lang.String name, int i0, int i1) accessor for properties attached to the dataset's second index.
int	rank() returns the rank of the dataset, which is the number of indeces used to access data.
double	value(int i) rank 1 accessor.
double	value(int i0, int i1) rank 2 accessor.
double	value(int i0, int i1, int i2) rank 3 accessor.

Field Detail

DEPEND_0

static final java.lang.String DEPEND_0

type QDataSet. This dataset is a dependent parameter of the independent parameter represented in this DataSet. The tags for the DataSet's 0th index are identified by this tags dataset.

See Also:

Constant Field Values

DEPEND_1

static final java.lang.String DEPEND_1

type QDataSet. This dataset is a dependent parameter of the independent parameter represented in this DataSet. The tags for the DataSet's 1st index are identified by this tags dataset. Note this is not very mature code, and it's probably safe to assume there will be problems with this for datasets where DEPEND_1 is dependent on the 0th index. The legacy das2 DataSet API had the abstraction of tables, and this may be replaced by a bundling dimension or metadata that indicates where DEPEND_1 changes. For now, correct codes should should assume that this changes with each 0th index value, and a helper method should be introduced that finds the geometry changes.

See Also:

Constant Field Values

DEPEND_2

static final java.lang.String DEPEND_2

type QDataSet. This dataset is a dependent parameter of the independent parameter represented in this DataSet. The tags for the DataSet's 2nd index are identified by this tags dataset.

See Also:

Constant Field Values

PLANE_0

static final java.lang.String PLANE_0

type QDataSet. Correllated plane of data. An additional dependent DataSet that is correllated by the first index. Note "0" is just a count, and does not refer to the 0th index. All correllated datasets must be correllated by the first index. TODO: what about two rank 2 datasets?

See Also:

Constant Field Values

MAX_PLANE_COUNT

static final int MAX_PLANE_COUNT

this is the maximum number of allowed planes. This should be used to enumerates all the planes.

See Also:

Constant Field Values

MAX_RANK

static final int MAX_RANK

this is the highest rank supported by the library. Rank 0 is supported though Rank0DataSet. High rank datasets are supported through RankNDataSet.

See Also:

Constant Field Values

UNITS

static final java.lang.String UNITS

type Units. The dataset units, found in org.das2.units.Units.

See Also:

Constant Field Values

FILL_VALUE

static final java.lang.String FILL_VALUE

Double, Double value to be considered fill (invalid) data.

See Also:

Constant Field Values

VALID_MIN

static final java.lang.String VALID_MIN

type double. Range bounding measurements to be considered valid. Lower and Upper bounds are inclusive. FILL_VALUE should be used to make the lower bound or upper bound exclusive. Note DatumRange contains logic is exclusive on the upper bound.

See Also:

Constant Field Values

VALID_MAX

static final java.lang.String VALID_MAX

type double. Range bounding measurements to be considered valid. Lower and Upper bounds are inclusive. FILL_VALUE should be used to make the lower bound or upper bound exclusive. Note DatumRange contains logic is exclusive on the upper bound.

See Also:

Constant Field Values

TYPICAL_MIN

static final java.lang.String TYPICAL_MIN

type double. Range used to discover datasets. This should be a reasonable representation of the expected dynamic range of the dataset.

See Also:

Constant Field Values

TYPICAL_MAX

static final java.lang.String TYPICAL_MAX

type double. Range used to discover datasets. This should be a reasonable representation of the expected dynamic range of the dataset.

See Also:

Constant Field Values

SCALE_TYPE

static final java.lang.String SCALE_TYPE

String "linear" or "log"

See Also:

Constant Field Values

LABEL

static final java.lang.String LABEL

String, Concise Human-consumable label suitable for a plot label. (10 chars)

See Also:

Constant Field Values

TITLE

static final java.lang.String TITLE

String, Human-consumable string suitable for a plot title. (100 chars).

See Also:

Constant Field Values

MONOTONIC

static final java.lang.String MONOTONIC

Boolean, Boolean.TRUE if dataset is monotonically increasing. Also, the data must not contain invalid values. Generally this will be used with tags datasets.

See Also:

Constant Field Values

WEIGHTS_PLANE

static final java.lang.String WEIGHTS_PLANE

QDataSet, dataset of same geometry that indicates the weights for each point. Often weights are computed in processing, and this is where they should be stored for other routines. When the weights plane is present, routines can safely ignore the FILL_VALUE, VALID_MIN, and VALID_MAX properties, and use non-zero weight to indicate valid data. Further, averages of averages will compute accurately.

See Also:

Constant Field Values

CADENCE

static final java.lang.String CADENCE

Double, the expected distance between successive measurements where it is valid to make inferences about the data. For example, interpolation is disallowed for points 1.5*CADENCE apart. This property only makes sense with a tags dataset.

See Also:

Constant Field Values

DELTA_PLUS

static final java.lang.String DELTA_PLUS

QDataSet of rank 0 or correlated plane that limits accuracy. Integration intervals should be indicated here, as well as measurement uncertainty.

See Also:

Constant Field Values

DELTA_MINUS

static final java.lang.String DELTA_MINUS

QDataSet of rank 0 or correlated plane limits limits accuracy. Integration intervals should be indicated here, as well as measurement uncertainty.

See Also:

Constant Field Values

CACHE_TAG

static final java.lang.String CACHE_TAG

CacheTag, to be attached to tags datasets.

See Also:

Constant Field Values

RENDER_TYPE

static final java.lang.String RENDER_TYPE

Hint as to preferred rendering method. Examples include "spectrogram", "time_series", and "stack_plot"

See Also:

Constant Field Values

NAME

static final java.lang.String NAME

String a java identifier that should can be used when an identifier is needed. This is originally introduced for debugging purposes, so datasets can have a concise, meaningful name that is decoupled from the label. When NAMEs are used, properties with the same name should only refer to the named dataset.

See Also:

Constant Field Values

QUBE

static final java.lang.String QUBE

Boolean.TRUE indicates that the dataset is a "qube," meaning that all dimensions have fixed length and certain optimizations and operators are allowed.

See Also:

Constant Field Values

COORDINATE_FRAME

static final java.lang.String COORDINATE_FRAME

String representing the coordinate frame of the vector index. The units of a dataset should be EnumerationUnits which convert the data in this dimension to dimension labels that are understood in the coordinate frame label context. (E.g. X,Y,Z in GSM.)

See Also:

Constant Field Values

USER_PROPERTIES

static final java.lang.String USER_PROPERTIES

Map representing additional properties used by client codes. No interpretation is done of these properties, but they are passed around as much as possible.

See Also:

Constant Field Values

Method Detail

rank

int rank()

returns the rank of the dataset, which is the number of indeces used to access data. Only rank 1, 2, and 3 datasets are supported in the interface. When a dataset's rank is 4 or greater, it should implement the HighRankDataSet interface which affords a slice operation to reduce rank. When a dataset's rank is 0, it should implement the RankZeroDataSet interface, which has a no-argument accessor. (TODO: Note that rank 0 and rank N have very limited use, so many routines aren't coded to handle them.)

value

double value(int i)

rank 1 accessor.

Throws:

java.lang.IllegalArgumentException - if the dataset is not rank 1.

value

double value(int i0,
             int i1)

rank 2 accessor.

Throws:

java.lang.IllegalArgumentException - if the dataset is not rank 2.

value

double value(int i0,
             int i1,
             int i2)

rank 3 accessor.

Throws:

java.lang.IllegalArgumentException - if the dataset is not rank 2.

property

java.lang.Object property(java.lang.String name)

accessor for properties attached to the dataset. See final static members for example properties.

property

java.lang.Object property(java.lang.String name,
                          int i)

accessor for properties attached to the dataset's first index. These properties override (or shadow) properties attached to the dataset, and often implementations will simply return the result of the no-index accessor.

property

java.lang.Object property(java.lang.String name,
                          int i0,
                          int i1)

accessor for properties attached to the dataset's second index. These properties override (or shadow) properties attached to the dataset's first index, and often implementations will simply return the result of the one-index (or zero-index) accessor.

length

int length()

return the length of the first dimension

length

int length(int i)

return the length of the second dimension, for the ith element of the first dimension

length

int length(int i,
           int j)

return the length of the third dimension, for the ith element of the first dimension and jth element of the second dimension.