ucar.nc2.dataset

Class VariableDS

java.lang.Object

ucar.nc2.CDMNode

ucar.nc2.Variable

ucar.nc2.dataset.VariableDS

All Implemented Interfaces:

java.lang.Comparable<VariableSimpleIF>, java.lang.Iterable<Attribute>, IsMissingEvaluator, AttributeContainer, ucar.nc2.dataset.Enhancements, ucar.nc2.dataset.EnhanceScaleMissingUnsigned, VariableEnhanced, ProxyReader, VariableSimpleIF

Direct Known Subclasses:

CoordinateAxis

public class VariableDS
extends Variable
implements VariableEnhanced, ucar.nc2.dataset.EnhanceScaleMissingUnsigned

A wrapper around a Variable, creating an "enhanced" Variable. The original Variable is used for the I/O. There are several distinct uses:

1. Handle scale/offset/missing/enum/unsigned conversion; this can change DataType and data values
2. Container for coordinate system information
3. NcML modifications to underlying Variable

See Also:

NetcdfDataset

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VariableDS.Builder<T extends VariableDS.Builder<T>>

Field Summary

Fields inherited from class ucar.nc2.Variable

defaultCoordsSizeToCache, defaultSizeToCache, permitCaching

Method Summary

Modifier and Type	Method and Description
Array	applyScaleOffset(Array data) Apply scale and offset to each element of in and return the result as a new Array, but only if EnhanceScaleMissingUnsigned.hasScaleOffset().
double	applyScaleOffset(java.lang.Number value) Apply scale and offset to the specified value if EnhanceScaleMissingUnsigned.hasScaleOffset().
static VariableDS.Builder<?>	builder() Get Builder for this class that allows subclassing.
Array	convertMissing(Array in) Returns a copy of in, except that each missing value is replaced by Double.NaN.
java.lang.Number	convertMissing(java.lang.Number value) If value is missing, return Double.NaN.
Array	convertUnsigned(Array in) Performs an unsigned conversion of each element of in and returns the result as a new Array.
java.lang.Number	convertUnsigned(java.lang.Number value) Convert value to the next largest integral data type by an unsigned conversion.
java.lang.Number	convertUnsigned(java.lang.Number value, DataType dataType)
boolean	fillValueIsMissing()
com.google.common.collect.ImmutableList<CoordinateSystem>	getCoordinateSystems() Get the list of Coordinate Systems for this Variable.
java.lang.String	getDatasetLocation() The location of the dataset this belongs to.
java.lang.String	getDescription() Get the description of the Variable.
java.util.Set<NetcdfDataset.Enhance>	getEnhanceMode() Returns the enhancements applied to this variable.
double	getFillValue() return value of _FillValue attribute
Array	getMissingDataArray(int[] shape) Return Array with missing data
double[]	getMissingValues() return values of missing_value attributes
NetcdfFile	getNetcdfFile() Get the NetcdfFile that this variable is contained in.
double	getOffset() The number to be added to the data after it is read.
DataType	getOriginalDataType() When this wraps another Variable, get the original Variable's DataType.
java.lang.String	getOriginalName() When this wraps another Variable, get the original Variable's name.
Variable	getOriginalVariable() A VariableDS usually wraps another Variable.
DataType	getScaledOffsetType() Return the data type for values that have undergone scale/offset conversion.
double	getScaleFactor() The data are to be multiplied by this value after the data are read.
DataType.Signedness	getSignedness() Returns the signedness of the decorated variable.
java.lang.String	getUnitsString() Get the Unit String for the Variable.
DataType	getUnsignedConversionType() Return the data type for values that have undergone unsigned conversion.
double	getValidMax() return the maximum value in the valid range
double	getValidMin() return the minimum value in the valid range
boolean	hasFillValue() true if Variable has _FillValue attribute
boolean	hasMissing() true if Variable has missing data values
boolean	hasMissingValue() true if Variable has missing_value attribute
boolean	hasScaleOffset() true if Variable data will be converted using scale and offset
boolean	hasValidData() true if Variable has valid_range, valid_min or valid_max attributes
boolean	invalidDataIsMissing()
boolean	isFillValue(double val) return true if val equals the _FillValue
boolean	isInvalidData(double val) return true if val is outside the valid range
boolean	isMissing(double val) Returns true if the argument is a missing value.
boolean	isMissingValue(double val) return true if val equals a missing_value (low-level)
java.lang.String	lookupEnumString(int val) Lookup the enum string for this value.
boolean	missingDataIsMissing()
long	readToStream(Section section, java.io.OutputStream out) Read variable data to a stream.
Array	reallyRead(Variable client, CancelTask cancelTask) public by accident, do not call directly.
Array	reallyRead(Variable client, Section section, CancelTask cancelTask) public by accident, do not call directly.
void	showScaleMissingProxy(java.util.Formatter f) public for debugging
VariableDS.Builder<?>	toBuilder() Turn into a mutable Builder.
java.lang.String	toStringDebug() String representation of Variable and its attributes.

Methods inherited from class ucar.nc2.Variable

attributes, compareTo, createNewCache, equals, findAttribute, findAttributeString, findDimensionIndex, getDataType, getDimension, getDimensions, getDimensionsString, getElementSize, getEnumTypedef, getFileTypeId, getFullName, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getParentGroup, getParentStructure, getRanges, getRank, getShape, getShape, getShapeAsSection, getSize, getSizeToCache, getSPobject, hasCachedData, hashCode, isCaching, isCoordinateVariable, isMemberOfStructure, isMetadata, isScalar, isUnlimited, isVariableLength, read, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, reduce, section, section, slice, toString

Methods inherited from class ucar.nc2.CDMNode

getShortName

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface ucar.nc2.dataset.VariableEnhanced

getFullName, getShortName

Methods inherited from interface ucar.nc2.dataset.Enhancements

addCoordinateSystem, removeCoordinateSystem

Methods inherited from interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

convert

Methods inherited from interface ucar.nc2.VariableSimpleIF

getShortName

Methods inherited from interface ucar.nc2.AttributeContainer

filter, findAttributeDouble, findAttributeIgnoreCase, findAttributeInteger, getName, hasAttribute, hasAttributeIgnoreCase, isEmpty, iterator

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

applyScaleOffset

public Array applyScaleOffset(Array data)

Description copied from interface: EnhanceScaleMissingUnsigned

Apply scale and offset to each element of in and return the result as a new Array, but only if EnhanceScaleMissingUnsigned.hasScaleOffset(). Otherwise, just return value. Otherwise, just return data.

Specified by:

applyScaleOffset in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Parameters:

data - convert this

Returns:

converted data.

applyScaleOffset

public double applyScaleOffset(java.lang.Number value)

Description copied from interface: EnhanceScaleMissingUnsigned

Apply scale and offset to the specified value if EnhanceScaleMissingUnsigned.hasScaleOffset(). Otherwise, just return value.

Specified by:

applyScaleOffset in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

builder

public static VariableDS.Builder<?> builder()

Get Builder for this class that allows subclassing.

See Also:

"https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"

convertMissing

public Array convertMissing(Array in)

Description copied from interface: EnhanceScaleMissingUnsigned

Returns a copy of in, except that each missing value is replaced by Double.NaN.

Specified by:

convertMissing in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Parameters:

in - an array containing floating-point numbers to convert.

Returns:

the result of a missing conversion of each element of in.

convertMissing

public java.lang.Number convertMissing(java.lang.Number value)

Description copied from interface: EnhanceScaleMissingUnsigned

If value is missing, return Double.NaN. Otherwise, simply return value

Specified by:

convertMissing in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

convertUnsigned

public Array convertUnsigned(Array in)

Description copied from interface: EnhanceScaleMissingUnsigned

Performs an unsigned conversion of each element of in and returns the result as a new Array. The data type of the returned array will be EnhanceScaleMissingUnsigned.getUnsignedConversionType().

Specified by:

convertUnsigned in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Parameters:

in - an Array containing integral Numbers to convert.

Returns:

the result of an unsigned conversion of each element of in.

convertUnsigned

public java.lang.Number convertUnsigned(java.lang.Number value)

Description copied from interface: EnhanceScaleMissingUnsigned

Convert value to the next largest integral data type by an unsigned conversion. The conversion only happens if the decorated variable is unsigned and value is a negative integer. Otherwise, simply return value.

Specified by:

convertUnsigned in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Parameters:

value - an integral number to convert.

Returns:

the result of an unsigned conversion of value.

convertUnsigned

public java.lang.Number convertUnsigned(java.lang.Number value,
                                        DataType dataType)

fillValueIsMissing

public boolean fillValueIsMissing()

getCoordinateSystems

public com.google.common.collect.ImmutableList<CoordinateSystem> getCoordinateSystems()

Description copied from interface: Enhancements

Get the list of Coordinate Systems for this Variable.

Specified by:

getCoordinateSystems in interface ucar.nc2.dataset.Enhancements

Returns:

list of type CoordinateSystem; may be empty but not null.

getDatasetLocation

public java.lang.String getDatasetLocation()

Description copied from class: Variable

The location of the dataset this belongs to. Labeling purposes only.

Overrides:

getDatasetLocation in class Variable

getDescription

public java.lang.String getDescription()

Description copied from class: Variable

Get the description of the Variable. Default is to use CDM.LONG_NAME attribute value. If not exist, look for "description", "title", or "standard_name" attribute value (in that order).

Specified by:

getDescription in interface ucar.nc2.dataset.Enhancements

Specified by:

getDescription in interface VariableSimpleIF

Overrides:

getDescription in class Variable

Returns:

description, or null if not found.

getEnhanceMode

public java.util.Set<NetcdfDataset.Enhance> getEnhanceMode()

Returns the enhancements applied to this variable. If this variable wraps another variable, the returned set will also contain the enhancements applied to the nested variable, recursively.

Returns:

the enhancements applied to this variable.

getFillValue

public double getFillValue()

Description copied from interface: EnhanceScaleMissingUnsigned

return value of _FillValue attribute

Specified by:

getFillValue in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

getMissingDataArray

public Array getMissingDataArray(int[] shape)

Return Array with missing data

Parameters:

shape - of this shape

Returns:

Array with given shape

getMissingValues

public double[] getMissingValues()

Description copied from interface: EnhanceScaleMissingUnsigned

return values of missing_value attributes

Specified by:

getMissingValues in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

getNetcdfFile

public NetcdfFile getNetcdfFile()

Description copied from class: Variable

Get the NetcdfFile that this variable is contained in. May be null.

Overrides:

getNetcdfFile in class Variable

getOffset

public double getOffset()

Description copied from interface: EnhanceScaleMissingUnsigned

The number to be added to the data after it is read. If both CDM.SCALE_FACTOR and CDM.ADD_OFFSET attributes are present, the data are first scaled before the offset is added. By default it is 0.0, i.e. no offset. It will remain that value if the variable defines no CDM.SCALE_FACTOR attribute.

Specified by:

getOffset in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Returns:

the number to add to the data.

getOriginalDataType

public DataType getOriginalDataType()

When this wraps another Variable, get the original Variable's DataType.

Returns:

original Variable's DataType, or current data type if it doesnt wrap another variable

getOriginalName

public java.lang.String getOriginalName()

When this wraps another Variable, get the original Variable's name.

Specified by:

getOriginalName in interface VariableEnhanced

Returns:

original Variable's name

getOriginalVariable

public Variable getOriginalVariable()

A VariableDS usually wraps another Variable.

Specified by:

getOriginalVariable in interface VariableEnhanced

Returns:

original Variable or null

getScaledOffsetType

@Nullable
public DataType getScaledOffsetType()

Description copied from interface: EnhanceScaleMissingUnsigned

Return the data type for values that have undergone scale/offset conversion. This will be null if the decorated variable lacks scale_factor or add_offset attributes. You can check with EnhanceScaleMissingUnsigned.hasScaleOffset().

Specified by:

getScaledOffsetType in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Returns:

the data type for values that have undergone scale/offset conversion.

getScaleFactor

public double getScaleFactor()

Description copied from interface: EnhanceScaleMissingUnsigned

The data are to be multiplied by this value after the data are read. By default it is 1.0, i.e. no scaling. It will remain that value if the variable defines no CDM.SCALE_FACTOR attribute.

Specified by:

getScaleFactor in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Returns:

the multiplier to apply to the data.

getSignedness

public DataType.Signedness getSignedness()

Description copied from interface: EnhanceScaleMissingUnsigned

Returns the signedness of the decorated variable.

Specified by:

getSignedness in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Returns:

the signedness of the decorated variable.

getUnitsString

public java.lang.String getUnitsString()

Description copied from class: Variable

Get the Unit String for the Variable. Looks for the CDM.UNITS attribute value

Specified by:

getUnitsString in interface ucar.nc2.dataset.Enhancements

Specified by:

getUnitsString in interface VariableSimpleIF

Overrides:

getUnitsString in class Variable

Returns:

unit string, or null if not found.

getUnsignedConversionType

public DataType getUnsignedConversionType()

Description copied from interface: EnhanceScaleMissingUnsigned

Return the data type for values that have undergone unsigned conversion. This will never be null, even when no unsigned conversion is necessary (because the underlying variable isn't unsigned). In such cases, this data type will be the same as that of the underlying variable.

Specified by:

getUnsignedConversionType in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Returns:

the data type for values that have undergone unsigned conversion.

getValidMax

public double getValidMax()

Description copied from interface: EnhanceScaleMissingUnsigned

return the maximum value in the valid range

Specified by:

getValidMax in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

getValidMin

public double getValidMin()

Description copied from interface: EnhanceScaleMissingUnsigned

return the minimum value in the valid range

Specified by:

getValidMin in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

hasFillValue

public boolean hasFillValue()

Description copied from interface: EnhanceScaleMissingUnsigned

true if Variable has _FillValue attribute

Specified by:

hasFillValue in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

hasMissing

public boolean hasMissing()

Description copied from interface: EnhanceScaleMissingUnsigned

true if Variable has missing data values

Specified by:

hasMissing in interface IsMissingEvaluator

Specified by:

hasMissing in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Returns:

true if Variable has missing data values

hasMissingValue

public boolean hasMissingValue()

Description copied from interface: EnhanceScaleMissingUnsigned

true if Variable has missing_value attribute

Specified by:

hasMissingValue in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

hasScaleOffset

public boolean hasScaleOffset()

Description copied from interface: EnhanceScaleMissingUnsigned

true if Variable data will be converted using scale and offset

Specified by:

hasScaleOffset in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

hasValidData

public boolean hasValidData()

Description copied from interface: EnhanceScaleMissingUnsigned

true if Variable has valid_range, valid_min or valid_max attributes

Specified by:

hasValidData in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

invalidDataIsMissing

public boolean invalidDataIsMissing()

isFillValue

public boolean isFillValue(double val)

Description copied from interface: EnhanceScaleMissingUnsigned

return true if val equals the _FillValue

Specified by:

isFillValue in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

isInvalidData

public boolean isInvalidData(double val)

Description copied from interface: EnhanceScaleMissingUnsigned

return true if val is outside the valid range

Specified by:

isInvalidData in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

isMissing

public boolean isMissing(double val)

Description copied from interface: EnhanceScaleMissingUnsigned

Returns true if the argument is a missing value. Note that Float.NaN and Double.NaN are considered missing data.

Specified by:

isMissing in interface IsMissingEvaluator

Specified by:

isMissing in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

Parameters:

val - an unpacked value.

Returns:

true if the argument is a missing value.

isMissingValue

public boolean isMissingValue(double val)

Description copied from interface: EnhanceScaleMissingUnsigned

return true if val equals a missing_value (low-level)

Specified by:

isMissingValue in interface ucar.nc2.dataset.EnhanceScaleMissingUnsigned

lookupEnumString

public java.lang.String lookupEnumString(int val)

Description copied from class: Variable

Lookup the enum string for this value. Can only be called on enum types, where dataType.isEnum() is true.

Overrides:

lookupEnumString in class Variable

Parameters:

val - the integer value of this enum

Returns:

the String value

missingDataIsMissing

public boolean missingDataIsMissing()

readToStream

public long readToStream(Section section,
                         java.io.OutputStream out)
                  throws java.io.IOException,
                         InvalidRangeException

Description copied from class: Variable

Read variable data to a stream. Support for NcStreamWriter.

Overrides:

readToStream in class Variable

Throws:

java.io.IOException

InvalidRangeException

reallyRead

public Array reallyRead(Variable client,
                        CancelTask cancelTask)
                 throws java.io.IOException

Description copied from class: Variable

public by accident, do not call directly.

Specified by:

reallyRead in interface ProxyReader

Overrides:

reallyRead in class Variable

Parameters:

client - the client Variable

cancelTask - user may cancel

Returns:

Array

Throws:

java.io.IOException - on error

reallyRead

public Array reallyRead(Variable client,
                        Section section,
                        CancelTask cancelTask)
                 throws java.io.IOException,
                        InvalidRangeException

Description copied from class: Variable

public by accident, do not call directly.

Specified by:

reallyRead in interface ProxyReader

Overrides:

reallyRead in class Variable

Parameters:

client - the client Variable

section - the section of data to read.

cancelTask - user may cancel

Returns:

Array

Throws:

java.io.IOException - on error

InvalidRangeException - if section has incorrect rank or illegal shape.

showScaleMissingProxy

public void showScaleMissingProxy(java.util.Formatter f)

public for debugging

Parameters:

f - put info here

toBuilder

public VariableDS.Builder<?> toBuilder()

Description copied from class: Variable

Turn into a mutable Builder. Can use toBuilder().build() to copy.

Overrides:

toBuilder in class Variable

toStringDebug

public java.lang.String toStringDebug()

Description copied from class: Variable

String representation of Variable and its attributes.

Overrides:

toStringDebug in class Variable