ucar.nc2
Class Variable

java.lang.Object
  ucar.nc2.Variable

All Implemented Interfaces:

VariableIF

Direct Known Subclasses:

Structure, VariableDS

public class Variable
extends java.lang.Object
implements VariableIF

A Variable is a logical container for data. It has a dataType, a set of Dimensions that define its array shape, and optionally 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.

Version:

$Revision: 1.50 $ $Date: 2006/05/19 23:20:52 $

Author:

caron

See Also:

Array

Field Summary

static int

defaultSizeToCache

Constructor Summary

Variable(NetcdfFile ncfile, Group group, Structure parentStructure, java.lang.String shortName)
Create a Variable.

Variable(Variable from)
Copy constructor

Method Summary

void	addAttribute(Attribute att) Add new or replace old if has same name
boolean	equals(java.lang.Object oo) Instances which have same content are equal.
Attribute	findAttribute(java.lang.String name) Find an Attribute by name.
Attribute	findAttributeIgnoreCase(java.lang.String name) Find an Attribute by name, ignoring the case.
int	findDimensionIndex(java.lang.String name) Find the index of the named Dimension in this Variable.
java.util.List	getAttributes() Returns the set of attributes for this variable.
Dimension	getCoordinateDimension() If this is a coordinate variable or axis, return the corresponding dimension.
DataType	getDataType() Get the data type of the Variable.
java.lang.String	getDescription() Get the description of the Variable.
Dimension	getDimension(int i) Get the ith dimension.
java.util.List	getDimensions() Get the list of dimensions used by this variable.
java.util.List	getDimensionsAll() Get list of Dimensions, including parents if any.
java.lang.String	getDimensionsString() Get the list of Dimension names, space delineated.
int	getElementSize() Get the number of bytes for one element of this Variable.
Variable	getIOVar() should not be public.
java.lang.String	getName() Get the full name of this Variable, starting from rootGroup.
void	getNameAndDimensions(java.lang.StringBuffer buf, boolean useFullName, boolean showDimLength) display name plus the dimensions
Group	getParentGroup() Get the containing Group.
Structure	getParentStructure() Get the parent Variable if this is a member of a Structure, or null if its not.
java.util.List	getRanges() Get index subsection as an array of Range objects.
java.util.List	getRangesAll() Get index subsection as an array of Range objects, including parents if any.
int	getRank() Get the number of dimensions of the Variable.
int[]	getShape() Get the shape: length of Variable in each dimension.
java.lang.String	getShortName() Get the short name of this Variable.
long	getSize() Get the total number of elements in the Variable.
int	getSizeToCache() If total data is less than SizeToCache in bytes, then cache.
java.lang.Object	getSPobject() should not be public
java.lang.String	getUnitsString() Get the Unit String for the Variable.
boolean	hasCachedData() Does this have its data read in and cached?
int	hashCode() Override Object.hashCode() to implement equals.
void	invalidateCache() Invalidate the data cache
boolean	isCaching() Will this Variable be cached when read.
boolean	isMemberOfStructure() Is this variable is a member of a Structure?.
boolean	isMetadata() Is this variable metadata?.
boolean	isScalar() Whether this is a scalar Variable (rank == 0).
boolean	isSection() Is this Variable a section of another variable ?.
boolean	isUnknownLength() Deprecated. use isVariableLength()
boolean	isUnlimited() Can this variable's size grow?.
boolean	isUnsigned() Is this Variable unsigned?.
boolean	isVariableLength() Does this variable have an variable length dimension.
Array	read() Read all the data for this Variable and return a memory resident Array.
Array	read(int[] origin, int[] shape) Read a section of the data for this Variable and return a memory resident Array.
Array	read(java.util.List section) Read a section of the data for this Variable from the netcdf file and return a memory resident Array.
Array	read(java.lang.String sectionSpec) Read data section specified by a "section selector", and return a memory resident Array.
Array	readAllStructures(java.util.List sectionAll, boolean flatten) Read data from all structures for this Variable.
Array	readAllStructuresSpec(java.lang.String sectionSpec, boolean flatten) Read data in all structures for this Variable, using a string sectionSpec to specify the section.
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.
java.lang.String	readScalarString() Get the value as a String for a scalar Variable.
boolean	remove(Attribute a) Remove an Attribute : uses the attribute hashCode to find it.
void	replaceDimension(Dimension dim) Replace a dimension with an equivalent one.
Variable	section(java.util.List section) Create a new Variable that is a logical subsection of this Variable.
void	setCachedData(Array cacheData, boolean isMetadata) Set the data cache
void	setCaching(boolean caching) Set whether to cache or not.
void	setDataType(DataType dataType) Set the data type
void	setDimension(int idx, Dimension dim) Set a dimension with an equivalent one.
void	setDimensions(java.util.List dims) Set the shape with a list of Dimensions.
void	setDimensions(java.lang.String dimString) Set the dimensions using the dimensions names.
void	setDimensionsAnonymous(int[] shape) Set the dimensions using all anonymous (unshared) dimensions
void	setElementSize(int elementSize) Set the element size.
void	setIOVar(Variable orgVar) should not be public.
void	setIsCoordinateAxis(Dimension dim) true is its a 1D coordinate axis or variable for its dimension
void	setName(java.lang.String shortName) Set the short name
void	setParentGroup(Group group) Set the parent group.
void	setParentStructure(Structure parent) Set the parent structure.
void	setSizeToCache(int sizeToCache) Set sizeToCache.
void	setSPobject(java.lang.Object spiObject) should not be public
java.lang.String	toString() String representation of Variable and its attributes.
java.lang.String	toStringDebug() String representation of Variable and its attributes.
java.lang.String	writeCDL(java.lang.String indent, boolean useFullName, boolean strict) String representation of a Variable and its attributes.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

defaultSizeToCache

public static final int defaultSizeToCache

See Also:

Constant Field Values

Constructor Detail

Variable

public Variable(NetcdfFile ncfile,
                Group group,
                Structure parentStructure,
                java.lang.String shortName)

Create a Variable. Also must call setDataType() and setDimensions()

Parameters:

ncfile - the containing NetcdfFile.

group - the containing group; if null, use rootGroup

parentStructure - the containing structure; may be null

shortName - variable shortName.

Variable

public Variable(Variable from)

Copy constructor

Method Detail

getName

public java.lang.String getName()

Get the full name of this Variable, starting from rootGroup. The name is unique within the entire NetcdfFile.

Specified by:

getName in interface VariableIF

getShortName

public java.lang.String getShortName()

Get the short name of this Variable. The name is unique within its parent group.

Specified by:

getShortName in interface VariableIF

getDataType

public DataType getDataType()

Get the data type of the Variable.

Specified by:

getDataType in interface VariableIF

getShape

public int[] getShape()

Get the shape: length of Variable in each dimension.

Specified by:

getShape in interface VariableIF

Returns:

int array whose length is the rank of this and whose values equal the length of that Dimension.

getSize

public long getSize()

Get the total number of elements in the Variable. If this is an unlimited Variable, will return the current number of elements. If this is a Sequence, will return 0.

Specified by:

getSize in interface VariableIF

Returns:

total number of elements in the Variable.

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.

Specified by:

getElementSize in interface VariableIF

Returns:

total number of bytes for the Variable

getRank

public int getRank()

Get the number of dimensions of the Variable.

Specified by:

getRank in interface VariableIF

getParentGroup

public Group getParentGroup()

Get the containing Group.

Specified by:

getParentGroup in interface VariableIF

getCoordinateDimension

public Dimension getCoordinateDimension()

If this is a coordinate variable or axis, return the corresponding dimension. If not, return null. A coordinate axis has this as its single dimension, and names this Dimensions's the coordinates. A coordinate variable is the same as a coordinate axis, but its name must match the dimension name. If numeric, coordinate axis must be strictly monotonically increasing or decreasing.

Specified by:

getCoordinateDimension in interface VariableIF

See Also:

Dimension.getCoordinateVariables()

isMetadata

public boolean isMetadata()

Is this variable metadata?. Yes, if needs to be included explicitly in NcML output.

Specified by:

isMetadata in interface VariableIF

isScalar

public boolean isScalar()

Whether this is a scalar Variable (rank == 0).

Specified by:

isScalar in interface VariableIF

isUnknownLength

public boolean isUnknownLength()

Deprecated. use isVariableLength()

isVariableLength

public boolean isVariableLength()

Does this variable have an variable length dimension. If so, it is a one-dimensional array with dimension = Dimension.UNKNOWN.

Specified by:

isVariableLength in interface VariableIF

isUnsigned

public boolean isUnsigned()

Is this Variable unsigned?. Only meaningful for byte, short, int, long types.

Specified by:

isUnsigned in interface VariableIF

isUnlimited

public boolean isUnlimited()

Can this variable's size grow?. This is equivalent to saying at least one of its dimensions is unlimited.

Specified by:

isUnlimited in interface VariableIF

Returns:

boolean true iff this variable can grow

getDimensions

public java.util.List 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 interface VariableIF

Returns:

List with objects of type ucar.nc2.Dimension

getDimension

public Dimension getDimension(int i)

Get the ith dimension.

Specified by:

getDimension in interface VariableIF

Parameters:

i - index of the dimension.

Returns:

requested Dimension, or null if i is out of bounds.

getDimensionsString

public java.lang.String getDimensionsString()

Get the list of Dimension names, space delineated.

findDimensionIndex

public int findDimensionIndex(java.lang.String name)

Find the index of the named Dimension in this Variable.

Specified by:

findDimensionIndex in interface VariableIF

Parameters:

name - the name of the dimension

Returns:

the index of the named Dimension, or -1 if not found.

getAttributes

public java.util.List getAttributes()

Returns the set of attributes for this variable.

Specified by:

getAttributes in interface VariableIF

Returns:

List of object type ucar.nc2.Attribute

findAttribute

public Attribute findAttribute(java.lang.String name)

Find an Attribute by name.

Specified by:

findAttribute in interface VariableIF

Parameters:

name - the name of the attribute

Returns:

the attribute, or null if not found

findAttributeIgnoreCase

public Attribute findAttributeIgnoreCase(java.lang.String name)

Find an Attribute by name, ignoring the case.

Specified by:

findAttributeIgnoreCase in interface VariableIF

Parameters:

name - the name of the attribute

Returns:

the attribute, or null if not found

getDescription

public java.lang.String getDescription()

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

Returns:

description, or null if not found.

getUnitsString

public java.lang.String getUnitsString()

Get the Unit String for the Variable. Default is to use "units" attribute value

Returns:

unit string, or null if not found.

getRanges

public java.util.List getRanges()

Get index subsection as an array of Range objects. If this is a section, will reflect the index range reletive to the original variable. If not a section, this will equal the shape.

Specified by:

getRanges in interface VariableIF

Returns:

array of Ranges, one for each Dimension.

isSection

public boolean isSection()

Is this Variable a section of another variable ?.

Specified by:

isSection in interface VariableIF

section

public Variable section(java.util.List section)
                 throws InvalidRangeException

Create a new Variable that is a logical subsection of this Variable. No data is read until a read method is called on it.

Specified by:

section in interface VariableIF

Parameters:

section - List of type ucar.ma2.Range, with size equal to getRank(). Each Range corresponds to a Dimension, and specifies the section of data to read in that Dimension. A Range object may be null, which means use the entire dimension.

Returns:

a new Variable which is a logical section of this Variable.

Throws:

InvalidRangeException

read

public Array read(int[] origin,
                  int[] shape)
           throws java.io.IOException,
                  InvalidRangeException

Read a section of the data for this Variable 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.

assert(origin[ii] + shape[ii]*stride[ii] <= Variable.shape[ii]);

Specified by:

read in interface VariableIF

Parameters:

origin - int array specifying the starting index. If null, assume all zeroes.

shape - int array specifying the extents in each dimension. If null, assume getShape(); This becomes the shape of the returned Array.

Returns:

the requested data in a memory-resident Array

Throws:

java.io.IOException

InvalidRangeException

read

public Array read(java.lang.String sectionSpec)
           throws java.io.IOException,
                  InvalidRangeException

Read data section specified by a "section selector", and return a memory resident Array. Uses Fortran 90 array section syntax.

Specified by:

read in interface VariableIF

Parameters:

sectionSpec - specification string, eg "1:2,10,:,1:100:10". May optionally have ().

Returns:

the requested data in a memory-resident Array

Throws:

java.io.IOException

InvalidRangeException

See Also:

for sectionSpec syntax

read

public Array read(java.util.List section)
           throws java.io.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.

If the Variable is a member of an array of Structures, this returns only the variable's data in the first Structure, so that the Array shape is the same as the Variable. To read the data in all structures, use readAllStructures().

Note this only allows you to specify a subset of this variable. If the variable is nested in a array of structures and you want to subset that, use NetcdfFile.read(String sectionSpec, boolean flatten);

Specified by:

read in interface VariableIF

Parameters:

section - list of Range specifying 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.

Returns:

the requested data in a memory-resident Array

Throws:

java.io.IOException

InvalidRangeException

See Also:

to read member variables in all structures, to read nested variables with Structure subsetting

read

public Array read()
           throws java.io.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.

If the Variable is a member of an array of Structures, this returns only the variable's data in the first Structure, so that the Array shape is the same as the Variable. To read the data in all structures, use readAllStructures().

Specified by:

read in interface VariableIF

Returns:

the requested data in a memory-resident Array.

Throws:

java.io.IOException

See Also:

to read member variables in all structures

isMemberOfStructure

public boolean isMemberOfStructure()

Is this variable is a member of a Structure?.

Specified by:

isMemberOfStructure in interface VariableIF

getParentStructure

public Structure getParentStructure()

Get the parent Variable if this is a member of a Structure, or null if its not.

Specified by:

getParentStructure in interface VariableIF

getRangesAll

public java.util.List getRangesAll()

Get index subsection as an array of Range objects, including parents if any. If not isMemberOfStructure(), this is the same as getRanges();

Returns:

array of Ranges, rank of v plus all parents.

getDimensionsAll

public java.util.List getDimensionsAll()

Get list of Dimensions, including parents if any.

Specified by:

getDimensionsAll in interface VariableIF

Returns:

array of Dimension, rank of v plus all parents.

readAllStructuresSpec

public Array readAllStructuresSpec(java.lang.String sectionSpec,
                                   boolean flatten)
                            throws java.io.IOException,
                                   InvalidRangeException

Read data in all structures for this Variable, using a string sectionSpec to specify the section. See readAllStructures(List section, boolean flatten) method for details.

Specified by:

readAllStructuresSpec in interface VariableIF

Parameters:

sectionSpec - specification string, eg "1:2,10,:,1:100:10"

flatten - if true, remove enclosing StructureData.

Returns:

the requested data which has the shape of the request.

Throws:

java.io.IOException

InvalidRangeException

See Also:

readAllStructures(java.util.List, boolean), Range.parseSpec(String sectionSpec)

readAllStructures

public Array readAllStructures(java.util.List sectionAll,
                               boolean flatten)
                        throws java.io.IOException,
                               InvalidRangeException

Read data from all structures for this Variable. This is used for member variables whose parent Structure(s) is not a scalar. You must specify a Range for each dimension in the enclosing parent Structure(s). The returned Array will have the same shape as the requested section.

If flatten is false, return nested Arrays of StructureData that correspond to the nested Structures. The innermost Array(s) will match the rank and type of the Variable, but they will be inside Arrays of StructureData.

If flatten is true, remove the Arrays of StructureData that wrap the data, and return an Array of the same type as the Variable. The shape of the returned Array will be an accumulation of all the shapes of the Structures containing the variable.

Specified by:

readAllStructures in interface VariableIF

Parameters:

sectionAll - an array of Range objects, one for each Dimension of the enclosing Structures, as well as for the Variable itself. If the list is null, use the full shape for everything. If an individual Range is null, use the full shape for that dimension.

flatten - if true, remove enclosing StructureData. Otherwise, each parent Structure will create a StructureData container for the returned data array.

Returns:

the requested data which has the shape of the request.

Throws:

java.io.IOException

InvalidRangeException

readScalarByte

public byte readScalarByte()
                    throws java.io.IOException

Get the value as a byte for a scalar Variable. May also be one-dimensional of length 1.

Specified by:

readScalarByte in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.

ForbiddenConversionException - if data type not convertible to byte

readScalarShort

public short readScalarShort()
                      throws java.io.IOException

Get the value as a short for a scalar Variable. May also be one-dimensional of length 1.

Specified by:

readScalarShort in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.

ForbiddenConversionException - if data type not convertible to short

readScalarInt

public int readScalarInt()
                  throws java.io.IOException

Get the value as a int for a scalar Variable. May also be one-dimensional of length 1.

Specified by:

readScalarInt in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.

ForbiddenConversionException - if data type not convertible to int

readScalarLong

public long readScalarLong()
                    throws java.io.IOException

Get the value as a long for a scalar Variable. May also be one-dimensional of length 1.

Specified by:

readScalarLong in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar Variable

ForbiddenConversionException - if data type not convertible to long

readScalarFloat

public float readScalarFloat()
                      throws java.io.IOException

Get the value as a float for a scalar Variable. May also be one-dimensional of length 1.

Specified by:

readScalarFloat in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.

ForbiddenConversionException - if data type not convertible to float

readScalarDouble

public double readScalarDouble()
                        throws java.io.IOException

Get the value as a double for a scalar Variable. May also be one-dimensional of length 1.

Specified by:

readScalarDouble in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.

ForbiddenConversionException - if data type not convertible to double

readScalarString

public java.lang.String readScalarString()
                                  throws java.io.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 wil be turned into a scalar String.

Specified by:

readScalarString in interface VariableIF

Throws:

java.io.IOException - if theres an IO Error

java.lang.UnsupportedOperationException - if not a scalar or one-dimensional.

java.lang.ClassCastException - if data type not DataType.STRING or DataType.CHAR.

getNameAndDimensions

public void getNameAndDimensions(java.lang.StringBuffer buf,
                                 boolean useFullName,
                                 boolean showDimLength)

display name plus the dimensions

Specified by:

getNameAndDimensions in interface VariableIF

toString

public java.lang.String toString()

String representation of Variable and its attributes.

Overrides:

toString in class java.lang.Object

writeCDL

public java.lang.String writeCDL(java.lang.String indent,
                                 boolean useFullName,
                                 boolean strict)

String representation of a Variable and its attributes.

Parameters:

indent - start each line with this much space

useFullName - use full name, else use short name

strict - stictly comply with ncgen syntax

Returns:

CDL representation of the Variable.

toStringDebug

public java.lang.String toStringDebug()

String representation of Variable and its attributes.

Specified by:

toStringDebug in interface VariableIF

equals

public boolean equals(java.lang.Object oo)

Instances which have same content are equal.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Override Object.hashCode() to implement equals.

Overrides:

hashCode in class java.lang.Object

setDataType

public void setDataType(DataType dataType)

Set the data type

setName

public void setName(java.lang.String shortName)

Set the short name

setParentStructure

public void setParentStructure(Structure parent)

Set the parent structure.

setParentGroup

public void setParentGroup(Group group)

Set the parent group.

setElementSize

public void setElementSize(int elementSize)

Set the element size. Usually elementSize is determined by the dataType, use this only for exceptional cases.

addAttribute

public void addAttribute(Attribute att)

Add new or replace old if has same name

remove

public boolean remove(Attribute a)

Remove an Attribute : uses the attribute hashCode to find it.

Returns:

true if was found and removed

setDimensions

public void setDimensions(java.util.List dims)

Set the shape with a list of Dimensions. The Dimensions may be shared or not. Technically you can use Dimensions from any group; pragmatically you should only use Dimensions contained in the Variable's parent groups.

Parameters:

dims - list of type ucar.nc2.Dimension

setDimensions

public void setDimensions(java.lang.String dimString)

Set the dimensions using the dimensions names. The dimension is searched for recursively in the parent groups.

Parameters:

dimString - : whitespace seperated list of dimension names, or '*' for Dimension.UNKNOWN.

setDimensionsAnonymous

public void setDimensionsAnonymous(int[] shape)

Set the dimensions using all anonymous (unshared) dimensions

Parameters:

shape - defines the dimension lengths

replaceDimension

public void replaceDimension(Dimension dim)

Replace a dimension with an equivalent one.

Parameters:

dim - must have the same name, length as old one

setDimension

public void setDimension(int idx,
                         Dimension dim)

Set a dimension with an equivalent one.

Parameters:

idx - index into dimension array

dim - to set

setIsCoordinateAxis

public void setIsCoordinateAxis(Dimension dim)

true is its a 1D coordinate axis or variable for its dimension

getSPobject

public java.lang.Object getSPobject()

should not be public

setSPobject

public void setSPobject(java.lang.Object spiObject)

should not be public

getIOVar

public Variable getIOVar()

should not be public.

setIOVar

public void setIOVar(Variable orgVar)

should not be public.

getSizeToCache

public int getSizeToCache()

If total data is less than SizeToCache in bytes, then cache.

setSizeToCache

public void setSizeToCache(int sizeToCache)

Set sizeToCache.

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.

Parameters:

caching - set if caching.

isCaching

public boolean isCaching()

Will this Variable be cached when read. Set externally, or calculated based on total size < sizeToCache.

Returns:

true is caching

invalidateCache

public void invalidateCache()

Invalidate the data cache

setCachedData

public void setCachedData(Array cacheData,
                          boolean isMetadata)

Set the data cache

Parameters:

isMetadata - : synthesized data, set true if must be saved in NcML output (ie data not actually in the file).

hasCachedData

public boolean hasCachedData()

Does this have its data read in and cached?