/source/NCDFSeriesVariable.h

  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