# 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'