NetcdfVariable Class Reference
Provides read-only access to the array data in the underlying netCDF dataset. More...
#import <NetcdfVariable.h>
Inherits NetcdfTypedComponent.
Public Member Functions | |
| (id) | - initByOwner:varid: |
| This is called only from an instance of NetcdfDataset that owns the variable. | |
| (NSError *) | - lastError |
| Return an autoreleased NSError report on the last error, or nil if no error. | |
| (int) | - countDimensions |
| Returns the number of dimensions in this variable. | |
| (NSArray *) | - shape |
| NSArray of NSNumber (unsigned int); describes data space of an array variable. | |
| (NSArray *) | - dimensions |
| NSArray of NetcdfDimension references;. | |
| (BOOL) | - isUnlimited |
| Returns YES if the variable allows unlimited growth. | |
| (BOOL) | - isCoordinate |
| YES if a "coordinate variable". | |
| (int) | - countAttributes |
| Returns number of attributes attached to this variable. | |
| (NSArray *) | - attributes |
| Returns an NSArray of NetcdfAttributes that are attached to this variable. | |
| (NetcdfAttribute *) | - attributeByName: |
| Returns an attribute object given its name. | |
| (NSMutableDictionary *) | - schema |
| Structure of the variable object. | |
Navigation | |
The following methods return or set the vectors that navigate the data space of the variable. The NSData objects encapsulate C arrays. The order is the same as the dimensions of the variable. The index vector determines the starting point of a data read or write, and must be set before using the -var1... -vara... -vars... or -varm... methods. The offset vector determines the count of data elements to read or write in each corresponding dimension, and must be set before using the -vara... -vars... or -varm... methods. The stride vector determines the number of data elements skipped in the read or write operation for each dimension, and must be set before using the -vars... or -varm... methods. The map vector reorders the data in memory versus the netCDF data file, and must be set before using the -varm... methods.
For a valid read or write: | |
| (NSMutableData *) | - index |
| The starting point for a slice of data. | |
| (BOOL) | - setIndexWithValues: |
| Sets the elements of the starting point for a slice of data. | |
| (void) | - setIndex: |
| Sets the starting point for a slice of data. | |
| (NSMutableData *) | - offset |
| The offset from index for a slice of data; determines the amount of data to transfer. | |
| (BOOL) | - setOffsetWithValues: |
| Sets the elements of the offset vector for a slice of data; determines the amount of data to transfer. | |
| (void) | - setOffset: |
| Sets the offset vector for a slice of data; determines the amount of data to transfer. | |
| (NSMutableData *) | - stride |
| The subsample interval for a slice of data. | |
| (BOOL) | - setStrideWithValues: |
| Sets the elements of the stride vector for a slice of data. | |
| (void) | - setStride: |
| Sets the stride vector for a slice of data. | |
| (NSMutableData *) | - map |
| A vector that transposes the dimensions in the returned data. | |
| (BOOL) | - setMapWithValues: |
| Sets the elements of the map vector to transpose the dimensions of the returned data. | |
| (void) | - setMap: |
| Sets the map vector to transpose the dimensions of the returned data. | |
Data retrieval methods | |
Numerical methods return a data block. The ...AsString methods return an array of strings; the last dimension or offset value is assumed to be the fixed string-length. Retrieving a multidimensional array of strings will flatten the data to a 1-D array. The ...GetData:asType: methods return the data in the content of a user-defined NSData object. The ...DataAsType: methods return an autoreleased NSData object if successful, or nil if failed. The ...AsType: methods take objCType in the form of "@encode(type)" where type is one of char, unsigned char, short, int, long, float, or double. Unsupported types return NIL. [NSData bytes] returns (void*) so remember to cast it. The length of the NSData used with ...GetData:asType: methods must be at least the count of data times the size of data to be read, or else an error will occur. Use countVar, countVara, countVars or countVarm to find the count of data appropriate to the read operation.
| |
| (id) | - var |
| Returns all the data by automatically calling a default method. | |
| (size_t) | - countVar |
| Returns the count of all data to be transferred from or to the variable using the dimension lengths. | |
| (BOOL) | - varGetData:asType: |
| Returns all data converted to a C array of type objCType in the user-defined NSData contents. | |
| (NSData *) | - varDataAsType: |
| Returns all data converted to a C array of type objCType inside an autoreleased NSData. | |
| (NSArray *) | - varAsString |
| Returns all strings in a single NSArray of NSString. | |
| (id) | - var1 |
| Returns one datum at the index vector by automatically calling a default method. | |
| (BOOL) | - var1GetNumber:asType: |
| Returns one datum converted to type objCType at the C pointer. | |
| (NSNumber *) | - var1NumberAsType: |
| Returns one datum converted to a C number of type objCType inside an NSNumber. | |
| (NSString *) | - var1AsString |
| Returns one datum at the index vector converted to a 1-character NSString. | |
| (id) | - vara |
| Returns a slice of the variable's data by automatically calling a default method. | |
| (size_t) | - countVara |
| Returns the count of data to be transferred from or to an array slice using index and offset. | |
| (BOOL) | - varaGetData:asType: |
| Returns a slice of data converted to a C array of type objCType in the user-defined NSData. | |
| (NSData *) | - varaDataAsType: |
| Returns a slice of data converted to a C array of type objCType inside an autoreleased NSData. | |
| (NSArray *) | - varaAsString |
| Returns a slice fo the data as NSArray of NSString. | |
| (id) | - vars |
| Returns a sub-sample from a slice of data by automatically calling a default method. | |
| (size_t) | - countVars |
| Returns the count of data to be transferred from or to a sub-sample of an array slice using index offset and stride. | |
| (BOOL) | - varsGetData:asType: |
| Returns a sub-sample from a slice of data converted to a C array of type objCType in the user-defined NSData. | |
| (NSData *) | - varsDataAsType: |
| Returns a sub-sample from a slice of data converted to a C array of type objCType inside an autoreleased NSData. | |
| (NSArray *) | - varsAsString |
| Returns a sub-sample from a slice of data as an NSArray of NSString. | |
| (id) | - varm |
| Returns a sub-sampled slice of data with transposed dimensions by automatically calling a default method. | |
| (size_t) | - countVarm |
| Returns the count of data to be transferred from or to a sub-sampled array slice with transposed dimensions using index offset and stride. | |
| (BOOL) | - varmGetData:asType: |
| Returns a sub-sampled slice of data with transposed dimensions converted to a C array of type objCType in the user-defined NSData. | |
| (NSData *) | - varmDataAsType: |
| Returns a sub-sampled slice of data with transposed dimensions converted to a C array of type objCType inside an autoreleased NSData. | |
| (NSArray *) | - varmAsString |
| Returns a sub-sampled slice of data with transposed dimensions as an NSArray of NSString. | |
Conventions | |
NetCDF defines certain variable attributes by convention. They are all optional. NetCDF-compliant applications should recognize them if they are implemented. | |
| (NSNumber *) | - validMin |
| If defined, returns smallest valid data value, else NIL. | |
| (NSNumber *) | - validMax |
| If defined, returns largest valid data value, else NIL. | |
| (NSNumber *) | - fillValue |
| If defined, returns the fill value used to pad the data structure, else NIL. | |
| (NSString *) | - units |
| If defined, returns the unit of the data, else NIL. | |
| (NSString *) | - longName |
| If defined, returns a longer descriptive name for the variable, else NIL. | |
| (NSNumber *) | - addOffset |
| If defined, returns a number, else NIL. | |
| (NSNumber *) | - scaleFactor |
| If defined, returns a number, else NIL. | |
| (NSString *) | - cFormat |
| If defined, returns a format string, else NIL. | |
Protected Attributes | |
| int | countDimensions |
| The number of array dimensions. | |
| NSMutableArray * | dimensions |
| array of NetcdfDimension | |
| NSMutableArray * | shape |
| array of dimension lengths | |
| int | countAttributes |
| the number of attributes attached to this variable | |
| NSMutableArray * | attributes |
| array of NetcdfAttribute | |
| NSMutableData * | index |
| starting vector of a read/write operation | |
| NSMutableData * | offset |
| length vector of a read/write operation | |
| NSMutableData * | stride |
| subsampling vector of a read/write operation | |
| NSMutableData * | map |
| vector that reorders data of a read/write operation | |
| BOOL | isUnlimited |
| has an unlimited dimension? | |
| BOOL | isCoordinate |
| has one dimension of the same name? | |
Detailed Description
Provides read-only access to the array data in the underlying netCDF dataset.The NetcdfDataset owns an NSArray of NetcdfVariable objects, and manages their instantiation. First, a NetcdfVariable has a data type; the netCDF datatypes defined in netcdf.h are: NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_FLOAT, and NC_DOUBLE (as of netCDF 3.6.2 there is no support for 64-bit long-long integers). The NetcdfVariable has an array of NetcdfDimension objects that describe its data space; the array may be empty in the case of a scalar variable. A NetcdfVariable also has an array of NetcdfAttribute objects that it manages; these attributes may (should) contain metadata about the variable.
The NetcdfVariable object provides access methods corresponding to the netCDF library calls. NetCDF datasets store data in a platform-independent representation, and the various function calls convert the data to the native data types. In addition, NetcdfVariable provides convenience methods that return data using a default type conversion. Array data is returned as a C array encapsulated inside an NSData object; refer to the netCDF documentation for the layout or the returned arrays. [NSData bytes] returns a pointer of type (void*); remember to cast it to the actual type of the data. Arrays of character data may be returned as NSStrings using the ...AsString methods; multidimensional string arrays are flattened to a 1-D array of NSStrings. NSStrings will be zero-padded to the length of the string dimension. Single-valued data items are returned as NSNumbers. On error, data retrieval methods return NULL and set ncErrNo; use -lastError to get a descriptive NSError object.
To access a subset of multidimensional data, you set the navigational vectors index, offset, stride and map before calling the access method.
Several attributes are defined as conventions in the netCDF standard. Pre-built methods exist to access them if they are present in the dataset. NetCDF-compliant applications should recognize and use them.
Member Function Documentation
| - (NSNumber *) addOffset |
If defined, returns a number, else NIL.
The variable attribute "add_offset" is defined by convention in netCDF, but is optional. A netCDF-compliant application will recognize this and automatically add it to every datum. Used in conjunction with -scaleFactor to perform a linear transformation on the data. Offset is applied after scale factor.
| - (NetcdfAttribute *) attributeByName: | (NSString *) | name |
Returns an attribute object given its name.
Searches only self for an attribute with the matching name; does not search globally. Returns NIL if not found; sets ncErrNo.
| - (NSString *) cFormat |
If defined, returns a format string, else NIL.
The variable attribute "C_format" is defined by convention in netCDF, but is optional. This is a user-defined default format string for the data in this variable.
| - (int) countDimensions |
Returns the number of dimensions in this variable.
May be zero for a scalar variable. Same as "rank" in netCDF terminology
| - (NSNumber *) fillValue |
If defined, returns the fill value used to pad the data structure, else NIL.
The variable attribute "fill_value" is defined by convention in netCDF, but is optional. The netcdf standard provides default fill values, but using this option overrides the default. Un-written areas of the netCDF dataset are filled with this value. Any returned data having this value is invalid.
| - (NSMutableData *) index |
The starting point for a slice of data.
Returns an NSData object encapsulating a C array of type size_t, and length equal to the number of dimensions or 1 for a scalar variable.
The indices are in the same order as the dimensions array. Valid range of index values is 0..dimension[i] - 1. The indices may be manipulated directly with pointers or by using the -setIndexWithValues: method.
| - (id) initByOwner: | (id) | newOwner | ||
| varid: | (int) | newVarid | ||
This is called only from an instance of NetcdfDataset that owns the variable.
If it fails, it returns a truncated object, sets isValid = NO and returns an error code in ncErrNo.
| - (BOOL) isCoordinate |
YES if a "coordinate variable".
A coordinate variable has only one dimension, and the variable and dimension have the same name. This is a convention used by some netCDF-compliant applications.
| - (BOOL) isUnlimited |
Returns YES if the variable allows unlimited growth.
An unlimited variable may grow along its first dimension as it is written to acommodate new data.
| - (NSError *) lastError |
Return an autoreleased NSError report on the last error, or nil if no error.
The NSError will contain have the error code set to ncErrNo, domain set to "netCDF" and its userInfo dictionary will contain:
key: NSLocalizedDescription value: NSString human readable error message
key: "path" value: NSString path to the netCDF data file
key: "class" value: NSString "NetcdfVariable"
key: "name" value: NSString name of variable
| - (NSString *) longName |
If defined, returns a longer descriptive name for the variable, else NIL.
The variable attribute "long_name" is defined by convention in netCDF, but is optional.
| - (NSMutableData *) map |
A vector that transposes the dimensions in the returned data.
Returns an NSData object encapsulating a C array of type ptrdiff_t, and length equal to the number of dimensions or 1 for a scalar variable.
Refer to the netCDF documentation for full detail. Sometimes it is useful to have the returned data be in a different order of dimensions than the original data.
The map offsets are in the same order as the dimensions array. The valid range is not checked. The map offsets may be manipulated directly with pointers or by using the -setMapWithValues: method.
| - (NSMutableData *) offset |
The offset from index for a slice of data; determines the amount of data to transfer.
Returns an NSData object encapsulating a C array of type size_t, and length equal to the number of dimensions of the variable or 1 for a scalar variable.
The offsets are in the same order as the dimensions array. Valid range of offset values is 1..(dimension[i] - index[i]). Each offset give the number of data elements to read/write from its corresponding dimension. The offsets may be manipulated directly with pointers or by using the -setOffsetWithValues: method.
| - (NSNumber *) scaleFactor |
If defined, returns a number, else NIL.
The variable attribute "scale_factor" is defined by convention in netCDF, but is optional. A netCDF-compliant application will recognize this and automatically multiply every datum by it. Used in conjunction with -addOffset to perform a linear transformation on the data. Scale factor is applied before offset.
| - (NSMutableDictionary *) schema |
Structure of the variable object.
key: "name" value: NSString variable name string
key: "type" value: NSNumber variable data type (nc_type)
key: "dimensions" value: NSArray of dimension schema, possibly empty
key: "attributes" value: NSArray of attribute schema, possibly empty
Reimplemented from NetcdfTypedComponent.
| - (void) setIndex: | (NSMutableData *) | newIndex |
Sets the starting point for a slice of data.
The NSData object encapsulates a C array of type size_t, and length equal to the number of dimensions of the variable or 1 for a scalar variable. The order is the same as the order of the dimensions. Valid range of index values is 0..dimension[i] - 1.
The index array must be set before invoking -var1... -vara... -vars... -varm... methods.
| - (BOOL) setIndexWithValues: | (size_t) | numArgs | ||
| , | ... | |||
Sets the elements of the starting point for a slice of data.
numArgs must be equal to countDimensions or 1 for a scalar variable. List the dimension indices in the same order as the dimensions array. Valid range of index values is 0..dimension[i] - 1.
Returns YES if successful. Failure can leave the vector in an incompletely defined state.
The index array must be set before invoking -var1... -vara... -vars... -varm... methods.
| - (void) setMap: | (NSMutableData *) | newMap |
Sets the map vector to transpose the dimensions of the returned data.
The NSData object encapsulates a C array of type ptrdiff_t, and length equal to the number of dimensions of the variable or 1 for a scalar variable. The order of the map offsets is the same as the order of the dimensions. The valid range is not checked.
The map array must be set before invoking -varm... methods.
| - (BOOL) setMapWithValues: | (ptrdiff_t) | numArgs | ||
| , | ... | |||
Sets the elements of the map vector to transpose the dimensions of the returned data.
numArgs must be equal to countDimensions or 1 for a scalar variable. The variable arguments list contains map offsets in the same order as the dimensions array. The valid range is not checked.
Returns YES if successful. Failure can leave the vector in an incompletely defined state.
The map array must be set before invoking -varm... methods.
| - (void) setOffset: | (NSMutableData *) | newOffset |
Sets the offset vector for a slice of data; determines the amount of data to transfer.
The NSData object encapsulates a C array of type size_t, and length equal to the number of dimensions of the variable or 1 for a scalar variable. The order of the offsets is the same as the order of the dimensions. Each offset give the number of data elements to read/write from its corresponding dimension. Valid range of offset values is 1..(dimension[i] - index[i]).
The offset array must be set before invoking -vara... -vars... -varm... methods.
| - (BOOL) setOffsetWithValues: | (size_t) | numArgs | ||
| , | ... | |||
Sets the elements of the offset vector for a slice of data; determines the amount of data to transfer.
numArgs must be equal to countDimensions or 1 for a scalar variable. The variable arguments list contains dimension offsets in the same order as the dimensions array. Each offset give the number of data elements to read/write from its corresponding dimension. Valid range of offset values is 1..(dimension[i] - index[i]).
Returns YES if successful. Failure can leave the vector in an incompletely defined state.
The offset array must be set before invoking -vara... -vars... -varm... methods.
| - (void) setStride: | (NSMutableData *) | newStride |
Sets the stride vector for a slice of data.
The NSData object encapsulates a C array of type ptrdiff_t, and length equal to the number of dimensions of the variable or 1 for a scalar variable. The valid range of strides is 1..dimension[i]. The order of the strides is the same as the order of the dimensions.
The stride must be set before invoking -vars... or -varm... methods.
| - (BOOL) setStrideWithValues: | (ptrdiff_t) | numArgs | ||
| , | ... | |||
Sets the elements of the stride vector for a slice of data.
numArgs must be equal to countDimensions or 1 for a scalar variable. The variable arguments list contains dimension strides in the same order as the dimensions array. Valid range of stride is 1..dimension[i].
Returns YES if successful. Failure can leave the vector in an incompletely defined state.
The stride array must be set before invoking -vars... -varm... methods.
| - (NSArray *) shape |
NSArray of NSNumber (unsigned int); describes data space of an array variable.
Variables with an unlimited dimension can have their size changed. This method recomputes the shape array and returns it. The ivar shape is a cached copy, and becomes stale if the unlimited dimension changes size.
| - (NSMutableData *) stride |
The subsample interval for a slice of data.
Returns an NSData object encapsulating a C array of type ptrdiff_t, and length equal to the number of dimensions or 1 for a scalar variable.
When retrieving a regular subsampling of data, the stride is the increment of the access pointer. A stride of 1 samples every datum; 2 samples every second datum; 3 samples every third datum... Since stride is a vector, each dimension may have a different stride value.
The strides are in the same order as the dimensions array. Valid range of stride is 1..dimension[i]. The offsets may be manipulated directly with pointers or by using the -setStrideWithValues: method.
| - (NSString *) units |
If defined, returns the unit of the data, else NIL.
The variable attribute "units" is defined by convention in netCDF, but is optional. This may be used in conjunction with the udunits library to perform unit conversions.
| - (NSNumber *) validMax |
If defined, returns largest valid data value, else NIL.
The variable attribute "valid_max" is defined by convention in netCDF, but is optional. The variable attribute "valid_range[1]" may be used to serve the same purpose, but both should not be defined. This method checks first for valid_max, then for valid_range.
| - (NSNumber *) validMin |
If defined, returns smallest valid data value, else NIL.
The variable attribute "valid_min" is defined by convention in netCDF, but is optional. The variable attribute "valid_range[0]" may be used to serve the same purpose, but both should not be defined. This method checks first for valid_min, then for valid_range.
| - (id) var |
Returns all the data by automatically calling a default method.
The default methods are:
NC_CHAR ==> -varAsString
NC_BYTE ==> -varDataAsType: @encode(char)
NC_SHORT ==> -varDataAsType: @encode(short)
NC_INT ==> -varDataAsType: @encode(int)
NC_FLOAT ==> -varDataAsType: @encode(float)
NC_DOUBLE ==> -varDataAsType: @encode(double)
| - (id) var1 |
Returns one datum at the index vector by automatically calling a default method.
The default methods are:
NC_CHAR ==> -var1AsString
NC_BYTE ==> -var1NumberAsType: @encode(char)
NC_SHORT ==> -var1NumberAsType: @encode(short)
NC_INT ==> -var1NumberAsType: @encode(int)
NC_FLOAT ==> -var1NumberAsType: @encode(float)
NC_DOUBLE ==> -var1NumberAsType: @encode(double)
| - (id) vara |
Returns a slice of the variable's data by automatically calling a default method.
The default methods are:
NC_CHAR ==> -varaAsString
NC_BYTE ==> -varaDataAsType: @encode(char)
NC_SHORT ==> -varaDataAsType: @encode(short)
NC_INT ==> -varaDataAsType: @encode(int)
NC_FLOAT ==> -varaDataAsType: @encode(float)
NC_DOUBLE ==> -varaDataAsType: @encode(double)
| - (NSArray *) varaAsString |
Returns a slice fo the data as NSArray of NSString.
By convention, the string dimension is assumed to be the last one. It can be used to return substrings.
| - (NSData *) varaDataAsType: | (const char *) | objCType |
Returns a slice of data converted to a C array of type objCType inside an autoreleased NSData.
On failure, returns nil. Sets ncErrNo.
| - (BOOL) varaGetData: | (NSData *) | buffer | ||
| asType: | (const char *) | objCType | ||
Returns a slice of data converted to a C array of type objCType in the user-defined NSData.
[buffer length] must be at least countVara*sizeof(type) else ncErrNo = NCS_DATASIZE_E.
Returns YES if successful. Sets ncErrNo.
| - (NSArray *) varAsString |
Returns all strings in a single NSArray of NSString.
By convention, the last dimension is assumed to be the string dimension. Multidimensional arrays of strings are flattened to a 1-dimensional NSArray of NSString.
| - (NSData *) varDataAsType: | (const char *) | objCType |
Returns all data converted to a C array of type objCType inside an autoreleased NSData.
On failure, returns nil. Sets ncErrNo.
| - (BOOL) varGetData: | (NSData *) | buffer | ||
| asType: | (const char *) | objCType | ||
Returns all data converted to a C array of type objCType in the user-defined NSData contents.
[buffer length] must be at least countVar*sizeof(type) else ncErrNo = NCS_DATASIZE_E.
Returns YES if successful. Sets ncErrNo.
| - (id) varm |
Returns a sub-sampled slice of data with transposed dimensions by automatically calling a default method.
The default methods are:
NC_CHAR ==> -varmAsString
NC_BYTE ==> -varmDataAsType: @encode(char)
NC_SHORT ==> -varmDataAsType: @encode(short)
NC_INT ==> -varmDataAsType: @encode(int)
NC_FLOAT ==> -varmDataAsType: @encode(float)
NC_DOUBLE ==> -varmDataAsType: @encode(double)
| - (NSArray *) varmAsString |
Returns a sub-sampled slice of data with transposed dimensions as an NSArray of NSString.
By convention, the string dimension is assumed to be the last one. Normally you want a stride of 1 in the string dimension
| - (NSData *) varmDataAsType: | (const char *) | objCType |
Returns a sub-sampled slice of data with transposed dimensions converted to a C array of type objCType inside an autoreleased NSData.
On failure, returns nil. Sets ncErrNo.
| - (BOOL) varmGetData: | (NSData *) | buffer | ||
| asType: | (const char *) | objCType | ||
Returns a sub-sampled slice of data with transposed dimensions converted to a C array of type objCType in the user-defined NSData.
[buffer length] must be at least countVarm*sizeof(type) else ncErrNo = NCS_DATASIZE_E.
Returns YES if successful. Sets ncErrNo.
| - (id) vars |
Returns a sub-sample from a slice of data by automatically calling a default method.
The default methods are:
NC_CHAR ==> -varsAsString
NC_BYTE ==> -varsDataAsType: @encode(char)
NC_SHORT ==> -varsDataAsType: @encode(short)
NC_INT ==> -varsDataAsType: @encode(int)
NC_FLOAT ==> -varsDataAsType: @encode(float)
NC_DOUBLE ==> -varsDataAsType: @encode(double)
| - (NSArray *) varsAsString |
Returns a sub-sample from a slice of data as an NSArray of NSString.
By convention, the string dimension is assumed to the be the last one. Normally you want the stride to be 1 in the string dimension.
| - (NSData *) varsDataAsType: | (const char *) | objCType |
Returns a sub-sample from a slice of data converted to a C array of type objCType inside an autoreleased NSData.
On failure, returns nil. Sets ncErrNo.
| - (BOOL) varsGetData: | (NSData *) | buffer | ||
| asType: | (const char *) | objCType | ||
Returns a sub-sample from a slice of data converted to a C array of type objCType in the user-defined NSData.
[buffer length] must be at least countVars*sizeof(type) else ncErrNo = NCS_DATASIZE_E.
Returns YES if successful. Sets ncErrNo.
