Skip to content

Commit ed08628

Browse files
FreddieAkeroydFreddieAkeroyd
authored
Add NXtextlog base class (#1590)
NXtextlog base class, this is similar to NXlog but specifically for text based data as NXlog only supports numeric data. It could be used for example to record status/error/log messages from hardware or software and meant to handle cases where a large number of NXnote entries is undesirable.
1 parent 9a4a123 commit ed08628

1 file changed

Lines changed: 128 additions & 0 deletions

File tree

‎contributed_definitions/NXtextlog.nxdl.xml‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
3+
<!--
4+
# NeXus - Neutron and X-ray Common Data Format
5+
#
6+
# Copyright (C) 2008-2026 NeXus International Advisory Committee (NIAC)
7+
#
8+
# This library is free software; you can redistribute it and/or
9+
# modify it under the terms of the GNU Lesser General Public
10+
# License as published by the Free Software Foundation; either
11+
# version 3 of the License, or (at your option) any later version.
12+
#
13+
# This library is distributed in the hope that it will be useful,
14+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
15+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16+
# Lesser General Public License for more details.
17+
#
18+
# You should have received a copy of the GNU Lesser General Public
19+
# License along with this library; if not, write to the Free Software
20+
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21+
#
22+
# For further information, see http://www.nexusformat.org
23+
-->
24+
<definition
25+
name="NXtextlog"
26+
type="group"
27+
extends="NXobject"
28+
category="base"
29+
xmlns="http://definition.nexusformat.org/nxdl/3.1"
30+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
31+
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
32+
>
33+
34+
<symbols>
35+
<doc>
36+
Symbols used below to illustrate the rank and sizes of datasets
37+
</doc>
38+
<symbol name="n"><doc>Number of logged values</doc></symbol>
39+
</symbols>
40+
41+
<doc>
42+
Textual Information recorded as a function of time.
43+
44+
This is very similar to an :ref:`NXlog` but aimed at character
45+
rather than numeric data. It is to cover use cases when character
46+
data is to be recorded but using a large number of e.g. :ref:`NXnote`
47+
classes is undesirable.
48+
49+
It would be used for cases like:
50+
51+
- Status or error messages from hardware or software
52+
- Character based metadata e.g. labels that may vary during data collection
53+
54+
Data is stored with times at which they were measured as elapsed time
55+
since a starting time recorded in ISO8601 format. The time units are
56+
specified in the units attribute. An optional scaling attribute
57+
can be used to accomodate non standard clocks.
58+
59+
In order to make random access to timestamped data faster there is an optional array pair of
60+
``cue_timestamp_zero`` and ``cue_index``. The ``cue_timestamp_zero`` will
61+
contain coarser timestamps than in the time array, say
62+
every five minutes. The ``cue_index`` will then contain the
63+
index into the time,value pair of arrays for that
64+
coarser ``cue_timestamp_zero``.
65+
66+
</doc>
67+
68+
<field name="time" type="NX_NUMBER" units="NX_TIME">
69+
<doc>
70+
Time of logged entry. The times are relative to the "start" attribute
71+
and in the units specified in the "units"
72+
attribute. Please note that absolute
73+
timestamps under unix are relative to ``1970-01-01T00:00:00.0Z``.
74+
75+
The "scaling_factor" attribute, when present, has to be applied to the time values in order
76+
to arrive at the units specified in the units attribute. The "scaling_factor" allows
77+
for arbitrary time units such as ticks of some hardware clock.
78+
</doc>
79+
<dimensions rank="1">
80+
<dim index="1" value="n" />
81+
</dimensions>
82+
<attribute name="start" type="NX_DATE_TIME" />
83+
<attribute name="scaling_factor" type="NX_NUMBER" />
84+
</field>
85+
<field name="value" type="NX_CHAR" >
86+
<doc>
87+
String array of logged values, same length and dimensionality
88+
as ``time`` array field. If you have stored multiple items here and
89+
wish each to be interpreted separately by the reader then you can specify
90+
a "separator" attribute to indicate how to split them up. However you should
91+
consider whether it is clearer to write multiple ``value`` elements with the
92+
same ``time``, or separate NXtextlog instances, instead.
93+
</doc>
94+
<dimensions rank="1">
95+
<dim index="1" value="n" />
96+
</dimensions>
97+
<attribute name="separator" type="NX_CHAR">
98+
<doc>
99+
Optional character string that can be used to specify how to split a
100+
text ``value`` into multiple items.
101+
</doc>
102+
</attribute>
103+
</field>
104+
<field name="description">
105+
<doc>Description of logged value</doc>
106+
</field>
107+
<field name="duration" type="NX_FLOAT" units="NX_ANY">
108+
<doc>Total time log was taken</doc>
109+
</field>
110+
<field name="cue_timestamp_zero" type="NX_NUMBER" units="NX_TIME">
111+
<doc>
112+
Timestamps matching the corresponding cue_index into the
113+
time, value pair.
114+
</doc>
115+
<attribute name="start" type="NX_DATE_TIME">
116+
<doc>If missing start is assumed to be the same as for "time".</doc>
117+
</attribute>
118+
<attribute name="scaling_factor" type="NX_NUMBER">
119+
<doc>If missing start is assumed to be the same as for "time".</doc>
120+
</attribute>
121+
</field>
122+
<field name="cue_index" type="NX_INT">
123+
<doc>
124+
Index into the time, value pair matching the corresponding
125+
cue_timestamp_zero.
126+
</doc>
127+
</field>
128+
</definition>

0 commit comments

Comments
 (0)