ucar.nc2.dataset
Class VariableDS

java.lang.Object
  extended by ucar.nc2.Variable
      extended by ucar.nc2.dataset.VariableDS
All Implemented Interfaces:
Comparable<VariableSimpleIF>, Enhancements, EnhanceScaleMissing, VariableEnhanced, ProxyReader, VariableIF, VariableSimpleIF
Direct Known Subclasses:
AddeVariable, CoordinateAxis

public class VariableDS
extends Variable
implements VariableEnhanced, EnhanceScaleMissing

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

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

Author:
caron
See Also:
NetcdfDataset

Nested Class Summary
 
Nested classes/interfaces inherited from class ucar.nc2.Variable
Variable.Cache
 
Field Summary
protected  DataType orgDataType
           
protected  String orgName
           
protected  Variable orgVar
           
 
Fields inherited from class ucar.nc2.Variable
attributes, cache, dataType, debugCaching, defaultCoordsSizeToCache, defaultSizeToCache, dimensions, elementSize, group, hashCode, isMetadata, isVariableLength, ncfile, parent, proxyReader, shape, shapeAsSection, shortName, sizeToCache, spiObject
 
Constructor Summary
  VariableDS(Group group, Structure parent, String shortName, Variable orgVar)
          Make a new VariableDS, delegate data reading to the original variable, but otherwise dont take any info from it.
  VariableDS(Group g, Variable orgVar, boolean enhance)
          Wrap the given Variable, making it into a VariableDS.
  VariableDS(NetcdfDataset ds, Group group, Structure parentStructure, String shortName, DataType dataType, String dims, String units, String desc)
          Constructor when there's no underlying variable.
protected VariableDS(VariableDS vds, boolean isCopy)
          Copy constructor, for subclasses.
 
Method Summary
protected  Array _read()
           
protected  Array _read(Section section)
           
 void addCoordinateSystem(CoordinateSystem p0)
          Add a CoordinateSystem to the dataset.
 void clearCoordinateSystems()
          Remove coordinate system info.
protected  Array convertEnums(Array values)
           
 Array convertScaleOffsetMissing(Array data)
          Convert data if hasScaleOffset, using scale and offset.
 double convertScaleOffsetMissing(byte value)
          Convert this byte value to a double, using scale/offset/missing value if applicable
 double convertScaleOffsetMissing(double value)
          Convert this double value using scale/offset/missing value if applicable
 double convertScaleOffsetMissing(int value)
          Convert this int value to a double, using scale/offset/missing value if applicable
 double convertScaleOffsetMissing(long value)
          Convert this long value to a double, using scale/offset/missing value if applicable
 double convertScaleOffsetMissing(short value)
          Convert this short value to a double, using scale/offset/missing value if applicable
protected  Variable copy()
           
 void enhance(Set<NetcdfDataset.Enhance> mode)
          DO NOT USE DIRECTLY.
 List<CoordinateSystem> getCoordinateSystems()
          Get the list of Coordinate Systems for this Variable.
 String getDescription()
          Get the description of the Variable.
 EnumSet<NetcdfDataset.Enhance> getEnhanceMode()
          Get the enhancement mode
 Array getMissingDataArray(int[] shape)
          Return Array with missing data
 DataType getOriginalDataType()
          When this wraps another Variable, get the original Variable's DataType.
 String getOriginalName()
          When this wraps another Variable, get the original Variable's name.
 Variable getOriginalVariable()
          A VariableDS usually wraps another Variable.
 String getUnitsString()
          Get the Unit String for the Variable.
 boolean getUseNaNs()
          get whether to use NaNs for missing float/double values (for efficiency)
 double getValidMax()
          return the maximum value in the valid range
 double getValidMin()
          return the minimum value in the valid range
 boolean hasCachedDataRecurse()
           
 boolean hasFillValue()
          true if Variable has _FillValue attribute
 boolean hasInvalidData()
          true if Variable has valid_range, valid_min or valid_max attributes
 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 offet
 boolean isFillValue(double p0)
          return true if val equals the _FillValue
 boolean isInvalidData(double p0)
          return true if val is outside the valid range
 boolean isMissing(double val)
          true if val is a missing data value.
 boolean isMissingFast(double val)
          true if val is a missing data value.
 boolean isMissingValue(double p0)
          return true if val equals a missing_value
 String lookupEnumString(int val)
          Lookup the enum string for this value.
 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 removeCoordinateSystem(CoordinateSystem p0)
          Remove a CoordinateSystem from the dataset.
 void setCaching(boolean caching)
          Set whether to cache or not.
 void setFillValueIsMissing(boolean p0)
          set if _FillValue is considered isMissing(); better set in constructor if possible
 void setInvalidDataIsMissing(boolean p0)
          set if valid_range is considered isMissing(); better set in constructor if possible
 void setMissingDataIsMissing(boolean p0)
          set if missing_data is considered isMissing(); better set in constructor if possible
 String setName(String newName)
          Set the short name, converting to valid CDM object name if needed.
 void setOriginalVariable(Variable orgVar)
          Set the Variable to wrap.
 void setUnitsString(String units)
          Set the Unit String for this Variable.
 void setUseNaNs(boolean useNaNs)
          set whether to use NaNs for missing float/double values, for efficiency
 void showScaleMissingProxy(Formatter f)
          public for debugging
 String toStringDebug()
          String representation of Variable and its attributes.
 
Methods inherited from class ucar.nc2.Variable
addAttribute, clone, compareTo, createNewCache, equals, extraInfo, findAttribute, findAttributeIgnoreCase, findDimensionIndex, getAttributes, getDataType, getDimension, getDimensions, getDimensionsAll, getDimensionsString, getElementSize, getEnumTypedef, getFullName, getFullNameEscaped, getName, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getParentGroup, getParentStructure, getProxyReader, getRanges, getRank, getScalarData, getShape, getShape, getShapeAll, getShapeAsSection, getShortName, getSize, getSizeToCache, getSPobject, hasCachedData, hashCode, invalidateCache, isCaching, isCoordinateVariable, isImmutable, isMemberOfStructure, isMetadata, isScalar, isUnknownLength, isUnlimited, isUnsigned, isVariableLength, read, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, readToByteChannel, remove, removeAttribute, removeAttributeIgnoreCase, resetDimensions, resetShape, section, section, setCachedData, setCachedData, setDataType, setDimension, setDimensions, setDimensions, setDimensionsAnonymous, setElementSize, setEnumTypedef, setImmutable, setIsScalar, setParentGroup, setParentStructure, setProxyReader, setSizeToCache, setSPobject, setValues, setValues, slice, toString, writeCDL, writeCDL
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ucar.nc2.VariableIF
findAttribute, findAttributeIgnoreCase, findDimensionIndex, getAttributes, getDataType, getDimension, getDimensions, getDimensionsAll, getElementSize, getFullName, getFullNameEscaped, getNameAndDimensions, getParentGroup, getParentStructure, getRanges, getRank, getShape, getShapeAsSection, getShortName, getSize, isCoordinateVariable, isMemberOfStructure, isMetadata, isScalar, isUnlimited, isUnsigned, isVariableLength, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, section
 
Methods inherited from interface ucar.nc2.VariableSimpleIF
getName
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Field Detail

orgVar

protected Variable orgVar

orgDataType

protected DataType orgDataType

orgName

protected String orgName
Constructor Detail

VariableDS

public VariableDS(NetcdfDataset ds,
                  Group group,
                  Structure parentStructure,
                  String shortName,
                  DataType dataType,
                  String dims,
                  String units,
                  String desc)
Constructor when there's no underlying variable. You must also set the values by doing one of:
  1. set the values with setCachedData()
  2. set a proxy reader with setProxyReader()
Otherwise, it is assumed to have constant values (using the fill value)

Parameters:
ds - the containing dataset
group - the containing group
parentStructure - the containing Structure (may be null)
shortName - the (short) name
dataType - the data type
dims - list of dimension names, these must already exist in the Group; empty String = scalar
units - String value of units, may be null
desc - String value of description, may be null

VariableDS

public VariableDS(Group group,
                  Structure parent,
                  String shortName,
                  Variable orgVar)
Make a new VariableDS, delegate data reading to the original variable, but otherwise dont take any info from it. This is used by NcML explicit mode.

Parameters:
group - the containing group; may not be null
parent - parent Structure, may be null
shortName - variable shortName, must be unique within the Group
orgVar - the original Variable to wrap. The original Variable is not modified. Must not be a Structure, use StructureDS instead.

VariableDS

public VariableDS(Group g,
                  Variable orgVar,
                  boolean enhance)
Wrap the given Variable, making it into a VariableDS. Delegate data reading to the original variable. Take all metadata from original variable. Does not share cache, iosp.

Parameters:
g - logical container, if null use orgVar's group
orgVar - the original Variable to wrap. The original Variable is not modified. Must not be a Structure, use StructureDS instead.
enhance - if true, use NetcdfDataset.defaultEnhanceMode to define what enhancements are made. Note that this can change DataType and data values. You can also call enhance() later. If orgVar is VariableDS, then enhance is inherited from there, and this parameter is ignored.

VariableDS

protected VariableDS(VariableDS vds,
                     boolean isCopy)
Copy constructor, for subclasses. Used by copy() and CoordinateAxis Share everything except the coord systems.

Parameters:
vds - copy from here.
isCopy - called from copy()
Method Detail

copy

protected Variable copy()
Overrides:
copy in class Variable

clearCoordinateSystems

public void clearCoordinateSystems()
Remove coordinate system info.

Specified by:
clearCoordinateSystems in interface VariableEnhanced

enhance

public void enhance(Set<NetcdfDataset.Enhance> mode)
DO NOT USE DIRECTLY. public by accident. Calculate scale/offset/missing value info. This may change the DataType.

Specified by:
enhance in interface VariableEnhanced

getEnhanceMode

public EnumSet<NetcdfDataset.Enhance> getEnhanceMode()
Get the enhancement mode

Returns:
the enhancement mode

addCoordinateSystem

public void addCoordinateSystem(CoordinateSystem p0)
Description copied from interface: Enhancements
Add a CoordinateSystem to the dataset.

Specified by:
addCoordinateSystem in interface Enhancements
Parameters:
p0 - add this Coordinate System

removeCoordinateSystem

public void removeCoordinateSystem(CoordinateSystem p0)
Description copied from interface: Enhancements
Remove a CoordinateSystem from the dataset.

Specified by:
removeCoordinateSystem in interface Enhancements
Parameters:
p0 - remove this coordinate system

getCoordinateSystems

public List<CoordinateSystem> getCoordinateSystems()
Description copied from interface: Enhancements
Get the list of Coordinate Systems for this Variable.

Specified by:
getCoordinateSystems in interface Enhancements
Returns:
list of type CoordinateSystem; may be empty but not null.

getDescription

public String getDescription()
Description copied from class: Variable
Get the description of the Variable. Default is to use "long_name" attribute value. If not exist, look for "description", "title", or "standard_name" attribute value (in that order).

Specified by:
getDescription in interface Enhancements
Specified by:
getDescription in interface VariableIF
Specified by:
getDescription in interface VariableSimpleIF
Overrides:
getDescription in class Variable
Returns:
description, or null if not found.

getUnitsString

public String getUnitsString()
Description copied from class: Variable
Get the Unit String for the Variable. Looks for the "units" attribute value

Specified by:
getUnitsString in interface Enhancements
Specified by:
getUnitsString in interface VariableIF
Specified by:
getUnitsString in interface VariableSimpleIF
Overrides:
getUnitsString in class Variable
Returns:
unit string, or null if not found.

setUnitsString

public void setUnitsString(String units)
Description copied from interface: VariableEnhanced
Set the Unit String for this Variable. Default is to use the "units" attribute.

Specified by:
setUnitsString in interface VariableEnhanced
Parameters:
units - unit string

convertScaleOffsetMissing

public Array convertScaleOffsetMissing(Array data)
Description copied from interface: EnhanceScaleMissing
Convert data if hasScaleOffset, using scale and offset. Also if useNaNs = true, return NaN if value is missing data.

Specified by:
convertScaleOffsetMissing in interface EnhanceScaleMissing
Parameters:
data - convert this
Returns:
converted data.

getValidMax

public double getValidMax()
Description copied from interface: EnhanceScaleMissing
return the maximum value in the valid range

Specified by:
getValidMax in interface EnhanceScaleMissing

getValidMin

public double getValidMin()
Description copied from interface: EnhanceScaleMissing
return the minimum value in the valid range

Specified by:
getValidMin in interface EnhanceScaleMissing

hasFillValue

public boolean hasFillValue()
Description copied from interface: EnhanceScaleMissing
true if Variable has _FillValue attribute

Specified by:
hasFillValue in interface EnhanceScaleMissing

hasInvalidData

public boolean hasInvalidData()
Description copied from interface: EnhanceScaleMissing
true if Variable has valid_range, valid_min or valid_max attributes

Specified by:
hasInvalidData in interface EnhanceScaleMissing

hasMissing

public boolean hasMissing()
Description copied from interface: EnhanceScaleMissing
true if Variable has missing data values

Specified by:
hasMissing in interface EnhanceScaleMissing
Returns:
true if Variable has missing data values

hasMissingValue

public boolean hasMissingValue()
Description copied from interface: EnhanceScaleMissing
true if Variable has missing_value attribute

Specified by:
hasMissingValue in interface EnhanceScaleMissing

hasScaleOffset

public boolean hasScaleOffset()
Description copied from interface: EnhanceScaleMissing
true if Variable data will be converted using scale and offet

Specified by:
hasScaleOffset in interface EnhanceScaleMissing

isFillValue

public boolean isFillValue(double p0)
Description copied from interface: EnhanceScaleMissing
return true if val equals the _FillValue

Specified by:
isFillValue in interface EnhanceScaleMissing

isInvalidData

public boolean isInvalidData(double p0)
Description copied from interface: EnhanceScaleMissing
return true if val is outside the valid range

Specified by:
isInvalidData in interface EnhanceScaleMissing

isMissing

public boolean isMissing(double val)
Description copied from interface: EnhanceScaleMissing
true if val is a missing data value.

Specified by:
isMissing in interface EnhanceScaleMissing
Parameters:
val - unpacked value
Returns:
true if this value is a misssing value

isMissingFast

public boolean isMissingFast(double val)
Description copied from interface: EnhanceScaleMissing
true if val is a missing data value. if useNaNs is true (default) and the variable is of type float or double, then assume that missing values have been set to NaN, which speeds up the test considerably.

Specified by:
isMissingFast in interface EnhanceScaleMissing
Parameters:
val - unpacked value
Returns:
true if this value is a misssing value

isMissingValue

public boolean isMissingValue(double p0)
Description copied from interface: EnhanceScaleMissing
return true if val equals a missing_value

Specified by:
isMissingValue in interface EnhanceScaleMissing

setFillValueIsMissing

public void setFillValueIsMissing(boolean p0)
Description copied from interface: EnhanceScaleMissing
set if _FillValue is considered isMissing(); better set in constructor if possible

Specified by:
setFillValueIsMissing in interface EnhanceScaleMissing

setInvalidDataIsMissing

public void setInvalidDataIsMissing(boolean p0)
Description copied from interface: EnhanceScaleMissing
set if valid_range is considered isMissing(); better set in constructor if possible

Specified by:
setInvalidDataIsMissing in interface EnhanceScaleMissing

setMissingDataIsMissing

public void setMissingDataIsMissing(boolean p0)
Description copied from interface: EnhanceScaleMissing
set if missing_data is considered isMissing(); better set in constructor if possible

Specified by:
setMissingDataIsMissing in interface EnhanceScaleMissing

setUseNaNs

public void setUseNaNs(boolean useNaNs)
Description copied from interface: EnhanceScaleMissing
set whether to use NaNs for missing float/double values, for efficiency

Specified by:
setUseNaNs in interface EnhanceScaleMissing

getUseNaNs

public boolean getUseNaNs()
Description copied from interface: EnhanceScaleMissing
get whether to use NaNs for missing float/double values (for efficiency)

Specified by:
getUseNaNs in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(byte value)
Description copied from interface: EnhanceScaleMissing
Convert this byte value to a double, using scale/offset/missing value if applicable

Specified by:
convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(short value)
Description copied from interface: EnhanceScaleMissing
Convert this short value to a double, using scale/offset/missing value if applicable

Specified by:
convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(int value)
Description copied from interface: EnhanceScaleMissing
Convert this int value to a double, using scale/offset/missing value if applicable

Specified by:
convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(long value)
Description copied from interface: EnhanceScaleMissing
Convert this long value to a double, using scale/offset/missing value if applicable

Specified by:
convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(double value)
Description copied from interface: EnhanceScaleMissing
Convert this double value using scale/offset/missing value if applicable

Specified by:
convertScaleOffsetMissing in interface EnhanceScaleMissing

getOriginalVariable

public Variable getOriginalVariable()
A VariableDS usually wraps another Variable.

Specified by:
getOriginalVariable in interface VariableEnhanced
Returns:
original Variable or null

setOriginalVariable

public void setOriginalVariable(Variable orgVar)
Set the Variable to wrap. Used by NcML explicit mode.

Specified by:
setOriginalVariable in interface VariableEnhanced
Parameters:
orgVar - original Variable, must not be a Structure

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 anothe rvariable

getOriginalName

public String getOriginalName()
When this wraps another Variable, get the original Variable's name.

Specified by:
getOriginalName in interface VariableEnhanced
Returns:
original Variable's name

lookupEnumString

public 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

setName

public String setName(String newName)
Description copied from class: Variable
Set the short name, converting to valid CDM object name if needed.

Overrides:
setName in class Variable
Parameters:
newName - set to this value
Returns:
valid CDM object name

toStringDebug

public String toStringDebug()
Description copied from class: Variable
String representation of Variable and its attributes.

Specified by:
toStringDebug in interface VariableIF
Overrides:
toStringDebug in class Variable

hasCachedDataRecurse

public boolean hasCachedDataRecurse()

setCaching

public void setCaching(boolean caching)
Description copied from class: Variable
Set whether to cache or not. Implies that the entire array will be stored, once read. Normally this is set automatically based on size of data.

Overrides:
setCaching in class Variable
Parameters:
caching - set if caching.

_read

protected Array _read()
               throws IOException
Overrides:
_read in class Variable
Throws:
IOException

reallyRead

public Array reallyRead(Variable client,
                        CancelTask cancelTask)
                 throws 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:
IOException - on error

_read

protected Array _read(Section section)
               throws IOException,
                      InvalidRangeException
Overrides:
_read in class Variable
Throws:
IOException
InvalidRangeException

reallyRead

public Array reallyRead(Variable client,
                        Section section,
                        CancelTask cancelTask)
                 throws 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:
IOException - on error
InvalidRangeException - if section has incorrect rank or illegal shape.

getMissingDataArray

public Array getMissingDataArray(int[] shape)
Return Array with missing data

Parameters:
shape - of this shape
Returns:
Array with given shape

showScaleMissingProxy

public void showScaleMissingProxy(Formatter f)
public for debugging

Parameters:
f - put info here

convertEnums

protected Array convertEnums(Array values)


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.