das2c_vars

FUNCTION

das2c_vars

PURPOSE

List the variables present in a physical dimension, in a das2 dataset.

CALLING SEQUENCE

var_array = das2c_vars(pdim)
var_struct = das2c_vars(pdim, var_role)

INPUTS

Parameter	Type	Purpose
pdim	DAS2C_PDIM	A structure as returned by das2c_pdims Implementation note: IDL does not allow for variable length arrays in structures. Thus there are actually 8 variations of DAS2C_PDIM, one for each length of the SHAPE array.

OPTIONAL INPUTS

Parameter	Type	Purpose
var_role	String	A variable's role name. This argument is only needed if information on a single variable is desired. Variable role names are standardized. The most common one is 'center' which represents the central point of a measurement in a particular physical dimension. The full set is: 'center', 'offset', 'min', 'max', 'width', 'mean', 'median', 'mode', 'reference', 'offset', 'max_error', 'min_error', 'uncertainty', 'std_dev', 'point_spread', 'weight'

OUTPUT

This function returns an array of DAS2C_VAR structures providing an overview of each variable in this physical dimension. Output structures have the following fields:

Field	Type	Purpose
RESULT	Long	The result ID of this dataset, starts from 1
DSET	Long	The ID number of this dataset, starts from 0
PDIM	String	The name of this physical dimension, ex: 'time'
VAR	String	The role name for this variable. These are standardized. See the optional inputs section above for details.
UNITS	String	The units for values from this variable. The default units format follows the fortran (and PDS3) convention of using two asterisks (**) to indicate exponentiation.
TYPE	String	The IDL datatype of the output of das2c_data calls for this variable. Will be one of the strings: 'BYTE', 'BYTE(N)', 'UINT', 'INT', 'LONG', 'LONG64','FLOAT', 'DOUBLE', 'DAS2C_TIME', 'STRING'. Most of the strings are just IDL type names and are thus self explanatory. See the notes below on the 'BYTE(N)' and 'DAS2C_TIME' "Types".
SHAPE	Long64[N]	This array is DAS2C_DSET.RANK elements long. It provides information on the internal data storage of the variable. See notes on special flag values in the SHAPE array.
N_VALS	Long64	If this variable is directly backed by an array this is the total number of real storage locations in the array.

If a variable is requested for a role that doesn't exist in the given physical dimension, !NULL is returned.

OUTPUT NOTES

1. BYTE(N) - Type 'BYTE(N)' indicates fixed length byte arrays, here N will actually be an integer greater than 1. These contain binary data and unless some out-of-band knowledge is available, there's no specific interpretation of the bytes.

2. DAS2C_TIME - Type 'DAS2C_TIME' means that the return value from a das2c_data call will be an array of DAS2C_TIME structures which contains broken down times. Note most servers send time values as type DOUBLE, and set the units field to one of:

   • 'TT2000', 'us2000', 't1970', 'mj1958', 't2000'

   to indicate an epoch and time tick size. Actual time structures are not efficient to send, or use, and thus rarely encountered.

3. SHAPE - One of the principles of the das2C data model, is that all variables in the same dataset always have the same shape in index space. Thus for example if a 'DATA' array is rank 3, then the time coordinate for data index [1,247,895], may also be found at time index [1,247,895]... always.

   However, this is just the indexing interface. The actual backing arrays do not waste space repeating values so that everything has the same rank. Coordinates for many datasets are backed by arrays that are actually smaller than the overall DAS2C_DSET shape would indicate. Also, some variables may generate data from a sequence calculation and thus do not have any backing array at all! Each element of SHAPE has one of the following values:

   • N: An integer >= 0 means that this variable produces potentially unique values in this index when calling das2c_data This integer will be the same as the corresponding value from DAS2C_DSET.SHAPE.

   • -3: The variable is degenerate in this index, so any integer used for this index will not affect the output of a das2c_data() call. This is common for variables in coordinate dimensions (see DAS2C_PDIM.USE)

   • -1: The variable has no internal storage at all corresponding to this index. It is a sequence. The output from a das2c_data() call is calculated based on the index values supplied, or indicated, by the caller.

EXAMPLES

1. List summary of all variable roles for the 'time' dimension in dataset 0 of result 27

   result = das2c_readhttp(some_query_string)
   ds = das2c_datasets(result, 0)
   pd_time = das2c_pdims(ds, 'time')
   
   das2c_vars(pd_time)

2. List summary information of the 'center' variable for the 'time' dimension above:

   das2c_vars(pd_time, 'center')

MODIFICATION HISTORY:

C. Piker, 2020-03-13 - Initial version