Package ucar.nc2
Class Variable
- java.lang.Object
-
- ucar.nc2.Variable
-
- All Implemented Interfaces:
Comparable<VariableSimpleIF>
,ProxyReader
,VariableSimpleIF
- Direct Known Subclasses:
Structure
,VariableDS
@Immutable public class Variable extends Object implements VariableSimpleIF, ProxyReader
A logical container for data, with a dataType, a set of Dimensions that define its array shape, and a set of Attributes. The data is a multidimensional array of primitive types, Strings, or Structures. Data access is done through the read() methods, which return a memory resident Array.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Variable.Builder<T extends Variable.Builder<T>>
-
Field Summary
Fields Modifier and Type Field Description static boolean
permitCaching
Globally permit or prohibit caching.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description AttributeContainer
attributes()
The attributes contained by this Variable.static Variable.Builder<?>
builder()
Get Builder for this class that allows subclassing.int
compareTo(VariableSimpleIF o)
Sort by nameboolean
equals(Object oo)
Attribute
findAttribute(String name)
Find the attribute by name, return null if not existString
findAttributeString(String attName, String defaultValue)
Find a String-valued Attribute by name (ignore case), return the String value of the Attribute.int
findDimensionIndex(String name)
Find the index of the named Dimension in this Variable.ArrayType
getArrayType()
Get the data type of the Variable.String
getDatasetLocation()
The location of the dataset this belongs to.String
getDescription()
Get the description of the Variable.Dimension
getDimension(int i)
Get the ith dimension.com.google.common.collect.ImmutableList<Dimension>
getDimensions()
Get the list of dimensions used by this variable.com.google.common.collect.ImmutableSet<Dimension>
getDimensionSet()
Get the variable's Dimensions as a Set.String
getDimensionsString()
Get the list of Dimension names, space delineated.int
getElementSize()
Get the number of bytes for one element of this Variable.EnumTypedef
getEnumTypedef()
Get the EnumTypedef, only use if getDataType.isEnum()String
getFileTypeId()
Get the file type id for the underlying data source.String
getFullName()
Get the full name of this Variable.String
getNameAndDimensions()
Get the display name plus the dimensions, eg 'float name(dim1, dim2)'void
getNameAndDimensions(Formatter buf, boolean useFullName, boolean strict)
Add display name plus the dimensions to the FormatterNetcdfFile
getNetcdfFile()
Get the NetcdfFile that this variable is contained in.Group
getParentGroup()
Get its containing Group, never nullStructure
getParentStructure()
Get its parent structure, or null if not in structureint
getRank()
Get the number of dimensions of the Variable, aka the rank.Section
getSection()
Get shape as a Section object.int[]
getShape()
Get the shape: length of Variable in each dimension.int
getShape(int index)
Get the size of the ith dimensionString
getShortName()
The short name of the variablelong
getSize()
Get the total number of elements in the Variable.int
getSizeToCache()
If total data size is less than SizeToCache in bytes, then cache.Object
getSPobject()
Get immutable service provider opaque object.String
getUnitsString()
Get the Unit String for the Variable.boolean
hasCachedData()
If this has cached data, or source data.int
hashCode()
void
invalidateCache()
Remove any cached values (but not srcData)boolean
isCaching()
Will this Variable be cached when read.boolean
isCoordinateVariable()
Calculate if this is a classic coordinate variable: has same name as its first dimension.boolean
isMemberOfStructure()
Is this a Structure Member?boolean
isMetadata()
Is this variable metadata?.boolean
isScalar()
Whether this is a scalar Variable (rank == 0).boolean
isUnlimited()
Can this variable's size grow?.boolean
isVariableLength()
Does this variable have a variable length dimension? If so, it has as one of its dimensions Dimension.VLEN.String
lookupEnumString(int val)
Lookup the enum string for this value.Array<?>
proxyReadArray(Variable client, Section section, CancelTask cancelTask)
public by accident, do not call directly.Array<?>
proxyReadArray(Variable client, CancelTask cancelTask)
public by accident, do not call directly.Array<?>
readArray()
Read all the data for this Variable and return a memory resident Array.Array<?>
readArray(Section section)
Read a section of the data for this Variable from the netcdf file and return a memory resident Array.byte
readScalarByte()
Get the value as a byte for a scalar Variable.double
readScalarDouble()
Get the value as a double for a scalar Variable.float
readScalarFloat()
Get the value as a float for a scalar Variable.int
readScalarInt()
Get the value as a int for a scalar Variable.long
readScalarLong()
Get the value as a long for a scalar Variable.short
readScalarShort()
Get the value as a short for a scalar Variable.String
readScalarString()
Get the value as a String for a scalar Variable.Variable
reduce(List<Dimension> dims)
Create a new Variable that is a logical view of this Variable, by eliminating the specified dimension(s) of length 1.Variable
section(Section subsection)
void
setCaching(boolean caching)
Set whether to cache or not.Variable
slice(int dim, int value)
Create a new Variable that is a logical slice of this Variable, by fixing the specified dimension at the specified index value.Variable.Builder<?>
toBuilder()
Turn into a mutable Builder.String
toString()
String
toStringDebug()
Debugging info
-
-
-
Field Detail
-
permitCaching
public static boolean permitCaching
Globally permit or prohibit caching. For use during testing and debugging.A
true
value for this field does not indicate whether a Variableis caching
, only that it's permitted to cache.
-
-
Method Detail
-
findDimensionIndex
public int findDimensionIndex(String name)
Find the index of the named Dimension in this Variable.- Parameters:
name
- the name of the dimension- Returns:
- the index of the named Dimension, or -1 if not found.
-
getDatasetLocation
public String getDatasetLocation()
The location of the dataset this belongs to. Labeling purposes only.
-
getArrayType
public ArrayType getArrayType()
Get the data type of the Variable.- Specified by:
getArrayType
in interfaceVariableSimpleIF
-
getDescription
public String getDescription()
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 interfaceVariableSimpleIF
- Returns:
- description, or null if not found.
-
getDimensions
public com.google.common.collect.ImmutableList<Dimension> getDimensions()
Get the list of dimensions used by this variable. The most slowly varying (leftmost for Java and C programmers) dimension is first. For scalar variables, the list is empty.- Specified by:
getDimensions
in interfaceVariableSimpleIF
-
getDimensionSet
public com.google.common.collect.ImmutableSet<Dimension> getDimensionSet()
Get the variable's Dimensions as a Set.
-
getDimension
public Dimension getDimension(int i)
Get the ith dimension.- Parameters:
i
- index of the dimension.- Returns:
- requested Dimension, or null if i is out of bounds.
-
getDimensionsString
public String getDimensionsString()
Get the list of Dimension names, space delineated.- Returns:
- Dimension names, space delineated
-
getElementSize
public int getElementSize()
Get the number of bytes for one element of this Variable. For Variables of primitive type, this is equal to getDataType().getSize(). Variables of String type dont know their size, so what they return is undefined. Variables of Structure type return the total number of bytes for all the members of one Structure, plus possibly some extra padding, depending on the underlying format. Variables of Sequence type return the number of bytes of one element.- Returns:
- total number of bytes for the Variable
-
getEnumTypedef
@Nullable public EnumTypedef getEnumTypedef()
Get the EnumTypedef, only use if getDataType.isEnum()
-
getFileTypeId
@Nullable public String getFileTypeId()
Get the file type id for the underlying data source.- Returns:
- registered id of the file type
- See Also:
- "https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"
-
getFullName
public String getFullName()
Get the full name of this Variable. seeNetcdfFiles.makeFullName(Variable)
- Specified by:
getFullName
in interfaceVariableSimpleIF
-
getNetcdfFile
@Nullable public NetcdfFile getNetcdfFile()
Get the NetcdfFile that this variable is contained in. May be null when the Variable is self contained.
-
getParentGroup
public Group getParentGroup()
Get its containing Group, never null
-
getParentStructure
@Nullable public Structure getParentStructure()
Get its parent structure, or null if not in structure
-
getRank
public int getRank()
Get the number of dimensions of the Variable, aka the rank.- Specified by:
getRank
in interfaceVariableSimpleIF
-
getShape
public int[] getShape()
Get the shape: length of Variable in each dimension. A scalar (rank 0) will have an int[0] shape.- Specified by:
getShape
in interfaceVariableSimpleIF
-
getShape
public int getShape(int index)
Get the size of the ith dimension
-
getSection
public Section getSection()
Get shape as a Section object.- Returns:
- Section describing this Variable's shape.
-
getShortName
public String getShortName()
The short name of the variable- Specified by:
getShortName
in interfaceVariableSimpleIF
-
getSize
public long getSize()
Get the total number of elements in the Variable. If this is an unlimited Variable, will use the current number of elements. If this is a Sequence, will return 1. If variable length, will skip vlen dimensions- Returns:
- total number of elements in the Variable.
-
getUnitsString
@Nullable public String getUnitsString()
Get the Unit String for the Variable. Looks for the CDM.UNITS attribute value- Specified by:
getUnitsString
in interfaceVariableSimpleIF
- Returns:
- unit string, or null if not found.
-
isCoordinateVariable
public boolean isCoordinateVariable()
Calculate if this is a classic coordinate variable: has same name as its first dimension. If type char, must be 2D, else must be 1D.- Returns:
- true if a coordinate variable.
-
isMemberOfStructure
public boolean isMemberOfStructure()
Is this a Structure Member?
-
isMetadata
public boolean isMetadata()
Is this variable metadata?. True if its values need to be included explicitly in NcML output.
-
isScalar
public boolean isScalar()
Whether this is a scalar Variable (rank == 0).
-
isUnlimited
public boolean isUnlimited()
Can this variable's size grow?. This is equivalent to saying at least one of its dimensions is unlimited.- Returns:
- boolean true iff this variable can grow
-
isVariableLength
public boolean isVariableLength()
Does this variable have a variable length dimension? If so, it has as one of its dimensions Dimension.VLEN.- Returns:
- true if Variable has a variable length dimension?
-
lookupEnumString
@Nullable public String lookupEnumString(int val)
Lookup the enum string for this value. Can only be called on enum types, where dataType.isEnum() is true.- Parameters:
val
- the integer value of this enum- Returns:
- the String value, or null if not exist.
-
section
public Variable section(Section subsection) throws InvalidRangeException
- Throws:
InvalidRangeException
-
slice
public Variable slice(int dim, int value) throws ucar.ma2.InvalidRangeException
Create a new Variable that is a logical slice of this Variable, by fixing the specified dimension at the specified index value. This reduces rank by 1. No data is read until a read method is called on it.- Parameters:
dim
- which dimension to fixvalue
- at what index value- Returns:
- a new Variable which is a logical slice of this Variable.
- Throws:
ucar.ma2.InvalidRangeException
- if dimension or value is illegal
-
reduce
public Variable reduce(List<Dimension> dims)
Create a new Variable that is a logical view of this Variable, by eliminating the specified dimension(s) of length 1. No data is read until a read method is called on it.- Parameters:
dims
- list of dimensions of length 1 to reduce- Returns:
- a new Variable which is a logical slice of this Variable.
-
readScalarByte
public byte readScalarByte() throws IOException
Get the value as a byte for a scalar Variable. May also be one-dimensional of length 1.- Throws:
IOException
- if theres an IO ErrorUnsupportedOperationException
- if not a scalar Variable or one-dimensional of length 1.RuntimeException
- if data type not convertible to byte
-
readScalarShort
public short readScalarShort() throws IOException
Get the value as a short for a scalar Variable. May also be one-dimensional of length 1.- Throws:
IOException
- if theres an IO ErrorUnsupportedOperationException
- if not a scalar Variable or one-dimensional of length 1.RuntimeException
- if data type not convertible to short
-
readScalarInt
public int readScalarInt() throws IOException
Get the value as a int for a scalar Variable. May also be one-dimensional of length 1.- Throws:
IOException
- if theres an IO ErrorUnsupportedOperationException
- if not a scalar Variable or one-dimensional of length 1.RuntimeException
- if data type not convertible to int
-
readScalarLong
public long readScalarLong() throws IOException
Get the value as a long for a scalar Variable. May also be one-dimensional of length 1.- Throws:
IOException
- if theres an IO ErrorUnsupportedOperationException
- if not a scalar VariableRuntimeException
- if data type not convertible to long
-
readScalarFloat
public float readScalarFloat() throws IOException
Get the value as a float for a scalar Variable. May also be one-dimensional of length 1.- Throws:
IOException
- if theres an IO ErrorUnsupportedOperationException
- if not a scalar Variable or one-dimensional of length 1.RuntimeException
- if data type not convertible to float
-
readScalarDouble
public double readScalarDouble() throws IOException
Get the value as a double for a scalar Variable. May also be one-dimensional of length 1.- Throws:
IOException
- if theres an IO ErrorUnsupportedOperationException
- if not a scalar Variable or one-dimensional of length 1.RuntimeException
- if data type not convertible to double
-
readScalarString
public String readScalarString() throws IOException
Get the value as a String for a scalar Variable. May also be one-dimensional of length 1. May also be one-dimensional of type CHAR, which will be turned into a scalar String.- Throws:
IOException
- if theres an IO ErrorIllegalArgumentException
- if data type not STRING or CHAR
-
readArray
public Array<?> readArray() throws IOException
Read all the data for this Variable and return a memory resident Array. The Array has the same element type and shape as the Variable.- Throws:
IOException
-
readArray
public Array<?> readArray(@Nullable Section section) throws IOException, InvalidRangeException
Read a section of the data for this Variable from the netcdf file and return a memory resident Array. The Array has the same element type as the Variable, and the requested shape. Note that this does not do rank reduction, so the returned Array has the same rank as the Variable. Use Array.reduce() for rank reduction.- Parameters:
section
- The section of data to read. Must be null or same rank as variable. If list is null, assume all data. Each Range corresponds to a Dimension. If the Range object is null, it means use the entire dimension.- Throws:
IOException
InvalidRangeException
-
proxyReadArray
public Array<?> proxyReadArray(Variable client, CancelTask cancelTask) throws IOException
public by accident, do not call directly.- Specified by:
proxyReadArray
in interfaceProxyReader
- Throws:
IOException
-
proxyReadArray
public Array<?> proxyReadArray(Variable client, Section section, CancelTask cancelTask) throws IOException, InvalidRangeException
public by accident, do not call directly.- Specified by:
proxyReadArray
in interfaceProxyReader
- Throws:
IOException
InvalidRangeException
-
getNameAndDimensions
public String getNameAndDimensions()
Get the display name plus the dimensions, eg 'float name(dim1, dim2)'
-
getNameAndDimensions
public void getNameAndDimensions(Formatter buf, boolean useFullName, boolean strict)
Add display name plus the dimensions to the Formatter- Parameters:
buf
- add info to thisuseFullName
- use full name else short name. strict = true implies short namestrict
- strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escaping
-
toStringDebug
public String toStringDebug()
Debugging info
-
compareTo
public int compareTo(VariableSimpleIF o)
Sort by name- Specified by:
compareTo
in interfaceComparable<VariableSimpleIF>
-
attributes
public AttributeContainer attributes()
The attributes contained by this Variable.- Specified by:
attributes
in interfaceVariableSimpleIF
-
findAttribute
@Nullable public Attribute findAttribute(String name)
Find the attribute by name, return null if not exist
-
findAttributeString
public String findAttributeString(String attName, String defaultValue)
Find a String-valued Attribute by name (ignore case), return the String value of the Attribute.- Returns:
- the attribute value, or defaultValue if not found
-
getSPobject
public Object getSPobject()
Get immutable service provider opaque object.
-
getSizeToCache
public int getSizeToCache()
If total data size is less than SizeToCache in bytes, then cache.- Returns:
- size at which caching happens
-
setCaching
public void setCaching(boolean caching)
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. if false, cachedData is cleared.
-
isCaching
public boolean isCaching()
Will this Variable be cached when read. Set externally by setCaching, or calculated based on total size < sizeToCache.This will always return
false
ifcaching isn't permitted
.- Returns:
- true is caching
-
invalidateCache
public void invalidateCache()
Remove any cached values (but not srcData)
-
hasCachedData
public boolean hasCachedData()
If this has cached data, or source data.
-
toBuilder
public Variable.Builder<?> toBuilder()
Turn into a mutable Builder. Can use toBuilder().build() to copy.
-
builder
public static Variable.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"
-
-