org.das2.qds

Class SemanticOps

java.lang.Object

org.das2.qds.SemanticOps

public final class SemanticOps
extends java.lang.Object

Common expressions that apply semantics to QDataSet. Introduced to reduce a lot of repeated code, but also to make it clear where semantics are being applied.

Method Summary

Modifier and Type	Method and Description
static QDataSet	bounds(QDataSet ds) return the bounds DS[ JOIN_0=x,y; BINS_1=min,maxInclusive ] of the datasets independent parameters.
static QDataSet	cadenceCheck(QDataSet tds, QDataSet ds) return a dataset with 1's where the cadence preceeding this measurement is acceptable, and 0's where there should be a break in the data.
static boolean	checkPropertyType(java.lang.String prop, java.lang.Object value, boolean throwException) verify property types.
static java.lang.Double	doubleValue(java.lang.Number value) returns the Double value of the number, preserving null and NaN.
static java.lang.String[]	getComponentLabels(QDataSet ds) return the labels for a dataset using BUNDLE_1 and DEPEND_1.
static java.lang.String[]	getComponentNames(QDataSet ds) return the labels for a bundle dataset.
static Datum	getDatum(QDataSet ds, double d) returns the value as a datum.
static QDataSet	getDependentDataSet(QDataSet ds) return the dataset that is dependent on others.
static UnitsConverter	getLooseUnitsConverter(QDataSet src, QDataSet dst) returns the UnitsConverter, or IDENTITY if the converter cannot be found and one of the two units is dimensionless.
static QDataSet	getPlanarView(QDataSet ds, java.lang.String name) returns the plane requested by name, or null if it does not exist.
static java.lang.String	getPropertyType(java.lang.String prop) return the property type expected for the property.
static QDataSet	getSimpleTableContaining(QDataSet tds, Datum x, Datum y) return the first table of the bundle containing x and y
static Units	getUnits(QDataSet ds) returns the units found in the UNITS property of the dataset, or Units.dimensionless if it is not found.
static UnitsConverter	getUnitsConverter(QDataSet src, QDataSet dst) return the UnitsConverter that will convert data from src to the units of dst.
static Datum	guessXTagWidth(QDataSet ds, QDataSet yds) return a reasonable tag width to use, or null if one cannot be guessed.
static boolean	isBins(QDataSet ds) Test for bins scheme, where BINS_1 (or BINS_0) is set.
static boolean	isBundle(QDataSet ds) Test for bundle scheme.
static boolean	isJoin(QDataSet ds) returns true if the dataset is rank 2 or greater with the first dimension a join dimension.
static boolean	isLegacyBundle(QDataSet zds) See Ops.isLegacyBundle
static boolean	isMonotonic(QDataSet ds) returns true if the dataset indicates that it is monotonically increasing.
static boolean	isRank1Bundle(QDataSet ds) returns true if the rank 1 dataset is a bundle of rank 0 datasets, or where DEPEND_0 is a labels dataset.
static boolean	isRank2Waveform(QDataSet fillDs) Test for rank 2 waveform dataset, where DEPEND_1 is offset from DEPEND_0, and the data is the waveform.
static boolean	isRank3JoinOfRank2Waveform(QDataSet ds) Test for rank 3 dataset that is a join of rank 2 waveform datasets.
static boolean	isSimpleBundleDataSet(QDataSet ds) returns true if the dataset is a bundle of rank 1 datasets.
static boolean	isSimpleTableDataSet(QDataSet ds) returns true if the dataset is the scheme of a legacy TableDataSet with only one table.
static boolean	isTableDataSet(QDataSet ds) returns true if the dataset is the scheme of a legacy TableDataSet
static boolean	isTimeSeries(QDataSet ds) returns true if the dataset is a time series.
static boolean	isYXT(QDataSet ds) YXT is a dataset where T → X → Y.
static Units	lookupTimeLengthUnit(java.lang.String s) Deprecated. use Units.lookupTimeLengthUnit
static Units	lookupTimeUnits(Datum base, Units offsetUnits) Deprecated. use Units.lookupTimeUnits
static Units	lookupTimeUnits(java.lang.String units) Deprecated. use Units.lookupTimeUnits
static Units	lookupUnits(java.lang.String sunits) Deprecated. use Units.lookupUnits
static QDataSet	trim(QDataSet ds, DatumRange xrange, DatumRange yrange) return the parts of the dataset within the bounds.
static QDataSet	weightsDataSet(QDataSet ds) return the weights dataset, possibly creating one based on VALID_MIN VALID_MAX and FILL_VALUE properties.
static QDataSet	xtagsDataSet(QDataSet ds) return the dataset containing the x tags for the dataset.
static QDataSet	ytagsDataSet(QDataSet ds) return the ytags for the simple table that is ds. rank 2 spectrogram: Z[X,Y] → Y bundle_1: ds[ :, [x,y,z] ] → y [x,y,z] → y TODO: consider that these break duck typing goal, and really need a scheme to tell it how to get the dataset.
static QDataSet	yxt() YXT is a dataset where T → X → Y.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getUnits

public static Units getUnits(QDataSet ds)

returns the units found in the UNITS property of the dataset, or Units.dimensionless if it is not found.

Parameters:

ds -

Returns:

the units found in the dataset, or Units.dimensionless.

getUnitsConverter

public static UnitsConverter getUnitsConverter(QDataSet src,
                                               QDataSet dst)

return the UnitsConverter that will convert data from src to the units of dst.

Parameters:

src - the dataset from which we get the original units.

dst - the dataset from which we get the destination units.

Returns:

the UnitsConverter

Throws:

java.lang.IllegalArgumentException

getLooseUnitsConverter

public static UnitsConverter getLooseUnitsConverter(QDataSet src,
                                                    QDataSet dst)

returns the UnitsConverter, or IDENTITY if the converter cannot be found and one of the two units is dimensionless.

Parameters:

src - the dataset from which we get the original units.

dst - the dataset from which we get the destination units.

Returns:

the UnitsConverter

Throws:

InconvertibleUnitsException - when it just can't be done (EnumerationUnits and Ratiometric)

getComponentNames

public static java.lang.String[] getComponentNames(QDataSet ds)

return the labels for a bundle dataset. For a rank 2 bundle, this will be found in BUNDLE_1, or legacy ones may have nominal data for DEPEND_1. For a rank 1 bundle this will be BUNDLE_0.

Parameters:

ds - rank 1 or rank 2 bundle.

Returns:

the column names.

getComponentLabels

public static java.lang.String[] getComponentLabels(QDataSet ds)

return the labels for a dataset using BUNDLE_1 and DEPEND_1. If BUNDLE_1 is defined and contains a LABEL, then it is used, otherwise a string value of the data is used, supporting legacy bundles, and if no DEPEND_1 is found then use the NAME properties from the bundle, or "ch_i" for each channel.

Parameters:

ds - the dataset, with a BUNDLE_1 or DEPEND_1 dimension which could be used.

Returns:

labels for each bundled dataset.

lookupUnits

public static Units lookupUnits(java.lang.String sunits)

Deprecated. use Units.lookupUnits

lookupUnits canonical units object, or allocate one. Examples include:

• "nT" where it's already allocated,
• "apples" where it allocates a new one, and
• "seconds since 2011-12-21T00:00" where it uses lookupTimeUnits.

Parameters:

sunits - string identifier.

Returns:

canonical units object.

lookupTimeLengthUnit

public static Units lookupTimeLengthUnit(java.lang.String s)
                                  throws java.text.ParseException

Deprecated. use Units.lookupTimeLengthUnit

return canonical das2 unit for colloquial time.

Parameters:

s -

Returns:

Throws:

java.text.ParseException

lookupTimeUnits

public static Units lookupTimeUnits(java.lang.String units)
                             throws java.text.ParseException

Deprecated. use Units.lookupTimeUnits

lookupUnits canonical units object, or allocate one. If one is allocated, then parse for "<unit> since <datum>" and add conversion to "microseconds since 2000-001T00:00" (us2000). Note leap seconds are ignored in the returned units, so each day is 86400 seconds long.

Parameters:

units - string like "microseconds since 2000-001T00:00"

Returns:

a units object that implements.

Throws:

java.text.ParseException

lookupTimeUnits

public static Units lookupTimeUnits(Datum base,
                                    Units offsetUnits)

Deprecated. use Units.lookupTimeUnits

lookupUnits canonical units object, or allocate one. If one is allocated, then parse for "<unit> since <datum>" and add conversion to "microseconds since 2000-001T00:00." Note leap seconds are ignored!

Parameters:

base - the base time, for example 2000-001T00:00.

offsetUnits - the offset units for example microseconds. Positive values of the units will be since the base time.

Returns:

the unit.

isRank1Bundle

public static boolean isRank1Bundle(QDataSet ds)

returns true if the rank 1 dataset is a bundle of rank 0 datasets, or where DEPEND_0 is a labels dataset.

Parameters:

ds - a dataset

Returns:

if rank 1 bundle or rank 1 having labels dataset for DEPEND_0.

isBundle

public static boolean isBundle(QDataSet ds)

Test for bundle scheme. Returns true if the BUNDLE_1 is set.

Parameters:

ds -

Returns:

true if the dataset is a bundle

isRank2Waveform

public static boolean isRank2Waveform(QDataSet fillDs)

Test for rank 2 waveform dataset, where DEPEND_1 is offset from DEPEND_0, and the data is the waveform. Other rules include:

• DEPEND_1 must be at least 128 elements long.
• DEPEND_1 must not be dimensionless.
• if DEPEND_1 is in the same units as DEPEND_0, then DEPEND_0 can be ignored.

Parameters:

fillDs -

Returns:

isRank3JoinOfRank2Waveform

public static boolean isRank3JoinOfRank2Waveform(QDataSet ds)

Test for rank 3 dataset that is a join of rank 2 waveform datasets.

Parameters:

ds -

Returns:

isLegacyBundle

public static boolean isLegacyBundle(QDataSet zds)

See Ops.isLegacyBundle

Parameters:

zds -

Returns:

isBins

public static boolean isBins(QDataSet ds)

Test for bins scheme, where BINS_1 (or BINS_0) is set. This is where a two-element index is min, max. Note the BINS dimension must be the last index of the QDataSet.

Parameters:

ds -

Returns:

isMonotonic

public static boolean isMonotonic(QDataSet ds)

returns true if the dataset indicates that it is monotonically increasing. See DataSetUtil.isMonotonic.

Parameters:

ds -

Returns:

isJoin

public static boolean isJoin(QDataSet ds)

returns true if the dataset is rank 2 or greater with the first dimension a join dimension. Note this does not return true for implicit joins, where JOIN_0 is not set.

Parameters:

ds -

Returns:

getPlanarView

public static QDataSet getPlanarView(QDataSet ds,
                                     java.lang.String name)

returns the plane requested by name, or null if it does not exist. If the name is PLANE_i, then return PLANE_i, otherwise return the dataset with this name. Note QDataSet has the rule that if PLANE_i is null, then all PLANE_(i+1) must also be null.

Parameters:

ds -

name -

Returns:

weightsDataSet

public static QDataSet weightsDataSet(QDataSet ds)

return the weights dataset, possibly creating one based on VALID_MIN VALID_MAX and FILL_VALUE properties. The weights dataset will have value zero where the data is invalid, and a non-zero weight where it is valid. DataSets may also contain a weights table with relative weights, but this is not uniformly supported. Note: this uses QDataSet.WEIGHTS_PLANE Note: calls org.das2.qds.DataSetUtil.weightsDataSet.

Parameters:

ds -

Returns:

QDataSet with same geometry containing zeros and non-zeros.

See Also:

which is equivalent, which detects for gaps in cadence.

guessXTagWidth

public static Datum guessXTagWidth(QDataSet ds,
                                   QDataSet yds)

return a reasonable tag width to use, or null if one cannot be guessed.

Parameters:

ds - the dataset containing data with a cadence.

yds - null or a dataset that may contain fill.

Returns:

xtagsDataSet

public static QDataSet xtagsDataSet(QDataSet ds)

return the dataset containing the x tags for the dataset. This is QDataSet.DEPEND_0, or if that's null then IndexGenDataSet(ds.length). For a bundle, this is just the 0th dataset. For a join, this is a join of the xtags datasets of each dataset.

Parameters:

ds -

Returns:

ytagsDataSet

public static QDataSet ytagsDataSet(QDataSet ds)

return the ytags for the simple table that is ds.

• rank 2 spectrogram: Z[X,Y] → Y
• bundle_1: ds[ :, [x,y,z] ] → y
• [x,y,z] → y

TODO: consider that these break duck typing goal, and really need a scheme to tell it how to get the dataset.

Parameters:

ds - the dataset

Returns:

the ytags

getSimpleTableContaining

public static QDataSet getSimpleTableContaining(QDataSet tds,
                                                Datum x,
                                                Datum y)

return the first table of the bundle containing x and y

Parameters:

tds -

x -

y -

Returns:

getDependentDataSet

public static QDataSet getDependentDataSet(QDataSet ds)

return the dataset that is dependent on others. For a bundle, we use DataSetOps.unbundleDefaultDataSet

Parameters:

ds -

Returns:

bounds

public static QDataSet bounds(QDataSet ds)

return the bounds DS[ JOIN_0=x,y; BINS_1=min,maxInclusive ] of the datasets independent parameters. This is only implemented for:

rank 2 Tables	extent(X),extent(Y) and Z is not represented
rank 3 array of tables	extent(X),extent(Y) and Z is not represented
rank 1 Y(X)	extent(X),extent(Y)
not for rank 2 bundle dataset
not for rank 1 bundle dataset

The zeroth dimension will be the physical dimension of the DEPEND_0 values. Or said another way:

bounds[0,0]= X min	bounds[0,1] = X max	bounds.slice(0) is the extent of X
bounds[1,0]= Y min	bounds[1,1] = Y max	bounds.slice(1) is the extent of Y

Parameters:

ds - rank 2 dataset with BINS_1="min,maxInclusive"

Returns:

Throws:

java.lang.IllegalArgumentException - when the dataset scheme is not supported

isTableDataSet

public static boolean isTableDataSet(QDataSet ds)

returns true if the dataset is the scheme of a legacy TableDataSet

Parameters:

ds -

Returns:

isSimpleTableDataSet

public static boolean isSimpleTableDataSet(QDataSet ds)

returns true if the dataset is the scheme of a legacy TableDataSet with only one table. Note "Tables" have just one X unit and one Y unit, no bundles. Consider: rule about "duck typing": rules like !Ops.isBundle break this because it requires to be a simpleTable, you cannot be a bundle. LANL rich ASCII allows datasets to be both bundles and simple tables.

Parameters:

ds -

Returns:

isSimpleBundleDataSet

public static boolean isSimpleBundleDataSet(QDataSet ds)

returns true if the dataset is a bundle of rank 1 datasets. If no dependence is declared, it is assumed that the first one or two datasets are the independent datasets, and the last is the dependent.

    X,Y   -->  Y(X)
    X,Y,Z -->  Z(X,Y)

Parameters:

ds -

Returns:

isTimeSeries

public static boolean isTimeSeries(QDataSet ds)

returns true if the dataset is a time series. This is either something that has DEPEND_0 as a dataset with time location units, or a join of other datasets that are time series.

Parameters:

ds -

Returns:

doubleValue

public static java.lang.Double doubleValue(java.lang.Number value)

returns the Double value of the number, preserving null and NaN.

Parameters:

value -

Returns:

getDatum

public static Datum getDatum(QDataSet ds,
                             double d)

returns the value as a datum. Note this should be used with reservation, this is not very efficient when the operation is done many times.

Parameters:

ds - dataset providing the UNITS and VALID_MIN, VALID_MAX and FILL_VALUE.

d - the double.

Returns:

a datum representing the value.

trim

public static QDataSet trim(QDataSet ds,
                            DatumRange xrange,
                            DatumRange yrange)

return the parts of the dataset within the bounds. This assumes how the data is visualized, so for example see SemanticOps.xtagsDataSet for which dimensions correspond to x and y.

Parameters:

ds - the rank 1 or more dataset, including joins.

xrange - the range or null if no trimming should be done

yrange - the range or null if no trimming should be done

Returns:

the trimmed dataset.

isYXT

public static boolean isYXT(QDataSet ds)

YXT is a dataset where T → X → Y. This pattern comes up all the time and we need to identify it. Ideally the data would be represented as T &rarr (X;Y).

Parameters:

ds -

Returns:

yxt

public static QDataSet yxt()

YXT is a dataset where T → X → Y. This pattern comes up all the time and we need to identify it. Ideally the data would be represented as T &rarr (X;Y).

Returns:

a dataset with this form.

cadenceCheck

public static QDataSet cadenceCheck(QDataSet tds,
                                    QDataSet ds)

return a dataset with 1's where the cadence preceeding this measurement is acceptable, and 0's where there should be a break in the data. For example, here's some pseudocode:

   findex= Ops.interpolate( xds, x )
   cadenceCheck= cadenceCheck(xds)
   r= where( cadenceCheck[floor(findex)] eq 0 )
   x[r]= fill

Presently this just uses guessXTagWidth to get the cadence, but this may allow a future version to support mode changes. The result is a dataset with the same length, and the zeroth element is always 1.

Parameters:

tds - rank 1 dataset of length N.

ds - dataset dependent on tds and used to detect valid measurements, or null.

Returns:

dataset with length N

See Also:

which checks for fill and valid_min, valid_max.

checkPropertyType

public static boolean checkPropertyType(java.lang.String prop,
                                        java.lang.Object value,
                                        boolean throwException)

verify property types. For example, that UNITS is a org.das2.datum.Units, etc. Returns true for unrecognized property names (future expansion) and null. If throwException is true, then an IllegalArgumentException is thrown.

Parameters:

prop - the property name, e.g. QDataSet.CADENCE

value - the candidate value for the property.

throwException - if true, throw descriptive exception instead of returning false.

Returns:

true if the property type is okay.

getPropertyType

public static java.lang.String getPropertyType(java.lang.String prop)

return the property type expected for the property.

Parameters:

prop -

Returns:

QDataSet, String, Number, Units, or CacheTag