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.

Sign up for GitHub

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

NXexperiment and NXexperimentdata #580

Closed
wants to merge 1 commit into from
Closed

NXexperiment and NXexperimentdata #580

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
56 changes: 56 additions & 0 deletions contributed_definitions/NXexperiment.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
<?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) 2012-2017 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="NXexperiment" extends="NXobject" type="group"
version="1.0"
category="contributed"
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>
Describe the contents of an NXentry resulting from a data collection using multiple detectors,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

per #469 & #270, make the first line a one-line summary since only the first line will be used to generate the summary documentation about each NXDL shown on http://download.nexusformat.org/doc/html/classes/contributed_definitions/index.html

generating raw and derived data, potentially being scanned across multiple dimensions.

It is not uncommon for a beamline at a synchrotron to collect data from multiple detectors in during a single scan. NeXus files
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove in

from these scans will contain many :ref:`NXdata` either containing direct links to :ref:`NXdetector` data, or data derived from
this data. The aim of the :ref:`NXexperiment` class is to store NeXus classes in a way that better represents the *experiment* performed,
rather than the *instrument* the experiment was performed on.

For example, a small-angle scattering beamline with a detector for SAXS,
WAXS, XRF, a diode for transmitted intensity and an XY stage performs a single grid scan: The XRF raw data
might be have multiple channels that are summed to give the MCA, then small regions of this sum may also
be summed to produce simple elemental maps.

This file contains multiple plottable datasets, therefore multiple NXdata groups and NXdetectors,
but with no obvious way to discern what was measured and how the plottable datasets are related.

The :ref:`NXexperimentdata` class allows (multiple) :ref:`NXdata` to be related to each other (through the ``DATANAME_origin`` attribute in :ref:`NXexperimentdata`), and back to the :ref:`NXdetector`
used to collect the data.

(**required**) :ref:`NXexperimentdata` container for :ref:`NXdata` and single :ref:`NXdetector` used for the measurement

</doc>
<group type="NXexperimentdata" />

</definition>
56 changes: 56 additions & 0 deletions contributed_definitions/NXexperimentdata.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
<?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) 2012-2017 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="NXexperimentdata" extends="NXobject" type="group"
version="1.0"
category="contributed"
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>
Describe all the plottable data from a single detector in a single entity. To be used
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

per #469 & #270, make the first line a one-line summary since only the first line will be used to generate the summary documentation about each NXDL shown on http://download.nexusformat.org/doc/html/classes/contributed_definitions/index.html

inside :ref:`NXexperiment`

Allows data to be related back to the detector that collected it.

(**required**) :ref:`NXdetector` detector used to acquire data.

(**required**) :ref:`NXdata` at least one NXdata, related to the NXdetector
</doc>
<attribute name="DATANAME_origin">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add nameType="any" (per #562) to indicate that DATANAME is not required text in the name

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to check, the issue suggests using this in fields, whereas this is an attribute. No other attributes (such as AXISNAME_indices) follow this convention.

<doc>
Best description of the origin of this data, use . for the :ref:`NXdetector`. ``DATANAME`` refers to the
name of an :ref:`NXdata` that must be in the same :ref:`NXexperimentdata`.
</doc>
</attribute>
<attribute name="primary">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change name of this attribute to default (per #380)

documentation should mention that an absolute HDF5 path address (starts with /, such as /entry/instrument/detector1/ccd3) must be used.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer not to have to use the absolute HDF5 path for this, just the name of (one of) the NXdata in this class.

This would be expected to be used more like the signal attribute in NXData, that is, from my collection of objects, which is the one i should actually care about. If it is a path to a location outside the group, it loses all the connections in the group.
For example, NXexperimentdata contains

Xspress3 (/entry/instrument/detector)[NXDetector]
AllElementSum(/entry/AllElementSum)[NXData]
FeKAlpha(/entry/FeKAlpha)[NXData]

with default wanting to refer to FeKalpha (which has an origin of AllElementSum, which has an origin of Xspress3). If default was /entry/FeKalpha I have to strip the HDF5 path to make any use of the origin attributes.
There is the requirement that all the NXdata groups in this class must have unique names (which could be explicitly stated in the doc) but if there are mulitple NXdata, derived from the same NXDetector, with the same name, that suggests to me bigger issues with the file.

Since this behaviour breaks with the use of default in the issue (by not using the full path), but would work with the external default definition (I assume there is no reason why the default in an NXentry couldn't contain the full path to the NXdata in an NXexperimentaldata), maybe a different name would be better.

<doc>
Default :ref:`NXdata` to plot to represent this detector.
</doc>
</attribute>
<group type="NXdetector" />
<group type="NXdata" />

</definition>