Package noaa.coastwatch.util

Class DataVariable

java.lang.Object
noaa.coastwatch.util.MetadataContainer
noaa.coastwatch.util.DataVariable
All Implemented Interfaces:
Cloneable, ValueSource
Direct Known Subclasses:
Grid, Line
public abstract class DataVariable extends MetadataContainer implements ValueSource
A data variable is a container class to hold data values and a specific set of metadata. The required metadata includes the variable name, units, dimensions, number format, scaling, and missing data value. Other metadata may also be attached using the TreeMap functions, where it is expected that the key be a Java String object. Note that this class and any subclasses are not guaranteed to be thread safe.
Since:
3.1.0
Author:
Peter Hollemans

  • Field Details

    • dims

      protected int[] dims
      Array of data dimension sizes.

    • data

      protected Object data
      Array of data values.

    • isUnsigned

      protected boolean isUnsigned
      The unsigned flag, true if the data values are unsigned.

    • unsignedType

      protected int unsignedType
      The unsigned type.

    • lookup

      protected double[] lookup
      The lookup table.

  • Constructor Details

    • DataVariable

      public DataVariable(String name, String longName, String units, int[] dimensions, Object data, NumberFormat format, double[] scaling, Object missing)
      Constructs a new data variable with the specified properties.
      Parameters:
      name - a short variable name. The variable name should reflect what the data values represent without being overly verbose. For example, avhrr_ch4 would describe data from the AVHRR sensor, channel 4.
      longName - a long variable name. The long name is a verbose string to describe the variable in common terms. For example, the variable named sst might have the long name sea surface temperature.
      units - the real world variable units. For example if the variable data describes a temperature in Celsius, the variable units might be Celsius.
      dimensions - the variable data array dimensions. For a 2D image data array, the dimensions would be the number of rows and columns in the image.
      data - the variable data array. The data should be stored as a 1D array of values. It is up to the subclass to determine the mapping between data coordinate and index into the data array for data with dimensions greater than 1. If the passed array is null, data get/set/format methods are undefined.
      format - a number format specification. The number format will be used to convert data values from their numerical representation to a string representation.
      scaling - the scaling factor and offset. These values will be used to convert between data stored in the data array and real world values. In general, scaling is only necessary when floating point data is stored as integers. When data is retrieved from the data array, the following formula is used to scale the values: (val - scaling[1])*scaling[0]. When setting values in the data array, the following formula is used: val/scaling[0] + scaling[1]. If scaling is null, no scaling is performed.
      missing - the missing data value. The missing value is used to represent data values in the data array that have purposely not been recorded or were flagged as invalid. If missing is null, no missing value is used.

  • Method Details

    • getName

      public String getName()
      Gets the short variable name.

    • setName

      public void setName(String name)
      Sets the short variable name.

    • getLongName

      public String getLongName()
      Gets the descriptive variable name.

    • setLongName

      public void setLongName(String longName)
      Sets the descriptive variable name.

    • getUnits

      public String getUnits()
      Gets the variable units.

    • setUnits

      public void setUnits(String units)
      Sets the variable units.

    • getDimensions

      public int[] getDimensions()
      Gets the variable data array dimensions.

    • getRank

      public int getRank()
      Gets the variable data array rank.

    • getData

      public Object getData()
      Gets the variable data array. The returned data is read-only -- the result of attempting to set values in the data is undefined.

    • setData

      public void setData(Object data)
      Sets the variable data array.

    • getScaling

      public double[] getScaling()
      Gets the scaling factor and offset.

    • getFormat

      public NumberFormat getFormat()
      Gets the data number format.

    • setFormat

      public void setFormat(NumberFormat format)
      Sets the data number format.

    • getMissing

      public Object getMissing()
      Gets the data missing value.

    • setMissing

      public void setMissing(Object missing)
      Sets the data missing value.

    • setLookup

      public void setLookup(double[] lookup)
      Sets the lookup table. The lookup table is an alternative to the scaling factor and offset, and may be used to translate integer valued data to floating point data values. If a lookup table is employed, the setValue() may not be used. If both lookup and scaling are set, the lookup takes precedence over the scaling and the scaling is ignored.
      Parameters:
      lookup - the lookup table to use.

    • getDataClass

      public Class getDataClass()
      Gets the class associated with components of the data array.
      Returns:
      the data class or null if the data array is null.

    • setUnsigned

      public void setUnsigned(boolean flag)
      Sets the unsigned data flag. This may only be used if the data array is of type byte[], short[], int[], or long[]. If the data class is null, this method has no effect.
      Parameters:
      flag - the unsigned flag, true is the data array contains unsigned data.
      Throws:
      IllegalArgumentException - if the data class is not allowed to be unsigned.
      See Also:

    • getUnsigned

      public boolean getUnsigned()
      Gets the unsigned flag.

    • getClassBits

      public static int getClassBits(Class c)
      Gets the memory required by a primitive class.
      Parameters:
      c - the primitive class.
      Returns:
      the number of bits needed for each primitive value. The value 0 is returned if the class is not primitive.

    • interpolate

      public abstract double interpolate(DataLocation loc)
      Reads an interpolated data value.
      Parameters:
      loc - the data value location.
      Returns:
      the scaled data value as a double. The Double.NaN value is used if the data value is missing.
      See Also:

    • getValue

      public double getValue(DataLocation loc)
      Reads a scaled data value. The data value is read from the data array and scaled according to the scaling factor and offset.
      Specified by:
      getValue in interface ValueSource
      Parameters:
      loc - the data value location.
      Returns:
      the scaled data value as a double. The Double.NaN value is used if the data value is missing.
      See Also:

    • getValues

      public int getValues()
      Gets the total number of data values indicated by the dimensions.
      Returns:
      the number of data values.

    • getValue

      protected double getValue(int index, Object data)
      Reads a scaled data value.
      Parameters:
      index - the index into the data array.
      data - the data array to use for raw data.
      Returns:
      the scaled data value as a double. The Double.NaN value is used if the data value is missing.

    • getValue

      public double getValue(int index)
      Reads a scaled data value. The data value is read from the data array and scaled according to the scaling factor and offset.
      Parameters:
      index - the index into the data array.
      Returns:
      the scaled data value as a double. The Double.NaN value is used if the data value is missing.
      See Also:

    • setValue

      public void setValue(DataLocation loc, double val)
      Writes a scaled data value. The data value is scaled according to the scaling factor and offset and written to the data array.
      Parameters:
      loc - the data location.
      val - the data value as a double. If the data value is Double.NaN and the missing value is non-null, the missing value is written to the array.
      See Also:

    • setValue

      public void setValue(int index, double val)
      Writes a scaled data value. The data value is scaled according to the scaling factor and offset and written to the data array.
      Parameters:
      index - the index into the data array.
      val - the data value as a double. If the data value is Double.NaN and the missing value is non-null, the missing value is written to the array.
      See Also:

    • setValue

      protected void setValue(int index, Object data, double val)
      Writes a scaled data value. The data value is scaled according to the scaling factor and offset and written to the data array.
      Parameters:
      index - the index into the data array.
      data - the data array to use for raw data.
      val - the data value as a double. If the data value is Double.NaN and the missing value is non-null, the missing value is written to the array.

    • format

      public String format(DataLocation loc)
      Formats a data value to a string.
      Parameters:
      loc - the data value location.
      Returns:
      the formatted data value string.
      See Also:

    • format

      public String format(int index)
      Formats a data value to a string.
      Parameters:
      index - the index into the data array.
      Returns:
      the formatted data value string.
      See Also:

    • format

      public String format(double val)
      Formats a data value to a string.
      Parameters:
      val - the data value as a double.
      Returns:
      the formatted data value string.
      See Also:

    • getStatistics

      public Statistics getStatistics(double factor)
      Gets the data variable statistics. The computed statistics include the number of valid data values sampled, minimum, maximum, mean, and standard deviation.
      Parameters:
      factor - the sample size as a fraction of the total number of values. For example, to sample 1 percent of the data the sample size is 0.01. The sample size is used to compute an optimal stride while preserving sample frequency uniformity in each dimension. The total number of sampled values is guaranteed to be bounded below by the requested sample size.
      Returns:
      the data statistics. If the number of valid data values is zero, the minimum, maximum, mean, and standard deviation values are undefined.
      See Also:

    • getOptimalStride

      public int[] getOptimalStride(DataLocation start, DataLocation end, double factor, int minCount)
      Gets the optimal statistical sampling stride for this variable based on a desired sampling factor and minimum number of values. This method may be used in the case where statistics are desired for a subset of the variable, but the sampling factor produces a stride which is too large and results in too few data values being retrieved.
      Parameters:
      start - the starting data location.
      end - the ending data location.
      factor - the sampling factor as a value in the range [0..1].
      minCount - the minimum desired number of values. The stride should ensure that the number of values actually sampled is greater than this quantity.
      Returns:
      the optimal stride vector.
      See Also:

    • getStatistics

      public Statistics getStatistics(DataLocation start, DataLocation end, double factor)
      Gets the data variable statistics. The computed statistics include the number of valid data values sampled, minimum, maximum, mean, and standard deviation.
      Parameters:
      start - the starting data location. If null, the start is the first location.
      end - the ending data location. If null, the end is the last location.
      factor - the sample size as a fraction of the total number of values. For example, to sample 1 percent of the data the sample size is 0.01. The sample size is used to compute an optimal stride while preserving sample frequency uniformity in each dimension. The total number of sampled values is guaranteed to be bounded below by the requested sample size.
      Returns:
      the data statistics. If the number of valid data values is zero, the minimum, maximum, mean, and standard deviation values are undefined.
      See Also:

    • getStatistics

      public Statistics getStatistics(int[] stride)
      Gets the data variable statistics. The computed statistics include the number of valid data values sampled, minimum, maximum, mean, and standard deviation.
      Parameters:
      stride - the data location stride in each dimension. The stride is used to reduce the number of calculations required to compute the statistics. The data variable is sampled at every nth value along each dimension. For example if the stride is 4, every 4th value is sampled. If null, the stride is 1 in each dimension.
      Returns:
      the data statistics. If the number of valid data values is zero, the minimum, maximum, mean, and standard deviation values are undefined.
      See Also:

    • getStatistics

      public Statistics getStatistics(DataLocation start, DataLocation end, int[] stride)
      Gets the data variable statistics. The computed statistics include the number of valid data values sampled, minimum, maximum, mean, and standard deviation.
      Parameters:
      start - the starting data location. If null, the start is the first location.
      end - the ending data location. If null, the end is the last location.
      stride - the data location stride in each dimension. The stride is used to reduce the number of calculations required to compute the statistics. The data variable is sampled at every nth value along each dimension. For example if the stride is 4, every 4th value is sampled. If null, the stride is 1 in each dimension.
      Returns:
      the data statistics. If the number of valid data values is zero, the minimum, maximum, mean, and standard deviation values are set to Double.NaN.
      Throws:
      RuntimeException - if the start or end locations are invalid.
      See Also:

    • getDecimals

      public static int getDecimals(String number)
      Gets the number of digits after the decimal place in a string representing a fractional number with possible exponential part.
      Parameters:
      number - the fractional number string.
      Returns:
      the number of decimal digits.

    • convertUnits

      public void convertUnits(String newUnitSpec)
      Converts the units of this variable to the new units. The scaling factor and offset are adjusted accordingly. If the new units are identical to the existing units, no operation is performed.
      Parameters:
      newUnitSpec - the new units to convert to.
      Throws:
      IllegalArgumentException - if the existing or new data units cannot be recognized, or if the new units are incompatible with the existing units.

    • setAccessHint

      public void setAccessHint(int[] start, int[] end, int[] stride)
      Sets a hint to the variable that subsequent data access will only read/write values within the specified data extents. This method performs no action in the abstract class, but may be used by subclasses that wish to setup internal structures prior to some sort of intensive data access. For example, if data rendering is to occur, it might be useful to read in only the data that will be rendered and make it availalble.
      Parameters:
      start - the starting data coordinates.
      end - the ending data coordinates.
      stride - the data stride along each dimension.

    • setAccessType

      public void setAccessType(DataVariable.AccessType type)
      Sets a hint to the variable that subsequent data access will be of the specified access type. This is an opportunity for the underlying data structures to be rearranged to better accomodate the specified access type.
      Parameters:
      type - the access type hint.
      Since:
      3.8.1

    • toString

      public String toString()
      Gets a string representation of this variable.
      Overrides:
      toString in class Object

    • dispose

      public void dispose()
      Disposes of any resources used by this variable prior to being finalized. After calling this method, any calls to retrieve data values may generate errors.
      Since:
      3.3.1