das2c_data

FUNCTION

das2c_data

PURPOSE

Get data arrays from das2 variables

CALLING SEQUENCE

array = das2c_data(var)
array = das2c_data(var, slice)

INPUTS

Parameter	Type	Purpose
var	DAS2C_VAR	A das2 variable structure as returned by das2c_vars

OPTIONAL INPUTS

Parameter	Type	Purpose
slice	Anonymous Structure	Provides a sub-range in index space. SLICE structures are not an exact data type but are inspected for various properties as describe below.

SLICE Structures

By default, das2c_data returns an array that has the same extent in index space as the overall dataset (see DAS2C_DSET.SHAPE). This handles the "scatter data" case, and since any dataset can be represented as scatter data, this makes the Das2DLM data model more flexible then many others.

Many analysis packages assume that physical dimensions correspond 1-to-1 with array dimensions and thus have difficulty dealing with arbitrary data-to-coordinate correlations. Das2C, and thus Das2DLM, are more general and do not make this assumption.

If an optional SLICE structure is provided, the array returned from das2c_data can smaller but still provide all necessary values, especially if the data happen to have each data array dimension corresponding to a single physical dimension.

Anonymous SLICE structures have the following field names:

Field	Type	Purpose
I	Long64 String	The location in the left-most (fastest moving) index
J	Long64 String	The location in the next fastest moving index
K	Long64 String	The location in the next fastest moving index
...	Long64 String	... and so on, up to the letter 'P'

The following example specifies a single point in an 8 dimensional index space, which is the maximum number of array dimensions in IDL:

{I:-2, J:3, K:13, L:7, M:1567, N:-2, O:42, P:117}

Which is equivalent to:

[-2,3,13,7,1567,-2,42,117]

in standard IDL array subset notation.

Negative integers are interpreted to indicate offsets from the end of the index range, where -1 is the last legal index value.

To indicate that an index should be allowed to vary over it's entire range, use the string '*' for the field value. See the examples below for the use of '*'. Any field not specified is assumed to have the value '*'. Thus the following two calls produce identical output:

array = das2c_data(var, {I:'*', J:'*', K:'*'})
array = das2c_data(var)

Any fields in the slice structure that apply to dimensions higher than the RANK of the dataset are ignored. (see DAS2C_DSET.RANK)

Currently only integers (both positive and negative) and the string '*' are understood as slice field values. Arrays and ranges are not currently supported, though such support could be added if desired.

OUTPUT

An array of values. The IDL data type of the array is the same as the DAS2C_VAR.TYPE field.

EXAMPLES

1. Get all time and frequency center coordinates from a dataset regardless of its RANK and iterate over all coordinates. This operation is common when generating spectrograms.

   v_time  = das2c_vars( das2c_pdims(ds, 'time'),      'center' )
   v_freq  = das2c_vars( das2c_pdims(ds, 'frequency'), 'center' )
   v_amp   = das2c_vars( das2c_pdims(ds, 'electric'),  'center' )
   
   a_time  = das2c_data(v_time)
   a_freq  = das2c_data(v_time)
   a_amp   = das2c_data(v_time)
   
   a_time  = reform(a_time, n_elements(a_time) )
   a_freq  = reform(a_freq, n_elements(a_freq) )
   a_amp   = reform(a_amp,  n_elements(a_amp)  )
   
   for I=0,n_elements(a_time)-1 do begin
      ; some plotting/binning code here
   endfor

   So long as the dataset has the indicated physical dimensions, this code works regardless of the internal storage mechanisms.

2. Get a all unique center time values for a rank 2 dataset where time is not a function of the first index.

   pd_time = das2c_pdims(ds, 'time')
   v_time = das2c_vars(pd_time, 'center')
   a_time = das2c_data(vTime, {I:0, J:'*'})

MODIFICATION HISTORY

C. Piker, 2020-06-12 - Initial version