Package ucar.nc2.dataset

Interface EnhanceScaleMissingUnsigned

  • All Superinterfaces:
    IsMissingEvaluator
    All Known Implementing Classes:
    CoordinateAxis, CoordinateAxis1D, CoordinateAxis1DTime, CoordinateAxis2D, VariableDS, VariableEnhancer
    @Deprecated
public interface EnhanceScaleMissingUnsigned
extends IsMissingEvaluator
    Deprecated.
    use implementations in Filter package
    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 Detail

      • hasScaleOffset

        boolean hasScaleOffset()
        Deprecated.
        true if Variable data will be converted using scale and offset

      • getScaleFactor

        double getScaleFactor()
        Deprecated.
        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()
        Deprecated.
        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()
        Deprecated.
        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)
        Deprecated.
        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()
        Deprecated.
        true if Variable has valid_range, valid_min or valid_max attributes

      • getValidMin

        double getValidMin()
        Deprecated.
        return the minimum value in the valid range

      • getValidMax

        double getValidMax()
        Deprecated.
        return the maximum value in the valid range

      • isInvalidData

        boolean isInvalidData​(double val)
        Deprecated.
        return true if val is outside the valid range

      • hasFillValue

        boolean hasFillValue()
        Deprecated.
        true if Variable has _FillValue attribute

      • getFillValue

        double getFillValue()
        Deprecated.
        return value of _FillValue attribute

      • isFillValue

        boolean isFillValue​(double val)
        Deprecated.
        return true if val equals the _FillValue

      • hasMissingValue

        boolean hasMissingValue()
        Deprecated.
        true if Variable has missing_value attribute

      • getMissingValues

        double[] getMissingValues()
        Deprecated.
        return values of missing_value attributes

      • isMissingValue

        boolean isMissingValue​(double val)
        Deprecated.
        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()
        Deprecated.
        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()
        Deprecated.
        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()
        Deprecated.
        Returns the signedness of the decorated variable.
        Returns:
        the signedness of the decorated variable.

      • convertUnsigned

        Number convertUnsigned​(Number value)
        Deprecated.
        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)
        Deprecated.
        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)
        Deprecated.
        Apply scale and offset to the specified value if hasScaleOffset(). Otherwise, just return value.

      • applyScaleOffset

        Array applyScaleOffset​(Array data)
        Deprecated.
        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

        Array convertMissing​(Array in)
        Deprecated.
        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)
        Deprecated.
        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.