/source/NCDFSeriesVariable.h
C Header | 295 lines | 38 code | 31 blank | 226 comment | 0 complexity | d3d03237e04240a6c2d56ec3cdccfbd2 MD5 | raw file
1// 2// NCDFSeriesVariable.h 3// netcdf 4// 5// Created by Tom Moore on 6/16/07. 6// Copyright 2007 PaleoTerra. All rights reserved. 7// 8 9#import <Cocoa/Cocoa.h> 10#import "NCDFProtocols.h" 11/*! 12@header 13 @class NCDFSeriesVariable 14 @abstract NCDFSeriesVariable objects for accessing netcdf variables over multiple files 15 16 17 @discussion NCDFSeriesVariable is an immutable class designed to allow a programmer to access netcdf data over multiple files using standard notation. This approach simplifies multi-file access by hiding the complexity of accessing each file into one simplified interface. 18 */ 19@interface NCDFSeriesVariable : NSObject <NCDFImmutableVariableProtocol>{ 20 NSString *_variableName; 21 nc_type _dataType; 22 NSString *_typeName; 23 NCDFSeriesHandle *_seriesHandle; 24 NSArray *_theDims; 25 int32_t _unlimitedDimLocation; 26} 27 28 29/*! 30 31 32@method initWithVariable:fromHandle: 33@abstract Initialize a new NCDFSeriesVariable using a NCDFVariable and NCDFSeriesHandle. 34@param aVar NCDFVariable object. Typically the root NCDFHandle from NCDFSeriesHandle. 35@discussion Initializes a new NCDFSeriesVariable. This method should be considered private and should not be instanciated outside of an NCDFSeriesHandle. This variable class is also limited to variables that use an unlimited dimension, otherwise use a NCDFVariable object derived from a NCDFHandle. 36*/ 37-(id)initWithVariable:(NCDFVariable *)aVar fromHandle:(NCDFSeriesHandle *)aHandle; 38 39 40//reading 41 42 /*! 43 44 45@method readAllVariableData 46 @abstract Read all variable data. 47 @discussion Returns all data in a NSData object. The NSData object includes data from all files in order. 48 */ 49-(NSData *)readAllVariableData; 50 51 /*! 52 53 54 @method variableName 55 @abstract Returns variable name. 56 @discussion Returns variable name as a NSString object. 57 */ 58-(NSString *)variableName; 59 60 /*! 61 62 63 @method variableType 64 @abstract Returns variable type. 65 @discussion Returns variable type as a NSString object. Type strings include NC_CHAR,NC_INT, and several others. 66 */ 67-(NSString *)variableType; 68 69 /*! 70 71 72 @method variableNC_TYPE 73 @abstract Returns variable type. 74 @discussion Returns variable type as a netcdf type (nc_type) value. 75 */ 76-(nc_type)variableNC_TYPE; 77 78 /*! 79 80 81 @method variableDimDescription 82 @abstract Returns a simplified dimension description. 83 @discussion Returns a human-readable description string for the dimensions describing the variable using a standard bracketing style: e.g. [time, lat, lon]. 84 */ 85-(NSString *)variableDimDescription; 86 87 /*! 88 89 90 @method dataTypeWithDimDescription 91 @abstract Returns a variable type and simplified dimension description. 92 @discussion Returns a human-readable description string for the variable type and dimensions. This is a combination of variableType and variableDimDescription methods. 93 */ 94-(NSString *)dataTypeWithDimDescription; 95 96 /*! 97 98 99 @method getVariableAttributes 100 @abstract Returns an array of NCDFAttributes for the variable. 101 @discussion Returns an array of NCDFAttributes derived from the root NCDF handle representing the attributes of the receiver. 102 */ 103-(NSArray *)getVariableAttributes; 104 105 106 /*! 107 108 109 @method getSingleValue: 110 @abstract Returns a single value as an id value. 111 @param coordinates NSArray object with the coordinates of the data using NSNumber intValues. 112 @discussion Returns a single value. See NCDFVariable getSingleValue method for more information. This method is transparent to which file contains the data. 113 114 115 */ 116-(id)getSingleValue:(NSArray *)coordinates; 117 118 /*! 119 120 121 @method getValueArrayAtLocation:edgeLengths: 122 @abstract Returns selected data as an NSData object. 123 @param startCoordinates NSArray object with the coordinates of the data using NSNumber intValues. Values range from 0 to dimension length -1 for each dimension (in significance order). 124 @param edgeLengths NSArray object with the lengths of the data along dimensions using NSNumber intValues. Values range from 1 to dimension length for each dimension (in significance order). 125 @discussion Returns an NSData object containing all selected data. The data will automatically span files. 126 */ 127-(NSData *)getValueArrayAtLocation:(NSArray *)startCoordinates edgeLengths:(NSArray *)edgeLengths; 128 129 /*! 130 131 132 @method isDimensionVariable 133 @abstract Returns whether the variable represents the values of a dimension 134 @discussion If the variable name matches a dimension name, the variable is assumed to be a dimension variable. 135 */ 136-(BOOL)isDimensionVariable; 137 138 /*! 139 140 141 @method sizeUnitVariable 142 @abstract Returns the size of the variable in value counts for a unlimited variable unit. 143 @discussion This method returns the size of the variable in counts of values for each unlimited step or, when the variable has no unlimited variable, the count of the entire variable. 144 */ 145-(int)sizeUnitVariable; 146 147 /*! 148 149 150 @method sizeUnitVariableForType 151 @abstract Returns the size of the variable in bytes for a unlimited variable unit. 152 @discussion This method returns the size of the variable in bytes for each unlimited step or, when the variable has no unlimited variable, the bytes of the entire variable. 153 */ 154-(int)sizeUnitVariableForType; 155 156 /*! 157 158 159 @method currentVariableSize 160 @abstract Returns the total size of the variable in counts for a unlimited variable unit. 161 @discussion This method returns the count size of the variable. 162 */ 163-(int)currentVariableSize; 164 165 /*! 166 167 168 @method currentVariableByteSize 169 @abstract Returns the total size of the variable in bytes for a unlimited variable unit. 170 @discussion This method returns the byte size of the variable. 171 */ 172-(int)currentVariableByteSize; 173 174 /*! 175 176 177 @method lengthArray 178 @abstract Returns an array with the lengths of each dimension in significance order. 179 @discussion This method returns the lengths of each dimension used by a variable. These lengths account for multiple files. 180 */ 181-(NSArray *)lengthArray; 182 183 /*! 184 185 186 @method isUnlimited 187 @abstract Returns a boolean whether the variable uses an unlimited variable 188 189 190 191 */ 192-(BOOL)isUnlimited; 193 194 /*! 195 196 197 @method doesVariableUseDimensionName: 198 @param aDimName the name of the requested dimension. 199 @abstract Returns a boolean on whether the variable uses a dimension with the name aDimName. 200 201 */ 202-(BOOL)doesVariableUseDimensionName:(NSString *)aDimName; 203 /*! 204 205 206 @method unlimitedVariableLength 207 @abstract Returns the length of the unlimited dimension used by the variable. 208 209 */ 210-(int)unlimitedVariableLength; 211 212 /*! 213 214 215 @method dimensionNames 216 @abstract Returns the names of the dimensions, in significance order, as an array of NSString objects. 217 218 */ 219-(NSArray *)dimensionNames; 220 221 /*! 222 223 224 @method allVariableDimInformation 225 @abstract Returns a NSArray containing all of the NCDFSeriesDimensions used by the receiver. 226 227 */ 228 229-(NSArray *)allVariableDimInformation; 230 231 /*! 232 233 234 @method variableAttributeByName: 235 @abstract Returns an NCDFAttribute used by the variable from the root handle by name. 236 237 */ 238-(NCDFAttribute *)variableAttributeByName:(NSString *)name; 239 240 /*! 241 242 243 @method stringValueForSingleValueCoordinates: 244 @abstract Obtains a value from the coordinates and formats the result as a NSString and returns. 245 @discussion This method is a convienence method for accessing a value and formating into a string. 246 247 */ 248-(NSString *)stringValueForSingleValueCoordinates:(NSArray *)coordinates; 249 250 /*! 251 252 253 @method attributeCount 254 @abstract Returns the count of the 255 256 257 @discussion This method is a convienence method for accessing a value and formating into a string. 258 259 */ 260-(int)attributeCount; 261 262 /*! 263 264 265 @method getSlabForStartCoordinates:edgeLengths: 266 @abstract Returns a slab of data for later access using start coordinates and length coordinates. 267 @discussion This method returns an NCDFSlab object containing the requested data. Accessing data from slabs allows faster data access than through file I/O and affords some thread safety. This method can span multiple files. 268 269 */ 270-(NCDFSlab *)getSlabForStartCoordinates:(NSArray *)startCoordinates edgeLengths:(NSArray *)edgeLengths; 271 /*! 272 273 274 @method getAllDataInSlab 275 @abstract Returns a slab of data for later access using all data available for the variable.. 276 @discussion This method returns an NCDFSlab object containing the requested data. Accessing data from slabs allows faster data access than through file I/O and affords some thread safety. This method will span all files. 277 278 */ 279-(NCDFSlab *)getAllDataInSlab; 280 281 /*! 282 283 284 @method variableID 285 @abstract Returns netCDF variable ID number for the variable. 286 287 288 289 290 @discussion Returns netCDF variable ID number for the variable from the root handle only. 291 292 293 */ 294-(int)variableID; 295@end