ucar.nc2.dataset

Interface EnhanceScaleMissingUnsigned

All Superinterfaces:

IsMissingEvaluator

All Known Implementing Classes:

CoordinateAxis, CoordinateAxis1D, CoordinateAxis1DTime, CoordinateAxis2D, VariableDS, VariableEnhancer

public interface EnhanceScaleMissingUnsigned
extends IsMissingEvaluator

A Variable decorator that handles unsigned data, scale/offset packed data, and missing data. Specifically, it handles:

• unsigned data using _Unsigned
• packed data using scale_factor and add_offset
• invalid/missing data using valid_min, valid_max, valid_range, missing_value, or _FillValue

if those "standard attributes" are present.

Standard Use

Implementation rules for unsigned data

1. A variable is considered unsigned if it has an unsigned data type or an _Unsigned attribute with value true.
2. Values will be widened, which effectively reinterprets signed data as unsigned data.
3. To accommodate the unsigned conversion, the variable's data type will be changed to the next larger type.

Implementation rules for scale/offset

1. If scale_factor and/or add_offset variable attributes are present, then this is a "packed" Variable.
2. The data type of the variable will be set to the largest of:
   • the original data type
   • the unsigned conversion type, if applicable
   • the scale_factor attribute type
   • the add_offset attribute type
   The signedness of the variable's data type will be preserved. For example, if the variable was originally unsigned, then getScaledOffsetType() will be unsigned as well.
3. External (packed) data is converted to internal (unpacked) data transparently during the applyScaleOffset(Array) call.

Implementation rules for missing data

Here "missing data" is a general name for invalid/never-written/missing values. Use this interface when you don't need to distinguish these variants. See below for a lower-level interface if you do need to distinguish between them.

1. By default, hasMissing() is true if any of hasValidData(), hasFillValue() or hasMissingValue() are true (see below). You can modify this behavior by calling setInvalidDataIsMissing(), setFillValueIsMissing(), or setMissingDataIsMissing().
2. Test specific values through isMissing(double). Note that the data is converted and compared as a double.
3. Data values of float or double NaN are considered missing data and will return true if called with isMissing(). (However isMissing() will not detect if you are setting NaNs yourself).

Implementation rules for missing data with scale/offset

1. _FillValue and missing_value values are always in the units of the external (packed) data.
2. If valid_range is the same type as scale_factor (actually the wider of scale_factor and add_offset) and this is wider than the external data, then it will be interpreted as being in the units of the internal (unpacked) data. Otherwise it is in the units of the external (packed) data.

Low Level Access

The following provide more direct access to missing/invalid data. These are mostly convenience routines for checking the standard attributes. If you set useNaNs = true in the constructor, these routines cannot be used when the data has type float or double.

Implementation rules for valid_range

1. If valid_range is present, valid_min and valid_max attributes are ignored. Otherwise, the valid_min and/or valid_max is used to construct a valid range. If any of these exist, hasValidData() is true.
2. To test a specific value, call isInvalidData(). Note that the data is converted and compared as a double. Or get the range through getValidMin() and getValidMax().

Implementation rules for _FillData

1. If the _FillData attribute is present, it must have a scalar value of the same type as the data. In this case, hasFillValue() returns true.
2. Test specific values through isFillValue(). Note that the data is converted and compared as a double.

Implementation rules for missing_value

1. If the missing_value attribute is present, it must have a scalar or vector value of the same type as the data. In this case, hasMissingValue() returns true.
2. Test specific values through isMissingValue(). Note that the data is converted and compared as a double.

Strategies for using EnhanceScaleMissingUnsigned

1. Low-level: use the is/has InvalidData/FillValue/MissingValue routines to "roll-your own" tests for the various kinds of missing/invalid data.
2. Standard: use is/hasMissing() to test for missing data when you don't need to distinguish between the variants. Use the setXXXisMissing() to customize the behavior if needed.

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 hasScaleOffset().
double	applyScaleOffset(Number value) Apply scale and offset to the specified value if hasScaleOffset().
Array	convert(Array in, boolean convertUnsigned, boolean applyScaleOffset, boolean convertMissing) Perform the specified conversions on each element of in and return the result as a new Array.
Array	convertMissing(Array in) Returns a copy of in, except that each missing value is replaced by Double.NaN.
Number	convertMissing(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.
Number	convertUnsigned(Number value) Convert value to the next largest integral data type by an unsigned conversion.
double	getFillValue() return value of _FillValue attribute
double[]	getMissingValues() return values of missing_value attributes
double	getOffset() The number to be added to the data after it is read.
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.
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	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)
void	setFillValueIsMissing(boolean b) Deprecated. Do not use.
void	setInvalidDataIsMissing(boolean b) Deprecated. Do not use.
void	setMissingDataIsMissing(boolean b) Deprecated. Do not use.

Method Detail

hasScaleOffset

boolean hasScaleOffset()

true if Variable data will be converted using scale and offset

getScaleFactor

double getScaleFactor()

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.

Returns:

the multiplier to apply to the data.

getOffset

double getOffset()

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.

Returns:

the number to add to the data.

hasMissing

boolean hasMissing()

true if Variable has missing data values

Specified by:

hasMissing in interface IsMissingEvaluator

Returns:

true if Variable has missing data values

isMissing

boolean isMissing(double val)

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

Parameters:

val - an unpacked value.

Returns:

true if the argument is a missing value.

hasValidData

boolean hasValidData()

true if Variable has valid_range, valid_min or valid_max attributes

getValidMin

double getValidMin()

return the minimum value in the valid range

getValidMax

double getValidMax()

return the maximum value in the valid range

isInvalidData

boolean isInvalidData(double val)

return true if val is outside the valid range

hasFillValue

boolean hasFillValue()

true if Variable has _FillValue attribute

getFillValue

double getFillValue()

return value of _FillValue attribute

isFillValue

boolean isFillValue(double val)

return true if val equals the _FillValue

hasMissingValue

boolean hasMissingValue()

true if Variable has missing_value attribute

getMissingValues

double[] getMissingValues()

return values of missing_value attributes

isMissingValue

boolean isMissingValue(double val)

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

setFillValueIsMissing

@Deprecated
void setFillValueIsMissing(boolean b)

Deprecated. Do not use.

Set if _FillValue is considered isMissing().

setInvalidDataIsMissing

@Deprecated
void setInvalidDataIsMissing(boolean b)

Deprecated. Do not use.

set if valid_range is considered isMissing(); better set in constructor if possible

setMissingDataIsMissing

@Deprecated
void setMissingDataIsMissing(boolean b)

Deprecated. Do not use.

set if missing_data is considered isMissing(); better set in constructor if possible

getScaledOffsetType

@Nullable
DataType getScaledOffsetType()

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 hasScaleOffset().

Returns:

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

getUnsignedConversionType

@Nonnull
DataType getUnsignedConversionType()

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.

Returns:

the data type for values that have undergone unsigned conversion.

getSignedness

DataType.Signedness getSignedness()

Returns the signedness of the decorated variable.

Returns:

the signedness of the decorated variable.

convertUnsigned

Number convertUnsigned(Number value)

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.

Parameters:

value - an integral number to convert.

Returns:

the result of an unsigned conversion of value.

convertUnsigned

Array convertUnsigned(Array in)

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 getUnsignedConversionType().

Parameters:

in - an Array containing integral Numbers to convert.

Returns:

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

applyScaleOffset

double applyScaleOffset(Number value)

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

applyScaleOffset

Array applyScaleOffset(Array data)

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

Parameters:

data - convert this

Returns:

converted data.

convertMissing

Number convertMissing(Number value)

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

convertMissing

Array convertMissing(Array in)

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

Parameters:

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

Returns:

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

convert

Array convert(Array in,
              boolean convertUnsigned,
              boolean applyScaleOffset,
              boolean convertMissing)

Perform the specified conversions on each element of in and return the result as a new Array. Note that this method is more efficient than calling convertUnsigned(Array), followed by applyScaleOffset(Array), followed by convertMissing(Array), as only one copy of in is made.

Parameters:

in - a numeric array.

convertUnsigned - true if we should convert unsigned.

applyScaleOffset - true if we should apply scale/offset.

convertMissing - true if we should convert missing.

Returns:

a new array, with the specified conversions performed.