## org.das2.qds.DataSetUtil

Utilities for QDataSet, such as conversions from various forms to QDataSet, and doing a units conversion. TODO: DataSetUtil, DataSetOps, and org.virbo.dsops.Ops have become blurred over the years. These should either be combined or new mission statements need to be created.

## DataSetUtil( )

## PROPERTY_TYPE_STRING

## PROPERTY_TYPE_NUMBER

## PROPERTY_TYPE_BOOLEAN

## PROPERTY_TYPE_MAP

## PROPERTY_TYPE_QDATASET

## PROPERTY_TYPE_CACHETAG

## PROPERTY_TYPE_UNITS

## addContext

addContext( org.das2.qds.MutablePropertyDataSet ds, QDataSet cds ) → void

adds the rank 0 dataset (a Datum) to the dataset's properties, after all the other CONTEXT_<i> properties.

### Parameters

ds - a MutablePropertyDataSet
cds - a QDataSet

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## addContext

addContext( java.util.Map props, QDataSet cds ) → void

adds the rank 0 dataset (a Datum) to the properties, after all the other CONTEXT_<i> properties.

### Parameters

props - the properties
cds - the context in a rank 0 dataset

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## addQube

addQube( org.das2.qds.MutablePropertyDataSet ds ) → void

add QUBE property to dataset, maybe verifying that it is a qube. This is intended to reduce code that builds datasets, not to verify that a dataset is a qube.

### Parameters

ds - the dataset

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## as2DArrayOfDoubles

as2DArrayOfDoubles( QDataSet d ) → double[][]

convert the QDataSet to an array. Units and fill are ignored...

### Parameters

d - the rank 2 dataset

### Returns:

2-D array of doubles
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asArrayOfDoubles

asArrayOfDoubles( QDataSet d ) → double[]

convert the QDataSet to an array. Units and fill are ignored...

### Parameters

d - the rank 1 dataset.

### Returns:

an array of doubles
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( org.das2.datum.DatumVector dv ) → QDataSet

return the rank 1 dataset equivalent to the DatumVector

### Parameters

dv - a DatumVector

### Returns:

rank 1 QDataSet.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( DatumRange dr ) → QDataSet

return a 2-element rank 1 bins dataset with BINS_0=QDataSet.VALUE_BINS_MIN_MAX

### Parameters

dr - a Das2 DatumRange

### Returns:

a 2-element rank 1 bins dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( double d, Units u ) → org.das2.qds.DRank0DataSet

create a rank 0 dataset from the double and units.

### Parameters

d - a double, or Double.NaN
u - null or the units of d.

### Returns:

rank 0 dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( double d ) → org.das2.qds.DRank0DataSet

create a dimensionless rank 0 dataset from the double.

### Parameters

d - a double, or Double.NaN

### Returns:

rank 0 dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( Datum d ) → org.das2.qds.DRank0DataSet

create a rank 0 dataset from the Datum.

### Parameters

d - a datum

### Returns:

rank 0 dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( Object arr ) → QDataSet

convert java arrays into QDataSets.

### Parameters

arr - 1-D or 2-D array of java native type.

### Returns:

Rank 1 or Rank 2 dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( Object x, Object y ) → QDataSet

convert java arrays into QDataSets.

### Parameters

x - array, number, or String parsed with DatumUtil.parse
y - array, number, or String parsed with DatumUtil.parse

### Returns:

dataset

### See Also:

org.das2.datum.DatumUtil#parse(java.lang.String)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDataSet

asDataSet( Object x, Object y, Object z ) → QDataSet

convert java types into QDataSets.

### Parameters

x - array, number, or String parsed with DatumUtil.parse
y - array, number, or String parsed with DatumUtil.parse
z - array, number, or String parsed with DatumUtil.parse

### Returns:

dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDatum

asDatum( org.das2.qds.RankZeroDataSet ds ) → Datum

### Parameters

ds - a RankZeroDataSet

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDatum

asDatum( QDataSet ds ) → Datum

convert the rank 0 QDataSet to a Datum.

### Parameters

ds - rank 0 dataset.

### Returns:

Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDatumRange

asDatumRange( QDataSet ds, boolean sloppy ) → DatumRange

return the DatumRange equivalent of this 2-element, rank 1 bins dataset.

### Parameters

ds - a rank 1, 2-element bins dataset.
sloppy - true indicates we don't check BINS_0 property.

### Returns:

an equivalent DatumRange
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDatumRange

asDatumRange( QDataSet ds ) → DatumRange

return the DatumRange equivalent of this 2-element, rank 1 bins dataset. This uses the sloppy mode, which does not check the BINS_0 property.

### Parameters

ds - a two-element dataset

### Returns:

a DatumRange.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## asDatumVector

asDatumVector( QDataSet ds ) → org.das2.datum.DatumVector

return DatumVector, which is a 1-d array of Datums.

### Parameters

ds - a rank 1 QDataSet

### Returns:

a DatumVector
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bestFormatter

bestFormatter( QDataSet datums ) → org.das2.datum.format.DatumFormatter

return a DatumFormatter that can accurately format all of the datums in the dataset. The goal is to identify a formatter which is also efficient, and doesn't waste an excess of digits. This sort of code is often needed, and is also found in:

- QStream--where ASCII mode needs efficient representation

TODO: make one code for this. TODO: there also needs to be an optional external context ('2017-03-15') so that 'HH:mm' is a valid response. See sftp://jbf@jfaden.net/home/jbf/ct/autoplot/script/development/bestDataSetFormatter.jy

### Parameters

datums - a rank 1 dataset, or if rank>1, then return the formatter for a slice.

### Returns:

DatumFormatter for the dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## binarySearch

binarySearch( QDataSet ds, double key, int low, int high ) → int

perform a binary search for key within ds, constraining the search to between low and high.

### Parameters

ds - a rank 1 monotonic dataset.
key - the value to find.
low - an int
high - an int

### Returns:

a positive index of the found value or -index-1 the insertion point.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bundleNames

bundleNames( QDataSet ds ) → String[]

return the name for each column of the bundle. This simply calls SemanticOps.getComponentNames.

### Parameters

ds - dataset, presumably with BUNDLE_1 property.

### Returns:

array of names.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bundleWeightsDataSet

bundleWeightsDataSet( QDataSet ds ) → QDataSet

special weightsDataSet for when there is a bundle, and each component could have its own FILL_VALID and VALID_MAX. Each component gets its own weights dataset in a JoinDataSet.

### Parameters

ds - rank 2 bundle dataset

### Returns:

dataset with the same geometry but a weightsDataSet of each bundled dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## canonizeFill

canonizeFill( QDataSet ds ) → org.das2.qds.WritableDataSet

Iterate through the dataset, changing all points outside of validmin, validmax and with zero weight to fill=-1e31. VALID_MIN and VALID_MAX properties are cleared, and FILL_VALUE is set to -1e31. If the dataset is writable, then the dataset is modified.

### Parameters

ds - rank N QUBE dataset.

### Returns:

ds with same geometry as ds.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## checkListOfIndeces

checkListOfIndeces( QDataSet ds, QDataSet indices ) → void

verify that the indeces really are indeces, and a warning may be printed if the indeces don't appear to match the array by looking at the MAX_VALUE property of the indeces.

### Parameters

ds - the dataset.
indices - the indeces which refer to a subset of dataset.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## checkQube

checkQube( QDataSet ds ) → boolean

check to see if a dataset really is a qube, even if there is a rank 2 dep1. Note this ignores BUNDLE_1 property if there is a DEPEND_1. This was motivated by the fftPower routine, which returned a rank 2 DEPEND_1, but is typically constant, and RBSP/ECT datasets that often have rank 2 DEPEND_1s that are constant. This will putProperty(QDataSet.QUBE,Boolean.TRUE) when the dataset really is a qube, or Boolean.FALSE if is clearly not a qube.

### Parameters

ds - any dataset

### Returns:

true if the dataset really is a qube.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## closest

closest( QDataSet ds, double d, int guess ) → int

return the index of the closest value in ds to d, using guess as a starting point. This implementation ignores guess, but wise clients will supply it as a parameter.

### Parameters

ds - a rank 1, monotonic dataset.
d - the value to find.
guess - a guess at a close index, or -1 if no guess should be made. In this case, a binary search is performed.

### Returns:

index of the closest.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## closestIndex

closestIndex( QDataSet ds, Datum datum ) → int

returns the index of the closest index in the data. This supports rank 1 datasets, and rank 2 bins datasets where the bin is min,max.

### Parameters

ds - tags dataset
datum - the location to find

### Returns:

the index of the closest point.
[search for examples] [view on GitHub] [view on old javadoc] [view source]
closestIndex( QDataSet table, double x, Units units ) → int [view source]

## contextAsString

contextAsString( QDataSet ds ) → String

provide the context as a string, for example to label a plot. The dataset CONTEXT_i properties are inspected, each of which must be one of:

- rank 0 dataset
- rank 1 bins dataset
- rank 1 bundle

Here a comma is used as the delimiter.

### Parameters

ds - the dataset containing context properties which are rank 0 datums or rank 1 datum ranges.

### Returns:

a string describing the context.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## contextAsString

contextAsString( QDataSet ds, String delim ) → String

provide the context as a string, for example to label a plot. The dataset CONTEXT_i properties are inspected, each of which must be one of:

- rank 0 dataset
- rank 1 bins dataset
- rank 1 bundle

### Parameters

ds - the dataset containing context properties which are rank 0 datums or rank 1 datum ranges.
delim - the delimiter between context elements, such as "," or "!c"

### Returns:

a string describing the context.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## convertTo

convertTo( QDataSet ds, Units u ) → QDataSet

convert the dataset to the given units.

### Parameters

ds - the dataset
u - new Units

### Returns:

equivalent dataset with the new units.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## copyDimensionProperties

copyDimensionProperties( QDataSet source, org.das2.qds.MutablePropertyDataSet dest ) → void

Copy over all the dimension properties, including: UNITS, FORMAT, SCALE_TYPE, TYPICAL_MIN, TYPICAL_MAX, VALID_MIN, VALID_MAX, FILL_VALUE, NAME, LABEL, TITLE, USER_PROPERTIES These are dimension properties, as opposed to structural see dimensionProperties() for a list of dimension properties. TODO: This DOES NOT support join datasets yet.

### Parameters

source - a QDataSet
dest - a MutablePropertyDataSet

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## correlativeProperties

correlativeProperties( ) → String[]

properties that go along with the zeroth index. These are all QDataSets with dimensions compatible with the datasets. If you trim the dataset, then these must be trimmed as well.

### Returns:

the properties that go along with the zeroth index
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## courserCadence

courserCadence( org.das2.qds.RankZeroDataSet yTagWidth0, org.das2.qds.RankZeroDataSet yTagWidth1 ) → org.das2.qds.RankZeroDataSet

return the courser cadence of the two cadences. Das2's AverageTableRebinner needs to get the coursest of all the ytags.

### Parameters

yTagWidth0 - rank 0 dataset that is one cadence (e.g. 84 sec)
yTagWidth1 - rank 0 dataset that is the second cadence (e.g. 70 sec)

### Returns:

the courser of the two cadences. (e.g. 84 sec)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## dimensionProperties

dimensionProperties( ) → String[]

return the list of properties that pertain to the dimension that dataset values exist. These are the properties that survive through most operations. For example, if you flattened the dataset, what properties would still exist? If you shuffled the data? These are not structural properties like DEPEND_0, BUNDLE_1, etc. Note that BUNDLE_1 will carry dimension properties as well.

### Returns:

a String[]
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## firstValidPoint

firstValidPoint( QDataSet ds ) → QDataSet

returns the first valid point found in a dataset, or null if no such point is found.

### Parameters

ds - non-bundle dataset.

### Returns:

rank zero dataset containing the first valid point, or null.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( QDataSet ds ) → String

return a human-readable string representing the dataset

### Parameters

ds - the dataset to represent

### Returns:

a human-readable string
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( QDataSet ds, boolean showContext ) → String

return a human-readable string representing the dataset

### Parameters

ds - the dataset to represent
showContext - show the context property (@slice2=1) if present and ds is rank0.

### Returns:

a human-readable string

### See Also:

toString(QDataSet)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## gcd

gcd( QDataSet ds, QDataSet d, QDataSet limit ) → QDataSet

return the greatest common divisor, which is the unit for which all elements in the dataset are integer multiples of the result. This works on continuous data, however, so limit is used to determine the fuzz allowed. TODO: this needs review and is not for production use.

### Parameters

ds - any dataset
d - rank 0 dataset, first factor for the dataset, error is used to detect non-zero significance.
limit - rank 0 dataset, the resolution for which data is considered equal, and this limit should be greater than numerical precision.

### Returns:

the greatest common divisor.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## gcd

gcd( QDataSet ds, QDataSet limit ) → QDataSet

return the greatest common divisor, which is the unit for which all elements in the dataset are integer multiples of the result. This works on continuous data, however, so limit is used to determine the fuzz allowed. TODO: this needs review and is not for production use.

### Parameters

ds - any dataset
limit - the resolution for which data is considered equal. The result will be an integer multiple of this.

### Returns:

the greatest common divisor.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getCadenceWaveform

getCadenceWaveform( QDataSet ds ) → org.das2.qds.RankZeroDataSet

return the cadence between measurements of a waveform dataset. This is different than the cadence typically quoted, which is the cadence between waveform records.

### Parameters

ds - a QDataSet

### Returns:

the cadence, possibly null.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getContext

getContext( QDataSet ds ) → QDataSet

collect the context for the dataset. This will be a rank 2 join of scalars or ranges, so CONTEXT_0 will be in the zeroth index of the result. Rank 0 CONTEXT values are joined to make them rank 1.

### Parameters

ds - the dataset

### Returns:

a rank 2 join of 1- and 2-element datasets.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDimensionProperties

getDimensionProperties( QDataSet ds, java.util.Map def ) → java.util.Map

return just the properties attached to the dataset, like UNITS and SCALE_TYPE, and not like DEPEND_x, etc.

### Parameters

ds - the dataset
def - default values or null.

### Returns:

a map of all the properties.

### See Also:

dimensionProperties()
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getNextIndex

getNextIndex( QDataSet ds, Datum datum ) → int

returns the first column that is after the given datum. Note the if the datum identifies (==) an xtag, then the previous column is returned.

### Parameters

ds - the dataset
datum - a datum in the same units of the dataset.

### Returns:

an int
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getNextIndexStrict

getNextIndexStrict( QDataSet ds, Datum datum ) → java.lang.Integer

Returns the index of the value which is greater than the value less of the datum. Note for rank 2 bins, the first bin which has an beginning less than the datum.

### Parameters

ds - rank 1 monotonic tags, or rank 2 bins.
datum - a datum of the same or convertible units.

### Returns:

the index, or null (None).
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getNextInterval

getNextInterval( QDataSet ds, DatumRange dr0 ) → DatumRange

return the next interval (typically time) containing data, centered on data, with the roughly the same width.

### Parameters

ds - the dataset
dr0 - the current interval

### Returns:

the next interval
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getPreviousIndex

getPreviousIndex( QDataSet ds, Datum datum ) → int

returns the first index that is before the given datum, or zero if no data is found before the datum. PARV! if the datum identifies (==) an xtag, then the previous column is returned.

### Parameters

ds - the dataset
datum - a datum in the same units of the dataset.

### Returns:

the index
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getPreviousIndexStrict

getPreviousIndexStrict( QDataSet ds, Datum datum ) → java.lang.Integer

Returns the index of the value which is less than the value less of the datum. Note for rank 2 bins, the first bin which has an end less than the datum.

### Parameters

ds - rank 1 monotonic tags, or rank 2 bins.
datum - a datum of the same or convertible units.

### Returns:

the index, or null (None).
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getPreviousInterval

getPreviousInterval( QDataSet ds, DatumRange dr0 ) → DatumRange

return the previous interval (typically time) containing data, centered on data, with the roughly the same width.

### Parameters

ds - the dataset
dr0 - the current interval

### Returns:

the previous interval
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getProperties

getProperties( QDataSet ds, String[] names, java.util.Map def ) → java.util.Map

return the properties listed, using the defaults if provided. See dimensionProperties(), globalProperties().

### Parameters

ds - dataset source of the properties.
names - array of names
def - defaults, or null if no defaults are to be used.

### Returns:

map of the properties.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getProperties

getProperties( QDataSet ds, java.util.Map def ) → java.util.Map

gets all the properties of the dataset. This is a shallow copy of properties.

### Parameters

ds - the dataset
def - an empty map.

### Returns:

the properties.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getProperties

getProperties( QDataSet ds ) → java.util.Map

gets all the properties of the dataset. This is a shallow copy of properties.

### Parameters

ds - the dataset

### Returns:

the properties

### See Also:

putProperties(java.util.Map, org.das2.qds.MutablePropertyDataSet)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getProperty

getProperty( QDataSet ds, String name, Object deflt ) → Object

### Parameters

ds - a QDataSet
name - a String
deflt - an Object

### Returns:

java.lang.Object
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getPropertyClass

getPropertyClass( String name ) → java.lang.Class

return the class for the property, to support Jython.

### Parameters

name - the property name, e.g. QDataSet.TITLE

### Returns:

String.class

### See Also:

getPropertyType(java.lang.String) //TODO: super inefficient, this needs to be rewritten as switch
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getPropertyType

getPropertyType( String name ) → String

return the type of the property, as a string to support use in Jython: String,Number,Boolean,Map,QDataSet,CacheTag,Units

### Parameters

name - the property name

### Returns:

the property type or null if the name is not recognized

### See Also:

getPropertyClass(java.lang.String)
QDataSet
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getStringValue

getStringValue( QDataSet ds, double value, int i ) → String

return the value, which gets units from index i. from rank 1 bundle dataset.

### Parameters

ds - the dataset providing units and format information.
value - double value from the dataset
i - the index of the value

### Returns:

a String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getStringValue

getStringValue( QDataSet yds, double value ) → String

return the string value of the double, considering QDataSet.FORMAT, the units and the value. formatting is done assuming someone else will report the units. If the value is invalid, then "***" is returned.

### Parameters

yds - the dataset, maybe with FORMAT and VALID_MIN, etc.
value - the double from the dataset (presumably).

### Returns:

human-readable string representation.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getStringValue

getStringValue( QDataSet ds ) → String

Return just the value encoded as richly as possible, for human consumption. Example results of this include "9.5 km" "Chicago" or "fill" see also format(ds), toString(ds), getStringValue(ds,d)

### Parameters

ds - a QDataSet

### Returns:

just the value, without labels.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getUserProperty

getUserProperty( QDataSet ds, String name ) → Object

return the "User" property, which allow for extensions of the data model that aren't used. This returns the property "name" under the name USER_PROPERTIES, which must either be null or a Map<String,Object>.

### Parameters

ds - The dataset containing the property.
name - The name of the user property.

### Returns:

an Object
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## globalProperties

globalProperties( ) → String[]

properties that describe the dataset itself, rather than those of a dimension or structural properties.

### Returns:

the properties that describe the dataset itself
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## guessCadence

guessCadence( QDataSet xds, QDataSet yds ) → QDataSet

return the cadence for the given x tags. The goal will be a rank 0 dataset that describes the intervals, but this will also return a rank 1 dataset when multiple cadences are found. The yds values for each xds value can also be set, specifying where the x values can be ignored because of fill. TODO: this needs review.

### Parameters

xds - the x tags, which may not contain fill values for non-null result.
yds - the y values, which if non-null is only used for fill values. This is only used if it is rank 1.

### Returns:

rank 0 or rank 1 dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## guessCadence

guessCadence( QDataSet xds, QDataSet yds, QDataSet zds ) → QDataSet

return the cadence in X for the given X tags and Y tags. The Y tags can repeat, and when this is the case, the X cadence will be span between successive X tags with the same Y tag. The goal will be a rank 0 dataset that describes the intervals, but this will also return a rank 1 dataset when multiple cadences are found.

### Parameters

xds - the x tags, which may not contain fill values for non-null result.
yds - the y values, which may not contain fill values for non-null result.
zds - the z values

### Returns:

rank 0 or rank 1 dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## guessCadenceNew

guessCadenceNew( QDataSet xds, QDataSet yds ) → org.das2.qds.RankZeroDataSet

returns a rank 0 dataset indicating the cadence of the dataset. Using a dataset as the result allows the result to indicate SCALE_TYPE and UNITS. History:

- 2011-02-21: keep track of repeat values, allowing zero to be considered either mono increasing or mono decreasing
- 2011-02-21: deal with interleaved fill values, keeping track of last valid value.

### Parameters

xds - the x tags, which may not contain fill values for non-null result.
yds - the y values, which if non-null is only used for fill values. This is only used if it is rank 1.

### Returns:

null or the cadence in a rank 0 dataset. The following may be properties of the result:

- SCALE_TYPE may be "log"
- UNITS will be a ratiometric unit when the SCALE_TYPE is log, and will be the offset unit for interval units like Units.t2000.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

## indexGenDataSet

indexGenDataSet( int n ) → org.das2.qds.MutablePropertyDataSet

creates a dataset of integers 0,1,2,...,n-1.

### Parameters

n - the bound

### Returns:

the dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## inferBins

inferBins( QDataSet yds ) → QDataSet

This is the one code to infer bin boundaries when only the centers are available. This uses centers of adjacent data, and extrapolates to get the edge boundaries to create an acceptable limit. When the data is log-spaced, the centers are done in the ratiometric space. Small (<1000 element) datasets will be sorted if necessary.

### Parameters

yds - rank 1 dataset.

### Returns:

rank 2 bins dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## inferBinsRank2

inferBinsRank2( QDataSet ydss ) → QDataSet[]

infer the bins for the rank 2 ytags. This was first used with Juno high-rate data, where the ytags follow the FCE implied by the magnetic field detector.

### Parameters

ydss - rank 2 dataset[n,m]

### Returns:

two-element array of rank 2 datasets[n,m], where 0 is the min and 1 is the max.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isConstant

isConstant( QDataSet ds ) → boolean

return true if each record of DEPEND_0 is the same. Rank 0 datasets are trivially constant. TODO: ds.slice(i) can be slow because equivalent does so much with the metadata.

### Parameters

ds - any dataset

### Returns:

true if the dataset doesn't change with DEPEND_0 or is rank 0.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isConstant

isConstant( QDataSet ds, int dim ) → boolean

return true if each record of DEPEND_i is the same. Rank 0 datasets are trivially constant.

### Parameters

ds - any dataset
dim - the index

### Returns:

true if the dataset doesn't change with DEPEND_0 or is rank 0.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isDataAt

isDataAt( QDataSet ds, Datum t ) → boolean

is data found at the time t, or might it be within a gap in the data?

### Parameters

ds - any time-series dataset
t - the time

### Returns:

true if t is within data.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isDimensionProperty

isDimensionProperty( String name ) → boolean

return true if the property name is a valid dimension property like "UNITS" or "FORMAT". See dimensionProperties().

### Parameters

name - property name to test

### Returns:

true if the property is a dimension property.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isInheritedProperty

isInheritedProperty( String prop ) → boolean

true if the property is one that is global and is relevant throughout the dataset, such as a title or the units. property( "TITLE",0,0 ) often returns property("TITLE"), but property( "DEPEND_0",0,0 ) should never return property("DEPEND_0"). This is false, for example, for DEPEND_1.

### Parameters

prop - the property name.

### Returns:

true if the property is inherited
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isLogSpacing

isLogSpacing( QDataSet ds ) → boolean

return true if the data appears to have log spacing. The data is assumed to be monotonically increasing or decreasing.

### Parameters

ds - rank 1 dataset.

### Returns:

true if the data is roughly log spaced.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isMonotonic

isMonotonic( QDataSet ds ) → boolean

returns true if the dataset is monotonically increasing. If the dataset has the MONOTONIC property set to Boolean.TRUE, believe it. The data can contain repeated values. An empty dataset is not monotonic. We now use a weights dataset to more thoroughly check for fill. The dataset may contain fill data, only the non-fill portions are considered.

### Parameters

ds - the rank 1 dataset with physical units.

### Returns:

true when the dataset is monotonically increasing.

### See Also:

QDataSet#MONOTONIC
org.das2.qds.ArrayDataSet#monotonicSubset(org.das2.qds.ArrayDataSet)
isMonotonicAndIncreasing(QDataSet)
Ops#ensureMonotonic
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isMonotonicAndIncreasing

isMonotonicAndIncreasing( QDataSet ds ) → boolean

returns true if the dataset is monotonically increasing and does not contain repeat values. An empty dataset is not monotonic. The dataset may contain fill data, only the non-fill portions are considered.

### Parameters

ds - the rank 1 dataset with physical units.

### Returns:

true when the dataset is monotonically increasing.

### See Also:

QDataSet#MONOTONIC
org.das2.qds.ArrayDataSet#monotonicSubset(org.das2.qds.ArrayDataSet)
isMonotonic(QDataSet)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isMonotonicAndIncreasingQuick

isMonotonicAndIncreasingQuick( QDataSet ds ) → boolean

quickly determine, with high accuracy, if data is monotonic. This should be a constant-time operation, and be extremely unlikely to fail.

### Parameters

ds - a QDataSet

### Returns:

true if the data does pass quick tests for monotonic increasing.

### See Also:

isMonotonicAndIncreasing(QDataSet)
QDataSet#MONOTONIC
Ops#ensureMonotonicAndIncreasingWithFill(QDataSet)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isMonotonicQuick

isMonotonicQuick( QDataSet ds ) → boolean

quickly determine, with high accuracy, if data is monotonic (repeated values allowed). This should be a constant-time operation, and be extremely unlikely to fail.

### Parameters

ds - a QDataSet

### Returns:

true if the data does pass quick tests for monotonic.

### See Also:

isMonotonicAndIncreasing(QDataSet)
QDataSet#MONOTONIC
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isNotBundle

isNotBundle( QDataSet ds ) → boolean

return true if the data is not a bundle and has uniform units throughout the dataset.

### Parameters

ds - any dataset.

### Returns:

true if the data is not a bundle and has uniform units throughout
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isQube

isQube( QDataSet ds ) → boolean

test to see that the dataset is a qube. TODO: this all needs review.

### Parameters

ds - QDataSet of any rank.

### Returns:

true if the dataset is a qube.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## kmeansCadence

kmeansCadence( QDataSet xds, int n ) → QDataSet

use K-means algorithm to find N means in a rank 1 dataset.

### Parameters

xds - dataset containing data from N normal distributions
n - number of divisions.

### Returns:

dataset containing the index for each point.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## makeValid

makeValid( org.das2.qds.MutablePropertyDataSet ds ) → void

throw out DEPEND and PLANE to make dataset valid.

### Parameters

ds - a MutablePropertyDataSet

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## maybeCopyRenderType

maybeCopyRenderType( QDataSet source, org.das2.qds.MutablePropertyDataSet dest ) → void

copy over the render type, if it is still appropriate. This nasty bit of code was introduced to support LANL data, where high-rank data is preferably plotted as a spectrogram, but can be plotted as a stack of lineplots.

### Parameters

source - a QDataSet
dest - a MutablePropertyDataSet

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## nLargest

nLargest( QDataSet set, int n ) → QDataSet

return the value of the nth biggest item. This keeps n values in memory.

### Parameters

set - rank 1 dataset containing comparable data.
n - the number of items to find

### Returns:

the n largest elements, sorted.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## oneUnit

oneUnit( QDataSet ds ) → boolean

Test for bundle scheme. Returns true if the data contains data with just one unit. For example ds[time=100,en=30] might have BUNDLE_1 to specify labels for each of the 30 channels, but each of its measurements have the same units. However, bundle(time,density) results in a dataset with BUNDLE_1 with the two datasets having different units. When two bundled dataset's units are convertible but not equal this will return false. This will return true for a zero-length dataset.

### Parameters

ds - the dataset

### Returns:

true if the dataset has just one unit.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## product

product( int[] qube ) → int

returns 1 for zero-length qube, the product otherwise.

### Parameters

qube - int array

### Returns:

the product of the elements of the array
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## propertyNames

propertyNames( ) → String[]

Return the names of non-structural properties of the dataset, like the UNITS and CADENCE. These are the dimensionProperties, plus others specific to the dataset, such as CADENCE and DELTA_PLUS.

### Returns:

the names of non-structural properties of the dataset, like the UNITS and CADENCE.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## putProperties

putProperties( java.util.Map properties, org.das2.qds.MutablePropertyDataSet ds ) → void

copy all properties into the dataset by iterating through the map. Properties that are equal to null are not copied, since null is equivalent to the property not found.

### Parameters

properties - the properties
ds - the mutable property dataset, which is still mutable.

### Returns:

void (returns nothing)

### See Also:

getProperties(QDataSet)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## qubeDims

qubeDims( QDataSet ds ) → int[]

provides a convenient way of indexing qubes, returning an int[] of length ds.rank() containing each dimension's length, or null if the dataset is not a qube.

### Parameters

ds - a QDataSet

### Returns:

int[] of length ds.rank() containing each dimension's length, or null if the dataset is not a qube.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## qubeSubset

qubeSubset( QDataSet ds, int reclen ) → QDataSet

return a subset of the dataset which is a qube.

### Parameters

ds - a rank N dataset like dataset[3,1616*,6144*], where asterisks (stars) indicate it is not a qube.
reclen - the record length for each record.

### Returns:

a rank N-1 dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## rangeOfMonotonic

rangeOfMonotonic( QDataSet ds ) → int[]

returns the indeces of the min and max elements of the monotonic dataset. This uses DataSetUtil.isMonotonic() which would be slow if MONOTONIC is not set.

### Parameters

ds - monotonic, rank 1 dataset.

### Returns:

the indeces [min,max] note max is inclusive.

### See Also:

org.das2.qds.ops.Ops#extent which returns the range containing any data.
isMonotonic(QDataSet) which must be true
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## repeatingSignal

repeatingSignal( QDataSet yds ) → int

return 0 or the number of values after which the signal repeats. For example, `ds= dataset([1,2,3,4,1,2,3,4,1,2,3,4,1,2,3,4,1,2]) assert repeatingSignal(ds)==4` if the data contains fill, then it is also not repeating.

### Parameters

yds - the rank 1 dataset.

### Returns:

the number of samples before a repeat, or 0 if the signal is not repeating.

### See Also:

guessCadenceNew
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## replicateDataSet

replicateDataSet( int n, double value ) → org.das2.qds.MutablePropertyDataSet

creates a dataset with the given cadence, start and length.

### Parameters

n - the number of elements
value - the value for each element

### Returns:

the dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## samePopulation

samePopulation( QDataSet ds1, QDataSet ds2 ) → boolean

true if the two datasets appear to be from the same population.

### Parameters

ds1 - first dataset
ds2 - second dataset

### Returns:

true if the two datasets appear to be from the same population
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## sliceProperties

sliceProperties( QDataSet ds, int index, java.util.Map result ) → java.util.Map

return properties attached to the slice at index. Note the slice implementations use this, and this only returns properties from dimensionProperties(). http://autoplot.org//QDataSet#20150514 Note this does not look at BUNDLE_1 properties. TODO: consider this.

### Parameters

ds - the dataset to slice.
index - index to slice at.
result - a map to insert the new properties, or null if a new one should be created.

### Returns:

a map of properties attached to the slice at index
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## statsString

statsString( QDataSet ds ) → String

return a human readable statistical representation of the dataset. Currently this is the mean, stddev ad number of points.

### Parameters

ds - the data

### Returns:

return a human readable statistical representation
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## sum

sum( int[] qube ) → int

returns 0 for zero-length qube, the sum otherwise.

### Parameters

qube - int array

### Returns:

the sum of the elements of the array
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## tagGenDataSet

tagGenDataSet( int n, double start, double cadence ) → org.das2.qds.MutablePropertyDataSet

creates a dataset with the given cadence, start and length. This is danger code, because the CADENCE must be reset if the UNITS are reset. use tagGenDataSet( int n, final double start, final double cadence, Units units ) if units are going to be specified.

### Parameters

n - the number of elements
start - the value for the first element.
cadence - the step size between elements

### Returns:

the dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## tagGenDataSet

tagGenDataSet( int n, double start, double cadence, Units units ) → org.das2.qds.MutablePropertyDataSet

creates a dataset with the given cadence, start and length. QDataSet.CADENCE will be set based on the units specified. Do not change the units of the result without updating cadence as well.

### Parameters

n - the number of elements
start - the value for the first element.
cadence - the step size between elements
units - the units of the dataset, for example Units.cm

### Returns:

the dataset
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toBundleDs

toBundleDs( QDataSet labels ) → org.das2.qds.MutablePropertyDataSet

make a proper bundle ds from a simple bundle containing ordinal units This assumes that labels is a unique set of labels. See http://autoplot.org/QDataSet#DataSet_Properties under BUNDLE_1. See DataSetOps.unbundle

### Parameters

labels - a QDataSet

### Returns:

a BundleDescriptor to be set as BUNDLE_i. See BundleDataSet
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toSparkline

toSparkline( QDataSet ds, QDataSet extent, boolean bar ) → String

Make a unicode spark line http://www.ssec.wisc.edu/~tomw/java/unicode.html. This should be for human consumption, because future versions may include data reduction and doubling up characters. See commented code in MetadataPanel.histStr. (I knew I had done this before...)

### Parameters

ds - the rank N (typically 1) dataset
extent - None or the range, see Ops.extent(ds)
bar - true indicates bars should be used instead of scatter

### Returns:

string that is a sparkline.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toString

toString( QDataSet ds ) → String

provide a string representation of the dataset. This is intended for human consumption, but does follow rules outlined in http://autoplot.org//developer.datasetToString

### Parameters

ds - any dataset.

### Returns:

a short, human-readable representation of the dataset.

### See Also:

format(QDataSet, boolean)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toString

toString( int[] qube ) → String

return string representation of the dimensions of the qube dimensions. For example [2,4] is represented as "[2,4]"

### Parameters

qube - an array of integers, 4 elements or fewer.

### Returns:

the formatted string representation
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## totalLength

totalLength( QDataSet ds ) → int

return the total number of values in the dataset. For qubes this is the product of the dimension lengths, for other datasets we create a dataset of lengths and total all the elements.

### Parameters

ds - a QDataSet

### Returns:

the number of values in the dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## totalLengthAsLong

totalLengthAsLong( QDataSet ds ) → long

return the total number of values in the dataset, as a long. For qubes this is the product of the dimension lengths, for other datasets we create a dataset of lengths and total all the elements.

### Parameters

ds - a QDataSet

### Returns:

the number of values in the dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## trimProperties

trimProperties( QDataSet ds, int start, int stop ) → java.util.Map

help out implementations of the QDataSet.trim() command. This does the dimension properties and geometric properties like DEPEND_0 and DELTA_PLUS. This also checks for indexed properties, which are NAME__i.

### Parameters

ds - the dataset with properties to trim.
start - start index of trim operation
stop - exclusive stop index of the trim operation.

### Returns:

the properties of ds, trimmed to the indices.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## validPoints

validPoints( QDataSet ds ) → QDataSet

return just the valid points of the dataset.

### Parameters

ds - a dataset rank > 0.

### Returns:

the valid points of the dataset in a rank 1 dataset.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## validate

validate( QDataSet ds, java.util.List problems ) → boolean

returns true if the dataset is valid, false otherwise. If problems is non-null, then problems will be indicated here.

### Parameters

ds - rank N dataset.
problems - insert problem descriptions here, if null then ignore

### Returns:

true if the dataset is valid, false otherwise
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## validate

validate( QDataSet xds, QDataSet yds, java.util.List problems ) → boolean

add method for validating before link is called.

### Parameters

xds - a QDataSet
yds - a QDataSet
problems - insert problem descriptions here, if null then ignore

### Returns:

true if the datasets can be linked into a valid dataset, false otherwise
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## validate

validate( QDataSet xds, QDataSet yds, QDataSet zds, java.util.List problems ) → boolean

add method for validating before link is called.

### Parameters

xds - rank 1 tags
yds - rank 1 or rank 2 tags
zds - the dependent data.
problems - insert problem descriptions here, if null then ignore

### Returns:

true if the datasets can be linked into a valid dataset, false otherwise
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## value

value( org.das2.qds.RankZeroDataSet ds, Units tu ) → double

get the value of the rank 0 dataset in the specified units. For example, value( ds, Units.km )

### Parameters

ds - a RankZeroDataSet
tu - target units

### Returns:

the double in target units.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## weightsDataSet

weightsDataSet( QDataSet ds ) → QDataSet

Provide consistent valid logic to operators by providing a QDataSet with >0.0 where the data is valid, and 0.0 where the data is invalid. VALID_MIN, VALID_MAX and FILL_VALUE properties are used. Note, when FILL_VALUE is not specified, -1e31 is used. This is to support legacy logic. For convenience, the property SUGGEST_FILL is set to the fill value used.

### Parameters

ds - the dataset

### Returns:

a dataset with the same geometry with zero or positive weights.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## xTagBinarySearch

xTagBinarySearch( QDataSet ds, Datum datum, int low, int high ) → int

returns the index of a tag, or the `(-(insertion point) - 1)`. (See Arrays.binarySearch)

### Parameters

ds - monotonically increasing data.
datum - value we are looking for
low - inclusive lower bound of the search
high - inclusive upper bound of the search

### Returns:

the index of a tag, or the `(-(insertion point) - 1)`
[search for examples] [view on GitHub] [view on old javadoc] [view source]