bundles/org.simantics.history/src-isv/sampleformat.mediawiki

   1 =Sample Format=
   2 The sample format is a record that contains fields that describe what and how data is stored from source. Its fields are defined by the user, their datatype, and possibly unit type too.
   3 At minimum requirement there must be two fields: "time" and "value".
   4 The data type can be anything numerical; but typically is a double or an integer type.
   5
   6 If there is the optional field "quality", then it is used for expressing discontinuation regions (value -1). Discontinuation can be passed to the collector with a NaN or null value.
   7
   8 An example of a simple '''Sample Format'''
   9 {| border="1" cellpadding="3" cellspacing="0" align="center"
  10 |- style="background-color: #f9f9f9;"
  11 |'''Field Name''' ||'''Required'''|| '''Description'''
  12 |-
  13 |time || yes || Time, the time of the 1st sample included into the band.
  14 |-
  15 |value || yes || First value in the band.
  16 |-
  17 |quality || no || 0 = Good, -1 = No value (Byte)
  18 |}
  19
  20 If collector is given interval or deadband settings, some input samples may need to be dropped.
  21 If the sample format is in ''banded'' mode, then some information about dropped steps are
  22 preserved as count, avg, min, max and median values.
  23 In a banded sample there are (start)time and endTime fields - henge the name value band.
  24
  25 An example of a '''Banded Sample Format''':
  26 {| border="1" cellpadding="3" cellspacing="0" align="center"
  27 |- style="background-color: #f9f9f9;"
  28 |'''Field Name''' ||'''Required'''|| '''Description'''
  29 |-
  30 |time || yes || Region start time, the time of the 1st sample included into the band.
  31 |-
  32 |endTime || no || Region end time, the time of the last sample included into the band.
  33 |-
  34 | ||
  35 |-
  36 |value || yes || First value in the band.
  37 |-
  38 |lastValue || no || Last value in the band.
  39 |-
  40 |avg || no || Average value from all the steps that were included.
  41 |-
  42 |median || no || Median value from all the steps that were included into the band.
  43 |-
  44 |min || no || Lowest value in the band.
  45 |-
  46 |max || no || Highest value in the band.
  47 |-
  48 | ||
  49 |-
  50 |quality || no || 0 = Good, -1 = No value (Byte)
  51 |-
  52 |count || no || The number of included samples in the band (Integer)
  53 |}
  54
  55 To create a sample format, instantiate RecordType and add fields.
  56 <pre>
  57         // Create a sample format ( simple though )
  58         RecordType sampleFormat = new RecordType();
  59         sampleFormat.addComponent("time", Datatypes.DOUBLE );
  60         sampleFormat.addComponent("value", Datatypes.DOUBLE );
  61         sampleFormat.addComponent("quality", Datatypes.BYTE );
  62 </pre>
  63
  64 Optionally, get sample format from a user defined class.
  65 <pre>
  66         class Sample {
  67                 public double time;
  68                 public double value;
  69         }
  70
  71         // Get sample binding from a class
  72         Binding sampleBinding = Bindings.getBinding( Sample.class );
  73         // Get sample type from the binding
  74         Datatype sampleFormat = sampleBinding.type();
  75 </pre>
  76