<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2008-2020 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
# For further information, see http://www.nexusformat.org
-->
<definition
	name="NXlog"
    type="group"
    extends="NXobject"
	category="base"
	xmlns="http://definition.nexusformat.org/nxdl/3.1"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
    >
    <doc>
		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``.

    </doc>
	<field name="time" type="NX_NUMBER" units="NX_TIME">
		<doc>
			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.
		</doc>
		<attribute name="start" type="NX_DATE_TIME" />
		<attribute name="scaling_factor" type="NX_NUMBER" />
	</field>
	<field name="value" units="NX_ANY" type="NX_NUMBER">
	  <doc>
	    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].
	  </doc>
	</field>
	<field name="raw_value" units="NX_ANY" type="NX_NUMBER">
		<doc>Array of raw information, such as thermocouple voltage</doc>
	</field>
	<field name="description">
		<doc>Description of logged value</doc>
	</field>
	<field name="average_value" type="NX_FLOAT" units="NX_ANY"/>
	<field name="average_value_error" type="NX_FLOAT" units="NX_ANY">
		<doc>estimated uncertainty (often used: standard deviation) of average_value</doc>
	</field>
	<field name="minimum_value" type="NX_FLOAT" units="NX_ANY"/>
	<field name="maximum_value" type="NX_FLOAT" units="NX_ANY"/>
	<field name="duration" type="NX_FLOAT" units="NX_ANY">
		<doc>Total time log was taken</doc>
	</field>
	<field name="cue_timestamp_zero" type="NX_NUMBER" units="NX_TIME">
	  <doc>
	    Timestamps matching the corresponding cue_index into the
	    time, value pair.
	  </doc>
	  <attribute name="start" type="NX_DATE_TIME">
			<doc>If missing start is assumed to be the same as for "time".</doc>
          </attribute>
          <attribute name="scaling_factor" type="NX_NUMBER">
		  <doc>If missing start is assumed to be the same as for "time".</doc>
  	  </attribute>
	</field>
	<field name="cue_index" type="NX_INT">
	  <doc>
	    Index into the time, value pair matching the corresponding
	    cue_timestamp_zero.
	  </doc>
	</field>
</definition>
