Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Detector channels #1252

Merged
merged 24 commits into from
Dec 20, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
7157d25
Add new datatype, the union of NX_CHAR and NX_NUMBER
phyy-nx Mar 13, 2023
db047de
Change AXISNAME field of NXdata to allow character values
phyy-nx Mar 13, 2023
3dc02ba
Whitespace
phyy-nx Mar 13, 2023
6d23703
Add NXdata attribute default_slice
phyy-nx Mar 17, 2023
6b2a84f
Add NX_CHAR_OR_NUMBER to the primitiveType enum
phyy-nx Apr 18, 2023
4f3c73a
Whitespace
phyy-nx Apr 18, 2023
81388d1
Add NXdetector_channel as a base class
phyy-nx Apr 5, 2023
3382235
Apply suggestions from code review
phyy-nx Apr 18, 2023
ab45175
Add NXdetector_channel to NXdetector and NXmx
phyy-nx Apr 18, 2023
1168f00
Merge branch 'main' into dimension_as_char
phyy-nx Jun 19, 2023
4ba9645
Fix formatting
phyy-nx Jun 19, 2023
6f2a056
Add example of default_sice using an integer as a string
phyy-nx Jun 19, 2023
65b8c8e
Merge branch 'dimension_as_char' into detector_channel
phyy-nx Jun 19, 2023
146a96a
Bring in additional fields from NXdetector into NXchannel
phyy-nx Jun 19, 2023
355b408
Update base_classes/NXdetector_channel.nxdl.xml
phyy-nx Jun 20, 2023
48a82e4
Bugfix in description
phyy-nx Sep 20, 2023
ac8c5d0
Full example
phyy-nx Sep 20, 2023
6e924a0
Merge branch 'dimension_as_char' into detector_channel
phyy-nx Sep 20, 2023
8ff58ed
Better example
phyy-nx Sep 20, 2023
bb6906e
Typo
phyy-nx Oct 19, 2023
d7ae84c
Added NX_CHAR as type for default_slice
phyy-nx Oct 19, 2023
78566e1
Actually use NXCHAR_OR_NUMBER
phyy-nx Oct 19, 2023
ad0a129
Merge branch 'main' into dimension_as_char
phyy-nx Nov 21, 2023
d71b5f2
Merge branch 'dimension_as_char' into detector_channel
phyy-nx Nov 21, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions applications/NXmx.nxdl.xml
Original file line number Diff line number Diff line change
Expand Up @@ -764,6 +764,19 @@
plate, CMOS, ...
</doc>
</field>

<group name="CHANNELNAME_channel" type="NXdetector_channel">
<doc>
Group containing the description and metadata for a single channel from a multi-channel
detector.

Given an :ref:`NXdata` group linked as part of an NXdetector group that has an axis with
named channels (see the example in :ref:`NXdata &lt;/NXdata@default_slice-attribute&gt;`),
the NXdetector will have a series of NXdetector_channel groups, one for each channel,
named CHANNELNAME_channel.
</doc>
</group>

</group>
<group type="NXbeam" minOccurs="1">
<attribute name="flux" optional="true">
Expand Down
50 changes: 49 additions & 1 deletion base_classes/NXdata.nxdl.xml
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,51 @@
https://www.nexusformat.org/NIAC2018Minutes.html
</doc>
</attribute>
<attribute name="default_slice" type="NX_CHAR_OR_NUMBER">
<doc>
Which slice of data to show in a plot by default. This is useful especially for
datasets with more than 2 dimensions.

Should be an array of length equal to the number of dimensions
in the data, with the following possible values:

* ".": All the data in this dimension should be included
* Integer: Only this slice should be used.
* String: Only this slice should be used. Use if ``AXISNAME`` is a string
array.

Example::

data:NXdata
@signal = "data"
@axes = ["image_id", "channel", ".", "."]
@image_id_indices = 0
@channel_indices = 1
@default_slice = [".", "difference", ".", "."]
image_id = [1, ..., nP]
channel = ["threshold_1", "threshold_2", "difference"]
data = uint[nP, nC, i, j]

Here, a data array with four dimensions, including the number of images
(nP) and number of channels (nC), specifies more dimensions than can be
visualized with a 2D image viewer for a given image. Therefore the
default_slice attribute specifies that the "difference" channel should be
shown by default.

Alternate version using an integer would look like this (note 2 is a string)::

data:NXdata
@signal = "data"
@axes = ["image_id", "channel", ".", "."]
@image_id_indices = 0
@channel_indices = 1
@default_slice = [".", "2", ".", "."]
image_id = [1, ..., nP]
channel = ["threshold_1", "threshold_2", "difference"]
data = uint[nP, nC, i, j]

</doc>
</attribute>
<attribute name="AXISNAME_indices" type="NX_INT">
<!--
nxdl.xsd rules do not allow us to show this as a variable name
Expand Down Expand Up @@ -294,14 +339,17 @@
</attribute>

<!-- Data and coordinate fields -->
<field name="AXISNAME" type="NX_NUMBER" nameType="any">
<field name="AXISNAME" type="NX_CHAR_OR_NUMBER" nameType="any">
<doc>
Coordinate values along one or more :ref:`data &lt;/NXdata/DATA-field&gt;` dimensions. The rank must be equal
to the number of dimensions it spans.

As the upper case ``AXISNAME`` indicates, the names of the ``AXISNAME`` fields can be chosen :ref:`freely &lt;validItemName&gt;`.
The :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute can be used to find all datasets in the
``NXdata`` that contain coordinate values.

Most AXISNAME fields will be sequences of numbers but if an axis is better represented using names, such as channel names,
an array of NX_CHAR can be provided.
</doc>
<attribute name="long_name"><doc>Axis label</doc></attribute>
<attribute name="units">
Expand Down
12 changes: 12 additions & 0 deletions base_classes/NXdetector.nxdl.xml
Original file line number Diff line number Diff line change
Expand Up @@ -421,6 +421,18 @@
</doc>
</field>

<group name="CHANNELNAME_channel" type="NXdetector_channel">
<doc>
Group containing the description and metadata for a single channel from a multi-channel
detector.

Given an :ref:`NXdata` group linked as part of an NXdetector group that has an axis with
named channels (see the example in :ref:`NXdata &lt;/NXdata@default_slice-attribute&gt;`),
the NXdetector will have a series of NXdetector_channel groups, one for each channel,
named CHANNELNAME_channel.
</doc>
</group>

<group name="efficiency" type="NXdata">
<doc>Spectral efficiency of detector with respect to e.g. wavelength</doc>
<attribute name="signal">
Expand Down
162 changes: 162 additions & 0 deletions base_classes/NXdetector_channel.nxdl.xml
phyy-nx marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
<?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-2022 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 category="base" extends="NXobject" name="NXdetector_channel"
type="group"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
xmlns="http://definition.nexusformat.org/nxdl/3.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://definition.nexusformat.org/nxdl/@NXDL_RELEASE@"
>

<symbols>
<doc>
These symbols will be used below to illustrate the coordination of the rank and sizes of datasets and the
preferred ordering of the dimensions. Each of these are optional (so the rank of the datasets
will vary according to the situation) and the general ordering principle is slowest to fastest.
The type of each dimension should follow the order of scan points, detector output (e.g. pixels),
then time-of-flight (i.e. spectroscopy, spectrometry). Note that the output of a detector is not limited
to single values (0D), lists (1D) and images (2D), but three or higher dimensional arrays can be produced
by a detector at each trigger.
</doc>

<symbol name="dataRank"><doc>Rank of the ``data`` field associated with this detector</doc></symbol>
<symbol name="nP"><doc>number of scan points</doc></symbol>
<symbol name="i"><doc>number of detector pixels in the slowest direction</doc></symbol>
<symbol name="j"><doc>number of detector pixels in the second slowest direction</doc></symbol>
<symbol name="k"><doc>number of detector pixels in the third slowest direction</doc></symbol>
</symbols>

<doc>
Description and metadata for a single channel from a multi-channel detector.

Given an :ref:`NXdata` group linked as part of an NXdetector group that has an axis with named channels (see the
example in :ref:`NXdata &lt;/NXdata@default_slice-attribute&gt;`), the NXdetector will have a series of NXdetector_channel groups, one for each
channel, named CHANNELNAME_channel.

Example, given these axes in the NXdata group::

@axes = ["image_id", "channel", ".", "."]

And this list of channels in the NXdata group::

channel = ["threshold_1", "threshold_2", "difference"]

The NXdetector group would have three NXdetector_channel groups::

detector:NXdetector
...
threshold_1_channel:NXdetector_channel
threshold_energy = float
flatfield = float[i, j]
pixel_mask = uint[i, j]
flatfield_applied = bool
pixel_mask_applied = bool
threshold_2_channel:NXdetector_channel
threshold_energy = float
flatfield = float[i, j]
pixel_mask = uint[i, j]
flatfield_applied = bool
pixel_mask_applied = bool
difference_channel:NXdetector_channel
threshold_energy = float[2]
phyy-nx marked this conversation as resolved.
Show resolved Hide resolved
</doc>

<field name="threshold_energy" type="NX_FLOAT" units="NX_ENERGY">
<doc>Energy at which a photon will be recorded</doc>
</field>

<field name="flatfield_applied" type="NX_BOOLEAN" >
<doc>
True when the flat field correction has been applied in the
electronics, false otherwise.
</doc>
</field>

<field name="flatfield" type="NX_NUMBER">
<doc>Response of each pixel given a constant input</doc>
<dimensions rank="dataRank">
<dim index="1" value="i" />
<dim index="2" value="j" />
<dim index="3" value="k" required="false"/>
</dimensions>
</field>

<field name="flatfield_errors" type="NX_FLOAT" >
<doc>
Errors of the flat field correction data.
The form flatfield_error is deprecated.
</doc>
<dimensions rank="2">
<dim index="1" value="i"/>
<dim index="2" value="j"/>
</dimensions>
</field>

<field name="pixel_mask_applied" type="NX_BOOLEAN" >
<doc>
True when the pixel mask correction has been applied in the
electronics, false otherwise.
</doc>
</field>

<field name="pixel_mask" type="NX_INT">
<doc>
Custom pixel mask for this channel. May include nP as the first dimension for
masks that vary for each scan point.
</doc>
<dimensions rank="dataRank">
<dim index="2" value="i" />
<dim index="3" value="j" />
<dim index="4" value="k" required="false"/>
</dimensions>
</field>

<field name="saturation_value" type="NX_NUMBER">
<doc>
The value at which the detector goes into saturation.
Especially common to CCD detectors, the data
is known to be invalid above this value.

For example, given a saturation_value and an underload_value, the valid
pixels are those less than or equal to the saturation_value and greater
than or equal to the underload_value.

The precise type should match the type of the data.
</doc>
</field>

<field name="underload_value" type="NX_NUMBER">
<doc>
The lowest value at which pixels for this detector would be reasonably
measured. The data is known to be invalid below this value.

For example, given a saturation_value and an underload_value, the valid
pixels are those less than or equal to the saturation_value and greater
than or equal to the underload_value.

The precise type should match the type of the data.
</doc>
</field>
</definition>
11 changes: 11 additions & 0 deletions nxdlTypes.xsd
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,7 @@
nxdl:NX_POSINT
nxdl:NX_QUATERNION
nxdl:NX_UINT
nxdl:NX_CHAR_OR_NUMBER
"/>
</xs:simpleType>

Expand Down Expand Up @@ -619,4 +620,14 @@
<xs:restriction base="xs:unsignedByte" />
</xs:simpleType>

<xs:simpleType name="NX_CHAR_OR_NUMBER">
<xs:annotation>
<xs:documentation>Any valid character string or NeXus number representation</xs:documentation>
</xs:annotation>
<xs:union memberTypes="
nxdl:NX_NUMBER
nxdl:NX_CHAR
" />
</xs:simpleType>

</xs:schema>
Loading