.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source NXlog.nxdl.xml

.. index::
    ! NXlog (base class)
    ! log (base class)
    see: log (base class); NXlog

.. _NXlog:

=====
NXlog
=====

**Status**:

  base class, extends :ref:`NXobject`

**Description**:

  Information recorded as a function of time.

  Description of information that is recorded against
  time. There are two common use cases for this:

  - When logging data such as temperature during a run
  - When data is taken in streaming mode data acquisition,
    i.e. just timestamp, value pairs are stored and
    correlated later in data reduction with other data,

  In both cases, NXlog contains
  the logged or streamed  values and the times at which they were measured as elapsed time since a starting
  time recorded in ISO8601 format. The time units are
  specified in the units attribute. An optional scaling attribute
  can be used to accomodate non standard clocks.

  This method of storing logged data helps to distinguish
  instances in which a variable is a dimension scale of the data, in which case it is stored
  in an :ref:`NXdata` group, and instances in which it is logged during the
  run, when it should be stored in an :ref:`NXlog` group.

  In order to make random access to timestamped data faster there is an optional array pair of
  ``cue_timestamp_zero`` and ``cue_index``. The ``cue_timestamp_zero`` will
  contain coarser timestamps than in the time array, say
  every five minutes. The ``cue_index`` will then contain the
  index into the time,value pair of arrays for that
  coarser ``cue_timestamp_zero``.


**Symbols**:

  No symbol table

**Groups cited**:
  none

**Structure**:

  .. index:: time (field)

  **time**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_TIME <NX_TIME>`}

    Time of logged entry. The times are relative to the "start" attribute
    and in the units specified in the "units"
    attribute. Please note that absolute
    timestamps under unix are relative to ``1970-01-01T:00:00``.

    The scaling_factor, when present, has to be applied to the time values in order
    to arrive at the units specified in the units attribute. The scaling_factor allows
    for arbitrary time units such as ticks of some hardware clock.

    .. index:: start (field attribute)

    **@start**: (optional) :ref:`NX_DATE_TIME <NX_DATE_TIME>`


    .. index:: scaling_factor (field attribute)

    **@scaling_factor**: (optional) :ref:`NX_NUMBER <NX_NUMBER>`


  .. index:: value (field)

  **value**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    Array of logged value, such as temperature. If this is
    a single value the dimensionality is
    nEntries. However, NXlog can also be used to store
    multi dimensional time stamped data such as images. In
    this example the dimensionality of values would be value[nEntries,xdim,ydim].

  .. index:: raw_value (field)

  **raw_value**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    Array of raw information, such as thermocouple voltage

  .. index:: description (field)

  **description**: (optional) :ref:`NX_CHAR <NX_CHAR>`

    Description of logged value

  .. index:: average_value (field)

  **average_value**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}


  .. index:: average_value_error (field)

  **average_value_error**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    estimated uncertainty (often used: standard deviation) of average_value

  .. index:: minimum_value (field)

  **minimum_value**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}


  .. index:: maximum_value (field)

  **maximum_value**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}


  .. index:: duration (field)

  **duration**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    Total time log was taken

  .. index:: cue_timestamp_zero (field)

  **cue_timestamp_zero**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_TIME <NX_TIME>`}

    Timestamps matching the corresponding cue_index into the
    time, value pair.

    .. index:: start (field attribute)

    **@start**: (optional) :ref:`NX_DATE_TIME <NX_DATE_TIME>`

      If missing start is assumed to be the same as for "time".

    .. index:: scaling_factor (field attribute)

    **@scaling_factor**: (optional) :ref:`NX_NUMBER <NX_NUMBER>`

      If missing start is assumed to be the same as for "time".

  .. index:: cue_index (field)

  **cue_index**: (optional) :ref:`NX_INT <NX_INT>`

    Index into the time, value pair matching the corresponding
    cue_timestamp_zero.

**NXDL Source**:
  https://github.com/nexusformat/definitions/blob/master/base_classes/NXlog.nxdl.xml