Data model: Difference between revisions

From SPEDAS Wiki
Jump to navigation Jump to search
 
(9 intermediate revisions by one other user not shown)
Line 3: Line 3:
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.   
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 Tplot Data ==
== 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".   
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".   
Line 9: Line 9:
To bind a name to zero to three structures:
To bind a name to zero to three structures:
<pre style="border: 1px solid LightGray">
<pre style="border: 1px solid LightGray">
store_data,'no_structures' ;creates tplot variable names "no_structures" no associated structures.
SPEDAS> store_data,'no_structures' ;creates tplot variable names "no_structures" no associated structures.


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


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,'two_structures',data={x:0},limits={y:0} ;creates a tplot variable named "two_structures" with a data and a limits structure


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
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
</pre>
</pre>


== One-dimensional Tplot Data ==
At any time you can see what tplot_variables you have stored in memory using the tplot_names command.


== Two-dimensional Tplot Data ==
<pre style="border: 1px solid LightGray">
SPEDAS> tplot_names
  1 no_structures   
  2 one_structure   
  3 two_structures 
  4 three_structures
</pre>
 
The structure data in tplot variables can be accessed using the get_data command.
 
<pre style="border: 1px solid LightGray">
 
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'
</pre>
 
Tplot variables can be identified by name string or by number(from the tplot_names listing)
 
<pre style="border: 1px solid LightGray">
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
</pre>
 
== 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.<br/>
"x": A 1-d array of [[time_handling|SPEDAS times]]<br/>
"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"<br/>
 
For example:
<pre style="border: 1px solid LightGray">
;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]
</pre>
 
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)
 
<pre style="border: 1px solid LightGray">
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]
</pre>
 
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 [[time_handling|SPEDAS times]]<br/>
"y": A 2-d array of numeric data.  The first dimension of the array, must have the same number of elements as "x"<br/>
"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:
<pre style="border: 1px solid LightGray">
get_data,'foo',dlimit=dl
print,'contents of dl:'
help,/str,dl
</pre>
 
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'''
<pre style="border: 1px solid LightGray">
; 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'
</pre>


== Importing Tplot Data into the SPEDAS GUI ==
== Importing Tplot Data into the SPEDAS GUI ==

Latest revision as of 02:51, 18 January 2018

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'

Importing Tplot Data into the SPEDAS GUI