Data model

Overview

The primary data model for SPEDAS is built around tplot-variables. Tplot-variables bind a name-string to a structure containing time series measurements with one or two structures storing heterogeneous metadata.

Getting, Storing, & Listing Tplot Data

At their core, tplot variables are binding of a name to zero to three structures of any type. The structures are called "data", "dlimits" and "limits".

To bind a name to zero to three structures:

SPEDAS> store_data,'no_structures' ;creates tplot variable names "no_structures" no associated structures.

SPEDAS> store_data,'one_structure',data={hello:'world'} ;creates a tplot variable named "one_structure" with a data structure

SPEDAS> store_data,'two_structures',data={x:0},limits={y:0} ;creates a tplot variable named "two_structures" with a data and a limits structure

SPEDAS> store_data,'three_structures',data={x:0},limits={height:7,width:9},dlimits={goodbye:'world'} ; creates a tplot variable named "three_structures" with all three structures

At any time you can see what tplot_variables you have stored in memory using the tplot_names command.

SPEDAS> tplot_names
   1 no_structures    
   2 one_structure    
   3 two_structures   
   4 three_structures 

The structure data in tplot variables can be accessed using the get_data command.

SPEDAS> get_data,'no_structures',data=d
SPEDAS> help,d
D               LONG      =            0
SPEDAS> get_data,'three_structures',data=d,limits=l,dlimits=dl
SPEDAS> help,d
** Structure <4c80a938>, 1 tags, length=4, data length=4, refs=1:
   X               LONG      Array[1]
SPEDAS> help,l
** Structure <4d40bd48>, 2 tags, length=8, data length=8, refs=2:
   HEIGHT          LONG                 7
   WIDTH           LONG                 9
SPEDAS> help,dl
** Structure <f0cadb58>, 1 tags, length=16, data length=16, refs=2:
   GOODBYE         STRING    'world'

Tplot variables can be identified by name string or by number(from the tplot_names listing)

SPEDAS> get_data,2,data=d,limits=l
SPEDAS> help,d
** Structure <4c80a938>, 1 tags, length=16, data length=16, refs=1:
   HELLO           STRING    Array[1]
SPEDAS> help,l
L               LONG      =            0

Line Data

One dimensional tplot variables are generally intended for line plotting. To be compatible with SPEDAS routines, the name conventions for structure fields must be followed. The data structure for the tplot variable must have two fields.
"x": A 1-d array of SPEDAS times
"y": A 1-d or 2-d array of numeric data. The first dimension of the array, must have the same number of elements as "x"

For example:

;two minutes of example data from 2007
SPEDAS> store_data,'line_variable',data={x:time_double('2007-03-23')+dindgen(120),y:dindgen(120)^2}
STORE_DATA(221): Creating tplot variable: 5 line_variable
SPEDAS> get_data,'line_variable',data=d
SPEDAS> help,d
** Structure <4c875918>, 2 tags, length=1920, data length=1920, refs=1:
   X               DOUBLE    Array[120]
   Y               DOUBLE    Array[120]

The x field stores the times associated with each sample, and the y field stores the measurements themselves.

Line data can be grouped, so that one time may be associated with multiple time-series measurements. (e.g. vectors)

SPEDAS> store_data,'vector_variable',data={x:time_double('2007-03-23')+dindgen(120),y:dindgen(120,3)^2}
STORE_DATA(221): Creating tplot variable: 6 vector_variable
SPEDAS> get_data,'vector_variable',data=d
SPEDAS> help,d
** Structure <4fb344a8>, 2 tags, length=3840, data length=3840, refs=1:
   X               DOUBLE    Array[120]
   Y               DOUBLE    Array[120, 3]

As in the first example, the x field stores the times associated with each sample, but this data associates 3 measurements with each time.

Spectral Data

Two dimensional tplot data are generally treated as spectral data, but they can also be interpreted in other ways, depending on the processing or analysis routine that they're used with.(e.g. as map data) To be compatible with SPEDAS routines, the name conventions for structure fields must be followed. The data structure for the tplot variable must have two or three fields.

"x": A 1-d array of SPEDAS times
"y": A 2-d array of numeric data. The first dimension of the array, must have the same number of elements as "x"
"v"(optional): A 1-d or 2-d array of numeric data. If 1-d the number of elements of "v" must match the number of elements in the second dimension of "y". If 2-d, "v" must have the same dimensions as "y". If omitted. Data are assumed to be evenly distributed in the second axis.

To be interpreted as spectral data, the dlimits or limits structure for the variable should also have the field "spec:1".

Metadata

The plot settings like color and labels can be stored in the "dlimit" structure of a tplot variable. This structure can be obtained using get_data function:

get_data,'foo',dlimit=dl
print,'contents of dl:'
help,/str,dl 

Structure "limits" of a tplot variable overrides defined plot settings. To add or modify settings use function options. To modify global tplot plotting options use function tplot_options

; set global tplot setting
tplot_options, 'ylog', 1

; set local tplot interpolation option 
options, 'foo', no_interp=0

;remove interpolation option, by setting the option without value
options, 'foo', 'no_interp'